Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
docs(init): every surface that teaches init says what the CLI does (#4255)
Raghav Chamadiya2572e8d36385
diff --git a/docs/agent/INTEGRATIONS.md b/docs/agent/INTEGRATIONS.mdindex 1c370ef52..cae9913a8 100644--- a/docs/agent/INTEGRATIONS.md+++ b/docs/agent/INTEGRATIONS.md@@ -26,6 +26,10 @@ it and repowise does not write it. `No` means the surface does not existfor that agent. `Indexing` is `Yes` when the agent's own CLI can run as theLLM that writes the index, selected by its provider id (`claude_cli`, forexample). It is separate from the tier: it says nothing about the session.+`init` offers a logged-in agent CLI but uses it only when you pick it or pass+`--provider`. An agent CLI has no embedder, so semantic search needs an+embedder key of its own: see+[Embeddings](../reference/CONFIG.md#embeddings-for-semantic-search).`Attribution` is `Yes` when repowise can record the agent's edits as theyhappen, an opt-in set by `attribution.capture` and `attribution.agents`. Everydiff --git a/docs/architecture/structurizr-export.md b/docs/architecture/structurizr-export.mdindex e6dc4fe6e..9fdda8cdf 100644--- a/docs/architecture/structurizr-export.md+++ b/docs/architecture/structurizr-export.md@@ -4,7 +4,7 @@ Repowise can emit your architecture as [Structurizr](https://structurizr.com)DSL — the C4 model as a text file you commit, diff and render in your owntoolchain instead of ours.-It is deterministic: no LLM call, no API key, works under `init --index-only`,+It is deterministic: no LLM call, no API key, works under `init --no-prose`,and nothing is added to indexing. The file is built on demand from the graphthat is already there.diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.mdindex a80e3c0e8..1e047b188 100644--- a/docs/reference/CLI_REFERENCE.md+++ b/docs/reference/CLI_REFERENCE.md@@ -140,15 +140,11 @@ repowise init .In workspace mode, adds: repo scanning, per-repo indexing, cross-repo analysis (co-changes, contracts, package deps), workspace CLAUDE.md generation.-**Interactive modes.** Running a bare `repowise init` on a TTY (no `--provider`, `--prose`/`--no-prose`, or `--yes`) opens a menu:+**Plan screen.** Running `repowise init` on a TTY (no `--provider`, `--no-prose`, `--mode fast`, `--resume` or `--yes`) opens one screen with the repo scan, an ETA, the plan, and an opt-in model line with what a model adds and costs. Enter starts the free run (documentation built from code). `m` picks a model, `e` edits the plan (advanced options, the agent checklist, the post-commit hook, and keeping machine-specific files out of git through `.git/info/exclude`, off by default), `s` leaves the global MCP entry where it is, and `q` quits. In a folder of repos the screen lists them, and `r` chooses the repos and the primary.-1. **Written by a model**, index + documentation a model writes. After picking a provider you can answer **"Customize?"** to tune any setting before the run.-2. **Built from code**, the same layers plus documentation built from code; no LLM, no key, no cost. Answer **"Customize indexing?"** to set exclude patterns, commit limit, skip-tests/infra, submodules, and fast mode.-3. **Advanced**, full control. First choose **"Have a model write the documentation?"**; the prompts then split into an **Indexing** section (always) and a **Generation** section (provider, concurrency, embedder, wiki style, onboarding, tiering, only when model-written docs are on).+**Page volume.** File pages are rendered from structure and cost no model tokens, so what bounds them buys wiki size, embedding calls and less retrieval noise, never spend. Two numbers govern it, both derived from the size distribution of real indexed repos. Above **2,000** documentable files (p95), the plan screen's `e` step offers the top 2,000 by importance instead of one page per file, quoted in pages and megabytes; nothing is capped automatically at that size. Above **4,500** file pages (about 40 MB of file layer, near p99), every run holds the bucket to 4,500 and says so in its output, because that is where the tail is the difference between a wiki that publishes and one that does not. `--max-file-pages N` sets a cap directly and `--max-file-pages 0` refuses one; either way the answer is saved as `max_file_pages` in `config.yaml`, which `update --full` and `generate` honour. A hosted or scripted caller sets the same field with no terminal involved.-**Page volume.** File pages are rendered from structure and cost no model tokens, so what bounds them buys wiki size, embedding calls and less retrieval noise, never spend. Two numbers govern it, both derived from the size distribution of real indexed repos. Above **2,000** documentable files (p95), an interactive advanced-mode run offers the top 2,000 by importance instead of one page per file, quoted in pages and megabytes; nothing is capped automatically at that size. Above **4,500** file pages (about 40 MB of file layer, near p99), every run holds the bucket to 4,500 and says so in its output, because that is where the tail is the difference between a wiki that publishes and one that does not. `--max-file-pages N` sets a cap directly and `--max-file-pages 0` refuses one; either way the answer is saved as `max_file_pages` in `config.yaml`, which `update --full` and `generate` honour. A hosted or scripted caller sets the same field with no terminal involved.--All three reach the indexing knobs; the LLM-only knobs appear only when model-written docs are enabled. Passing any of the flags below (or `--yes`) skips the menu and runs non-interactively. If the first prompt reads EOF (common when an agent pipes stdin), init prints a notice and continues with defaults instead of aborting.+If the screen reads EOF (common when an agent pipes stdin), init prints a notice and continues with defaults instead of aborting.**Cost gate.** Before any tokens are spent, init shows the estimate and asks for confirmation. It never prompts when stdin is not a TTY: it auto-declines, keeps the index it already built, and renders the structural wiki instead. The default answer is Yes up to $25 and flips to No above that.@@ -156,7 +152,7 @@ All three reach the indexing knobs; the LLM-only knobs appear only when model-wr| Flag | Description ||------|-------------|-| `--provider` | LLM provider: `anthropic`, `openai`, `openrouter`, `gemini`, `deepseek`, `kimi`, `ollama`, `litellm`, `codex_cli`, `opencode`, `edenai`, `mock` |+| `--provider` | LLM provider: `anthropic`, `openai`, `openrouter`, `gemini`, `deepseek`, `kimi`, `ollama`, `litellm`, `codex_cli`, `claude_cli`, `opencode`, `edenai`, `mock` || `--model` | Model name override (e.g., `claude-sonnet-4-6`) || `--embedder` | Embedder for semantic search: `gemini`, `openai`, `openrouter`, `ollama`, `edenai`, `mock` (default: auto-detect) || `--prose` / `--no-prose` | The single knob over LLM spend. The file, symbol, cycle (SCC), API and infra pages are rendered from structure either way, with no key and no cost. The model-written set is the subsystem (concept) tree plus the repo overview, the architecture diagram, and the onboarding collection: `--prose` writes those as model prose and needs a key; `--no-prose` leaves them as structural stubs, so the whole wiki is keyless and free. Default: prose when a key is available. Full-text search works either way; semantic search needs an embedder. `--no-prose` makes no model calls even when a key is set, so decision extraction from PRs, commit history and comments waits for a model run. Fill or refill that prose, and add those decisions, later with [`repowise generate`](#repowise-generate-path). |@@ -187,7 +183,7 @@ All three reach the indexing knobs; the LLM-only knobs appear only when model-wr| `--save-key` / `--no-save-key` | Save the provider API key this run authenticated with into `.repowise/.env` (git-ignored, owner-only). Default: on, because a scripted `init` that succeeds must leave a repo whose MCP server can actually answer, and a key supplied through the environment would otherwise vanish with the shell that set it. The file is what `repowise mcp`, `serve` and `update` read back; without it `get_answer` degrades to `no-llm-provider` and returns retrieval-only output. Use `--no-save-key` when the key is injected per-process (CI secrets, a shared machine) and must not reach disk; `REPOWISE_NO_SAVE_KEY=1` is the same switch for CI and sandboxes. Answering No to the interactive key prompt also wins over the default. Note this writes one line to the repo's `.gitignore`, so pair it with `--no-save-key` when you need `--no-editor-setup`'s "nothing written into the repo" guarantee. || `--seed-from` | Seed the index from an explicit base checkout instead of the auto-detected one. Rarely needed: inside a linked git worktree the base is detected and seeded automatically. See [WORKTREES.md](../scale/WORKTREES.md). || `--no-seed` | Disable worktree auto-seeding and run a full init even inside a linked worktree. |-| `--yes` / `-y` | Skip confirmation prompts |+| `--yes` / `-y` | Skip the plan screen and every question, with each answer at its default. A model writes the documentation only when a provider is configured; a logged-in Claude Code, Codex or OpenCode is used only with `--provider`. Add `--no-prose` to guarantee no model calls || `--dry-run` | Show the generation plan and cost estimate. Writes no wiki || `--test-run` | Write docs with the model for only the top 10 files (by PageRank). Not with `--no-prose` or `--mode fast` || `--all` | In a folder with several repos, index every detected repo without prompting. `--yes` and a piped stdin do the same and print which repos they took |diff --git a/docs/reference/CONFIG.md b/docs/reference/CONFIG.mdindex 2523f43ac..d437d43a9 100644--- a/docs/reference/CONFIG.md+++ b/docs/reference/CONFIG.md@@ -145,7 +145,7 @@ You can edit this file directly. Changes take effect on the next `init`,| Key | Default | Meaning ||-----|---------|---------|-| `provider` | auto-detected | `anthropic`, `openai`, `gemini`, `openrouter`, `deepseek`, `kimi`, `ollama`, `litellm`, `opencode` |+| `provider` | auto-detected | `anthropic`, `openai`, `gemini`, `openrouter`, `deepseek`, `kimi`, `ollama`, `litellm`, `edenai`, `claude_cli`, `codex_cli`, `opencode` || `model` | provider default | Model identifier passed to the provider || `embedder` | `mock` | `openai`, `gemini`, `ollama`, `openrouter`, `edenai`, `mock` || `embedding_model` | provider default | Embedding model identifier |@@ -1000,12 +1000,19 @@ The embedder is separate from the LLM provider.| Embedder | Env var | Notes ||----------|---------|-------|-| `gemini` | `GEMINI_API_KEY` | Default when key is present |+| `gemini` | `GEMINI_API_KEY` (or `GOOGLE_API_KEY`) | Default when key is present || `openai` | `OPENAI_API_KEY` | OpenAI `text-embedding-3-small` || `openrouter` | `OPENROUTER_API_KEY` | Routed through OpenRouter || `ollama` | `OLLAMA_EMBEDDING_MODEL` | Local Ollama embeddings, no API key |+| `edenai` | `EDENAI_API_KEY` | Eden AI gateway, see [Eden AI](#eden-ai-hosted-with-an-eu-endpoint) || `mock` | n/a | Dummy embeddings, no semantic search (default when no key is detected) |+Which embedder a run uses, first match wins: `--embedder`, then+`REPOWISE_EMBEDDER`, then the `embedder` pin in `.repowise/config.yaml`, then+the first key present in the order gemini, openai, openrouter, ollama, edenai,+then `embedder` in `~/.repowise/config.yaml`, then `mock`. `reindex` skips a+`mock` pin when a real embedder can be found.+```bashrepowise init --embedder openairepowise reindex --embedder gemini # switch embedder and rebuild indexdiff --git a/docs/scale/WORKSPACES.md b/docs/scale/WORKSPACES.mdindex 0cf7664bd..6cfdfcf45 100644--- a/docs/scale/WORKSPACES.md+++ b/docs/scale/WORKSPACES.md@@ -52,15 +52,19 @@ cd my-workspacerepowise init .```-`repowise init .` scans for git repositories up to 3 levels deep, asks which to-index and which is the primary repo (the default for MCP queries), walks you-through provider setup, then indexes each repo, generates its docs (unless-`--no-prose`), runs the cross-repo analysis, and registers the MCP server with-your editors.--To skip the picker, `--repos api,web` indexes only those repos (by alias,-directory name, or relative path) and makes the first one primary. `--yes`,-`--all` or a piped stdin take every repo and print which ones.+`repowise init .` scans for git repositories up to 3 levels deep (linked git+worktrees are skipped) and opens a plan screen listing them. By default every+repo is selected and its documentation is built from code; `r` chooses the+repos and the primary repo (the default for MCP queries), and `m` adds a model.+It then indexes each repo, runs the cross-repo analysis, and registers the MCP+server with your editors.++To skip the screen, `--repos api,web` indexes only those repos (by alias,+directory name, or relative path). In a new workspace the first one listed is+primary; an existing workspace keeps its primary. `--yes`, `--all` or a piped+stdin take every repo and print which ones. Picking fewer repos on a re-run+keeps the others in `.repowise-workspace.yaml`: an interactive run asks before+dropping them, and `--yes` never drops them.```bashrepowise status --workspace # workspace statusdiff --git a/docs/start/CI.md b/docs/start/CI.mdindex 51129c1f5..439155d3e 100644--- a/docs/start/CI.md+++ b/docs/start/CI.md@@ -300,7 +300,7 @@ jobs:- uses: actions/cache/restore@v4with: {path: .repowise, key: "repowise-${{ github.sha }}", restore-keys: "repowise-"}- run: pip install repowise- - run: if [ -f .repowise/state.json ]; then repowise update --index-only; else repowise init --yes --index-only; fi+ - run: if [ -f .repowise/state.json ]; then repowise update --index-only; else repowise init --yes --no-prose; fi- uses: actions/cache/save@v4with: {path: .repowise, key: "repowise-${{ github.sha }}"}```@@ -334,7 +334,7 @@ repowise-index:variables: {GIT_DEPTH: "0"}script:- pip install repowise- - if [ -f .repowise/state.json ]; then repowise update --index-only; else repowise init --yes --index-only; fi+ - if [ -f .repowise/state.json ]; then repowise update --index-only; else repowise init --yes --no-prose; ficache: {key: repowise-index, paths: [.repowise/], policy: pull-push}rules:- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCHdiff --git a/docs/start/DASHBOARD.md b/docs/start/DASHBOARD.mdindex 527dc9033..e3117d382 100644--- a/docs/start/DASHBOARD.md+++ b/docs/start/DASHBOARD.md@@ -21,21 +21,19 @@ looking at.## Two modes, and what changes between them-Repowise can index a repo without generating a wiki (`repowise init---no-prose`, or the fast option in the setup wizard). Everything derived from-the AST, the dependency graph, and git history works in both modes. The views-that read generated pages are the difference:+Without a model, `repowise init --no-prose` builds the documentation from+code. Everything derived from the AST, the dependency graph, and git history+works either way. The views that read written pages are the difference:| Needs a model or an embedder | Works on any indexed repo ||---|---|| Chat (needs a provider), semantic Search (needs an embedder) | Docs, Doc freshness, Present mode, Overview, Architecture, Knowledge Graph, Code Health, Refactoring, Files, Symbols, Commits, Contributors, Decisions, Stats, Usage, Settings, all Workspace views |-Every indexed repo has a wiki, including one indexed without a key, so the Docs-views are populated either way. What a keyless index lacks is model-written-prose and semantic search: the Docs view offers to upgrade pages with-`repowise generate`, and `repowise reindex` builds semantic search once an-embedder is configured. Either upgrade works in place, with no re-index from-scratch.+An index built from code has documentation, so the Docs views are populated.+It lacks written documentation and semantic search: `repowise generate` adds+the first, and `repowise reindex --embedder <name>` the second. An Index only+repo (`init --mode fast`) has no documentation until `repowise update --full`+builds it. Every upgrade works in place, with no re-index from scratch.## Overviewdiff --git a/docs/start/TROUBLESHOOTING.md b/docs/start/TROUBLESHOOTING.mdindex 594232103..e3d1bd630 100644--- a/docs/start/TROUBLESHOOTING.md+++ b/docs/start/TROUBLESHOOTING.md@@ -43,14 +43,15 @@ or rate limit can fail individual pages while the run completes.`repowise init --resume` writes only the pages that are absent and makes nomodel call for the ones you have, even if you switched provider.-**Doctor reports zero pages.** Even a keyless run writes pages, so an empty-wiki means the run did not finish. Run `repowise init --resume`.+**Doctor reports zero pages.** A keyless run writes pages too. Zero pages+means the run did not finish (run `repowise init --resume`) or the repo is+Index only (run `repowise update --full`).**Memory or time on a very large repository.** Options, roughly in order ofeffect:```bash-repowise init --yes --no-prose --mode fast # graph and essential git only; backfill later+repowise init --yes --no-prose --mode fast # Index only; `repowise update --full` adds the rest laterREPOWISE_PARSE_WORKERS=2 repowise init # fewer parse processes, less memoryrepowise init -x vendor/ -x 'generated/**' # exclude what you never editrepowise init --max-file-pages 2000 # cap file pages, highest importance firstdiff --git a/examples/dead-code/README.md b/examples/dead-code/README.mdindex aaecd83a3..3ed6628b5 100644--- a/examples/dead-code/README.md+++ b/examples/dead-code/README.md@@ -12,7 +12,7 @@ cleanup candidates ranked by confidence. No LLM key required.```bashcd /path/to/your-repo-repowise init --index-only --yes+repowise init --yes --no-prose```## 1. Scan the repodiff --git a/examples/decisions/README.md b/examples/decisions/README.mdindex 4c0fcbbde..904c788e0 100644--- a/examples/decisions/README.md+++ b/examples/decisions/README.md@@ -11,7 +11,7 @@ proposals, and read the health dashboard. No LLM key required for list/health.```bashcd /path/to/your-repo-repowise init --index-only --yes+repowise init --yes --no-prose```Decisions are mined during indexing from inline markers, commits, and otherdiff --git a/examples/distill/README.md b/examples/distill/README.mdindex 56e22b493..e15e168df 100644--- a/examples/distill/README.md+++ b/examples/distill/README.md@@ -14,7 +14,7 @@ required.```bashcd /path/to/your-repo-repowise init --index-only --yes+repowise init --yes --no-prose````distill` still works without a wiki: it wraps the command, picks a filter bydiff --git a/examples/health-coverage/README.md b/examples/health-coverage/README.mdindex c84388417..c60dc0a8b 100644--- a/examples/health-coverage/README.md+++ b/examples/health-coverage/README.md@@ -12,7 +12,7 @@ using real CLI commands. No LLM key required for these steps.```bashcd /path/to/your-repo-repowise init --index-only --yes+repowise init --yes --no-prose```## 1. Read code healthdiff --git a/examples/hooks-sync/README.md b/examples/hooks-sync/README.mdindex 54b16e5ed..97b476629 100644--- a/examples/hooks-sync/README.md+++ b/examples/hooks-sync/README.md@@ -12,7 +12,7 @@ Keep the wiki index fresh with `repowise hook` (post-commit) and```bashcd /path/to/your-repo-repowise init --index-only --yes+repowise init --yes --no-prose```## 1. Post-commit hookdiff --git a/examples/opencode/README.md b/examples/opencode/README.mdindex 0c80cd3c7..a01a5c3da 100644--- a/examples/opencode/README.md+++ b/examples/opencode/README.md@@ -34,7 +34,7 @@ repowise init --provider opencode --yesFast smoke without LLM wiki generation (index + graph/git/health only):```bash-repowise init --index-only --yes+repowise init --yes --no-prose```Then upgrade pages later with OpenCode:diff --git a/examples/search/README.md b/examples/search/README.mdindex 49efff81d..b1eae7f91 100644--- a/examples/search/README.md+++ b/examples/search/README.md@@ -12,7 +12,7 @@ key required for fulltext and symbol modes.```bashcd /path/to/your-repo-repowise init --index-only --yes+repowise init --yes --no-prose```## 1. Full-text search (default)diff --git a/examples/security-scan/README.md b/examples/security-scan/README.mdindex 5aa269c19..03981c864 100644--- a/examples/security-scan/README.md+++ b/examples/security-scan/README.md@@ -16,7 +16,7 @@ into docs, commits, or chat.```bashcd /path/to/your-repo-repowise init --index-only --yes+repowise init --yes --no-prose```## 1. Working-tree scan (automatic)@@ -96,7 +96,7 @@ separate from this local OSS history walk — see| Step | Expected ||------|----------|-| `repowise init --index-only --yes` | Completes; working-tree findings may appear in Security UI |+| `repowise init --yes --no-prose` | Completes; working-tree findings may appear in Security UI || `repowise security scan` | Short hint mentioning `--history` || `repowise security scan --history` | Table (or empty) of history findings || `repowise security scan --history --output json` | JSON list; re-run stays stable |diff --git a/examples/structurizr-export/README.md b/examples/structurizr-export/README.mdindex 8e43aa07c..d3a4e3b44 100644--- a/examples/structurizr-export/README.md+++ b/examples/structurizr-export/README.md@@ -2,7 +2,7 @@Emit your architecture as [Structurizr](https://structurizr.com) DSL from thegraph Repowise already built. Deterministic — no LLM key, works after-`init --index-only`.+`init --no-prose`.## Prerequisites@@ -13,7 +13,7 @@ graph Repowise already built. Deterministic — no LLM key, works after```bashcd /path/to/your-repo-repowise init --index-only --yes+repowise init --yes --no-prose```## 1. Model fragment (default)@@ -67,7 +67,7 @@ repowise export --format structurizr --no-externals| Step | Expected ||------|----------|-| `repowise init --index-only --yes` | Completes without an API key |+| `repowise init --yes --no-prose` | Completes without an API key || `repowise export --format structurizr` | Writes a `.dsl` fragment; prints include hint || `repowise export --format structurizr --standalone -o /tmp/rw-arch/` | Complete workspace that Structurizr can open alone || Zero containers in the printed counts | Index/graph problem — re-run init, not a format bug |diff --git a/examples/wiki-export/README.md b/examples/wiki-export/README.mdindex 79601697e..47a439427 100644--- a/examples/wiki-export/README.md+++ b/examples/wiki-export/README.md@@ -12,7 +12,7 @@ markdown, HTML, and JSON — no LLM key required. For Structurizr DSL, see```bashcd /path/to/your-repo-repowise init --index-only --yes+repowise init --yes --no-prose```## 1. Export wiki pagesdiff --git a/packages/cli/src/repowise/cli/agent_targets/_data/codex_prompts/repowise-init.md b/packages/cli/src/repowise/cli/agent_targets/_data/codex_prompts/repowise-init.mdindex ec596faf7..c074087d9 100644--- a/packages/cli/src/repowise/cli/agent_targets/_data/codex_prompts/repowise-init.md+++ b/packages/cli/src/repowise/cli/agent_targets/_data/codex_prompts/repowise-init.md@@ -12,26 +12,36 @@ Run: `repowise --version`If the command fails or is not found, ask the user:-"Repowise isn't installed yet. I can install it for you. Which do you prefer?"-- `pip install repowise` (recommended, includes every LLM provider SDK)-- "I'll install it myself"+"Repowise isn't installed yet. I can install it for you, or you can install it yourself."-If they want you to install it, run `pip install repowise`. If that fails, try `python -m pip install repowise`.+If they want you to install it, use the first installer that works:+`uv tool install repowise`, then `pipx install repowise`, then+`python -m pip install repowise`. Each one includes every LLM provider SDK.-After install, verify with `repowise --version`.+After install, verify with `repowise --version`. If the shell still says+`command not found`, the user runs `uv tool update-shell` or `pipx ensurepath`+and opens a new shell.If repowise IS found, print the version and move to Step 2.## Step 2: Check if this repo is already indexed-Check if `.repowise/` directory exists in the project root.+If the project root has no `.repowise/` directory, move to Step 3.-If it exists, tell the user:-"This repo is already indexed by Repowise. Run `/prompts:repowise-status` to check health, or `/prompts:repowise-update` to refresh. If you want to re-index from scratch, I can run `repowise init --force`."+If it has one, run `repowise status --format json` and act on what it says:-Then stop — do not continue to Step 3 unless the user asks to re-index.+- **Incomplete** (`incomplete` is set): a previous run stopped part way. Offer+ `repowise init --resume` with the flags of the original run (`--no-prose`+ for a run built from code).+- **Index only** (`upgrade_command` is set): the repo was indexed with+ `--mode fast` and has no documentation yet. Offer `repowise update --full`.+ It needs no API key: without a model it builds the documentation from code+ and backfills the full git history, reusing the index.+- **Otherwise** the index is ready: "This repo is already indexed by Repowise.+ Run `/prompts:repowise-status` to check health, or `/prompts:repowise-update` to refresh."+ Re-index from scratch with `repowise init --force` only if the user asks.-If `.repowise/` doesn't exist, move to Step 3.+Do not continue to Step 3 unless the user asks to re-index.## Step 3: Offer the mode, but do not block on it@@ -40,51 +50,54 @@ setting it up, and never stop and wait if you cannot get an answer.Tell the user:-"Repowise indexes your repo and writes a complete wiki with no API key. I'll run-`repowise init --yes` unless you'd rather pick:+"Repowise indexes your repo and builds its documentation from code with no API+key. I'll run `repowise init --yes --no-prose` unless you want to pick:-1. **Default (no key)** — full index plus a wiki rendered from your code's structure. Free, fast, nothing to configure.-2. **Model-written wiki** — everything above, but an LLM writes the wiki prose instead of rendering it from structure, which also enables decision mining. Needs a provider key (Anthropic, OpenAI, Gemini, or Ollama locally). You can start keyless and upgrade any page later with `repowise generate`.-3. **Show me the flags.**"+1. **Built from code** (default, no key): the full index, health, dead code,+ and documentation built from code. No model calls, no cost.+2. **Written by a model**: a model writes the documentation and reads+ decisions from PRs, git history and code comments. Needs a provider, and+ shows the estimated cost before any model call. You can start with option 1+ and add this later with `repowise generate`.+3. **Index only**: graph and essential git history, no documentation. For very+ large repos; `repowise update --full` adds the rest later.+4. **Show me the flags.**"If the user does not answer, or you are running unattended, take option 1.-### If Default (no key):+- **Built from code:** skip provider selection. The command is+ `repowise init --yes --no-prose`. Go to Step 3b.+- **Written by a model:** go to Step 3b, then Step 4.+- **Index only:** the command is `repowise init --yes --no-prose --mode fast`.+ Go to Step 3b.+- **Show me the flags:** print the reference below, then ask whether you+ should build the command or they will.-Skip provider selection entirely. Construct:-```-repowise init --no-prose --yes-```--Jump to Step 3b.--### If Full mode:--Move to Step 3b, then Step 4.--### If "show me flags":--Print the full flag reference:```repowise init [PATH]Core flags:- --provider NAME LLM provider: anthropic, openai, gemini, ollama, litellm+ --provider NAME LLM provider: anthropic, openai, gemini, openrouter,+ deepseek, kimi, ollama, litellm, edenai, claude_cli,+ codex_cli, opencode--model NAME Model identifier override- --prose / --no-prose Write the subsystem (concept) pages as model prose- (--prose, needs a key), or render the whole wiki from- structure with no model and no spend (--no-prose).- Every other page is structural either way.- Default: prose when a key is available.- --mode fast Quick first pass on very large repos: no wiki at all.+ --prose / --no-prose Documentation written by a model (--prose, needs a+ provider) or built from code (--no-prose: no model+ calls, whatever keys are set). Default: written by a+ model when a key is available.+ --mode fast Index only: graph and essential git, no documentation.+ 'repowise update --full' adds the rest later.Embeddings:- --embedder NAME Embedding provider: gemini, openai, openrouter, ollama,- edenai, mock (default: auto-detect)+ --embedder NAME Embedder for semantic search: gemini, openai,+ openrouter, ollama, edenai, mock (default: detected+ from keys)Cost control:--concurrency N Max parallel LLM calls (default: 10)- --test-run Limit to top 10 files by PageRank for quick validation+ --test-run Write documentation with the model for the top 10+ files only, for a quick check+ --dry-run Show the plan and cost estimate without runningExclusions:-x, --exclude PATTERN Gitignore-style exclude patterns. Repeatable.@@ -93,112 +106,102 @@ Exclusions:--skip-infra Skip infrastructure files (Dockerfile, Makefile, Terraform, shell)Git:- --commit-limit N Max commits to analyze per file (default: 500, max: 10000)+ --commit-limit N Max commits to analyze per file (default: 5000, max: 10000)--follow-renames Track files across renames (slower but more accurate history)Editor integration:- --editor-setup / Wire repowise into your editors (default), or skip it- --no-editor-setup entirely. Covers both halves: the machine-wide config- (~/.claude/settings.json, Claude Desktop's config, the- Claude Code hooks, the distill rewrite-hook offer) and- the project-local files (.mcp.json, .claude/CLAUDE.md,- .vscode/mcp.json, .vscode/extensions.json). With- --no-editor-setup only .repowise/ is touched. There is- one 'repowise' MCP entry per machine-wide config, so a- later init from another repo repoints it. See Step 3b.+ --no-editor-setup Write only .repowise/: no global MCP entry, no+ Claude Code hooks, no project files (.mcp.json,+ .claude/CLAUDE.md, .vscode/). See Step 3b.--hook / --no-hook Install the post-commit hook that runs 'repowise- update' in the background after each commit, so the- index does not go stale between sessions. Default: on.- --no-editor-setup keeps it off too, since a git hook- is a write outside .repowise/. Undo any time with- 'repowise hook uninstall'.+ update' after each commit. Default: on (off with+ --no-editor-setup). Undo with 'repowise hook uninstall'.Keys:- --save-key / Save the provider key this run authenticated with to- --no-save-key .repowise/.env (gitignored, owner-only). Default: on,- so the MCP server can answer later without the shell- that set it. Use --no-save-key in CI or on a shared- machine.+ --no-save-key Do not save the provider key to .repowise/.env+ (for CI or a shared machine)Output:- --no-claude-md Don't generate/update CLAUDE.md- -y, --yes Skip cost confirmation prompt- -v, --verbose Show per-phase internals plus debug logs (quiet by default)+ --no-claude-md Don't generate or update CLAUDE.md+ --progress json One JSON event per line on stdout, ending with a+ summary (status, mode, spend, next commands)+ -y, --yes No questions: every answer at its default, cost+ pre-approved. Add --no-prose to guarantee no spend.+ -v, --verbose Show per-phase internals plus debug logsRecovery:- --resume Resume a previously interrupted init- --force Re-index from scratch, overwriting existing .repowise/--Dry run:- --dry-run Show generation plan and cost estimate without running+ --resume Continue a run that stopped part way+ --force Re-index from scratch```-Then ask if they want you to construct a command or if they'll handle it.-## Step 3b: Is this repo a keeper?Every path reaches this step. It is about the repo, not the provider.-By default `init` registers repowise as the user's global MCP server, in-`~/.claude/settings.json` and Claude Desktop's config, and writes four-project-local files into the repo (`.mcp.json`, `.claude/CLAUDE.md`,-`.vscode/mcp.json`, `.vscode/extensions.json`). There is **one** `repowise` key-in each machine-wide config, so this repo replaces whatever repo is registered-now. That is the right default for the repo someone actually works in, and the-wrong one for a checkout that is about to disappear.+By default `init` points the global repowise MCP entry (in+`~/.claude/settings.json` and Claude Desktop's config) at this repo and writes+project files into it (`.mcp.json`, `.claude/CLAUDE.md`, `AGENTS.md`,+`.vscode/mcp.json`). There is **one** global `repowise` entry, so this repo+replaces whatever repo it points at now. With `--yes`, init moves it and prints+the old and new target. That is the right default for the repo someone+actually works in, and the wrong one for a checkout that is about to disappear.Add `--no-editor-setup` when either of these holds:- the path is a scratch clone, a fixture, a sample, a vendored copy, or sitsunder a temp directory-- it is a linked git worktree rather than the main checkout. Check with+- it is a linked git worktree, not the main checkout. Check with`git rev-parse --git-common-dir`: a value other than `.git` means a worktreeAlso add it if the user says they don't want their editor or MCP setup touched.-Do **not** infer that from "just index it" or "don't ask me questions" — those+Do **not** infer that from "just index it" or "don't ask me questions": thoseare about prompts, not config.-The index and the wiki are identical either way. What the flag skips is both-the machine-wide registration and the four project-local files, so with it only-`.repowise/` is touched. (`.repowise/mcp.json` is still written: it is what-`repowise mcp .` prints, and it is how you opt back in.) Either half can be-done later by re-running `repowise init` in that repo without the flag.+The index and the documentation are identical either way. With the flag only+`.repowise/` is written. Re-running `repowise init` in that repo without the+flag wires it up later.-Whichever you pick, say which in one line so the user can correct you.+Whichever you pick, say which in one line so the user can correct you. If+`init` prints the old and new target of the global entry, relay it: the user+may want it pointed back.-If `init` prints "Replacing the existing repowise MCP …", relay it. The global-entry just moved to this repo, and the user may want it pointed back.+Then continue to Step 4 for documentation written by a model, or Step 5+otherwise.-Then continue to Step 4 for the model-written wiki, or Step 5 otherwise.+## Step 4: Provider selection (written by a model only)-## Step 4: Provider selection (model-written wiki only)--**Skip this entire step unless the user chose the model-written wiki.** A-missing key is not a blocker: `init` renders the template wiki and exits 0-without one. If the user has no key, do not stop and do not ask again. Run-`repowise init --yes` and tell the user their wiki is rendered from structure-and can be upgraded per-page later with `repowise generate`.+**Skip this entire step unless the user chose documentation written by a+model.** A missing key is not a blocker. If the user has no key, do not stop and+do not ask again: run `repowise init --yes --no-prose` and tell the user they can+add a model later with `repowise generate`.Do not read, test or print the user's environment variables or key values-yourself. `repowise init` picks up a provider key from the environment on its-own, so a user who already has one set needs no `--provider`. Ask:+yourself. `repowise init` picks up a provider key from the environment and+`.repowise/.env` on its own, so a user who already has one set needs no+`--provider`. Ask:"Which LLM provider do you want to use?"-- **Anthropic** (Claude) — needs `ANTHROPIC_API_KEY`-- **OpenAI** (GPT-4o or compatible) — needs `OPENAI_API_KEY`-- **Google Gemini** (recommended for cost efficiency) — needs `GEMINI_API_KEY` or `GOOGLE_API_KEY`-- **Ollama** (fully local, no API key, slower) — needs Ollama running locally-- **LiteLLM** (100+ providers) — needs LiteLLM config--If they have not set that key yet, ask them to set it in their own shell. Show the exact export command:+- **Google Gemini** (good cost efficiency): needs `GEMINI_API_KEY` or `GOOGLE_API_KEY`+- **Anthropic** (Claude): needs `ANTHROPIC_API_KEY`+- **OpenAI**: needs `OPENAI_API_KEY`+- **OpenRouter, DeepSeek, Kimi, Eden AI**: need their own key+- **Ollama** (fully local, no API key, slower): needs Ollama running+- **LiteLLM** (100+ providers): needs LiteLLM config+- **Claude Code, Codex or OpenCode login** (`claude_cli`, `codex_cli`,+ `opencode`): uses the user's plan quota, or is billed per token when the+ CLI is signed in with an API key, and takes longer. `init` reads each CLI's+ auth status and uses one only with `--provider`. A Codex signed in through+ ChatGPT is listed in the picker but not offered.++The user sets a key in their own shell or in `.repowise/.env` (gitignored).+Never ask for a key in the chat. Show the export line for their provider:```bash-export ANTHROPIC_API_KEY="sk-ant-..."+export GEMINI_API_KEY="..."```-Every provider SDK (anthropic, openai, google-genai, litellm) ships with `repowise`-itself, so there is no per-provider package to install. If a provider import fails,-the install is broken rather than incomplete: reinstall with-`pip install --force-reinstall repowise` and run `repowise doctor`.+Every provider SDK ships with `repowise` itself, so there is no per-provider+package to install. If a provider import fails, the install is broken:+reinstall repowise with the same installer and run `repowise doctor`.## Step 5: Exclusions@@ -210,33 +213,53 @@ Add any exclusions as `-x` flags.## Step 6: Run it-For an unattended or non-interactive run, the canonical command is-`repowise init --yes`, plus `--no-prose` when you want to guarantee no spend.-`--yes` suppresses every prompt including the cost gate. You do not need to guard-against prompts beyond that: init treats an unanswerable question as a signal to-continue with defaults rather than a reason to fail, and the cost gate declines-by itself when stdin is not a terminal, keeping the finished index and landing on-the structural wiki.+The unattended command is `repowise init --yes --no-prose`. `--yes` answers+every prompt with its default and pre-approves the cost; `--no-prose` makes sure+nothing is spent. Without `--no-prose`, `--yes` uses a model whenever a key is+set; a logged-in agent CLI only with `--provider`. In a folder that holds+several repos, `--yes` indexes all of them; `--repos a,b` picks some. A model run passes `--yes` only after the user approved the estimate+(`repowise init --dry-run` prints it).Show the user the exact command you're about to run. Ask for confirmation.-Run it. For full mode, note: "This will take a while for the initial indexing. You can Ctrl+C safely — run `/prompts:repowise-init` again and I'll use `--resume` to continue where you left off."+Run it in the background. A small repo takes under a minute; a few thousand+files can take several minutes, longer than many tool timeouts. Wait for the+process to exit instead of relying on a fixed timeout, then read its exit code:++- `0`: ready.+- `2`: finished with gaps. Everything is saved; the last line names what is+ missing and the command that adds it.+- `130`: interrupted. `repowise init --resume` (same flags) continues it.+- anything else: failed. Run `repowise doctor`.++With `--progress json`, init writes one JSON event per line to stdout and ends+on a summary line with the status, mode, spend and next commands.++`repowise status` reports a first run as incomplete until it exits, so read it+after the process ends. Ctrl+C is safe at any point: running `/prompts:repowise-init` again+resumes with `--resume`.## Step 7: Post-setup-After init completes successfully:+After init exits with `0` or `2`:-1. Confirm the `.repowise/` directory was created-2. Run `repowise status` to show the summary-3. Tell the user:- - "Repowise has indexed your codebase. The MCP tools are now active — I can answer questions about your architecture, ownership, dependencies, and more."+1. Run `repowise status` to show the summary.+2. Tell the user:+ - "Run `repowise serve` to open the dashboard. It needs Node.js 20+, and the+ first run downloads the UI. It starts on port 3000, or the next free port."+ - "The MCP tools appear after you restart your agent, or run `/mcp` in+ Claude Code. They are not active in this session yet."**Only if you did not pass `--no-editor-setup`.** With that flag nothing was- registered and nothing was written into the repo outside `.repowise/`, so- say instead: "The index is built. I did not register it as your global MCP- server and wrote no editor files into the repo (this looked like a- temporary checkout). The repowise plugin's tools still work here; to wire- it up properly, re-run `repowise init` without `--no-editor-setup`."- - "Try asking me something like 'how does the auth module work?' or 'what depends on utils.py?'"- - "Run `/prompts:repowise-status` anytime to check the health of your index."- - "Run `/prompts:repowise-update` after making code changes to keep the wiki in sync."+ registered and no editor files were written, so say instead: "The index is+ built. I did not register it as your global MCP server and wrote no editor+ files into the repo (this looked like a temporary checkout). To wire it up,+ re-run `repowise init` without `--no-editor-setup`."+ - "After the restart, try asking me 'give me a tour of this codebase' or+ 'what depends on utils.py?'"+ - "Run `/prompts:repowise-status` anytime to check the index, and `/prompts:repowise-update`+ after code changes to keep it in sync."+3. If the documentation was built from code, add one line: "`repowise generate`+ has a model write the documentation and read decisions from PRs and+ history, with a cost estimate first." For an Index only run, name+ `repowise update --full` instead.4. If CLAUDE.md was generated (default): "I've also generated a CLAUDE.md with codebase context that I'll read on every session."diff --git a/packages/cli/src/repowise/cli/agent_targets/_data/codex_prompts/repowise-reindex.md b/packages/cli/src/repowise/cli/agent_targets/_data/codex_prompts/repowise-reindex.mdindex 18f4d6d7e..e10dd80e8 100644--- a/packages/cli/src/repowise/cli/agent_targets/_data/codex_prompts/repowise-reindex.md+++ b/packages/cli/src/repowise/cli/agent_targets/_data/codex_prompts/repowise-reindex.md@@ -1,5 +1,5 @@----description: Rebuild the Repowise vector store by re-embedding all wiki pages. No LLM calls — only embedding API calls.+description: Rebuild the Repowise vector store by re-embedding all documentation pages. No LLM calls, only embedding API calls.---# Repowise Reindex@@ -7,27 +7,28 @@ description: Rebuild the Repowise vector store by re-embedding all wiki pages. NRebuild the vector store (embeddings) without regenerating documentation.This is useful when:+- You want semantic search on an index built without an embedder key- You switched embedding providers- The LanceDB vector data got corrupted-- You want to refresh search quality after adding new wiki pages## Steps1. Check if `.repowise/` exists. If not: "This repo isn't indexed yet. Run `/prompts:repowise-init` first."-2. Run: `repowise reindex`+2. Run: `repowise reindex`, or `repowise reindex --embedder <name>` when the user named one.- This re-embeds all existing wiki pages into LanceDB. No LLM generation calls — only embedding API calls. Fast and cheap.+ This re-embeds all existing documentation pages into LanceDB. No LLM generation calls, only embedding API calls.## Available flags-- `--embedder gemini|openai|openrouter|ollama|edenai|auto` — embedding provider (default: auto-detect from env vars)-- `--batch-size N` — pages per embedding batch, must be 1 or greater (default: 32)+- `--embedder gemini|openai|openrouter|ollama|edenai|mock|auto`: embedding provider. `auto` (the default) keeps the repo's embedder, or picks one from the keys present when the repo has none yet+- `--batch-size N`: pages per embedding batch, must be 1 or greater (default: 32)## Requirements-Requires a key for one of the real embedders — `GEMINI_API_KEY`/`GOOGLE_API_KEY`, `OPENAI_API_KEY`, `OPENROUTER_API_KEY` or `EDENAI_API_KEY` — or a running Ollama. The mock embedder is not accepted for reindexing. If none is available, ask the user to set one before proceeding.+Semantic search needs a real embedder: a key for `gemini` (`GEMINI_API_KEY`/`GOOGLE_API_KEY`), `openai`, `openrouter` or `edenai`, or a local Ollama with `OLLAMA_EMBEDDING_MODEL` set. When none is available, `repowise reindex` exits 1 and prints the command that turns semantic search on; relay it and ask the user to set the key themselves, never in the chat. On an Index only repo there is no documentation to embed yet: `repowise update --full` builds it first.## Handling $ARGUMENTS-If $ARGUMENTS contains "full" or "from-scratch", confirm with the user: "This will regenerate ALL documentation from scratch, not just re-embed. It will take as long as the initial indexing and cost API tokens. Are you sure?" If yes: `repowise init --force`+- An embedder name (`gemini`, `openai`, `ollama`, ...): run `repowise reindex --embedder <name>`.+- "full" or "from-scratch": reindex already re-embeds every page. To rebuild the documentation itself, suggest `repowise generate` (a model writes it, with a cost estimate first), or `repowise update --full` on an Index only repo (no key needed).diff --git a/packages/cli/src/repowise/cli/agent_targets/_data/codex_prompts/repowise-search.md b/packages/cli/src/repowise/cli/agent_targets/_data/codex_prompts/repowise-search.mdindex f2e239d1a..a8a85af77 100644--- a/packages/cli/src/repowise/cli/agent_targets/_data/codex_prompts/repowise-search.md+++ b/packages/cli/src/repowise/cli/agent_targets/_data/codex_prompts/repowise-search.md@@ -19,12 +19,12 @@ repowise search "$ARGUMENTS"The default mode is `fulltext` (SQLite FTS5). You can specify a mode:-- `--mode fulltext` — fast keyword search (default)-- `--mode semantic` — vector similarity search using embeddings. Requires an embedding provider to be configured. If this fails with an error, suggest running `/prompts:repowise-reindex` first.-- `--mode symbol` — fuzzy match on symbol names (functions, classes, variables)+- `--mode fulltext`: fast keyword search (default)+- `--mode semantic`: vector similarity search using embeddings. Requires an embedding provider to be configured. If this fails with an error, suggest running `/prompts:repowise-reindex` first.+- `--mode symbol`: fuzzy match on symbol names (functions, classes, variables)Other flags:-- `--limit N` — max results (default: 10)+- `--limit N`: max results (default: 10)## Present results@@ -32,14 +32,16 @@ Show results as a clean list with the page title, type, and a brief snippet.## When search comes up empty-Search needs wiki pages, and every indexed repo has them: a keyless run renders-the whole wiki from structure. So an empty result is usually not a missing wiki.--- **No pages at all** means the index never finished, or the repo was indexed- with `--mode fast`, which is the one mode that writes no wiki. Suggest- `repowise init --yes` (no API key needed), or `repowise init --resume` if a- previous run was interrupted.-- **Pages exist but semantic search finds nothing** means the wiki was embedded- with the mock embedder, which keeps full-text search working and leaves- semantic search to be built later. Suggest `repowise reindex` with an embedder- configured. Full-text and symbol search (`--mode symbol`) work regardless.+Search reads the documentation pages, and an index built from code has them+too, so an empty result is usually not missing documentation.++- **No pages at all** means the index never finished, or the repo is Index+ only (`--mode fast`), the one mode with no documentation. Suggest+ `repowise update --full` (no API key needed), or `repowise init --resume` if+ a previous run was interrupted.+- **Pages exist but semantic search finds nothing** means the pages were+ embedded with the keyless `mock` embedder, which keeps full-text search+ working and leaves semantic search off. Suggest+ `repowise reindex --embedder <name>` once an embedder key is set (the user+ sets it, never in the chat). Full-text and symbol search (`--mode symbol`)+ work regardless.diff --git a/packages/cli/src/repowise/cli/agent_targets/_data/codex_prompts/repowise-update.md b/packages/cli/src/repowise/cli/agent_targets/_data/codex_prompts/repowise-update.mdindex d34672df4..f9b7cf2c4 100644--- a/packages/cli/src/repowise/cli/agent_targets/_data/codex_prompts/repowise-update.md+++ b/packages/cli/src/repowise/cli/agent_targets/_data/codex_prompts/repowise-update.md@@ -15,7 +15,7 @@ Trigger an incremental update of the Repowise index.This will:- Detect files changed since last sync commit- Update git metadata for changed files- - Regenerate affected wiki pages (up to cascade budget of 30)+ - Regenerate affected documentation pages (the cascade budget scales with the change)- Decay confidence scores for indirectly affected pages- Update dead code analysis- Update CLAUDE.md if enabled@@ -24,17 +24,19 @@ Trigger an incremental update of the Repowise index.## Available flags-- `--provider NAME` — override the LLM provider-- `--model NAME` — override the model-- `--since REF` — base git ref to diff from (overrides saved last_sync_commit). Accepts a commit SHA, tag, or branch name.-- `--cascade-budget N` — max pages to regenerate per run (default: 30)-- `--dry-run` — show affected pages without regenerating-- `-v, --verbose` — show the full changed-file list, per-phase internals, and debug logs (the run is quiet by default)+- `--full`: upgrade the index. On an Index only repo (`init --mode fast`) it backfills the full git history and builds the documentation: from code with no key, or written by a model when one is configured. On a repo built from code, a configured model writes the documentation. A model run shows the cost first; `--yes` accepts it.+- `--provider NAME`: override the LLM provider+- `--model NAME`: override the model+- `--since REF`: base git ref to diff from (overrides saved last_sync_commit). Accepts a commit SHA, tag, or branch name.+- `--cascade-budget N`: max pages to regenerate per run (auto-scaled when unset)+- `--working-tree`: also index uncommitted work+- `--dry-run`: show affected pages without regenerating+- `-v, --verbose`: show the full changed-file list, per-phase internals, and debug logs (the run is quiet by default)## Handling $ARGUMENTSIf the user provides arguments:-- "dry-run" or "dry run" → add `--dry-run` flag-- "force" or "full" → add `--cascade-budget 999` to regenerate all stale pages-- a git ref like a SHA or tag → add `--since {ref}`-- a file path → this is not supported by update; suggest `repowise update` which auto-detects changes+- "dry-run" or "dry run": add `--dry-run`+- "full" or "force": run `repowise update --full`. If a model is configured, ask the user before adding `--yes`, which accepts the cost estimate.+- a git ref like a SHA or tag: add `--since {ref}`+- a file path: update does not take one; suggest `repowise update`, which detects changes itselfdiff --git a/packages/cli/src/repowise/cli/agent_targets/instructions.py b/packages/cli/src/repowise/cli/agent_targets/instructions.pyindex 3374ac757..95808486d 100644--- a/packages/cli/src/repowise/cli/agent_targets/instructions.py+++ b/packages/cli/src/repowise/cli/agent_targets/instructions.py@@ -11,9 +11,9 @@ Cursor's ``.cursor/rules/*.mdc`` is the second, and a second copy of this proseis how the plugin skills forked: the two drift a sentence at a time and nothingdetects it.-Hosts differ in how the block is *framed* — Codex appends it to a file the user-owns, Cursor gets a file repowise creates outright with YAML frontmatter on top —-so the framing stays with each target and only the body is shared.+Hosts differ in how the block is *framed*: Codex appends it to a file the user+owns, Cursor gets a file repowise creates outright with YAML frontmatter on top.+The framing stays with each target and only the body is shared."""from __future__ import annotations@@ -32,7 +32,7 @@ DISTILL_SECTION_HEADING = "### Output Distillation"DISTILL_SECTION = f"""{DISTILL_SECTION_HEADING}-- Prefer `repowise distill <cmd>` for noisy commands — test runs, builds, `git status`/`log`/`diff`, searches, file listings. It runs the command unchanged (exit code preserved) and prints a compact, errors-first rendering; every error line survives.-- Output may contain a marker like `[repowise#a1b2c3d4e5f6: 230 lines omitted (~6.1k tokens); restore: repowise expand a1b2c3d4e5f6]`. The omitted content is fully preserved — run `repowise expand <ref>` to retrieve it, or `repowise expand <ref> -q <regex>` for just the matching lines.+- Prefer `repowise distill <cmd>` for noisy commands: test runs, builds, `git status`/`log`/`diff`, searches, file listings. It runs the command unchanged (exit code preserved) and prints a compact, errors-first rendering; every error line survives.+- Output may contain a marker like `[repowise#a1b2c3d4e5f6: 230 lines omitted (~6.1k tokens); restore: repowise expand a1b2c3d4e5f6]`. The omitted content is fully preserved: run `repowise expand <ref>` to retrieve it, or `repowise expand <ref> -q <regex>` for just the matching lines.- Never re-run a command to see omitted output; expand the marker instead.-- For structure-level questions about a large indexed file ("what's in here", "which function handles X"), `get_context(["path"], include=["skeleton"])` returns the file with bodies elided — every signature plus the bodies of the most central symbols — at a fraction of the cost of a full Read."""+- For structure-level questions about a large indexed file ("what's in here", "which function handles X"), `get_context(["path"], include=["skeleton"])` returns the file with bodies elided (every signature plus the bodies of the most central symbols) at a fraction of the cost of a full Read."""diff --git a/packages/core/src/repowise/core/generation/templates/_editor_block.j2 b/packages/core/src/repowise/core/generation/templates/_editor_block.j2index 0cda56ee6..3f93a1ab2 100644--- a/packages/core/src/repowise/core/generation/templates/_editor_block.j2+++ b/packages/core/src/repowise/core/generation/templates/_editor_block.j2@@ -16,7 +16,7 @@ Scope: {{ data.scope_gaps | join(' · ') }}. Missing evidence is not a negative### Key modules{% for mod in data.key_modules %}-- `{{ mod.name }}`{% if mod.purpose %} — {{ mod.purpose }}{% endif %}+- `{{ mod.name }}`{% if mod.purpose %}: {{ mod.purpose }}{% endif %}{% endfor %}{% endif %}@@ -29,9 +29,9 @@ Scope: {{ data.scope_gaps | join(' · ') }}. Missing evidence is not a negative{% endif %}{% if 'hotspots' in s and data.hotspots %}-### Files that need care (bug-fix history first, then churn — check `get_risk` before editing)+### Files that need care (bug-fix history first, then churn; check `get_risk` before editing){% for h in data.hotspots %}-- `{{ h.path }}` — {% if h.fix_count and h.last_fix_date %}{{ h.fix_count }} bug fix{{ 'es' if h.fix_count != 1 else '' }}, last fix {{ h.last_fix_date }}{% if h.bug_magnet %} (bug magnet){% endif %}; {% endif %}{{ h.commit_count_90d }} commits/90d+- `{{ h.path }}`: {% if h.fix_count and h.last_fix_date %}{{ h.fix_count }} bug fix{{ 'es' if h.fix_count != 1 else '' }}, last fix {{ h.last_fix_date }}{% if h.bug_magnet %} (bug magnet){% endif %}; {% endif %}{{ h.commit_count_90d }} commits/90d{% endfor %}{% endif %}{% set ch = data.code_health %}@@ -65,7 +65,7 @@ Fix first:- **Trust the index.** `verified: true` and `_meta.complete` mean the bytes were checked against the live tree, so never re-read them. Re-read only what `bounds: "approximate"` names. When `_meta.stale_warning` is set, Read the files that response served. After a batch of uncommitted edits, `repowise update --working-tree` refreshes the index. `confidence` rates the prose, not the evidence: on `low` read the top evidence row or the `candidate_files` the reply names, and run `repowise update` and ask again if `_meta.hint` says the index is behind HEAD. `index_behind: true` alone is informational.{% if data.keyless %}-- **No model on this index.** `get_answer` replies are low confidence by design, so open its top `best_guesses` / `candidate_files` rows; `search_codebase` is full-text only, so `[fts]` hits are normal.+- **No model on this index.** `get_answer` replies are low confidence by design, so open its top `best_guesses` / `candidate_files` rows; `search_codebase` is full-text only, so `[fts]` hits are normal. The user adds a model with a provider key and `{{ 'repowise update --full' if data.index_scope.get('content_provenance') == 'none' else 'repowise generate' }}`; suggest it, do not run it.{% endif %}- **A zero carries its basis.** An empty `callers`/`callees`/`used_by` comes with a `*_basis` saying how much of that language's calls the graph resolved, so read it before concluding nothing calls a symbol. On `get_answer`, `_meta.scope_hint` names the areas the answer did not touch.- **Pre-edit, not instead-of-edit.** These tools decide *which* files to read and edit. {{ read_note }}@@ -77,7 +77,7 @@ Fix first:- **Pre-edit, not instead-of-edit.** These tools decide *which* files to read and edit. {{ read_note }} Bytes marked `verified: true` need no re-read; re-read only what `bounds: "approximate"` names. An empty `callers`/`used_by` comes with a `*_basis`: read it before concluding nothing calls a symbol.{% if data.keyless %}-- **No model on this index.** `get_answer` replies are low confidence by design, so open its top `best_guesses` / `candidate_files` rows; `search_codebase` is full-text only, so `[fts]` hits are normal.+- **No model on this index.** `get_answer` replies are low confidence by design, so open its top `best_guesses` / `candidate_files` rows; `search_codebase` is full-text only, so `[fts]` hits are normal. The user adds a model with a provider key and `{{ 'repowise update --full' if data.index_scope.get('content_provenance') == 'none' else 'repowise generate' }}`; suggest it, do not run it.{% endif %}- **Noisy commands** (tests, builds, `git log`/`diff`): prefer `repowise distill <cmd>`, same exit code, errors first. Recover a `[repowise#<ref>: N lines omitted]` marker with `repowise expand <ref>` (`-q <regex>` filters); never re-run the command.- **Record a decision** you reasoned out: `repowise decision add --title T --decision D` (lands `proposed` for a person to confirm).diff --git a/packages/core/src/repowise/core/generation/templates/workspace_claude_md.j2 b/packages/core/src/repowise/core/generation/templates/workspace_claude_md.j2index 2da8855bf..466fa91be 100644--- a/packages/core/src/repowise/core/generation/templates/workspace_claude_md.j2+++ b/packages/core/src/repowise/core/generation/templates/workspace_claude_md.j2@@ -24,7 +24,7 @@{% if data.co_changes %}### Cross-Repo Co-Changes-Files that frequently change together across repos — consider reviewing both when editing either.+Files that frequently change together across repos; consider reviewing both when editing either.| Source | Target | Co-changes ||--------|--------|------------|diff --git a/packages/core/src/repowise/core/providers/embedding/registry.py b/packages/core/src/repowise/core/providers/embedding/registry.pyindex 91be91041..15406be30 100644--- a/packages/core/src/repowise/core/providers/embedding/registry.py+++ b/packages/core/src/repowise/core/providers/embedding/registry.py@@ -4,10 +4,12 @@ Mirrors the LLM provider registry pattern: lazy imports, built-in embedders,and runtime registration for community embedders.Built-in embedders:- openai → OpenAIEmbedder (text-embedding-3-small default)- gemini → GeminiEmbedder (gemini-embedding-001 default)- edenai → EdenAIEmbedder (openai/text-embedding-3-small via Eden AI's EU gateway)- mock → MockEmbedder (testing only, zero dependencies)+ openai -> OpenAIEmbedder (text-embedding-3-small default)+ gemini -> GeminiEmbedder (gemini-embedding-001 default)+ ollama -> OllamaEmbedder (embeddinggemma default, local, no key)+ openrouter -> OpenRouterEmbedder (google/gemini-embedding-001 default)+ edenai -> EdenAIEmbedder (openai/text-embedding-3-small via Eden AI's EU gateway)+ mock -> KeylessEmbedder (keyless runs and tests; no semantic signal)Custom embedder registration:from repowise.core.providers.embedding import register_embedderdiff --git a/packages/server/src/repowise/server/mcp_server/_failure_shield.py b/packages/server/src/repowise/server/mcp_server/_failure_shield.pyindex 114ba6fc9..34005cb88 100644--- a/packages/server/src/repowise/server/mcp_server/_failure_shield.py+++ b/packages/server/src/repowise/server/mcp_server/_failure_shield.py@@ -47,12 +47,12 @@ def _shape_not_indexed() -> dict[str, Any]:return {"error": "This repository has no repowise index yet.","remedy": (- "The user can build one by running 'repowise init --yes' in the "- "repo root. No API key is required: without one it renders the "- "whole wiki from the code's structure. Suggest --no-editor-setup "+ "The user can build one by running 'repowise init --yes --no-prose' "+ "in the repo root. It needs no API key and makes no model calls: "+ "the documentation is built from code. Suggest --no-editor-setup ""too if this is a scratch clone, fixture, or worktree, so init ""leaves their global MCP config pointed where it is. Indexing is "- "the user's decision — suggest it once, do not run it yourself."+ "the user's decision: suggest it once, do not run it yourself."),"guidance": ("Until an index exists, every repowise tool will return this "diff --git a/packages/server/src/repowise/server/mcp_server/_server.py b/packages/server/src/repowise/server/mcp_server/_server.pyindex 6bffbe551..47af2e4cd 100644--- a/packages/server/src/repowise/server/mcp_server/_server.py+++ b/packages/server/src/repowise/server/mcp_server/_server.py@@ -702,7 +702,8 @@ mcp = _RepowiseMCP("In workspace mode, get_architecture and get_blast_radius are also ""available. If the tools ""report that the repo has no index, tell the user to run "- "'repowise init --yes' in the repo root; it needs no API key. Suggest it, "+ "'repowise init --yes --no-prose' in the repo root; it needs no API key "+ "and makes no model calls. Suggest it, ""do not run it yourself."),lifespan=_lifespan,diff --git a/plugins/claude-code/commands/init.md b/plugins/claude-code/commands/init.mdindex d82d436c6..09649b55f 100644--- a/plugins/claude-code/commands/init.md+++ b/plugins/claude-code/commands/init.md@@ -1,6 +1,6 @@---description: Set up Repowise for this codebase. Installs if needed, asks about your preferences, and runs the indexing.-allowed-tools: Bash(repowise --version), Bash(repowise init:*), Bash(repowise status:*), Bash(git rev-parse --git-common-dir), Bash(pip install repowise), Bash(python -m pip install repowise), Read, AskUserQuestion+allowed-tools: Bash(repowise --version), Bash(repowise init:*), Bash(repowise status:*), Bash(repowise update:*), Bash(git rev-parse --git-common-dir), Bash(uv tool install repowise), Bash(pipx install repowise), Bash(pip install repowise), Bash(python -m pip install repowise), Read, AskUserQuestion---# Repowise Init@@ -13,26 +13,36 @@ Run: `repowise --version`If the command fails or is not found, ask the user:-"Repowise isn't installed yet. I can install it for you. Which do you prefer?"-- `pip install repowise` (recommended, includes every LLM provider SDK)-- "I'll install it myself"+"Repowise isn't installed yet. I can install it for you, or you can install it yourself."-If they want you to install it, run `pip install repowise`. If that fails, try `python -m pip install repowise`.+If they want you to install it, use the first installer that works:+`uv tool install repowise`, then `pipx install repowise`, then+`python -m pip install repowise`. Each one includes every LLM provider SDK.-After install, verify with `repowise --version`.+After install, verify with `repowise --version`. If the shell still says+`command not found`, the user runs `uv tool update-shell` or `pipx ensurepath`+and opens a new shell.If repowise IS found, print the version and move to Step 2.## Step 2: Check if this repo is already indexed-Check if `.repowise/` directory exists in the project root.+If the project root has no `.repowise/` directory, move to Step 3.-If it exists, tell the user:-"This repo is already indexed by Repowise. Run `/repowise:status` to check health, or `/repowise:update` to refresh. If you want to re-index from scratch, I can run `repowise init --force`."+If it has one, run `repowise status --format json` and act on what it says:-Then stop — do not continue to Step 3 unless the user asks to re-index.+- **Incomplete** (`incomplete` is set): a previous run stopped part way. Offer+ `repowise init --resume` with the flags of the original run (`--no-prose`+ for a run built from code).+- **Index only** (`upgrade_command` is set): the repo was indexed with+ `--mode fast` and has no documentation yet. Offer `repowise update --full`.+ It needs no API key: without a model it builds the documentation from code+ and backfills the full git history, reusing the index.+- **Otherwise** the index is ready: "This repo is already indexed by Repowise.+ Run `/repowise:status` to check health, or `/repowise:update` to refresh."+ Re-index from scratch with `repowise init --force` only if the user asks.-If `.repowise/` doesn't exist, move to Step 3.+Do not continue to Step 3 unless the user asks to re-index.## Step 3: Offer the mode, but do not block on it@@ -41,51 +51,54 @@ setting it up, and never stop and wait if you cannot get an answer.Tell the user:-"Repowise indexes your repo and writes a complete wiki with no API key. I'll run-`repowise init --yes` unless you'd rather pick:+"Repowise indexes your repo and builds its documentation from code with no API+key. I'll run `repowise init --yes --no-prose` unless you want to pick:-1. **Default (no key)** — full index plus a wiki rendered from your code's structure. Free, fast, nothing to configure.-2. **Model-written wiki** — everything above, but an LLM writes the wiki prose instead of rendering it from structure, which also enables decision mining. Needs a provider key (Anthropic, OpenAI, Gemini, or Ollama locally). You can start keyless and upgrade any page later with `repowise generate`.-3. **Show me the flags.**"+1. **Built from code** (default, no key): the full index, health, dead code,+ and documentation built from code. No model calls, no cost.+2. **Written by a model**: a model writes the documentation and reads+ decisions from PRs, git history and code comments. Needs a provider, and+ shows the estimated cost before any model call. You can start with option 1+ and add this later with `repowise generate`.+3. **Index only**: graph and essential git history, no documentation. For very+ large repos; `repowise update --full` adds the rest later.+4. **Show me the flags.**"If the user does not answer, or you are running unattended, take option 1.-### If Default (no key):+- **Built from code:** skip provider selection. The command is+ `repowise init --yes --no-prose`. Go to Step 3b.+- **Written by a model:** go to Step 3b, then Step 4.+- **Index only:** the command is `repowise init --yes --no-prose --mode fast`.+ Go to Step 3b.+- **Show me the flags:** print the reference below, then ask whether you+ should build the command or they will.-Skip provider selection entirely. Construct:-```-repowise init --no-prose --yes-```--Jump to Step 3b.--### If Full mode:--Move to Step 3b, then Step 4.--### If "show me flags":--Print the full flag reference:```repowise init [PATH]Core flags:- --provider NAME LLM provider: anthropic, openai, gemini, ollama, litellm+ --provider NAME LLM provider: anthropic, openai, gemini, openrouter,+ deepseek, kimi, ollama, litellm, edenai, claude_cli,+ codex_cli, opencode--model NAME Model identifier override- --prose / --no-prose Write the subsystem (concept) pages as model prose- (--prose, needs a key), or render the whole wiki from- structure with no model and no spend (--no-prose).- Every other page is structural either way.- Default: prose when a key is available.- --mode fast Quick first pass on very large repos: no wiki at all.+ --prose / --no-prose Documentation written by a model (--prose, needs a+ provider) or built from code (--no-prose: no model+ calls, whatever keys are set). Default: written by a+ model when a key is available.+ --mode fast Index only: graph and essential git, no documentation.+ 'repowise update --full' adds the rest later.Embeddings:- --embedder NAME Embedding provider: gemini, openai, openrouter, ollama,- edenai, mock (default: auto-detect)+ --embedder NAME Embedder for semantic search: gemini, openai,+ openrouter, ollama, edenai, mock (default: detected+ from keys)Cost control:--concurrency N Max parallel LLM calls (default: 10)- --test-run Limit to top 10 files by PageRank for quick validation+ --test-run Write documentation with the model for the top 10+ files only, for a quick check+ --dry-run Show the plan and cost estimate without runningExclusions:-x, --exclude PATTERN Gitignore-style exclude patterns. Repeatable.@@ -94,112 +107,102 @@ Exclusions:--skip-infra Skip infrastructure files (Dockerfile, Makefile, Terraform, shell)Git:- --commit-limit N Max commits to analyze per file (default: 500, max: 10000)+ --commit-limit N Max commits to analyze per file (default: 5000, max: 10000)--follow-renames Track files across renames (slower but more accurate history)Editor integration:- --editor-setup / Wire repowise into your editors (default), or skip it- --no-editor-setup entirely. Covers both halves: the machine-wide config- (~/.claude/settings.json, Claude Desktop's config, the- Claude Code hooks, the distill rewrite-hook offer) and- the project-local files (.mcp.json, .claude/CLAUDE.md,- .vscode/mcp.json, .vscode/extensions.json). With- --no-editor-setup only .repowise/ is touched. There is- one 'repowise' MCP entry per machine-wide config, so a- later init from another repo repoints it. See Step 3b.+ --no-editor-setup Write only .repowise/: no global MCP entry, no+ Claude Code hooks, no project files (.mcp.json,+ .claude/CLAUDE.md, .vscode/). See Step 3b.--hook / --no-hook Install the post-commit hook that runs 'repowise- update' in the background after each commit, so the- index does not go stale between sessions. Default: on.- --no-editor-setup keeps it off too, since a git hook- is a write outside .repowise/. Undo any time with- 'repowise hook uninstall'.+ update' after each commit. Default: on (off with+ --no-editor-setup). Undo with 'repowise hook uninstall'.Keys:- --save-key / Save the provider key this run authenticated with to- --no-save-key .repowise/.env (gitignored, owner-only). Default: on,- so the MCP server can answer later without the shell- that set it. Use --no-save-key in CI or on a shared- machine.+ --no-save-key Do not save the provider key to .repowise/.env+ (for CI or a shared machine)Output:- --no-claude-md Don't generate/update CLAUDE.md- -y, --yes Skip cost confirmation prompt- -v, --verbose Show per-phase internals plus debug logs (quiet by default)+ --no-claude-md Don't generate or update CLAUDE.md+ --progress json One JSON event per line on stdout, ending with a+ summary (status, mode, spend, next commands)+ -y, --yes No questions: every answer at its default, cost+ pre-approved. Add --no-prose to guarantee no spend.+ -v, --verbose Show per-phase internals plus debug logsRecovery:- --resume Resume a previously interrupted init- --force Re-index from scratch, overwriting existing .repowise/--Dry run:- --dry-run Show generation plan and cost estimate without running+ --resume Continue a run that stopped part way+ --force Re-index from scratch```-Then ask if they want you to construct a command or if they'll handle it.-## Step 3b: Is this repo a keeper?Every path reaches this step. It is about the repo, not the provider.-By default `init` registers repowise as the user's global MCP server, in-`~/.claude/settings.json` and Claude Desktop's config, and writes four-project-local files into the repo (`.mcp.json`, `.claude/CLAUDE.md`,-`.vscode/mcp.json`, `.vscode/extensions.json`). There is **one** `repowise` key-in each machine-wide config, so this repo replaces whatever repo is registered-now. That is the right default for the repo someone actually works in, and the-wrong one for a checkout that is about to disappear.+By default `init` points the global repowise MCP entry (in+`~/.claude/settings.json` and Claude Desktop's config) at this repo and writes+project files into it (`.mcp.json`, `.claude/CLAUDE.md`, `AGENTS.md`,+`.vscode/mcp.json`). There is **one** global `repowise` entry, so this repo+replaces whatever repo it points at now. With `--yes`, init moves it and prints+the old and new target. That is the right default for the repo someone+actually works in, and the wrong one for a checkout that is about to disappear.Add `--no-editor-setup` when either of these holds:- the path is a scratch clone, a fixture, a sample, a vendored copy, or sitsunder a temp directory-- it is a linked git worktree rather than the main checkout. Check with+- it is a linked git worktree, not the main checkout. Check with`git rev-parse --git-common-dir`: a value other than `.git` means a worktreeAlso add it if the user says they don't want their editor or MCP setup touched.-Do **not** infer that from "just index it" or "don't ask me questions" — those+Do **not** infer that from "just index it" or "don't ask me questions": thoseare about prompts, not config.-The index and the wiki are identical either way. What the flag skips is both-the machine-wide registration and the four project-local files, so with it only-`.repowise/` is touched. (`.repowise/mcp.json` is still written: it is what-`repowise mcp .` prints, and it is how you opt back in.) Either half can be-done later by re-running `repowise init` in that repo without the flag.+The index and the documentation are identical either way. With the flag only+`.repowise/` is written. Re-running `repowise init` in that repo without the+flag wires it up later.-Whichever you pick, say which in one line so the user can correct you.+Whichever you pick, say which in one line so the user can correct you. If+`init` prints the old and new target of the global entry, relay it: the user+may want it pointed back.-If `init` prints "Replacing the existing repowise MCP …", relay it. The global-entry just moved to this repo, and the user may want it pointed back.+Then continue to Step 4 for documentation written by a model, or Step 5+otherwise.-Then continue to Step 4 for the model-written wiki, or Step 5 otherwise.+## Step 4: Provider selection (written by a model only)-## Step 4: Provider selection (model-written wiki only)--**Skip this entire step unless the user chose the model-written wiki.** A-missing key is not a blocker: `init` renders the template wiki and exits 0-without one. If the user has no key, do not stop and do not ask again. Run-`repowise init --yes` and tell the user their wiki is rendered from structure-and can be upgraded per-page later with `repowise generate`.+**Skip this entire step unless the user chose documentation written by a+model.** A missing key is not a blocker. If the user has no key, do not stop and+do not ask again: run `repowise init --yes --no-prose` and tell the user they can+add a model later with `repowise generate`.Do not read, test or print the user's environment variables or key values-yourself. `repowise init` picks up a provider key from the environment on its-own, so a user who already has one set needs no `--provider`. Ask:+yourself. `repowise init` picks up a provider key from the environment and+`.repowise/.env` on its own, so a user who already has one set needs no+`--provider`. Ask:"Which LLM provider do you want to use?"-- **Anthropic** (Claude) — needs `ANTHROPIC_API_KEY`-- **OpenAI** (GPT-4o or compatible) — needs `OPENAI_API_KEY`-- **Google Gemini** (recommended for cost efficiency) — needs `GEMINI_API_KEY` or `GOOGLE_API_KEY`-- **Ollama** (fully local, no API key, slower) — needs Ollama running locally-- **LiteLLM** (100+ providers) — needs LiteLLM config--If they have not set that key yet, ask them to set it in their own shell. Show the exact export command:+- **Google Gemini** (good cost efficiency): needs `GEMINI_API_KEY` or `GOOGLE_API_KEY`+- **Anthropic** (Claude): needs `ANTHROPIC_API_KEY`+- **OpenAI**: needs `OPENAI_API_KEY`+- **OpenRouter, DeepSeek, Kimi, Eden AI**: need their own key+- **Ollama** (fully local, no API key, slower): needs Ollama running+- **LiteLLM** (100+ providers): needs LiteLLM config+- **Claude Code, Codex or OpenCode login** (`claude_cli`, `codex_cli`,+ `opencode`): uses the user's plan quota, or is billed per token when the+ CLI is signed in with an API key, and takes longer. `init` reads each CLI's+ auth status and uses one only with `--provider`. A Codex signed in through+ ChatGPT is listed in the picker but not offered.++The user sets a key in their own shell or in `.repowise/.env` (gitignored).+Never ask for a key in the chat. Show the export line for their provider:```bash-export ANTHROPIC_API_KEY="sk-ant-..."+export GEMINI_API_KEY="..."```-Every provider SDK (anthropic, openai, google-genai, litellm) ships with `repowise`-itself, so there is no per-provider package to install. If a provider import fails,-the install is broken rather than incomplete: reinstall with-`pip install --force-reinstall repowise` and run `repowise doctor`.+Every provider SDK ships with `repowise` itself, so there is no per-provider+package to install. If a provider import fails, the install is broken:+reinstall repowise with the same installer and run `repowise doctor`.## Step 5: Exclusions@@ -211,33 +214,53 @@ Add any exclusions as `-x` flags.## Step 6: Run it-For an unattended or non-interactive run, the canonical command is-`repowise init --yes`, plus `--no-prose` when you want to guarantee no spend.-`--yes` suppresses every prompt including the cost gate. You do not need to guard-against prompts beyond that: init treats an unanswerable question as a signal to-continue with defaults rather than a reason to fail, and the cost gate declines-by itself when stdin is not a terminal, keeping the finished index and landing on-the structural wiki.+The unattended command is `repowise init --yes --no-prose`. `--yes` answers+every prompt with its default and pre-approves the cost; `--no-prose` makes sure+nothing is spent. Without `--no-prose`, `--yes` uses a model whenever a key is+set; a logged-in agent CLI only with `--provider`. In a folder that holds+several repos, `--yes` indexes all of them; `--repos a,b` picks some. A model run passes `--yes` only after the user approved the estimate+(`repowise init --dry-run` prints it).Show the user the exact command you're about to run. Ask for confirmation.-Run it. For full mode, note: "This will take a while for the initial indexing. You can Ctrl+C safely — run `/repowise:init` again and I'll use `--resume` to continue where you left off."+Run it in the background. A small repo takes under a minute; a few thousand+files can take several minutes, longer than many tool timeouts. Wait for the+process to exit instead of relying on a fixed timeout, then read its exit code:++- `0`: ready.+- `2`: finished with gaps. Everything is saved; the last line names what is+ missing and the command that adds it.+- `130`: interrupted. `repowise init --resume` (same flags) continues it.+- anything else: failed. Run `repowise doctor`.++With `--progress json`, init writes one JSON event per line to stdout and ends+on a summary line with the status, mode, spend and next commands.++`repowise status` reports a first run as incomplete until it exits, so read it+after the process ends. Ctrl+C is safe at any point: running `/repowise:init` again+resumes with `--resume`.## Step 7: Post-setup-After init completes successfully:+After init exits with `0` or `2`:-1. Confirm the `.repowise/` directory was created-2. Run `repowise status` to show the summary-3. Tell the user:- - "Repowise has indexed your codebase. The MCP tools are now active — I can answer questions about your architecture, ownership, dependencies, and more."+1. Run `repowise status` to show the summary.+2. Tell the user:+ - "Run `repowise serve` to open the dashboard. It needs Node.js 20+, and the+ first run downloads the UI. It starts on port 3000, or the next free port."+ - "The MCP tools appear after you restart your agent, or run `/mcp` in+ Claude Code. They are not active in this session yet."**Only if you did not pass `--no-editor-setup`.** With that flag nothing was- registered and nothing was written into the repo outside `.repowise/`, so- say instead: "The index is built. I did not register it as your global MCP- server and wrote no editor files into the repo (this looked like a- temporary checkout). The repowise plugin's tools still work here; to wire- it up properly, re-run `repowise init` without `--no-editor-setup`."- - "Try asking me something like 'how does the auth module work?' or 'what depends on utils.py?'"- - "Run `/repowise:status` anytime to check the health of your index."- - "Run `/repowise:update` after making code changes to keep the wiki in sync."+ registered and no editor files were written, so say instead: "The index is+ built. I did not register it as your global MCP server and wrote no editor+ files into the repo (this looked like a temporary checkout). To wire it up,+ re-run `repowise init` without `--no-editor-setup`."+ - "After the restart, try asking me 'give me a tour of this codebase' or+ 'what depends on utils.py?'"+ - "Run `/repowise:status` anytime to check the index, and `/repowise:update`+ after code changes to keep it in sync."+3. If the documentation was built from code, add one line: "`repowise generate`+ has a model write the documentation and read decisions from PRs and+ history, with a cost estimate first." For an Index only run, name+ `repowise update --full` instead.4. If CLAUDE.md was generated (default): "I've also generated a CLAUDE.md with codebase context that I'll read on every session."diff --git a/plugins/claude-code/commands/reindex.md b/plugins/claude-code/commands/reindex.mdindex be7c3fb72..809acfe9d 100644--- a/plugins/claude-code/commands/reindex.md+++ b/plugins/claude-code/commands/reindex.md@@ -1,5 +1,5 @@----description: Rebuild the Repowise vector store by re-embedding all wiki pages. No LLM calls — only embedding API calls.+description: Rebuild the Repowise vector store by re-embedding all documentation pages. No LLM calls, only embedding API calls.allowed-tools: Bash(repowise reindex:*), Read, AskUserQuestion---@@ -8,27 +8,28 @@ allowed-tools: Bash(repowise reindex:*), Read, AskUserQuestionRebuild the vector store (embeddings) without regenerating documentation.This is useful when:+- You want semantic search on an index built without an embedder key- You switched embedding providers- The LanceDB vector data got corrupted-- You want to refresh search quality after adding new wiki pages## Steps1. Check if `.repowise/` exists. If not: "This repo isn't indexed yet. Run `/repowise:init` first."-2. Run: `repowise reindex`+2. Run: `repowise reindex`, or `repowise reindex --embedder <name>` when the user named one.- This re-embeds all existing wiki pages into LanceDB. No LLM generation calls — only embedding API calls. Fast and cheap.+ This re-embeds all existing documentation pages into LanceDB. No LLM generation calls, only embedding API calls.## Available flags-- `--embedder gemini|openai|openrouter|ollama|edenai|auto` — embedding provider (default: auto-detect from env vars)-- `--batch-size N` — pages per embedding batch, must be 1 or greater (default: 32)+- `--embedder gemini|openai|openrouter|ollama|edenai|mock|auto`: embedding provider. `auto` (the default) keeps the repo's embedder, or picks one from the keys present when the repo has none yet+- `--batch-size N`: pages per embedding batch, must be 1 or greater (default: 32)## Requirements-Requires a key for one of the real embedders — `GEMINI_API_KEY`/`GOOGLE_API_KEY`, `OPENAI_API_KEY`, `OPENROUTER_API_KEY` or `EDENAI_API_KEY` — or a running Ollama. The mock embedder is not accepted for reindexing. If none is available, ask the user to set one before proceeding.+Semantic search needs a real embedder: a key for `gemini` (`GEMINI_API_KEY`/`GOOGLE_API_KEY`), `openai`, `openrouter` or `edenai`, or a local Ollama with `OLLAMA_EMBEDDING_MODEL` set. When none is available, `repowise reindex` exits 1 and prints the command that turns semantic search on; relay it and ask the user to set the key themselves, never in the chat. On an Index only repo there is no documentation to embed yet: `repowise update --full` builds it first.## Handling $ARGUMENTS-If $ARGUMENTS contains "full" or "from-scratch", confirm with the user: "This will regenerate ALL documentation from scratch, not just re-embed. It will take as long as the initial indexing and cost API tokens. Are you sure?" If yes: `repowise init --force`+- An embedder name (`gemini`, `openai`, `ollama`, ...): run `repowise reindex --embedder <name>`.+- "full" or "from-scratch": reindex already re-embeds every page. To rebuild the documentation itself, suggest `repowise generate` (a model writes it, with a cost estimate first), or `repowise update --full` on an Index only repo (no key needed).diff --git a/plugins/claude-code/commands/search.md b/plugins/claude-code/commands/search.mdindex 8a5cdfd7d..e09d4c0a5 100644--- a/plugins/claude-code/commands/search.md+++ b/plugins/claude-code/commands/search.md@@ -20,12 +20,12 @@ repowise search "$ARGUMENTS"The default mode is `fulltext` (SQLite FTS5). You can specify a mode:-- `--mode fulltext` — fast keyword search (default)-- `--mode semantic` — vector similarity search using embeddings. Requires an embedding provider to be configured. If this fails with an error, suggest running `/repowise:reindex` first.-- `--mode symbol` — fuzzy match on symbol names (functions, classes, variables)+- `--mode fulltext`: fast keyword search (default)+- `--mode semantic`: vector similarity search using embeddings. Requires an embedding provider to be configured. If this fails with an error, suggest running `/repowise:reindex` first.+- `--mode symbol`: fuzzy match on symbol names (functions, classes, variables)Other flags:-- `--limit N` — max results (default: 10)+- `--limit N`: max results (default: 10)## Present results@@ -33,14 +33,16 @@ Show results as a clean list with the page title, type, and a brief snippet.## When search comes up empty-Search needs wiki pages, and every indexed repo has them: a keyless run renders-the whole wiki from structure. So an empty result is usually not a missing wiki.--- **No pages at all** means the index never finished, or the repo was indexed- with `--mode fast`, which is the one mode that writes no wiki. Suggest- `repowise init --yes` (no API key needed), or `repowise init --resume` if a- previous run was interrupted.-- **Pages exist but semantic search finds nothing** means the wiki was embedded- with the mock embedder, which keeps full-text search working and leaves- semantic search to be built later. Suggest `repowise reindex` with an embedder- configured. Full-text and symbol search (`--mode symbol`) work regardless.+Search reads the documentation pages, and an index built from code has them+too, so an empty result is usually not missing documentation.++- **No pages at all** means the index never finished, or the repo is Index+ only (`--mode fast`), the one mode with no documentation. Suggest+ `repowise update --full` (no API key needed), or `repowise init --resume` if+ a previous run was interrupted.+- **Pages exist but semantic search finds nothing** means the pages were+ embedded with the keyless `mock` embedder, which keeps full-text search+ working and leaves semantic search off. Suggest+ `repowise reindex --embedder <name>` once an embedder key is set (the user+ sets it, never in the chat). Full-text and symbol search (`--mode symbol`)+ work regardless.diff --git a/plugins/claude-code/commands/update.md b/plugins/claude-code/commands/update.mdindex 079a3be7c..84867eb31 100644--- a/plugins/claude-code/commands/update.md+++ b/plugins/claude-code/commands/update.md@@ -16,7 +16,7 @@ Trigger an incremental update of the Repowise index.This will:- Detect files changed since last sync commit- Update git metadata for changed files- - Regenerate affected wiki pages (up to cascade budget of 30)+ - Regenerate affected documentation pages (the cascade budget scales with the change)- Decay confidence scores for indirectly affected pages- Update dead code analysis- Update CLAUDE.md if enabled@@ -25,17 +25,19 @@ Trigger an incremental update of the Repowise index.## Available flags-- `--provider NAME` — override the LLM provider-- `--model NAME` — override the model-- `--since REF` — base git ref to diff from (overrides saved last_sync_commit). Accepts a commit SHA, tag, or branch name.-- `--cascade-budget N` — max pages to regenerate per run (default: 30)-- `--dry-run` — show affected pages without regenerating-- `-v, --verbose` — show the full changed-file list, per-phase internals, and debug logs (the run is quiet by default)+- `--full`: upgrade the index. On an Index only repo (`init --mode fast`) it backfills the full git history and builds the documentation: from code with no key, or written by a model when one is configured. On a repo built from code, a configured model writes the documentation. A model run shows the cost first; `--yes` accepts it.+- `--provider NAME`: override the LLM provider+- `--model NAME`: override the model+- `--since REF`: base git ref to diff from (overrides saved last_sync_commit). Accepts a commit SHA, tag, or branch name.+- `--cascade-budget N`: max pages to regenerate per run (auto-scaled when unset)+- `--working-tree`: also index uncommitted work+- `--dry-run`: show affected pages without regenerating+- `-v, --verbose`: show the full changed-file list, per-phase internals, and debug logs (the run is quiet by default)## Handling $ARGUMENTSIf the user provides arguments:-- "dry-run" or "dry run" → add `--dry-run` flag-- "force" or "full" → add `--cascade-budget 999` to regenerate all stale pages-- a git ref like a SHA or tag → add `--since {ref}`-- a file path → this is not supported by update; suggest `repowise update` which auto-detects changes+- "dry-run" or "dry run": add `--dry-run`+- "full" or "force": run `repowise update --full`. If a model is configured, ask the user before adding `--yes`, which accepts the cost estimate.+- a git ref like a SHA or tag: add `--since {ref}`+- a file path: update does not take one; suggest `repowise update`, which detects changes itselfdiff --git a/plugins/shared/commands/init.md b/plugins/shared/commands/init.mdindex ff674335c..16fe40a03 100644--- a/plugins/shared/commands/init.md+++ b/plugins/shared/commands/init.md@@ -1,7 +1,7 @@---frontmatter: |description: Set up Repowise for this codebase. Installs if needed, asks about your preferences, and runs the indexing.- allowed-tools: Bash(repowise --version), Bash(repowise init:*), Bash(repowise status:*), Bash(git rev-parse --git-common-dir), Bash(pip install repowise), Bash(python -m pip install repowise), Read, AskUserQuestion+ allowed-tools: Bash(repowise --version), Bash(repowise init:*), Bash(repowise status:*), Bash(repowise update:*), Bash(git rev-parse --git-common-dir), Bash(uv tool install repowise), Bash(pipx install repowise), Bash(pip install repowise), Bash(python -m pip install repowise), Read, AskUserQuestion---# Repowise Init@@ -14,26 +14,36 @@ Run: `repowise --version`If the command fails or is not found, ask the user:-"Repowise isn't installed yet. I can install it for you. Which do you prefer?"-- `pip install repowise` (recommended, includes every LLM provider SDK)-- "I'll install it myself"+"Repowise isn't installed yet. I can install it for you, or you can install it yourself."-If they want you to install it, run `pip install repowise`. If that fails, try `python -m pip install repowise`.+If they want you to install it, use the first installer that works:+`uv tool install repowise`, then `pipx install repowise`, then+`python -m pip install repowise`. Each one includes every LLM provider SDK.-After install, verify with `repowise --version`.+After install, verify with `repowise --version`. If the shell still says+`command not found`, the user runs `uv tool update-shell` or `pipx ensurepath`+and opens a new shell.If repowise IS found, print the version and move to Step 2.## Step 2: Check if this repo is already indexed-Check if `.repowise/` directory exists in the project root.+If the project root has no `.repowise/` directory, move to Step 3.-If it exists, tell the user:-"This repo is already indexed by Repowise. Run `{{cmd:status}}` to check health, or `{{cmd:update}}` to refresh. If you want to re-index from scratch, I can run `repowise init --force`."+If it has one, run `repowise status --format json` and act on what it says:-Then stop — do not continue to Step 3 unless the user asks to re-index.+- **Incomplete** (`incomplete` is set): a previous run stopped part way. Offer+ `repowise init --resume` with the flags of the original run (`--no-prose`+ for a run built from code).+- **Index only** (`upgrade_command` is set): the repo was indexed with+ `--mode fast` and has no documentation yet. Offer `repowise update --full`.+ It needs no API key: without a model it builds the documentation from code+ and backfills the full git history, reusing the index.+- **Otherwise** the index is ready: "This repo is already indexed by Repowise.+ Run `{{cmd:status}}` to check health, or `{{cmd:update}}` to refresh."+ Re-index from scratch with `repowise init --force` only if the user asks.-If `.repowise/` doesn't exist, move to Step 3.+Do not continue to Step 3 unless the user asks to re-index.## Step 3: Offer the mode, but do not block on it@@ -42,51 +52,54 @@ setting it up, and never stop and wait if you cannot get an answer.Tell the user:-"Repowise indexes your repo and writes a complete wiki with no API key. I'll run-`repowise init --yes` unless you'd rather pick:+"Repowise indexes your repo and builds its documentation from code with no API+key. I'll run `repowise init --yes --no-prose` unless you want to pick:-1. **Default (no key)** — full index plus a wiki rendered from your code's structure. Free, fast, nothing to configure.-2. **Model-written wiki** — everything above, but an LLM writes the wiki prose instead of rendering it from structure, which also enables decision mining. Needs a provider key (Anthropic, OpenAI, Gemini, or Ollama locally). You can start keyless and upgrade any page later with `repowise generate`.-3. **Show me the flags.**"+1. **Built from code** (default, no key): the full index, health, dead code,+ and documentation built from code. No model calls, no cost.+2. **Written by a model**: a model writes the documentation and reads+ decisions from PRs, git history and code comments. Needs a provider, and+ shows the estimated cost before any model call. You can start with option 1+ and add this later with `repowise generate`.+3. **Index only**: graph and essential git history, no documentation. For very+ large repos; `repowise update --full` adds the rest later.+4. **Show me the flags.**"If the user does not answer, or you are running unattended, take option 1.-### If Default (no key):+- **Built from code:** skip provider selection. The command is+ `repowise init --yes --no-prose`. Go to Step 3b.+- **Written by a model:** go to Step 3b, then Step 4.+- **Index only:** the command is `repowise init --yes --no-prose --mode fast`.+ Go to Step 3b.+- **Show me the flags:** print the reference below, then ask whether you+ should build the command or they will.-Skip provider selection entirely. Construct:-```-repowise init --no-prose --yes-```--Jump to Step 3b.--### If Full mode:--Move to Step 3b, then Step 4.--### If "show me flags":--Print the full flag reference:```repowise init [PATH]Core flags:- --provider NAME LLM provider: anthropic, openai, gemini, ollama, litellm+ --provider NAME LLM provider: anthropic, openai, gemini, openrouter,+ deepseek, kimi, ollama, litellm, edenai, claude_cli,+ codex_cli, opencode--model NAME Model identifier override- --prose / --no-prose Write the subsystem (concept) pages as model prose- (--prose, needs a key), or render the whole wiki from- structure with no model and no spend (--no-prose).- Every other page is structural either way.- Default: prose when a key is available.- --mode fast Quick first pass on very large repos: no wiki at all.+ --prose / --no-prose Documentation written by a model (--prose, needs a+ provider) or built from code (--no-prose: no model+ calls, whatever keys are set). Default: written by a+ model when a key is available.+ --mode fast Index only: graph and essential git, no documentation.+ 'repowise update --full' adds the rest later.Embeddings:- --embedder NAME Embedding provider: gemini, openai, openrouter, ollama,- edenai, mock (default: auto-detect)+ --embedder NAME Embedder for semantic search: gemini, openai,+ openrouter, ollama, edenai, mock (default: detected+ from keys)Cost control:--concurrency N Max parallel LLM calls (default: 10)- --test-run Limit to top 10 files by PageRank for quick validation+ --test-run Write documentation with the model for the top 10+ files only, for a quick check+ --dry-run Show the plan and cost estimate without runningExclusions:-x, --exclude PATTERN Gitignore-style exclude patterns. Repeatable.@@ -95,112 +108,102 @@ Exclusions:--skip-infra Skip infrastructure files (Dockerfile, Makefile, Terraform, shell)Git:- --commit-limit N Max commits to analyze per file (default: 500, max: 10000)+ --commit-limit N Max commits to analyze per file (default: 5000, max: 10000)--follow-renames Track files across renames (slower but more accurate history)Editor integration:- --editor-setup / Wire repowise into your editors (default), or skip it- --no-editor-setup entirely. Covers both halves: the machine-wide config- (~/.claude/settings.json, Claude Desktop's config, the- Claude Code hooks, the distill rewrite-hook offer) and- the project-local files (.mcp.json, .claude/CLAUDE.md,- .vscode/mcp.json, .vscode/extensions.json). With- --no-editor-setup only .repowise/ is touched. There is- one 'repowise' MCP entry per machine-wide config, so a- later init from another repo repoints it. See Step 3b.+ --no-editor-setup Write only .repowise/: no global MCP entry, no+ Claude Code hooks, no project files (.mcp.json,+ .claude/CLAUDE.md, .vscode/). See Step 3b.--hook / --no-hook Install the post-commit hook that runs 'repowise- update' in the background after each commit, so the- index does not go stale between sessions. Default: on.- --no-editor-setup keeps it off too, since a git hook- is a write outside .repowise/. Undo any time with- 'repowise hook uninstall'.+ update' after each commit. Default: on (off with+ --no-editor-setup). Undo with 'repowise hook uninstall'.Keys:- --save-key / Save the provider key this run authenticated with to- --no-save-key .repowise/.env (gitignored, owner-only). Default: on,- so the MCP server can answer later without the shell- that set it. Use --no-save-key in CI or on a shared- machine.+ --no-save-key Do not save the provider key to .repowise/.env+ (for CI or a shared machine)Output:- --no-claude-md Don't generate/update CLAUDE.md- -y, --yes Skip cost confirmation prompt- -v, --verbose Show per-phase internals plus debug logs (quiet by default)+ --no-claude-md Don't generate or update CLAUDE.md+ --progress json One JSON event per line on stdout, ending with a+ summary (status, mode, spend, next commands)+ -y, --yes No questions: every answer at its default, cost+ pre-approved. Add --no-prose to guarantee no spend.+ -v, --verbose Show per-phase internals plus debug logsRecovery:- --resume Resume a previously interrupted init- --force Re-index from scratch, overwriting existing .repowise/--Dry run:- --dry-run Show generation plan and cost estimate without running+ --resume Continue a run that stopped part way+ --force Re-index from scratch```-Then ask if they want you to construct a command or if they'll handle it.-## Step 3b: Is this repo a keeper?Every path reaches this step. It is about the repo, not the provider.-By default `init` registers repowise as the user's global MCP server, in-`~/.claude/settings.json` and Claude Desktop's config, and writes four-project-local files into the repo (`.mcp.json`, `.claude/CLAUDE.md`,-`.vscode/mcp.json`, `.vscode/extensions.json`). There is **one** `repowise` key-in each machine-wide config, so this repo replaces whatever repo is registered-now. That is the right default for the repo someone actually works in, and the-wrong one for a checkout that is about to disappear.+By default `init` points the global repowise MCP entry (in+`~/.claude/settings.json` and Claude Desktop's config) at this repo and writes+project files into it (`.mcp.json`, `.claude/CLAUDE.md`, `AGENTS.md`,+`.vscode/mcp.json`). There is **one** global `repowise` entry, so this repo+replaces whatever repo it points at now. With `--yes`, init moves it and prints+the old and new target. That is the right default for the repo someone+actually works in, and the wrong one for a checkout that is about to disappear.Add `--no-editor-setup` when either of these holds:- the path is a scratch clone, a fixture, a sample, a vendored copy, or sitsunder a temp directory-- it is a linked git worktree rather than the main checkout. Check with+- it is a linked git worktree, not the main checkout. Check with`git rev-parse --git-common-dir`: a value other than `.git` means a worktreeAlso add it if the user says they don't want their editor or MCP setup touched.-Do **not** infer that from "just index it" or "don't ask me questions" — those+Do **not** infer that from "just index it" or "don't ask me questions": thoseare about prompts, not config.-The index and the wiki are identical either way. What the flag skips is both-the machine-wide registration and the four project-local files, so with it only-`.repowise/` is touched. (`.repowise/mcp.json` is still written: it is what-`repowise mcp .` prints, and it is how you opt back in.) Either half can be-done later by re-running `repowise init` in that repo without the flag.+The index and the documentation are identical either way. With the flag only+`.repowise/` is written. Re-running `repowise init` in that repo without the+flag wires it up later.-Whichever you pick, say which in one line so the user can correct you.+Whichever you pick, say which in one line so the user can correct you. If+`init` prints the old and new target of the global entry, relay it: the user+may want it pointed back.-If `init` prints "Replacing the existing repowise MCP …", relay it. The global-entry just moved to this repo, and the user may want it pointed back.+Then continue to Step 4 for documentation written by a model, or Step 5+otherwise.-Then continue to Step 4 for the model-written wiki, or Step 5 otherwise.+## Step 4: Provider selection (written by a model only)-## Step 4: Provider selection (model-written wiki only)--**Skip this entire step unless the user chose the model-written wiki.** A-missing key is not a blocker: `init` renders the template wiki and exits 0-without one. If the user has no key, do not stop and do not ask again. Run-`repowise init --yes` and tell the user their wiki is rendered from structure-and can be upgraded per-page later with `repowise generate`.+**Skip this entire step unless the user chose documentation written by a+model.** A missing key is not a blocker. If the user has no key, do not stop and+do not ask again: run `repowise init --yes --no-prose` and tell the user they can+add a model later with `repowise generate`.Do not read, test or print the user's environment variables or key values-yourself. `repowise init` picks up a provider key from the environment on its-own, so a user who already has one set needs no `--provider`. Ask:+yourself. `repowise init` picks up a provider key from the environment and+`.repowise/.env` on its own, so a user who already has one set needs no+`--provider`. Ask:"Which LLM provider do you want to use?"-- **Anthropic** (Claude) — needs `ANTHROPIC_API_KEY`-- **OpenAI** (GPT-4o or compatible) — needs `OPENAI_API_KEY`-- **Google Gemini** (recommended for cost efficiency) — needs `GEMINI_API_KEY` or `GOOGLE_API_KEY`-- **Ollama** (fully local, no API key, slower) — needs Ollama running locally-- **LiteLLM** (100+ providers) — needs LiteLLM config--If they have not set that key yet, ask them to set it in their own shell. Show the exact export command:+- **Google Gemini** (good cost efficiency): needs `GEMINI_API_KEY` or `GOOGLE_API_KEY`+- **Anthropic** (Claude): needs `ANTHROPIC_API_KEY`+- **OpenAI**: needs `OPENAI_API_KEY`+- **OpenRouter, DeepSeek, Kimi, Eden AI**: need their own key+- **Ollama** (fully local, no API key, slower): needs Ollama running+- **LiteLLM** (100+ providers): needs LiteLLM config+- **Claude Code, Codex or OpenCode login** (`claude_cli`, `codex_cli`,+ `opencode`): uses the user's plan quota, or is billed per token when the+ CLI is signed in with an API key, and takes longer. `init` reads each CLI's+ auth status and uses one only with `--provider`. A Codex signed in through+ ChatGPT is listed in the picker but not offered.++The user sets a key in their own shell or in `.repowise/.env` (gitignored).+Never ask for a key in the chat. Show the export line for their provider:```bash-export ANTHROPIC_API_KEY="sk-ant-..."+export GEMINI_API_KEY="..."```-Every provider SDK (anthropic, openai, google-genai, litellm) ships with `repowise`-itself, so there is no per-provider package to install. If a provider import fails,-the install is broken rather than incomplete: reinstall with-`pip install --force-reinstall repowise` and run `repowise doctor`.+Every provider SDK ships with `repowise` itself, so there is no per-provider+package to install. If a provider import fails, the install is broken:+reinstall repowise with the same installer and run `repowise doctor`.## Step 5: Exclusions@@ -212,33 +215,53 @@ Add any exclusions as `-x` flags.## Step 6: Run it-For an unattended or non-interactive run, the canonical command is-`repowise init --yes`, plus `--no-prose` when you want to guarantee no spend.-`--yes` suppresses every prompt including the cost gate. You do not need to guard-against prompts beyond that: init treats an unanswerable question as a signal to-continue with defaults rather than a reason to fail, and the cost gate declines-by itself when stdin is not a terminal, keeping the finished index and landing on-the structural wiki.+The unattended command is `repowise init --yes --no-prose`. `--yes` answers+every prompt with its default and pre-approves the cost; `--no-prose` makes sure+nothing is spent. Without `--no-prose`, `--yes` uses a model whenever a key is+set; a logged-in agent CLI only with `--provider`. In a folder that holds+several repos, `--yes` indexes all of them; `--repos a,b` picks some. A model run passes `--yes` only after the user approved the estimate+(`repowise init --dry-run` prints it).Show the user the exact command you're about to run. Ask for confirmation.-Run it. For full mode, note: "This will take a while for the initial indexing. You can Ctrl+C safely — run `{{cmd:init}}` again and I'll use `--resume` to continue where you left off."+Run it in the background. A small repo takes under a minute; a few thousand+files can take several minutes, longer than many tool timeouts. Wait for the+process to exit instead of relying on a fixed timeout, then read its exit code:++- `0`: ready.+- `2`: finished with gaps. Everything is saved; the last line names what is+ missing and the command that adds it.+- `130`: interrupted. `repowise init --resume` (same flags) continues it.+- anything else: failed. Run `repowise doctor`.++With `--progress json`, init writes one JSON event per line to stdout and ends+on a summary line with the status, mode, spend and next commands.++`repowise status` reports a first run as incomplete until it exits, so read it+after the process ends. Ctrl+C is safe at any point: running `{{cmd:init}}` again+resumes with `--resume`.## Step 7: Post-setup-After init completes successfully:+After init exits with `0` or `2`:-1. Confirm the `.repowise/` directory was created-2. Run `repowise status` to show the summary-3. Tell the user:- - "Repowise has indexed your codebase. The MCP tools are now active — I can answer questions about your architecture, ownership, dependencies, and more."+1. Run `repowise status` to show the summary.+2. Tell the user:+ - "Run `repowise serve` to open the dashboard. It needs Node.js 20+, and the+ first run downloads the UI. It starts on port 3000, or the next free port."+ - "The MCP tools appear after you restart your agent, or run `/mcp` in+ Claude Code. They are not active in this session yet."**Only if you did not pass `--no-editor-setup`.** With that flag nothing was- registered and nothing was written into the repo outside `.repowise/`, so- say instead: "The index is built. I did not register it as your global MCP- server and wrote no editor files into the repo (this looked like a- temporary checkout). The repowise plugin's tools still work here; to wire- it up properly, re-run `repowise init` without `--no-editor-setup`."- - "Try asking me something like 'how does the auth module work?' or 'what depends on utils.py?'"- - "Run `{{cmd:status}}` anytime to check the health of your index."- - "Run `{{cmd:update}}` after making code changes to keep the wiki in sync."+ registered and no editor files were written, so say instead: "The index is+ built. I did not register it as your global MCP server and wrote no editor+ files into the repo (this looked like a temporary checkout). To wire it up,+ re-run `repowise init` without `--no-editor-setup`."+ - "After the restart, try asking me 'give me a tour of this codebase' or+ 'what depends on utils.py?'"+ - "Run `{{cmd:status}}` anytime to check the index, and `{{cmd:update}}`+ after code changes to keep it in sync."+3. If the documentation was built from code, add one line: "`repowise generate`+ has a model write the documentation and read decisions from PRs and+ history, with a cost estimate first." For an Index only run, name+ `repowise update --full` instead.4. If CLAUDE.md was generated (default): "I've also generated a CLAUDE.md with codebase context that I'll read on every session."diff --git a/plugins/shared/commands/reindex.md b/plugins/shared/commands/reindex.mdindex 759593126..a7be01c32 100644--- a/plugins/shared/commands/reindex.md+++ b/plugins/shared/commands/reindex.md@@ -1,6 +1,6 @@---frontmatter: |- description: Rebuild the Repowise vector store by re-embedding all wiki pages. No LLM calls — only embedding API calls.+ description: Rebuild the Repowise vector store by re-embedding all documentation pages. No LLM calls, only embedding API calls.allowed-tools: Bash(repowise reindex:*), Read, AskUserQuestion---@@ -9,27 +9,28 @@ frontmatter: |Rebuild the vector store (embeddings) without regenerating documentation.This is useful when:+- You want semantic search on an index built without an embedder key- You switched embedding providers- The LanceDB vector data got corrupted-- You want to refresh search quality after adding new wiki pages## Steps1. Check if `.repowise/` exists. If not: "This repo isn't indexed yet. Run `{{cmd:init}}` first."-2. Run: `repowise reindex`+2. Run: `repowise reindex`, or `repowise reindex --embedder <name>` when the user named one.- This re-embeds all existing wiki pages into LanceDB. No LLM generation calls — only embedding API calls. Fast and cheap.+ This re-embeds all existing documentation pages into LanceDB. No LLM generation calls, only embedding API calls.## Available flags-- `--embedder gemini|openai|openrouter|ollama|edenai|auto` — embedding provider (default: auto-detect from env vars)-- `--batch-size N` — pages per embedding batch, must be 1 or greater (default: 32)+- `--embedder gemini|openai|openrouter|ollama|edenai|mock|auto`: embedding provider. `auto` (the default) keeps the repo's embedder, or picks one from the keys present when the repo has none yet+- `--batch-size N`: pages per embedding batch, must be 1 or greater (default: 32)## Requirements-Requires a key for one of the real embedders — `GEMINI_API_KEY`/`GOOGLE_API_KEY`, `OPENAI_API_KEY`, `OPENROUTER_API_KEY` or `EDENAI_API_KEY` — or a running Ollama. The mock embedder is not accepted for reindexing. If none is available, ask the user to set one before proceeding.+Semantic search needs a real embedder: a key for `gemini` (`GEMINI_API_KEY`/`GOOGLE_API_KEY`), `openai`, `openrouter` or `edenai`, or a local Ollama with `OLLAMA_EMBEDDING_MODEL` set. When none is available, `repowise reindex` exits 1 and prints the command that turns semantic search on; relay it and ask the user to set the key themselves, never in the chat. On an Index only repo there is no documentation to embed yet: `repowise update --full` builds it first.## Handling $ARGUMENTS-If $ARGUMENTS contains "full" or "from-scratch", confirm with the user: "This will regenerate ALL documentation from scratch, not just re-embed. It will take as long as the initial indexing and cost API tokens. Are you sure?" If yes: `repowise init --force`+- An embedder name (`gemini`, `openai`, `ollama`, ...): run `repowise reindex --embedder <name>`.+- "full" or "from-scratch": reindex already re-embeds every page. To rebuild the documentation itself, suggest `repowise generate` (a model writes it, with a cost estimate first), or `repowise update --full` on an Index only repo (no key needed).diff --git a/plugins/shared/commands/search.md b/plugins/shared/commands/search.mdindex 80c6ca2b4..ddbe03a7f 100644--- a/plugins/shared/commands/search.md+++ b/plugins/shared/commands/search.md@@ -21,12 +21,12 @@ repowise search "$ARGUMENTS"The default mode is `fulltext` (SQLite FTS5). You can specify a mode:-- `--mode fulltext` — fast keyword search (default)-- `--mode semantic` — vector similarity search using embeddings. Requires an embedding provider to be configured. If this fails with an error, suggest running `{{cmd:reindex}}` first.-- `--mode symbol` — fuzzy match on symbol names (functions, classes, variables)+- `--mode fulltext`: fast keyword search (default)+- `--mode semantic`: vector similarity search using embeddings. Requires an embedding provider to be configured. If this fails with an error, suggest running `{{cmd:reindex}}` first.+- `--mode symbol`: fuzzy match on symbol names (functions, classes, variables)Other flags:-- `--limit N` — max results (default: 10)+- `--limit N`: max results (default: 10)## Present results@@ -34,14 +34,16 @@ Show results as a clean list with the page title, type, and a brief snippet.## When search comes up empty-Search needs wiki pages, and every indexed repo has them: a keyless run renders-the whole wiki from structure. So an empty result is usually not a missing wiki.--- **No pages at all** means the index never finished, or the repo was indexed- with `--mode fast`, which is the one mode that writes no wiki. Suggest- `repowise init --yes` (no API key needed), or `repowise init --resume` if a- previous run was interrupted.-- **Pages exist but semantic search finds nothing** means the wiki was embedded- with the mock embedder, which keeps full-text search working and leaves- semantic search to be built later. Suggest `repowise reindex` with an embedder- configured. Full-text and symbol search (`--mode symbol`) work regardless.+Search reads the documentation pages, and an index built from code has them+too, so an empty result is usually not missing documentation.++- **No pages at all** means the index never finished, or the repo is Index+ only (`--mode fast`), the one mode with no documentation. Suggest+ `repowise update --full` (no API key needed), or `repowise init --resume` if+ a previous run was interrupted.+- **Pages exist but semantic search finds nothing** means the pages were+ embedded with the keyless `mock` embedder, which keeps full-text search+ working and leaves semantic search off. Suggest+ `repowise reindex --embedder <name>` once an embedder key is set (the user+ sets it, never in the chat). Full-text and symbol search (`--mode symbol`)+ work regardless.diff --git a/plugins/shared/commands/update.md b/plugins/shared/commands/update.mdindex 4181bedf8..5db51c8cf 100644--- a/plugins/shared/commands/update.md+++ b/plugins/shared/commands/update.md@@ -17,7 +17,7 @@ Trigger an incremental update of the Repowise index.This will:- Detect files changed since last sync commit- Update git metadata for changed files- - Regenerate affected wiki pages (up to cascade budget of 30)+ - Regenerate affected documentation pages (the cascade budget scales with the change)- Decay confidence scores for indirectly affected pages- Update dead code analysis- Update CLAUDE.md if enabled@@ -26,17 +26,19 @@ Trigger an incremental update of the Repowise index.## Available flags-- `--provider NAME` — override the LLM provider-- `--model NAME` — override the model-- `--since REF` — base git ref to diff from (overrides saved last_sync_commit). Accepts a commit SHA, tag, or branch name.-- `--cascade-budget N` — max pages to regenerate per run (default: 30)-- `--dry-run` — show affected pages without regenerating-- `-v, --verbose` — show the full changed-file list, per-phase internals, and debug logs (the run is quiet by default)+- `--full`: upgrade the index. On an Index only repo (`init --mode fast`) it backfills the full git history and builds the documentation: from code with no key, or written by a model when one is configured. On a repo built from code, a configured model writes the documentation. A model run shows the cost first; `--yes` accepts it.+- `--provider NAME`: override the LLM provider+- `--model NAME`: override the model+- `--since REF`: base git ref to diff from (overrides saved last_sync_commit). Accepts a commit SHA, tag, or branch name.+- `--cascade-budget N`: max pages to regenerate per run (auto-scaled when unset)+- `--working-tree`: also index uncommitted work+- `--dry-run`: show affected pages without regenerating+- `-v, --verbose`: show the full changed-file list, per-phase internals, and debug logs (the run is quiet by default)## Handling $ARGUMENTSIf the user provides arguments:-- "dry-run" or "dry run" → add `--dry-run` flag-- "force" or "full" → add `--cascade-budget 999` to regenerate all stale pages-- a git ref like a SHA or tag → add `--since {ref}`-- a file path → this is not supported by update; suggest `repowise update` which auto-detects changes+- "dry-run" or "dry run": add `--dry-run`+- "full" or "force": run `repowise update --full`. If a model is configured, ask the user before adding `--yes`, which accepts the cost estimate.+- a git ref like a SHA or tag: add `--since {ref}`+- a file path: update does not take one; suggest `repowise update`, which detects changes itselfdiff --git a/scripts/gen_agent_matrix.py b/scripts/gen_agent_matrix.pyindex 084e2c28c..860f35501 100644--- a/scripts/gen_agent_matrix.py+++ b/scripts/gen_agent_matrix.py@@ -323,6 +323,10 @@ def render() -> str:"for that agent. `Indexing` is `Yes` when the agent's own CLI can run as the","LLM that writes the index, selected by its provider id (`claude_cli`, for","example). It is separate from the tier: it says nothing about the session.",+ "`init` offers a logged-in agent CLI but uses it only when you pick it or pass",+ "`--provider`. An agent CLI has no embedder, so semantic search needs an",+ "embedder key of its own: see",+ "[Embeddings](../reference/CONFIG.md#embeddings-for-semantic-search).","","`Attribution` is `Yes` when repowise can record the agent's edits as they","happen, an opt-in set by `attribution.capture` and `attribution.agents`. Every",diff --git a/tests/unit/cli/data/agent_target_baseline.json b/tests/unit/cli/data/agent_target_baseline.jsonindex da7d47bf3..77c9f1d63 100644--- a/tests/unit/cli/data/agent_target_baseline.json+++ b/tests/unit/cli/data/agent_target_baseline.json@@ -9,7 +9,7 @@"newlines": "platform"},".github/copilot-instructions.md": {- "content": "<!-- REPOWISE_DISTILL:START \u2014 Do not edit below this line. Auto-generated by Repowise. -->\n### Output Distillation\n\n- Prefer `repowise distill <cmd>` for noisy commands \u2014 test runs, builds, `git status`/`log`/`diff`, searches, file listings. It runs the command unchanged (exit code preserved) and prints a compact, errors-first rendering; every error line survives.\n- Output may contain a marker like `[repowise#a1b2c3d4e5f6: 230 lines omitted (~6.1k tokens); restore: repowise expand a1b2c3d4e5f6]`. The omitted content is fully preserved \u2014 run `repowise expand <ref>` to retrieve it, or `repowise expand <ref> -q <regex>` for just the matching lines.\n- Never re-run a command to see omitted output; expand the marker instead.\n- For structure-level questions about a large indexed file (\"what's in here\", \"which function handles X\"), `get_context([\"path\"], include=[\"skeleton\"])` returns the file with bodies elided \u2014 every signature plus the bodies of the most central symbols \u2014 at a fraction of the cost of a full Read.\n<!-- REPOWISE_DISTILL:END -->\n",+ "content": "<!-- REPOWISE_DISTILL:START \u2014 Do not edit below this line. Auto-generated by Repowise. -->\n### Output Distillation\n\n- Prefer `repowise distill <cmd>` for noisy commands: test runs, builds, `git status`/`log`/`diff`, searches, file listings. It runs the command unchanged (exit code preserved) and prints a compact, errors-first rendering; every error line survives.\n- Output may contain a marker like `[repowise#a1b2c3d4e5f6: 230 lines omitted (~6.1k tokens); restore: repowise expand a1b2c3d4e5f6]`. The omitted content is fully preserved: run `repowise expand <ref>` to retrieve it, or `repowise expand <ref> -q <regex>` for just the matching lines.\n- Never re-run a command to see omitted output; expand the marker instead.\n- For structure-level questions about a large indexed file (\"what's in here\", \"which function handles X\"), `get_context([\"path\"], include=[\"skeleton\"])` returns the file with bodies elided (every signature plus the bodies of the most central symbols) at a fraction of the cost of a full Read.\n<!-- REPOWISE_DISTILL:END -->\n","newlines": "lf"},".mcp.json": {@@ -33,7 +33,7 @@"newlines": "platform"},"AGENTS.md": {- "content": "# AGENTS.md\n\n<!-- Add your project instructions above or below the Repowise section. Repowise only updates the managed section between markers. -->\n\n<!-- REPOWISE_DISTILL:START \u2014 Do not edit below this line. Auto-generated by Repowise. -->\n### Output Distillation\n\n- Prefer `repowise distill <cmd>` for noisy commands \u2014 test runs, builds, `git status`/`log`/`diff`, searches, file listings. It runs the command unchanged (exit code preserved) and prints a compact, errors-first rendering; every error line survives.\n- Output may contain a marker like `[repowise#a1b2c3d4e5f6: 230 lines omitted (~6.1k tokens); restore: repowise expand a1b2c3d4e5f6]`. The omitted content is fully preserved \u2014 run `repowise expand <ref>` to retrieve it, or `repowise expand <ref> -q <regex>` for just the matching lines.\n- Never re-run a command to see omitted output; expand the marker instead.\n- For structure-level questions about a large indexed file (\"what's in here\", \"which function handles X\"), `get_context([\"path\"], include=[\"skeleton\"])` returns the file with bodies elided \u2014 every signature plus the bodies of the most central symbols \u2014 at a fraction of the cost of a full Read.\n<!-- REPOWISE_DISTILL:END -->\n",+ "content": "# AGENTS.md\n\n<!-- Add your project instructions above or below the Repowise section. Repowise only updates the managed section between markers. -->\n\n<!-- REPOWISE_DISTILL:START \u2014 Do not edit below this line. Auto-generated by Repowise. -->\n### Output Distillation\n\n- Prefer `repowise distill <cmd>` for noisy commands: test runs, builds, `git status`/`log`/`diff`, searches, file listings. It runs the command unchanged (exit code preserved) and prints a compact, errors-first rendering; every error line survives.\n- Output may contain a marker like `[repowise#a1b2c3d4e5f6: 230 lines omitted (~6.1k tokens); restore: repowise expand a1b2c3d4e5f6]`. The omitted content is fully preserved: run `repowise expand <ref>` to retrieve it, or `repowise expand <ref> -q <regex>` for just the matching lines.\n- Never re-run a command to see omitted output; expand the marker instead.\n- For structure-level questions about a large indexed file (\"what's in here\", \"which function handles X\"), `get_context([\"path\"], include=[\"skeleton\"])` returns the file with bodies elided (every signature plus the bodies of the most central symbols) at a fraction of the cost of a full Read.\n<!-- REPOWISE_DISTILL:END -->\n","newlines": "lf"}},diff --git a/tests/unit/generation/test_editor_file_base.py b/tests/unit/generation/test_editor_file_base.pyindex 531a79e42..0aaea24c6 100644--- a/tests/unit/generation/test_editor_file_base.py+++ b/tests/unit/generation/test_editor_file_base.py@@ -153,6 +153,12 @@ def test_keyless_index_gets_keyless_steering(any_gen):assert "[fts]` only has no semantic agreement" not in resultassert 'Cite `confidence: "high"`' not in resultassert "`degraded` means no prose; `confidence` rates the evidence" in result+ assert "provider key and `repowise generate`" in result+++def test_index_only_keyless_names_the_fast_to_full_command(any_gen):+ result = any_gen.render(_scoped({**_KEYLESS_SCOPE, "content_provenance": "none"}))+ assert "provider key and `repowise update --full`" in resultdef test_keyed_index_keeps_model_guidance(any_gen):@@ -497,7 +503,7 @@ def test_render_hotspot_row_falls_back_to_churn_without_fix_history(gen):data = dataclasses.replace(_minimal_data(), hotspots=[_hotspot("src/a.py")])result = gen.render(data)- assert "- `src/a.py` — 28 commits/90d" in result+ assert "- `src/a.py`: 28 commits/90d" in resultassert "bug fix" not in resultdiff --git a/tests/unit/generation/test_kg_claude_md_onboarding.py b/tests/unit/generation/test_kg_claude_md_onboarding.pyindex b4c76a0c4..b4c9deb06 100644--- a/tests/unit/generation/test_kg_claude_md_onboarding.py+++ b/tests/unit/generation/test_kg_claude_md_onboarding.py@@ -103,7 +103,7 @@ class TestClaudeMdKGSection:)rendered = tmpl.render(data=data)assert "### Key modules" in rendered- assert "- `src/api` — API layer" in rendered+ assert "- `src/api`: API layer" in rendered# No purpose → no dangling separator.assert "- `src/core`\n" in rendered