@@ -0,0 +1,189 @@
+# CLI reorganization — mapping existing features onto the proposed tree
+
+## Implemented so far (branch `cli-reorg`, non-breaking, no backend changes)
+- **Rename aliases** (old spellings still work): `workspaces use`←set; `databases use`←set, `remove`←delete; `databases tables remove`←delete; `ingest pause`←cancel, `logs`←runs, `remove`←delete; `datasource test`←validate, `add`←create, `remove`←delete; `results get`←show; `embedding-providers show`←get, `add`←create, `remove`←delete.
+- **`ingest sources`** — `datasource` command tree surfaced under `hotdata ingest sources …` (reuses the datasource dispatcher; top-level `datasource` kept).
+- **`manage`** — `usage` / `completions` / `upgrade` grouped under `hotdata manage …` (top-level kept; update-gate exemptions extended).
+- **`databases context`** — top-level `context` surfaced under `hotdata databases context …` (reuses the context handlers; top-level kept).
+- **`databases` absorption** — `query`, `queries`, `results` surfaced under `hotdata databases …`, and `tables show` added under `databases tables` (all reuse existing handlers/sub-enums; top-level kept). The `results get` alias flows through the nested path too.
+- **`search` reshape** — new `search` namespace: `create --type vector|text`, `list`, `show`, `query`, `remove`, and `providers` (embedding-providers). Indexes are addressed by name via a new `indexes::locate_by_name` resolver (scoped to the active database, else workspace-wide). `search` is dual-mode: the legacy `search "text" --table …` flag form still works (`args_conflicts_with_subcommands`), and top-level `indexes` / `embedding-providers` are untouched. 407 unit tests pass.
+
+- **`ingest create --stream`** — sugar for `--type continuous` (conflicts with `--type`).
+
+**All CLI-only reorg is now on the branch.** Remaining items need backend or are net-new features (out of scope for this reorg): `ingest run` (trigger), `workspaces show`, `databases tag/untag`, `databases tables create`, `manage config/doctor`, and the `models` namespace.
+
+## Backward compat dropped — collapsed to the clean surface
+The migration kept both old and new spellings; that's now removed. The surface is 8 top-level groups (`auth`, `workspaces`, `databases`, `skills`, `jobs`, `ingest`, `search`, `manage`):
+- **Renames are canonical** (old names gone, not aliased): `use` (was set), `remove` (was delete), `pause` (was cancel), `logs` (was runs), `test` (was validate), `add` (was create, datasource/embeddings), `get` (was show, results).
+- **Top-level duplicates removed**: `query`/`queries`/`results`/`context`/`tables` now live only under `databases`; `datasource` only under `ingest sources`; `indexes`/`embedding-providers` only under `search`; `usage`/`completions`/`upgrade` only under `manage`.
+- **`search` action reshaped** — the search action is `search "text" --index <name>` (query positional + `--index`, alias `--in`); index management stays as subcommands `create`/`list`/`show`/`remove`/`embeddings`. The redundant `search query` subcommand is gone (it read the verb twice and collided with SQL `query`), as is the old `--table`/`--column` inference.
+- **Dead code removed** — the legacy-path orphans are gone: `indexes::infer_for_search`/`resolve_search_params`/`matches_search_column` (+ their tests), `tables::list`/`TableRow`/`full_name`, and the unused `IndexesCommands`/`TablesCommands` enums. Warning-free build; 388 tests pass.
+- **`query` kept top-level** as a shortcut (`hotdata query "…"`) alongside `databases query` — the one deliberate ergonomic exception.
+- **`skills` moved under `manage`** — `hotdata manage skills install|status|list` (top-level `skills` removed).
+- **`databases run` removed** — the scoped-token exec command and its helpers (`run`, `mint_database_token`, `create_and_return_id`, `DatabaseTokenResponse`, + tests) are gone. The `HOTDATA_DATABASE_TOKEN` env-auth path in the client is kept (still usable by an externally-supplied database token); `database_session::save` is now `#[allow(dead_code)]` alongside the existing reserved `load`/`clear`.
+
+## End-to-end validation against production (api.hotdata.dev)
+Ran every reachable command against prod in a throwaway database (created + deleted, no existing resources touched). All read/nested/alias/reshape paths passed. One real bug found and fixed:
+
+- **Fixed:** `search query`/`show`/`remove` by name built SQL against the index listing's internal `__db_*` connection label instead of the database's SQL catalog alias, so `bm25_search`/`vector_distance` failed with "catalog '' is not attached". `indexes::locate_by_name` now prefers the active database's `default_catalog`. Verified: bm25 and vector (auto-embed via the system OpenAI provider) searches both return ranked results.
+- **Not bugs (auth/business rules the CLI surfaced correctly):** `datasource create` requires a workspace API key (`hd_…`), not a login session — so the datasource→ingest *write* cycle is auth-gated (read/validate paths all pass); an embedding-backed vector index can't coexist with other indexes on a table; `query` is read-only (no DDL/DML).
+
+---
+
+
+Scope: **relocate/rename features that already ship.** Greenfield (`models`,
+`ingest stream`, `workspaces show`, `databases tables create`, `search … show`,
+`manage config|doctor`, `ingest … run`) is out of scope here — this is only the
+move.
+
+Legend: **rename** = same behavior, new verb · **reparent** = same command, new
+home · **reshape** = command model actually changes.
+
+---
+
+## auth  (no change)
+| today | proposed | kind |
+|---|---|---|
+| `auth login/logout/status` | same | — |
+| `auth register` | *(no slot in proposal — keep)* | — |
+
+## workspaces
+| today | proposed | kind |
+|---|---|---|
+| `workspaces list` | `workspaces list` | — |
+| `workspaces set` | `workspaces use` | rename |
+
+## ingest  (biggest structural change: flat → `batch` / `stream`)
+Today `datasource` and `ingest` are two **top-level** commands. Proposed: one
+`ingest` parent, a `batch` child, and `datasource` folded in under
+`ingest batch sources`.
+
+| today | proposed | kind |
+|---|---|---|
+| `datasource create` | `ingest batch sources add` | rename + reparent |
+| `datasource list` | `ingest batch sources list` | reparent |
+| `datasource show` | `ingest batch sources show` | reparent |
+| `datasource validate` | `ingest batch sources test` | rename + reparent |
+| `datasource delete` | `ingest batch sources remove` | rename + reparent |
+| `datasource update-config` | `ingest batch sources update` *(no proposal slot — keep)* | reparent |
+| `datasource types` / `fields` | `ingest batch sources types` / `fields` *(keep)* | reparent |
+| `ingest create` | `ingest batch create` | reparent |
+| `ingest list` | `ingest batch list` | reparent |
+| `ingest show` | `ingest batch show` | reparent |
+| `ingest cancel` | `ingest batch pause` | rename + reparent |
+| `ingest resume` | `ingest batch resume` | reparent |
+| `ingest schedule` | `ingest batch schedule` | reparent |
+| `ingest runs` / `ingest run <run>` | `ingest batch logs` | reshape + reparent |
+| `ingest delete` | `ingest batch remove` | rename + reparent |
+
+Note: proposed `ingest batch run <ingest>` (trigger-now) has **no equivalent** —
+today the scheduler owns dispatch (`schedule --next now` is the workaround). Not
+part of the move; it's a new capability.
+
+## databases  (absorbs four top-level commands)
+| today | proposed | kind |
+|---|---|---|
+| `databases list/show/create/fork/attach/detach` | same | — |
+| `databases set` | `databases use` | rename |
+| `databases unset` | `databases use --clear` *(or keep)* | rename |
+| `databases delete` | `databases remove` | rename |
+| `databases count` | *(no slot — keep)* | — |
+| `databases run` | *(no slot — keep; scoped-token power feature)* | — |
+| `databases load` | `databases tables load` | reshape (dedupe w/ below) |
+| `databases tables list` | `databases tables list` | — |
+| `databases tables load` | `databases tables load` | — |
+| `databases tables delete` | `databases tables remove` | rename |
+| **`tables show`** (top-level) | `databases tables show` | reparent |
+| **`tables list`** (top-level) | `databases tables list` | reparent (merge) |
+| **`query "<sql>"`** (top-level) | `databases query "<sql>"` | reparent |
+| **`queries list` / `queries <id>`** (top-level) | `databases queries list\|show` | reparent |
+| **`results list` / `results show`** (top-level) | `databases results list\|get` | rename + reparent |
+| **`context list\|show\|pull\|push`** (top-level) | `databases context …` | reparent |
+
+## search  (the only non-mechanical reshape: merges 3 commands into an object model)
+Today search is three separate things: `indexes` (create/list/delete, typed
+vector|bm25), the flag-driven `search` query command, and `embedding-providers`.
+Proposed: one `search` parent split into `vector` / `text`, each treating an
+index as a named object.
+
+| today | proposed | kind |
+|---|---|---|
+| `indexes create --type vector …` | `search vector create <name> --from --column` | reshape |
+| `indexes create --type bm25 …` | `search text create <name> --from --column` | reshape |
+| `indexes list` | `search vector list` + `search text list` | reshape (split by type) |
+| `indexes delete` | `search vector remove` / `search text remove` | rename + reshape |
+| `search "q" --type vector …` | `search vector query <name> "q"` | reshape |
+| `search "q" --type bm25 …` | `search text query <name> "q"` | reshape |
+| `embedding-providers list` | `search vector providers list` | reparent |
+| `embedding-providers create` | `search vector providers add` | rename + reparent |
+| `embedding-providers delete` | `search vector providers remove` | rename + reparent |
+| `embedding-providers get` / `update` | `search vector providers show` / *(update kept)* | rename + reparent |
+
+This is the one bucket that's real code, not enum-shuffling: it introduces
+"index as a named, listable, show-able object" that doesn't exist today.
+
+## manage  (regroup three top-level utilities)
+| today | proposed | kind |
+|---|---|---|
+| `usage` | `manage usage` | reparent |
+| `completions` | `manage completions` | reparent |
+| `upgrade` | `manage upgrade` | reparent |
+
+## unhomed today — need a decision
+Not in the proposal at all; pick a parent or leave top-level:
+- `jobs` — cross-cutting (ingest runs, index builds). Candidate: `manage jobs`.
+- `skills` — agent-skill install. Candidate: `manage skills`.
+- `query` (top-level) — see keystroke note below.
+
+---
+
+## What it looks like in clap (illustrative)
+
+```rust
+pub enum Commands {
+    Auth       { command: AuthCommands },        // unchanged
+    Workspaces { command: WorkspaceCommands },   // list, use (was set)
+    Ingest     { command: IngestCommands },      // batch { sources { … }, … }
+    Databases  { command: DatabasesCommands },   // + query/queries/results/context/tables absorbed
+    Search     { command: SearchCommands },      // vector | text  (merges indexes + search + embedding-providers)
+    Manage     { command: ManageCommands },      // usage, completions, upgrade (+ jobs/skills?)
+    // kept without a proposal home: Query (alias), Jobs, Skills …
+}
+
+pub enum IngestCommands { Batch(BatchCommands) /*, Stream(…) later */ }
+pub enum BatchCommands {
+    Sources(SourceCommands),            // was top-level `datasource`
+    Create, List, Show, Schedule, Resume,
+    Pause,                              // was Cancel
+    Logs,                              // was Runs / Run
+    Remove,                            // was Delete
+}
+pub enum SourceCommands { Add, List, Show, Test, Remove /*, Update, Types, Fields kept */ }
+
+pub enum SearchCommands { Vector(VectorCommands), Text(TextCommands) }
+pub enum VectorCommands { Create, List, Query, Remove, Providers(ProviderCommands) /*, Show* */ }
+```
+
+The mechanical buckets (workspaces/databases/ingest/manage moves) are mostly
+moving enum variants between modules and adding a nesting layer. `search` is the
+one that needs new command logic.
+
+---
+
+## Two costs worth deciding before committing
+
+1. **`query` gets demoted.** `hotdata query "…"` → `hotdata databases query "…"`.
+   Query is the hottest path; nesting it taxes every ad-hoc SQL call. Strong
+   case for keeping a **top-level `query` visible alias** even after the move.
+
+2. **Depth.** `hotdata ingest batch sources add …` is four levels; `search
+   vector create` is three. More discoverable via `--help`, more to type. Fine
+   if aliases cover the common cases.
+
+## Suggested phasing (non-breaking → breaking)
+- **Phase 1 — additive.** Stand up the new nested paths as canonical; wire the
+  old spellings as hidden `alias`es. Zero breakage, scripts keep working.
+- **Phase 2 — search reshape.** The only real feature work: index-as-object +
+  `vector`/`text` split. Do this on its own so it's reviewable in isolation.
+- **Phase 3 — deprecate.** Warn on old spellings, then drop in a major. (Repo
+  already shipped a breaking ingest split in #256, so precedent exists.)