Pluggable embedding providers (ollama / openai / voyage) + storage-path unification

README.md

@@ -307,19 +307,48 @@ The watcher monitors the project with `fsnotify`, debounces events (5 s default)
 ### Configuration
 
 ```bash
-cix config show              # print current config
-cix config set <key> <val>   # set a value
+cix config init              # first-run wizard (TUI form)
+cix config edit              # interactive edit (TUI form)
+cix config show              # print current config (lists servers; * marks default)
+cix config keys              # list every settable key with default/env/description
+cix config set <key> <val>   # set one value
+cix config unset <key>       # remove a server / clear a key
 cix config path              # show config file location
 ```
 
-Config file: `~/.cix/config.yaml`
+Config file: `~/.cix/config.yaml`. The full key reference lives in
+[`doc/CLI_CONFIG.md`](doc/CLI_CONFIG.md) — `cix config keys` is the
+canonical runtime view.
 
-| Key | Default | Description |
-|-----|---------|-------------|
-| `api.url` | `http://localhost:21847` | API server URL |
-| `api.key` | — | Bearer token (`cix_*`) — required |
-| `watcher.debounce_ms` | `5000` | Delay before reindex triggers after a file change |
-| `indexing.batch_size` | `20` | Files per `/index/files` batch |
+#### Env overrides (CI)
+
+| Variable        | Overrides                                |
+|-----------------|------------------------------------------|
+| `CIX_SERVER`    | which alias resolves when `--server` is empty |
+| `CIX_API_URL`   | the resolved server's URL                |
+| `CIX_API_KEY`   | the resolved server's API key            |
+
+Precedence is **flag > env > file > default**. Env overrides apply only
+to the current process — they never write back to `~/.cix/config.yaml`.
+
+#### Multiple servers
+
+`cix` can be configured with several named servers and pick one per
+command with the global `--server <alias>` flag (without it, the
+`default_server` is used):
+
+```bash
+cix config set server.corporate.url https://cix.corp.internal
+cix config set server.corporate.key cix_...
+cix config set default_server corporate     # optional
+cix --server corporate search "rate limiter"
+cix config unset server.corporate           # remove it
+```
+
+The legacy `api.url` / `api.key` keys and the `--api-url` / `--api-key`
+flags still work — they read/override the default server — and old flat
+`api:` config files are migrated to the `servers:` layout automatically
+on first load.
 
 ---
 

cli/README.md

@@ -27,12 +27,16 @@ cli/
 │   ├── reindex.go       — `cix reindex`
 │   ├── cancel.go        — `cix cancel`
 │   ├── watch.go         — `cix watch` (start/stop/status, daemon)
-│   ├── config.go        — `cix config show/set/path`
+│   ├── config.go        — `cix config show/set/unset/path` (+ multi-server keys)
+│   ├── config_keys.go   — `cix config keys` (schema-driven key listing)
+│   ├── config_edit.go   — `cix config edit` / `cix config init` (huh-driven TUI)
 │   ├── workspace.go     — `cix workspace …` (cross-repo, name-first)
 │   └── version.go       — `cix version`
 ├── internal/
 │   ├── client/          — HTTP client to cix-server
 │   ├── config/          — YAML config (~/.cix/config.yaml)
+│   │   ├── schema/      — tag-driven walker over Config (single source of truth)
+│   │   └── tui/         — huh-based form for `cix config edit` / `init`
 │   ├── daemon/          — PID-file based watcher daemon
 │   ├── discovery/       — project-root detection for `cix init`
 │   ├── fileutil/        — binary/text + size helpers
@@ -82,6 +86,132 @@ Then any command picks up the saved URL + key from `~/.cix/config.yaml`.
 The server can be local Docker (`docker compose up -d` in the repo
 root) or a remote server. The CLI doesn't care.
 
