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: add plugin slash command reference and missing environment variables (#2090)

Akshat malik0629f5ecf730
diff --git a/docs/README.md b/docs/README.md
index 4cb43ad61..70e845ef4 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -30,6 +30,7 @@ For a map of every layer and how they feed each other, read
| [start/QUICKSTART.md](start/QUICKSTART.md) | Install, index, and connect your agent |
| [agent/INTEGRATIONS.md](agent/INTEGRATIONS.md) | Which agents are supported at what depth, and how to add one |
| [agent/MCP_TOOLS.md](agent/MCP_TOOLS.md) | The ten task-shaped tools, what each answers, and the opt-in extras |
+| [agent/CLAUDE_CODE_COMMANDS.md](agent/CLAUDE_CODE_COMMANDS.md) | The 18 `/repowise:*` slash commands in the Claude Code plugin |
| [agent/HOOKS.md](agent/HOOKS.md) | Context and warnings that reach the agent without it asking |
| [agent/DISTILL.md](agent/DISTILL.md) | Compress noisy command output before your agent reads it |
| [agent/LENS.md](agent/LENS.md) | Lens in the Claude Code plugin: the spinner, change review, Flow and the `/lens` map shown while Claude works |
diff --git a/docs/agent/CLAUDE_CODE_COMMANDS.md b/docs/agent/CLAUDE_CODE_COMMANDS.md
new file mode 100644
index 000000000..baab993b9
--- /dev/null
+++ b/docs/agent/CLAUDE_CODE_COMMANDS.md
@@ -0,0 +1,62 @@
+# Claude Code Slash Commands
+
+The [Repowise Claude Code plugin](../../plugins/claude-code/README.md) ships 18
+slash commands under the `/repowise:` namespace. Install the plugin with
+`/plugin install repowise@repowise` (see the plugin README), then run
+`/repowise:init` to index the repo.
+
+## How they work
+
+- Each command is a Markdown instruction file in
+ [`plugins/claude-code/commands/`](../../plugins/claude-code/commands/). Claude
+ reads it, runs the matching `repowise` CLI command, and presents the result.
+- The file's `allowed-tools:` frontmatter scopes what Claude may run: each
+ command allows only its own CLI subcommand (for example
+ `Bash(repowise health:*)`) plus `Read`.
+- `/repowise:init` also allows the install commands (`uv tool install`,
+ `pipx install`, `pip install`) and `AskUserQuestion`, so it can install
+ repowise and ask about your setup. `/repowise:reindex` also allows
+ `AskUserQuestion`.
+- Text after the command name reaches the command as `$ARGUMENTS`:
+
+```
+/repowise:search authentication middleware
+/repowise:context src/auth/token.py
+/repowise:dead-code safe
+/repowise:risk main..HEAD
+```
+
+## Command reference
+
+| Command | What it does |
+|---------|--------------|
+| `/repowise:init` | Install repowise if needed, ask about your preferences, and index the repo |
+| `/repowise:status` | Index health: sync state, page counts, provider, token usage |
+| `/repowise:update` | Incremental update to bring the index up to recent commits |
+| `/repowise:search` | Search the wiki by natural language, full text, or symbol |
+| `/repowise:ask` | Cited answer to a codebase question with a confidence rating (one LLM call) |
+| `/repowise:context` | Triage card for files, modules, or symbols: layer, hotspot, fix history, freshness |
+| `/repowise:symbol` | One symbol's body with live-verified line bounds (`path::Name`, a line range, or a distill omission ref) |
+| `/repowise:reindex` | Re-embed every wiki page into the vector store. Embedding calls only, no LLM calls |
+| `/repowise:health` | Code health: KPIs, lowest-scoring files, refactoring targets, trends, per-file markers |
+| `/repowise:coverage` | Ingest or inspect coverage reports (LCOV, Cobertura, Clover, Go, JaCoCo, Apex, repowise JSON; a coverage.py `.coverage` file builds the per-test map), or gate a change on patch coverage |
+| `/repowise:impacted-tests` | Tests whose coverage touches a change's lines, for a commit, a `base..head` range, or the staged diff |
+| `/repowise:risk` | Rank a change against recent history: repo-relative percentile plus a supporting diff-shape score |
+| `/repowise:security` | Security signals. Working-tree scanning runs during `init` and `update`; `--history` walks the full git history for leaked secrets |
+| `/repowise:dead-code` | Unreachable files, unused exports, and zombie packages, tiered by confidence |
+| `/repowise:export` | Export the wiki or architecture model to Markdown, HTML, JSON, or Structurizr DSL |
+| `/repowise:decision` | List, inspect, add, or confirm architectural decisions |
+| `/repowise:why` | Why the code is shaped this way: decisions, rationale, git archaeology |
+| `/repowise:doctor` | Diagnose the setup (install, API keys, index and store drift) and optionally repair it |
+
+## Slash commands and MCP tools
+
+- **Slash commands** are for you: run one when you want a specific report, such
+ as dead code before a cleanup or risk before a merge.
+- **MCP tools** are for Claude: it calls them on its own while working, for
+ example `get_risk` before editing a hotspot. See [MCP_TOOLS.md](MCP_TOOLS.md).
+
+Both read the same `.repowise/` index. The command files add presentation
+rules on top of the CLI output, such as showing the confidence with every
+`/repowise:ask` answer and treating only `safe_to_delete` findings as
+deletions in `/repowise:dead-code`.
diff --git a/docs/reference/CONFIG.md b/docs/reference/CONFIG.md
index 4e3bdfde1..86d998afc 100644
--- a/docs/reference/CONFIG.md
+++ b/docs/reference/CONFIG.md
@@ -1071,6 +1071,37 @@ Anonymous usage telemetry is **on by default** (opt-out).
| `REPOWISE_FORGE_HOSTS` | `host=forge` pairs, comma separated (`git.corp.com=gitlab,tfs.corp.com=azure`); wins over `forges.hosts` |
| `REPOWISE_CHANGELOG` | Changelog source for the "what's new" check |
| `REPOWISE_PARSE_WORKERS` | Indexing parse processes: default CPU count capped at 8, never above the files to parse. Each holds about 50 MB; above 8 is not measurably faster |
+| `REPOWISE_NO_SAVE_KEY` | Truthy: `init` does not save the provider API key to `.repowise/.env`, like `init --no-save-key`. Use it where credentials are injected at runtime and must not be written to disk |
+| `REPOWISE_MCP_NO_WATCHDOG` | `1`, `true` or `yes` turns off the parent-process watchdog in `repowise mcp --transport stdio`, which exits the server when the MCP client dies abnormally (crash, force-quit, killed terminal) |
+| `REPOWISE_INDEX_INFORMATION_FLOOR` | Minimum characters of substantive prose a wiki page needs to get a vector in the search index. Pages below it stay readable and linkable, they are only left out of semantic search. Default `0` (off) |
+
+### BLAS thread pool
+
+repowise caps the BLAS thread pool to 1 before numpy loads. An uncapped pool costs about 32 MB of memory per thread (about 750 MB on a 32-core machine) and does not speed up the sparse graph work repowise runs. Spawned worker processes inherit the cap through the environment.
+
+A value you set yourself always wins:
+
+```bash
+OPENBLAS_NUM_THREADS=4 repowise init # 4 BLAS threads instead of 1
+```
+
+| Variable | Applies to | Default |
+|----------|-----------|---------|
+| `OPENBLAS_NUM_THREADS` | OpenBLAS | `1` unless set |
+| `MKL_NUM_THREADS` | Intel MKL | `1` unless set |
+| `NUMEXPR_NUM_THREADS` | NumExpr | `1` unless set |
+| `VECLIB_MAXIMUM_THREADS` | Apple Accelerate | `1` unless set |
+
+`OMP_NUM_THREADS` is not set: igraph's community detection uses OpenMP threads and is slower without them.
+
+### Cache integrity key
+
+repowise integrity-checks its on-disk caches with a machine-local key.
+
+| Variable | Description |
+|----------|-------------|
+| `REPOWISE_CACHE_HMAC_KEY` | Hex-encoded key (at least 32 hex characters, 16 bytes) used instead of the key file. For CI and tests where the home directory is ephemeral or shared |
+| `REPOWISE_CACHE_KEY_PATH` | Path to the key file. Default `$XDG_CONFIG_HOME/repowise/cache_hmac_key`, or `~/.config/repowise/cache_hmac_key` when `XDG_CONFIG_HOME` is unset |
## Exclude patterns
diff --git a/docs/scale/AUTO_SYNC.md b/docs/scale/AUTO_SYNC.md
index 8314c5392..eff27a4ea 100644
--- a/docs/scale/AUTO_SYNC.md
+++ b/docs/scale/AUTO_SYNC.md
@@ -217,6 +217,21 @@ LLM cost. `POST /api/repos/{id}/full-resync` also regenerates every page.
---
+## Concurrent updates
+
+Rapid commits through the post-commit hook and a manual `repowise update` can
+start updates at once. One update runs at a time; a second one that finds the lock held
+records its commit and exits, and the running update rolls forward to it.
+
+| File | Purpose |
+|------|---------|
+| `.repowise/.update.lock` | Held by the running update. Records its PID, a process creation token and the target commit, so a lock left by a crashed update is cleared. A workspace update uses `.repowise-workspace/.update.lock` |
+| `.repowise/.update.queued` | Written by the post-commit hook before it starts the background update, so agent hooks stop reporting a stale wiki right away |
+| `.repowise/.update.pending` | Written by an update that found the lock held. Carries the newest HEAD, which the running update processes in an extra pass before it exits |
+| `.repowise/.update.log` | Output of background updates. Capped at 256 KB, keeping the last 64 KB |
+
+---
+
## Environment variables
| Variable | Used by | Description |