Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

docs: lead with interactive init, and stop printing a deprecated flag (#1075)

Raghav Chamadiya36ee6f07b091
diff --git a/README.md b/README.md
index f5818cdd1..95015063d 100644
--- a/README.md
+++ b/README.md
@@ -111,7 +111,7 @@ queryable from the CLI, the MCP tools, and the local dashboard.
| **★ Code health** | **25 deterministic markers**, 1 to 10 per file · three signals: defect risk · maintainability · performance · coverage ingestion · concrete refactoring plans (Extract Class / Helper, Move Method, Break Cycle, Split File) · **zero LLM, under 30s** | **★ Defect-validated, with the fix attached** |
**The whole wiki is generated with no LLM, then upgraded to model-written prose on
-demand.** `repowise init --index-only` builds the graph, git, decision and health
+demand.** `repowise init --no-prose` builds the graph, git, decision and health
layers and renders every wiki page from your code's structure, with no API key and
no spend. Convert any part of it to LLM-written prose whenever you want, one page,
one directory, or a ranked coverage slice at a time, and pay only for what you pick,
@@ -337,24 +337,38 @@ pip install repowise # Windows: python -m pip install repowise
repowise --version
```
-**2. Index your repo, with no LLM and no key**
+**2. Index your repo**
```bash
cd /path/to/your/repo
-repowise init --index-only -y
+repowise init
```
-That builds the dependency graph, git history, code-health scores and dead-code
-findings in seconds, and renders a complete wiki from the code's structure: file,
-module, layer and cycle pages, the architecture diagram, the repo overview, API
-and infra pages, and the onboarding collection. Every page carries a footer saying
-it was derived from structure, and the repo overview describes composition, entry
+Bare `init` asks. It scans the repo first, then offers three ways to index it:
+everything (the wiki written by a model), no prose (the same wiki rendered from
+your code's structure, no key and no spend), or advanced, which walks through the
+indexing and generation knobs. Nothing is spent before you see an estimate and
+confirm it.
+
+If you would rather not answer questions, or you are scripting this, name the
+mode and add `-y`:
+
+```bash
+repowise init --no-prose -y # free, no key, no questions
+repowise init --prose -y # model-written subsystem pages, cost pre-approved
+```
+
+Either way you get the dependency graph, git history, code-health scores and
+dead-code findings in seconds, plus a complete wiki: file, module, layer and cycle
+pages, the architecture diagram, the repo overview, API and infra pages, and the
+onboarding collection. On the keyless path every page carries a footer saying it
+was derived from structure, and the repo overview describes composition, entry
points, clusters and dependencies rather than what the project does end to end,
because no template can derive that. Full-text search works on this index;
semantic search needs an embedder configured (Ollama is the keyless option).
-Want the wiki written by a model? You do not have to decide now. Upgrade the
-index-only wiki whenever you like with `repowise generate`, a page, a directory,
+Went keyless and want the wiki written by a model later? You do not have to decide
+now. Upgrade it whenever you like with `repowise generate`, a page, a directory,
or the whole thing at a time, each behind a cost estimate:
```bash
@@ -368,7 +382,7 @@ Bare `repowise generate` prints the wiki's state and writes the unwritten
subsystem (concept) pages behind a single cost estimate. Every other page was
already rendered from structure at index time.
-Or write the whole wiki as part of the first index with `repowise init --provider
+Or pick the provider for the first index directly with `repowise init --provider
gemini|anthropic|openai`.
**3. Connect your agent.** The MCP server is `repowise mcp`, served from the repo directory.
@@ -525,8 +539,8 @@ Doing a security review? **[docs/business/SECURITY_COMPLIANCE.md →](docs/busin
## CLI
```bash
-repowise init [PATH] # index a codebase (one-time; --index-only needs no LLM)
-repowise generate [PATH] # write wiki pages with a model, on demand (upgrade an index-only wiki)
+repowise init [PATH] # index a codebase (one-time; asks, or --no-prose -y needs no LLM)
+repowise generate [PATH] # write wiki pages with a model, on demand (upgrade a keyless wiki)
repowise serve [PATH] # MCP server + local dashboard
repowise update [PATH] # incremental update (seconds; --workspace for every repo)
repowise watch # auto-sync daemon, re-index on file change
diff --git a/docs/business/COMMERCIAL.md b/docs/business/COMMERCIAL.md
index bd26ba144..ddd8ecd44 100644
--- a/docs/business/COMMERCIAL.md
+++ b/docs/business/COMMERCIAL.md
@@ -324,7 +324,7 @@ Repowise in the same network boundary — no outbound connectivity is required i
air-gapped mode.
**Indexing:** the graph, git, dead-code, and code-health layers build in minutes with
-zero LLM calls (`repowise init --index-only`); the documentation layer's one-time
+zero LLM calls (`repowise init --no-prose`); the documentation layer's one-time
wiki generation scales with repo size and can run in the background. Incremental
updates after each commit complete in under 30 seconds.
diff --git a/docs/business/SECURITY_COMPLIANCE.md b/docs/business/SECURITY_COMPLIANCE.md
index 6a5806868..a3d3d5aa3 100644
--- a/docs/business/SECURITY_COMPLIANCE.md
+++ b/docs/business/SECURITY_COMPLIANCE.md
@@ -56,7 +56,7 @@ Repowise splits cleanly into layers that need an LLM and layers that do not.
**Zero-LLM layers.** Graph, git, dead code, code health, change risk, and the
security pattern scan are pure local computation over tree-sitter and git data.
-`repowise init --index-only` builds all of them with **no outbound LLM calls at
+`repowise init --no-prose` builds all of them with **no outbound LLM calls at
all**. The health pass in particular is deterministic Python: no model, no
network.
@@ -187,7 +187,7 @@ assembled from the containers above rather than from a single bundle.
**Indexing cost profile, for capacity planning.** Graph, git, dead-code, and
code-health layers build in minutes with zero LLM calls
-(`repowise init --index-only`). One-time wiki generation scales with repo size
+(`repowise init --no-prose`). One-time wiki generation scales with repo size
and can run in the background. Incremental updates after each commit complete in
under 30 seconds.
@@ -234,7 +234,7 @@ own product and adds the layer above.
| Question | Answer |
|---|---|
-| Does our source code leave our infrastructure? | Not in the self-hosted distribution. Code is read from disk and parsed in memory. The only path that can send code-derived content out is the LLM call for documentation, chat, and decision extraction, and that goes to the provider you configured with your key. `--index-only` and offline mode remove it entirely. |
+| Does our source code leave our infrastructure? | Not in the self-hosted distribution. Code is read from disk and parsed in memory. The only path that can send code-derived content out is the LLM call for documentation, chat, and decision extraction, and that goes to the provider you configured with your key. `--no-prose` and offline mode remove it entirely. |
| Is raw source stored anywhere? | No. Raw source is processed transiently and never persisted. The index holds the graph, embeddings, wiki pages, git metadata, decisions, and health data. |
| Can the embeddings be reversed back into our code? | They are non-reversible vectors, not encrypted source. They are still derived from your code, so protect the index directory like the repo. |
| Can we run with no network access at all? | Yes. Ollama plus a local embedding model gives zero external API calls; disable telemetry and the process makes no outbound requests. In air-gapped mode the LLM provider and git server sit inside your boundary. |
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.md
index 2aaf09d02..6905337ec 100644
--- a/docs/reference/CLI_REFERENCE.md
+++ b/docs/reference/CLI_REFERENCE.md
@@ -45,7 +45,7 @@ repowise init .
1. **Ingestion**, walks every file, parses AST with tree-sitter, builds a two-tier dependency graph (file + symbol nodes), indexes git history (churn, hotspots, ownership, bus factor)
2. **Analysis**, detects dead code, extracts architectural decisions from inline markers, READMEs, and git history. Runs Leiden community detection and execution flow tracing.
-3. **Generation**, generates file-level, module-level, and repo-level wiki pages, either by prompting the LLM or, with `--index-only`, by rendering them from the parsed structure
+3. **Generation**, generates file-level, module-level, and repo-level wiki pages, either by prompting the LLM or, with `--no-prose`, by rendering them from the parsed structure
4. **Persistence**, stores everything in `.repowise/wiki.db`, builds search indexes, generates editor instruction files, registers MCP server and hooks
In workspace mode, adds: repo scanning, per-repo indexing, cross-repo analysis (co-changes, contracts, package deps), workspace CLAUDE.md generation.
@@ -107,7 +107,7 @@ repowise init # interactive
repowise init --provider anthropic --yes # automated
repowise init --provider codex_cli --codex --yes # use authenticated Codex CLI
repowise init --provider opencode --yes # use local OpenCode CLI
-repowise init --index-only # free, wiki rendered from structure
+repowise init --no-prose # free, wiki rendered from structure
repowise init --dry-run # preview cost
repowise init --test-run # quick test (10 files)
repowise init --provider openai --model qwen3 --reasoning off
@@ -117,7 +117,7 @@ repowise init -x vendor/ -x "*.gen.go" # exclude patterns
repowise init --include-submodules # include submodules
repowise init --no-codex --no-agents # skip Codex project files
repowise init . # workspace mode
-repowise init . --index-only -x "node_modules/" # workspace, no LLM
+repowise init . --no-prose -x "node_modules/" # workspace, no LLM
repowise init . --no-workspace # force single-repo, even in a workspace root
```
diff --git a/docs/scale/WORKSPACES.md b/docs/scale/WORKSPACES.md
index cafa421ac..c63371afb 100644
--- a/docs/scale/WORKSPACES.md
+++ b/docs/scale/WORKSPACES.md
@@ -68,7 +68,7 @@ Repowise will:
3. **Ask you to pick a primary repo** (the default for MCP queries)
4. **Walk you through provider setup** (LLM provider, model, cost estimate)
5. **Index each repo**, parse files, build graphs, index git history
-6. **Generate documentation** for each repo (unless `--index-only`)
+6. **Generate documentation** for each repo (unless `--no-prose`)
7. **Run cross-repo analysis**, co-changes, API contracts, package deps
8. **Register MCP servers** with Claude Desktop and Claude Code
@@ -119,7 +119,7 @@ Initialize a workspace in the current directory. Scans for git repos, prompts fo
| Flag | Description |
|------|-------------|
-| `--index-only` | Parse and analyze without LLM generation (free) |
+| `--no-prose` | Parse and analyze, wiki rendered from structure, no LLM (free) |
| `-x, --exclude` | Glob patterns to exclude (e.g., `-x "node_modules/"`) |
| `--yes` | Skip confirmation prompts |
| `--concurrency N` | Max concurrent file parses (default: auto) |
diff --git a/docs/start/DASHBOARD.md b/docs/start/DASHBOARD.md
index c54f8c487..a085c6056 100644
--- a/docs/start/DASHBOARD.md
+++ b/docs/start/DASHBOARD.md
@@ -22,7 +22,7 @@ looking at.
## Two modes, and what changes between them
Repowise can index a repo without generating a wiki (`repowise init
---index-only`, or the fast option in the setup wizard). Everything derived from
+--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:
diff --git a/docs/start/QUICKSTART.md b/docs/start/QUICKSTART.md
index 0caf86e53..08e49dc4b 100644
--- a/docs/start/QUICKSTART.md
+++ b/docs/start/QUICKSTART.md
@@ -32,18 +32,28 @@ repowise --version
```bash
cd /path/to/your-repo
-repowise init --yes
+repowise init
```
-No API key needed. If you want to be explicit that this run must not spend
-anything, spell it out:
+Bare `init` scans the repo and asks how to index it: everything (the wiki written
+by a model), no prose (the same wiki rendered from your code's structure, no key
+and no spend), or advanced, which walks through the indexing and generation knobs.
+Nothing is spent before you see an estimate and confirm it, so it is safe to run
+and read.
+
+If you would rather not answer questions, name the mode and add `--yes`. This is
+the form to use in a script, in CI, or when an agent is setting repowise up:
```bash
-repowise init --yes --no-prose
+repowise init --yes --no-prose # free, no key, no questions
+repowise init --yes --prose # model-written subsystem pages, cost pre-approved
```
-This is the step worth doing first, because it costs nothing and answers the
-question "is this useful on my codebase". It parses every file to an AST, builds
+Bare `repowise init --yes` needs no API key either: without a resolvable provider
+it renders the whole wiki from structure.
+
+The keyless run is the one worth doing first, because it costs nothing and answers
+the question "is this useful on my codebase". It parses every file to an AST, builds
the dependency graph, reads your git history, scores every file for code health,
and finds dead code. It also renders a complete wiki from that structure: file,
symbol, layer and cycle pages, the architecture diagram, the repo overview, API
diff --git a/docs/start/USER_GUIDE.md b/docs/start/USER_GUIDE.md
index f5724979b..a70836144 100644
--- a/docs/start/USER_GUIDE.md
+++ b/docs/start/USER_GUIDE.md
@@ -82,13 +82,15 @@ The failure mode to avoid is a stale index, because a confidently wrong answer i
worse than no answer. Every MCP response carries the indexed commit and warns when
it has diverged from your live `HEAD`, but the real fix is step 3.
-**Two modes, one upgrade path.** `--index-only` gives you the graph, git
+**Two modes, one upgrade path.** `--no-prose` gives you the graph, git
intelligence, code health, change risk and dead code, plus a complete wiki
rendered from the code's structure, with no LLM, no key and no network. Adding a
provider rewrites those pages as model-written prose and unlocks decision mining
and chat.
-You do not have to choose up front. Start index-only, then upgrade the wiki with
+You do not have to choose up front, and you do not have to know the flag: bare
+`repowise init` scans the repo and asks, with the keyless mode offered as one of
+the three answers. Start keyless, then upgrade the wiki with
`repowise generate` when you are ready, a page, a directory, or the whole thing
at a time, each behind a cost estimate:
@@ -137,8 +139,8 @@ Grouped by what you are trying to do. Every flag for every command lives in the
| Command | What it is for |
|---|---|
-| `repowise init` | First index. Runs keyless by default; asks for a provider only when you want model-written pages, then shows a cost estimate and waits for confirmation. `--index-only` builds the same wiki from structure, with no LLM. |
-| `repowise generate` | Write wiki pages with a model, on demand. The upgrade path for an index-only repo: `--unwritten` (default) writes everything still on a template, `--path`/`--page` writes a subset, all behind a cost estimate. |
+| `repowise init` | First index, and the one command to start with. Bare `init` scans the repo and asks how to index it: everything, no prose, or advanced (every indexing and generation knob). Nothing is spent before an estimate is shown and confirmed. `--no-prose -y` and `--prose -y` skip the questions for scripts and agents. |
+| `repowise generate` | Write wiki pages with a model, on demand. The upgrade path for a keyless repo: `--unwritten` (default) writes everything still on a template, `--path`/`--page` writes a subset, all behind a cost estimate. |
| `repowise update` | Incremental catch-up after pulling or committing. Seconds, not minutes. |
| `repowise watch` | File watcher that updates continuously while you work. |
| `repowise hook install` | Post-commit hook so syncing happens without you. |
@@ -310,8 +312,15 @@ Every view and what it answers: **[Dashboard](DASHBOARD.md)**.
```bash
pip install repowise
cd /path/to/your-project
-repowise init --index-only -y # free, no key, seconds
-repowise hook install # keep it current from here on
+repowise init # asks how to index: everything, no prose, or advanced
+repowise hook install # keep it current from here on
+```
+
+Scripting it, or running it as an agent? Name the mode and skip the questions:
+
+```bash
+repowise init --no-prose -y # free, no key, seconds
+repowise init --prose -y # model-written subsystem pages, cost pre-approved
```
Write the pages with a model when you want them, all at once or a piece at a
@@ -385,7 +394,7 @@ instead of them interrupting someone.
### In CI
```bash
-repowise init --index-only # free, no keys in CI
+repowise init --no-prose -y # free, no keys in CI, no questions
repowise risk "$BASE_SHA..$HEAD_SHA" # gate or annotate on risk
repowise export --format markdown --output ./docs/wiki/ # static hosting
```
@@ -451,7 +460,7 @@ validate on 10 files, and `--skip-tests --skip-infra` to cut scope. Lower
`repowise reindex` rebuilds it from the existing wiki pages, with no LLM calls.
**Doctor reports 0 pages**
-init failed or was interrupted. Even `--index-only` writes pages, so an empty
+init failed or was interrupted. Even `--no-prose` writes pages, so an empty
wiki means the run did not finish. Try `repowise init --resume`.
**Dashboard shows an empty repo list**
diff --git a/examples/codex/README.md b/examples/codex/README.md
index 650455ede..9f2b4d9dc 100644
--- a/examples/codex/README.md
+++ b/examples/codex/README.md
@@ -7,11 +7,11 @@ This example shows the expected Codex setup for an initialized Repowise reposito
```bash
cd /path/to/your-repo
codex login status
-repowise init --codex --index-only --yes # fast smoke: index only, no LLM wiki generation
+repowise init --codex --no-prose --yes # fast smoke: no LLM wiki prose, no key needed
repowise init --codex --provider codex_cli --yes
```
-`repowise init --codex --index-only` is the quick setup smoke path. Drop `--index-only` when you want the full LLM-generated wiki. `repowise init --codex` writes project-local Codex files:
+`repowise init --codex --no-prose` is the quick setup smoke path. Drop `--no-prose` when you want the full LLM-generated wiki, or drop `--yes` too and let `init` ask. `repowise init --codex` writes project-local Codex files:
```text
.codex/config.toml
diff --git a/website/getting-started.md b/website/getting-started.md
index 73f2c18ff..e5b54603e 100644
--- a/website/getting-started.md
+++ b/website/getting-started.md
@@ -31,14 +31,16 @@ pip install repowise # Windows: python -m pip install repowise
repowise --version # -> repowise, version 0.27.x
```
-**2. Index your repo — no LLM, no key**
+**2. Index your repo**
```bash
cd /path/to/your/repo
-repowise init --no-prose -y
+repowise init
```
-Builds the dependency graph, git history, code-health score, and dead-code findings in seconds. Also renders every wiki page from structure. Want the subsystem pages written as model prose? `repowise init --prose --provider gemini|anthropic|openai`.
+Bare `init` scans the repo and asks how to index it: everything (the wiki written by a model), no prose (the same wiki rendered from your code's structure, no key and no spend), or advanced for every knob. Nothing is spent before you see an estimate and confirm it.
+
+Scripting it instead? Name the mode and skip the questions: `repowise init --no-prose -y` for the free path, `repowise init --prose -y` for model-written subsystem pages. Either way you get the dependency graph, git history, code-health score and dead-code findings in seconds, plus every wiki page.
**3. Connect your agent** — the MCP server is `repowise mcp`, served from the repo dir.