+### Multiple servers
+
+The CLI can hold several **named servers** and pick one per command. The
+config stores a `servers:` list and a `default_server`; commands use the
+default unless `--server <alias>` is given.
+
+```bash
+# Add a second server and switch the default
+cix config set server.corporate.url https://cix.corp.internal
+cix config set server.corporate.key <bearer-token>
+cix config set default_server corporate
+
+# Target a specific server for one command (alias must exist in config)
+cix --server corporate search "rate limiter"
+
+# Inspect / remove
+cix config show                      # lists servers; * marks the default
+cix config unset server.corporate    # remove a server
+```
+
+The legacy `api.url` / `api.key` keys and the `--api-url` / `--api-key`
+flags still work — they operate on (or override) the **default** server,
+so single-server setups need no changes. Old `~/.cix/config.yaml` files
+that use the flat `api:` block are migrated to the `servers:` layout
+automatically on first load (the old single server becomes `default`).
+
+### Environment overrides (CI-friendly)
+
+For CI runners, containers, and one-off scripts you can override server
+selection via env vars instead of writing to `~/.cix/config.yaml`.
+Precedence is always **flag > env > file > built-in default** — env
+overrides never persist to disk.
+
+| Variable        | Overrides                                | Use case |
+|-----------------|------------------------------------------|----------|
+| `CIX_SERVER`    | which alias resolves when `--server` is empty | Switch active server in a shell session without touching the file |
+| `CIX_API_URL`   | the resolved server's `url`              | Point at a different cix-server instance per process |
+| `CIX_API_KEY`   | the resolved server's `key`              | Pass a secret from `secrets.CIX_API_KEY` in GitHub Actions |
+
+Example (GitHub Actions):
+
+```yaml
+env:
+  CIX_API_URL: https://cix.corp.internal
+  CIX_API_KEY: ${{ secrets.CIX_API_KEY }}
+steps:
+  - run: cix search "foo"
+```
+
+The 3-var surface is deliberately narrow — knobs like
+`watcher.debounce_ms` or `indexing.batch_size` live in the config file
+only, because they are persistent developer preferences, not per-process
+overrides.
+
+### Interactive setup (`cix config init` / `cix config edit`)
+
+`cix config init` is the first-run wizard for fresh machines: it opens
+a paged form (`huh`-driven TUI) that seeds the default server entry,
+asks for the API key, and walks through the watcher + indexing knobs.
+On submit it validates everything against the schema and writes
+`~/.cix/config.yaml`.
+
+`cix config edit` is the same form against an existing config — useful
+when you want to flip booleans (e.g. `watcher.enabled`) or tune timeouts
+without re-reading `cix config set --help`.
+
+```
+┌─ Servers ──────────────────────────────┐
+│ [default] URL  http://localhost:21847  │
+│ [default] API key  ●●●●●●●●            │
+│ Default server  ▼ default              │
+└────────────────────────────────────────┘
+┌─ File watcher ─────────────────────────┐
+│ Enable the watcher    [✓]              │
+│ Debounce (ms)         5000             │
+│ Sync interval (min)   5                │
+│ Exclude patterns      node_modules,…   │
+└────────────────────────────────────────┘
+┌─ Indexing ─────────────────────────────┐
+│ Batch size            20               │
+│ Streaming idle (s)    30               │
+└────────────────────────────────────────┘
+       [ Submit ]   ESC to cancel
+```
+
+Add/remove of server aliases is still done via
+`cix config set server.<name>.url …` / `cix config unset server.<name>`
+— the form edits URL/key of *existing* aliases.
+
+### Discovering keys (`cix config keys`)
+
+`cix config keys` prints every settable configuration key with its
+current value, default, env-var binding (if any), and a short
+description. This is the canonical reference — there is no hard-coded
+list anywhere else:
+
+```bash
+$ cix config keys
+KEY                                  VALUE                  DEFAULT  ENV         DESCRIPTION
+default_server                       default                —        CIX_SERVER  Alias of the server used when --server is omitted
+watcher.enabled                      true                   true     —           Run the file watcher
+watcher.debounce_ms                  5000                   5000     —           Debounce delay (ms)
+watcher.exclude                      [node_modules .git …]  …        —           Paths/globs to skip (REPLACE semantics on set)
+watcher.sync_interval_mins           5                      5        —           Periodic sync interval (minutes)
+indexing.batch_size                  20                     20       —           Indexing batch size
+indexing.streaming_idle_timeout_sec  30                     30       —           Streaming /index/files idle timeout (seconds); 0 disables
+```
+
+Slice keys (servers, projects) are not listed here — `cix config show`
+displays them in their dedicated formats.
+
+### List-valued keys (`watcher.exclude`)
+
+`watcher.exclude` is the one list-valued scalar that `cix config set`
+accepts. Input is **comma-separated**, and the semantics are
+**REPLACE, not append**:
+
+```bash
+$ cix config set watcher.exclude "node_modules,vendor,build"
+# overwrites the entire list; previous defaults are gone
+```
+
+There is no `cix config add` / `cix config append` — if you want to
+keep the existing defaults plus add an entry, repeat the full list.
+The interactive `cix config edit` form is usually nicer for this.
+
 ## Smoke test
 
 ```bash