docs: document CLI install/update commands and fix installer issues

README.md

@@ -44,6 +44,31 @@ pip install java-codebase-rag
 Python **3.11+** required. After install, `java-codebase-rag --help` should print the CLI groups.
 The package includes the CocoIndex lifecycle dependency used by `init`, `increment`, `reprocess`, and `erase`.
 
+### Interactive setup (recommended)
+
+Run `java-codebase-rag install` from your Java project root to launch an interactive setup wizard that:
+
+1. Detects Java source directories (Maven/Gradle modules)
+2. Configures the embedding model (auto-downloads ~90MB or uses a local path)
+3. Selects agent hosts (Claude Code, Qwen Code, GigaCode)
+4. Deploys MCP registration, skill, and agent artifacts
+5. Generates `.java-codebase-rag.yml` configuration
+6. Runs `init` to build the index
+
+```bash
+# Interactive mode
+java-codebase-rag install
+
+# Non-interactive mode (for CI/automation)
+java-codebase-rag install --non-interactive --agent claude-code
+```
+
+After `pip install --upgrade java-codebase-rag`, run `java-codebase-rag update` to refresh shipped artifacts.
+
+### Manual registration
+
+If you prefer manual configuration, see [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs/JAVA-CODEBASE-RAG-CLI.md) for the full CLI reference.
+
 > **Stability disclaimer.** This package does **not** promise backward compatibility. MCP tool contracts, env vars, Lance/Kuzu schemas, config files, and Python APIs may change without a deprecation period. Track `main` and rebuild indexes when ontology or embedding settings change.
 
 ---
@@ -84,7 +109,9 @@ If vector hits come back and graph expansion adds neighbor symbols, the install
 
 ## Wire into an MCP host
 
-### Claude Code
+> **Quick setup:** Run `java-codebase-rag install` from your Java project root. The interactive wizard handles MCP registration, skill deployment, and configuration for Claude Code, Qwen Code, and GigaCode in one step.
+
+### Claude Code (manual)
 
 With the package installed, the console script `java-codebase-rag-mcp` is on your `PATH`. Register it project-scoped:
 
@@ -167,6 +194,8 @@ Run `java-codebase-rag --help` to list grouped subcommands. Operator playbook wi
 
 | Group | Subcommand | What it does |
 |---|---|---|
+| Setup | `install` | Interactive setup wizard: config, MCP registration, skill/agent deployment, indexing. |
+| Setup | `update` | Refresh shipped artifacts (skill, agent, MCP entry) after pip upgrade. |
 | Lifecycle | `init` | First-time index. Refuses if artifacts already exist. |
 | Lifecycle | `increment` | CocoIndex catch-up + incremental Kuzu update. `--vectors-only` for Lance only. |
 | Lifecycle | `reprocess` | Full Lance + Kuzu rebuild. `--vectors-only` / `--graph-only` for a single phase. |

docs/JAVA-CODEBASE-RAG-CLI.md

@@ -17,6 +17,80 @@ If `java-codebase-rag` is missing, run the module entrypoint:
 .venv/bin/python -m java_codebase_rag.cli --help
 ```
 
+## Setup commands
+
+### `install`
+
+Interactive setup wizard that walks users through Java source detection, embedding model selection, agent host configuration, artifact deployment, and YAML config generation. Use `--non-interactive` for CI/automation.
+
+```bash
+# Interactive mode
+java-codebase-rag install
+
+# Non-interactive mode (requires at least one --agent)
+java-codebase-rag install --non-interactive --agent claude-code
+java-codebase-rag install --non-interactive --agent claude-code --agent qwen-code
+
+# With custom embedding model
+java-codebase-rag install --model /path/to/model
+
+# User-scope installation (available globally)
+java-codebase-rag install --scope user
+```
+
+**Flags:**
+- `--non-interactive` — Run without prompts (requires `--agent`).
+- `--agent {claude-code,qwen-code,gigacode}` — Agent host to configure (can be passed multiple times).
+- `--scope {project,user}` — Installation scope (default: `project`). Project scope writes to `.<host>/` in the project repo; user scope writes to `~/.<host>/` (globally available).
+- `--model MODEL` — Embedding model path or `auto` (default: `auto`, downloads `sentence-transformers/all-MiniLM-L6-v2` on first run).
+
+**Exit codes:**
+- `0` — Success (all stages completed).
+- `1` — Partial success (some stages failed). Re-run `install` to retry failed stages.
+- `2` — Fatal error (no Java files found, required flag missing).
+
+**Stages:**
+1. Java source detection — Maven/Gradle module roots.
+2. Embedding model selection — auto-download or local path.
+3. Agent host selection — Claude Code, Qwen Code, GigaCode (multi-select).
+4. Install scope — project or user.
+5. MCP entrypoint resolution + artifact deployment — config, skill, agent files.
+6. Index + finish — YAML generation, `.gitignore` update, `init`.
+
+**Re-running `install`:** If `.java-codebase-rag.yml` exists, the installer shows current values and offers "Update" (pre-filled) or "Start fresh". Existing MCP entries are updated in-place (merged, not duplicated). Skill/agent files trigger overwrite confirmation.
+
+### `update`
+
+Post-upgrade refresh: overwrites skill and agent files with the latest shipped versions and updates the MCP command path. Requires a prior `install` run.
+
+```bash
+# Refresh after pip upgrade
+pip install --upgrade java-codebase-rag
+java-codebase-rag update
+
+# Preview changes without writing
+java-codebase-rag update --dry-run
+
+# Force overwrite all artifacts
+java-codebase-rag update --force
+```
+
+**Flags:**
+- `--force` — Overwrite all artifacts even if content matches.
+- `--dry-run` — Print changes without writing files.
+
+**Behavior:**
+- Detects previously configured agent hosts (scans both project-level and user-level config files).
+- Refreshes skill and agent files (versioned assets from the package).
+- Updates MCP entrypoint path if `java-codebase-rag-mcp` has moved.
+- Runs `increment` on the index if it exists (LanceDB catch-up). Prints graph staleness warning.
+- Skips MCP config if the entry already exists and is correct.
+
+**Exit codes:**
+- `0` — Success.
+- `1` — Partial failure (some artifacts failed to write).
+- `2` — No configured hosts found.
+
 ## Output mode
 
 - **TTY:** human-readable `pprint` of the payload on stdout (except **successful selective `reprocess`** with `--vectors-only` / `--graph-only`, which prints `Rebuilt:` / `Skipped:` lines instead of dumping the full dict).