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.

feat(claude-plugin): add remaining CLI adapters as slash commands (#1428)

Felix-Ayush93d8b64d9ff1
diff --git a/plugins/claude-code/.claude-plugin/plugin.json b/plugins/claude-code/.claude-plugin/plugin.json
index babb4074f..42cafab9f 100644
--- a/plugins/claude-code/.claude-plugin/plugin.json
+++ b/plugins/claude-code/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "repowise",
- "description": "Codebase intelligence for Claude Code. Indexes your codebase into five layers (Graph, Git, Docs, Decisions, Code Health) and exposes them through ten task-shaped MCP tools — so Claude understands architecture, ownership, hotspots, why code is built the way it is, and where the defect risk lives.",
+ "description": "Codebase intelligence for Claude Code. Indexes your codebase into five layers (Graph, Git, Docs, Decisions, Code Health) and exposes them through eleven task-shaped MCP tools — so Claude understands architecture, ownership, hotspots, why code is built the way it is, and where the defect risk lives.",
"version": "0.40.0",
"author": {
"name": "Repowise",
diff --git a/plugins/claude-code/CHANGELOG.md b/plugins/claude-code/CHANGELOG.md
index 34d019130..e92951ccd 100644
--- a/plugins/claude-code/CHANGELOG.md
+++ b/plugins/claude-code/CHANGELOG.md
@@ -2,6 +2,15 @@
All notable changes to the Repowise Claude Code plugin are documented here.
+## Unreleased
+
+### Added
+- `/repowise:ask`, `/repowise:context`, `/repowise:symbol`, `/repowise:why`, and
+ `/repowise:export` — slash commands for the remaining CLI adapters so Claude
+ can synthesise answers, pull triage cards, read live-verified symbol bodies,
+ query decisions/archaeology, and export the wiki or a Structurizr model
+ without MCP-only flows.
+
## 0.40.0
### Added
diff --git a/plugins/claude-code/README.md b/plugins/claude-code/README.md
index 255f0b35d..aae12dda0 100644
--- a/plugins/claude-code/README.md
+++ b/plugins/claude-code/README.md
@@ -50,6 +50,9 @@ defect-validated score from deterministic markers).
| `/repowise:status` | Health check — sync state, page counts, provider info |
| `/repowise:update` | Incremental update — sync the index with recent code changes |
| `/repowise:search` | Search the codebase wiki (fulltext, semantic, or symbol) |
+| `/repowise:ask` | Cited, synthesised answer to a codebase question (LLM call) |
+| `/repowise:context` | Triage card for files/modules/symbols (layer, hotspot, freshness) |
+| `/repowise:symbol` | Read one symbol body with live-verified line bounds |
| `/repowise:reindex` | Rebuild the vector store (re-embed; no LLM calls) |
| `/repowise:health` | Code-health KPIs, lowest-scoring files, refactoring targets, trends |
| `/repowise:coverage` | Ingest or inspect coverage reports (lights up untested hotspots + per-test map) |
@@ -57,7 +60,9 @@ defect-validated score from deterministic markers).
| `/repowise:risk` | Defect-risk score for a change (commit or `base..head` range) |
| `/repowise:security` | Full-history secret scan (`repowise security scan --history`) |
| `/repowise:dead-code` | Unreachable files, unused exports, zombie packages by confidence |
+| `/repowise:export` | Export wiki pages or a Structurizr architecture model |
| `/repowise:decision` | List, inspect, add, or confirm architectural decisions |
+| `/repowise:why` | Why the code is shaped this way (decisions + archaeology) |
| `/repowise:doctor` | Diagnose (and optionally repair) the setup, keys, and index drift |
### Automatic skills
diff --git a/plugins/claude-code/commands/ask.md b/plugins/claude-code/commands/ask.md
new file mode 100644
index 000000000..1a6783cba
--- /dev/null
+++ b/plugins/claude-code/commands/ask.md
@@ -0,0 +1,44 @@
+---
+description: Ask a codebase question and get a cited, synthesised answer with a confidence rating (costs an LLM call).
+allowed-tools: Bash, Read
+---
+
+# Repowise Ask
+
+Answer a question about this codebase with citations. This is the same
+synthesis the `get_answer` MCP tool performs: hybrid retrieval followed by an
+LLM answer over what it found. Unlike `/repowise:search`, this **costs an LLM
+call** — use it when the user wants an answer, not a hit list.
+
+## Steps
+
+1. If `.repowise/` doesn't exist: "This repo isn't indexed yet. Run `/repowise:init` first." Stop.
+2. Resolve the question from `$ARGUMENTS`. If empty, ask: "What do you want to know about this codebase?"
+3. Run the command and present the answer, confidence, and retrieval quality.
+ Prefer citing the paths the answer names. Do not invent citations.
+
+## Choosing the invocation
+
+- Question only → `repowise ask "<question>"`
+- Restrict retrieval to a subtree → `repowise ask "<question>" --scope packages/cli/`
+- Machine-readable → `repowise ask "<question>" --format json`
+- Raw MCP payload (including dropped blocks) → `repowise ask "<question>" --full`
+
+```
+repowise ask "how does the retry backoff work?"
+repowise ask "where is the session cookie set?" --format json
+repowise ask "how is width resolved?" --scope packages/cli/
+repowise ask "why is auth split across two modules?" --full
+```
+
+Shared targeting flags (`--path`, `--repo`, `--no-workspace`) work the same as
+the other tool-adapter commands.
+
+## How to present the result
+
+- `confidence: high` is content-grounded — cite it directly.
+- `medium` / `low` — say so, and follow any `best_guesses` / `fallback_targets`
+ into `/repowise:context` or `get_context` rather than inventing detail.
+- If a `note` warns that numbers may be synthesised, surface that caveat.
+- Prefer this over `/repowise:search` when the user asked a *question*. Prefer
+ search when they want a list of matching pages / symbols.
diff --git a/plugins/claude-code/commands/context.md b/plugins/claude-code/commands/context.md
new file mode 100644
index 000000000..46af46ee9
--- /dev/null
+++ b/plugins/claude-code/commands/context.md
@@ -0,0 +1,50 @@
+---
+description: Triage card for files, modules, or symbols — layer, hotspot, fix history, freshness (relationships, not source bytes).
+allowed-tools: Bash, Read
+---
+
+# Repowise Context
+
+Pull a triage card for one or more files, modules, or symbols. This is the CLI
+adapter over `get_context`: title, summary, architectural layer, hotspot /
+bug-fix history, doc freshness, and optional relationship blocks. Relationships
+and risk signals — **not** source bytes by default.
+
+## Steps
+
+1. If `.repowise/` doesn't exist: "This repo isn't indexed yet. Run `/repowise:init` first." Stop.
+2. Resolve targets from `$ARGUMENTS`. If empty, ask which file / module /
+ `path::Symbol` to inspect.
+3. Run `repowise context` and present each card: layer, stale bit, hotspot,
+ summary. Call out fix history when present.
+
+## Choosing the invocation
+
+TARGETS are file paths, module paths, or `path/to/file.py::Symbol` ids. Batch
+them in one call.
+
+- Default triage → `repowise context <targets…>`
+- Opt-in blocks (repeatable) → `--include callers|callees|ownership|metrics|decisions|skeleton|…`
+- Richer card → `repowise context <targets…> --no-compact`
+- Machine-readable / raw payload → `--format json` / `--full`
+
+```
+repowise context src/api/routes.py src/api/auth.py
+repowise context src/api/routes.py::login --include callers --include metrics
+repowise context src/api/routes.py --include skeleton
+```
+
+`--include skeleton` adds the body-elided, line-verified file shape. For the
+exact function body, prefer `/repowise:symbol` (or `get_symbol`) with a
+`symbol_id` from the card.
+
+Shared targeting flags (`--path`, `--repo`, `--no-workspace`) work the same as
+the other tool-adapter commands.
+
+## Notes
+
+- Prefer this before opening many files with Read — one call batches cards.
+- A target the index cannot resolve returns an `error` card; report that
+ plainly instead of inventing structure.
+- For a synthesised Q&A answer, use `/repowise:ask`. For "why is it shaped
+ this way", use `/repowise:why`.
diff --git a/plugins/claude-code/commands/export.md b/plugins/claude-code/commands/export.md
new file mode 100644
index 000000000..7466d8001
--- /dev/null
+++ b/plugins/claude-code/commands/export.md
@@ -0,0 +1,60 @@
+---
+description: Export the wiki (or architecture model) to markdown, HTML, JSON, or Structurizr DSL.
+allowed-tools: Bash, Read
+---
+
+# Repowise Export
+
+Export indexed wiki pages to files, or emit a Structurizr DSL architecture
+model. Use this when the user wants a shareable dump, a static site, a JSON
+archive, or a C4/Structurizr model — not when they need an interactive Q&A
+answer (`/repowise:ask`).
+
+## Steps
+
+1. If `.repowise/` doesn't exist: "This repo isn't indexed yet. Run `/repowise:init` first." Stop.
+2. Resolve format and output from `$ARGUMENTS` (see below).
+3. Run `repowise export` and report where files were written (page count /
+ output path). Do not invent page content.
+
+## Choosing the invocation
+
+Default — markdown under `.repowise/export`:
+```
+repowise export
+```
+
+Handle `$ARGUMENTS`:
+- "html" / "site" → `repowise export --format html`
+- "json" → `repowise export --format json`
+- "json full" / "archive" → `repowise export --format json --full`
+ (`--full` keeps tombstones and adds decisions / dead code / hotspots)
+- "structurizr" / "c4" / "dsl" → `repowise export --format structurizr`
+- "structurizr standalone" → `repowise export --format structurizr --standalone`
+- "structurizr components" → add `--components`
+- "to <dir>" / "-o <dir>" → pass `--output <dir>`
+ (for structurizr, a path ending in `.dsl` names the file itself)
+- A repo path → `repowise export <path> …`
+
+```
+repowise export
+repowise export --format html -o ./site
+repowise export --format json --full
+repowise export --format structurizr --standalone --components
+repowise export --format structurizr -o architecture.dsl
+```
+
+## Structurizr notes
+
+- Default structurizr output is a **model fragment** to include from your own
+ `workspace.dsl`. Pass `--standalone` for a complete workspace with default
+ views.
+- `--force` overwrites an output file even if Repowise did not write it
+ (`--standalone` often targets `workspace.dsl`).
+- `--no-externals` leaves third-party dependencies out of the model.
+
+## Notes
+
+- Markdown / HTML / JSON write a directory of pages; structurizr writes DSL.
+- Never fabricate export contents. If the command reports no pages, say so and
+ suggest `/repowise:init`.
diff --git a/plugins/claude-code/commands/symbol.md b/plugins/claude-code/commands/symbol.md
new file mode 100644
index 000000000..a722edfc4
--- /dev/null
+++ b/plugins/claude-code/commands/symbol.md
@@ -0,0 +1,48 @@
+---
+description: Read one symbol's body with live-verified line bounds (path::Name, live range, or distill omission ref).
+allowed-tools: Bash, Read
+---
+
+# Repowise Symbol
+
+Read one function, class, or constant with live-verified line bounds. This is
+the CLI adapter over `get_symbol`. Prefer it over a raw file Read when you
+already have a `symbol_id` from `/repowise:context` or `search_codebase`.
+
+## Steps
+
+1. If `.repowise/` doesn't exist: "This repo isn't indexed yet. Run `/repowise:init` first." Stop.
+2. Resolve the symbol id from `$ARGUMENTS`. If empty, ask for
+ `path/to/file.py::Name`, a live range (`path:start-end`), or a
+ `repowise#<hex>` omission ref from distill.
+3. Run `repowise symbol` and present the body. Report `verified: true/false`
+ when shown. If the id is ambiguous, show every matching body — do not
+ silently pick one.
+
+## Choosing the invocation
+
+- Named symbol → `repowise symbol "src/api/routes.py::login"`
+- Live range read → `repowise symbol "src/api/routes.py:140-180"`
+- Distill omission ref → `repowise symbol "repowise#a1b2c3d4e5f6"`
+- Extra surrounding lines → `--context-lines N` (0–50)
+- Filter restored omission lines → `--query <regex-or-substring>`
+- Machine-readable / raw payload → `--format json` / `--full`
+
+```
+repowise symbol "src/api/routes.py::login"
+repowise symbol "src/api/routes.py:140-180"
+repowise symbol "repowise#a1b2c3d4e5f6"
+repowise symbol "src/api/routes.py::login" --context-lines 3
+```
+
+A truncated body carries a `continuation` you can pass straight back to
+`repowise symbol`. Shared targeting flags (`--path`, `--repo`,
+`--no-workspace`) match the other tool-adapter commands.
+
+## Notes
+
+- Cheaper and more precise than Read + offset math when you have a
+ `symbol_id`.
+- For triage (layer / hotspot / callers) without bytes, use
+ `/repowise:context`.
+- Never invent source — if the command errors or returns no body, say so.
diff --git a/plugins/claude-code/commands/why.md b/plugins/claude-code/commands/why.md
new file mode 100644
index 000000000..36de0b5cb
--- /dev/null
+++ b/plugins/claude-code/commands/why.md
@@ -0,0 +1,48 @@
+---
+description: Why the code is shaped this way — decisions, rationale, and git archaeology (question, path, or decision-health dashboard).
+allowed-tools: Bash, Read
+---
+
+# Repowise Why
+
+Answer *why* the code looks the way it does: decision records, rationale, and
+git archaeology. This is the CLI adapter over `get_why`. Worth running before a
+refactor or a deliberate divergence from a pattern.
+
+`/repowise:decision` manages decision records (list / add / confirm). This
+command **queries** why something is shaped a certain way.
+
+## Steps
+
+1. If `.repowise/` doesn't exist: "This repo isn't indexed yet. Run `/repowise:init` first." Stop.
+2. Map `$ARGUMENTS` to a mode (below), run `repowise why`, and present
+ decisions, alignment, and archaeology. Never invent rationale — if the
+ command falls back to git archaeology, say that plainly.
+
+## Modes
+
+- Question → `repowise why "why is auth using JWT?"`
+- File path (governing decisions + origin story) → `repowise why src/api/auth.py`
+- Target-anchored search → `repowise why "why the retry cap?" --target src/api/client.py`
+ (`--target` is repeatable)
+- No args → `repowise why` (decision-health dashboard: stale / proposed /
+ ungoverned hotspots)
+- Machine-readable / raw payload → `--format json` / `--full`
+
+```
+repowise why "why is auth using JWT?"
+repowise why src/api/auth.py
+repowise why "why the retry cap?" --target src/api/client.py
+repowise why
+```
+
+Shared targeting flags (`--path`, `--repo`, `--no-workspace`) match the other
+tool-adapter commands.
+
+## Notes
+
+- Falls back to git archaeology when a path has no decisions, so it is never
+ empty — call that out so the user knows it is reconstructed, not recorded.
+- For *managing* ADR records (add / confirm / deprecate), use
+ `/repowise:decision`.
+- Before contradicting an existing decision, surface it to the user first.
diff --git a/plugins/claude-code/skills/architectural-decisions/SKILL.md b/plugins/claude-code/skills/architectural-decisions/SKILL.md
index 1b40b33d6..a0ebe229a 100644
--- a/plugins/claude-code/skills/architectural-decisions/SKILL.md
+++ b/plugins/claude-code/skills/architectural-decisions/SKILL.md
@@ -45,8 +45,10 @@ Call `get_why()` with no arguments to get the decision-health dashboard:
- Proposed decisions awaiting confirmation
- Ungoverned hotspots (high-churn files with no recorded decisions)
-The same signals surface in the CLI via `repowise decision health`, and you can
-review auto-proposed decisions with `repowise decision confirm`.
+The same signals surface in the CLI via `repowise decision health` /
+`/repowise:decision`, and you can query *why* mid-task with `repowise why` /
+`/repowise:why` (the `get_why` adapter). Review auto-proposed decisions with
+`repowise decision confirm`.
## When a file has decision markers
diff --git a/plugins/claude-code/skills/codebase-exploration/SKILL.md b/plugins/claude-code/skills/codebase-exploration/SKILL.md
index fe7b623af..433d7179b 100644
--- a/plugins/claude-code/skills/codebase-exploration/SKILL.md
+++ b/plugins/claude-code/skills/codebase-exploration/SKILL.md
@@ -55,6 +55,9 @@ Otherwise the response is current — act on it.
Add `--no-editor-setup` if this repo is a scratch clone, a fixture, or a
worktree: `init` otherwise repoints the user's single global `repowise` MCP
entry at it.
+- MCP tools unavailable → prefer the matching CLI slash commands when the
+ plugin is installed (`/repowise:ask`, `/repowise:context`, `/repowise:symbol`,
+ `/repowise:search`) rather than grepping blind.
- `get_answer`/`search_codebase` come back empty → the repo may have a
template-rendered wiki. Fall back to `get_context` with explicit paths, and note
that model-written pages (`repowise generate`, or `/repowise:init` with an LLM
diff --git a/tests/unit/cli/test_claude_plugin.py b/tests/unit/cli/test_claude_plugin.py
index 8dce412b5..ffd193137 100644
--- a/tests/unit/cli/test_claude_plugin.py
+++ b/tests/unit/cli/test_claude_plugin.py
@@ -155,10 +155,13 @@ def test_claude_plugin_commands_have_frontmatter() -> None:
command_paths = sorted((PLUGIN_ROOT / "commands").glob("*.md"))
assert {path.stem for path in command_paths} == {
+ "ask",
+ "context",
"coverage",
"dead-code",
"decision",
"doctor",
+ "export",
"health",
"impacted-tests",
"init",
@@ -167,7 +170,9 @@ def test_claude_plugin_commands_have_frontmatter() -> None:
"search",
"security",
"status",
+ "symbol",
"update",
+ "why",
}
for path in command_paths:
diff --git a/website/claude-code-plugin.md b/website/claude-code-plugin.md
index 005b10686..4994e0210 100644
--- a/website/claude-code-plugin.md
+++ b/website/claude-code-plugin.md
@@ -96,6 +96,38 @@ Claude will ask for your query and search mode (fulltext, semantic, or symbol),
---
+### `/repowise:ask`
+
+Ask a codebase question and get a cited, synthesised answer (`repowise ask`).
+This is the CLI adapter over the `get_answer` MCP tool — hybrid retrieval plus
+an LLM answer — so it costs a model call where `/repowise:search` does not.
+
+Use it when you want an answer with confidence and citations, not a hit list.
+`--scope` restricts retrieval to a path prefix; `--format json` / `--full`
+match the other tool-adapter commands.
+
+---
+
+### `/repowise:context`
+
+Triage card for files, modules, or symbols (`repowise context`). CLI adapter
+over `get_context`: architectural layer, hotspot / fix history, doc freshness,
+and optional relationship blocks (`--include callers`, `skeleton`, …). Batch
+targets in one call. No source bytes by default — use `/repowise:symbol` for
+exact bodies.
+
+---
+
+### `/repowise:symbol`
+
+Read one symbol body with live-verified line bounds (`repowise symbol`). CLI
+adapter over `get_symbol`. Accepts `path/to/file.py::Name`, a live range
+(`path:start-end`), or a `repowise#<hex>` distill omission ref.
+`--context-lines` adds surrounding lines; a truncated body returns a
+`continuation` you can pass straight back.
+
+---
+
### `/repowise:reindex`
Rebuild the vector search index without making LLM calls.
@@ -146,12 +178,32 @@ Unreachable files, unused exports, and zombie packages by confidence.
---
+### `/repowise:export`
+
+Export wiki pages or the architecture model (`repowise export`). Formats:
+`markdown` (default), `html`, `json`, and `structurizr`. JSON `--full` keeps
+tombstones and adds decisions / dead code / hotspots. Structurizr can emit a
+model fragment or a `--standalone` workspace (`--components`,
+`--no-externals`, `--force`).
+
+---
+
### `/repowise:decision`
List, inspect, add, or confirm architectural decisions.
---
+### `/repowise:why`
+
+Why the code is shaped this way (`repowise why`). CLI adapter over `get_why`:
+decision search by question, governing decisions + origin story for a path,
+target-anchored search (`--target`), or the decision-health dashboard with no
+args. Falls back to git archaeology when no decision is recorded.
+`/repowise:decision` manages records; this command queries them.
+
+---
+
### `/repowise:doctor`
Diagnose (and optionally repair) setup, keys, and index drift.
diff --git a/website/cli-reference.md b/website/cli-reference.md
index 16dcc2202..0c5bfaf32 100644
--- a/website/cli-reference.md
+++ b/website/cli-reference.md
@@ -260,6 +260,164 @@ repowise search "AuthService" --mode symbol
repowise search "database connection" --limit 20
```
+For a synthesised answer rather than a keyword lookup, use [`ask`](#ask).
+
+---
+
+## `ask`
+
+Answer a question about the codebase, with citations. The same synthesis the
+`get_answer` MCP tool performs: hybrid retrieval followed by an LLM answer over
+what it found, so this command costs an LLM call where the other query commands
+do not.
+
+```bash
+repowise ask <QUESTION> [OPTIONS]
+```
+
+### Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--scope` | string | — | Restrict retrieval to a path prefix (e.g. `packages/cli/`) |
+| `--path` | string | cwd | Repo (or workspace) root |
+| `--repo` | string | — | Workspace repo alias to query |
+| `--no-workspace` | flag | false | Force single-repo mode even inside a workspace |
+| `--format` | choice | table | `table` or `json` |
+| `--full` | flag | false | Emit the raw MCP tool payload |
+
+### Examples
+
+```bash
+repowise ask "how does the retry backoff work?"
+repowise ask "where is the session cookie set?" --format json
+repowise ask "how is width resolved?" --scope packages/cli/
+repowise ask "why is auth split across two modules?" --full
+```
+
+`confidence: high` is content-grounded, so it can be cited directly. A
+low-confidence answer returns `best_guesses` instead of going silent.
+
+Also available as the Claude Code slash command `/repowise:ask`.
+
+---
+
+## `context`
+
+Triage card for files, modules or symbols: title, summary, architectural layer,
+hotspot and bug-fix history, doc freshness, and the shape of the verified
+skeleton. Relationships and risk signals, not source bytes. Batch targets in one
+call.
+
+```bash
+repowise context <TARGETS...> [OPTIONS]
+```
+
+TARGETS are file paths, module paths, or `path/to/file.py::Symbol` ids.
+
+### Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--include` | choice | — | Opt-in block, repeatable: `full_doc`, `ownership`, `last_change`, `callers`, `callees`, `metrics`, `community`, `decisions`, `health`, `skeleton` |
+| `--no-compact` | flag | false | Add structure, imports and docstrings to each card |
+| `--path` | string | cwd | Repo (or workspace) root |
+| `--repo` | string | — | Workspace repo alias to query |
+| `--no-workspace` | flag | false | Force single-repo mode even inside a workspace |
+| `--format` | choice | table | `table` or `json` |
+| `--full` | flag | false | Emit the raw MCP tool payload |
+
+### Examples
+
+```bash
+repowise context src/api/routes.py src/api/auth.py
+repowise context src/api/routes.py::login --include callers --include metrics
+repowise context src/api/routes.py --include skeleton # + the file's source shape
+```
+
+Pass `--include skeleton` for the whole file body-elided and line-verified, or
+use [`symbol`](#symbol) for one function body. Also available as `/repowise:context`.
+
+---
+
+## `symbol`
+
+Read one function, class or constant with live-verified line bounds. `source`
+arrives in the same line-numbered format a file read produces; `verified: true`
+means the bounds were checked against the live file.
+
+```bash
+repowise symbol <SYMBOL_ID> [OPTIONS]
+```
+
+`SYMBOL_ID` is `path/to/file.py::Name` (as `repowise context` reports it),
+`path/to/file.py:140-180` for a live range read, or a `repowise#<hex>`
+omission ref from a distilled command.
+
+### Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--context-lines` | int | 0 | Extra lines before and after the body (0–50) |
+| `--query` | string | — | Omission refs only: regex or substring filter on restored lines |
+| `--path` | string | cwd | Repo (or workspace) root |
+| `--repo` | string | — | Workspace repo alias to query |
+| `--no-workspace` | flag | false | Force single-repo mode even inside a workspace |
+| `--format` | choice | table | `table` or `json` |
+| `--full` | flag | false | Emit the raw MCP tool payload |
+
+### Examples
+
+```bash
+repowise symbol "src/api/routes.py::login"
+repowise symbol "src/api/routes.py:140-180" # live range read
+repowise symbol "repowise#a1b2c3d4e5f6" # a distill omission ref
+```
+
+An ambiguous id returns every matching body rather than silently picking one.
+A truncated body carries a `continuation` you can pass straight back.
+Also available as `/repowise:symbol`.
+
+---
+
+## `why`
+
+Why the code is shaped this way: decision records, rationale and git
+archaeology. Worth running before a refactor or a deliberate divergence from a
+pattern.
+
+```bash
+repowise why [QUERY] [OPTIONS]
+```
+
+QUERY is a question (`why is auth using JWT?`), a file path (its governing
+decisions, origin story and alignment score), or omitted for the
+decision-health dashboard.
+
+### Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--target` | string | — | File path to anchor the search to (repeatable) |
+| `--path` | string | cwd | Repo (or workspace) root |
+| `--repo` | string | — | Workspace repo alias to query |
+| `--no-workspace` | flag | false | Force single-repo mode even inside a workspace |
+| `--format` | choice | table | `table` or `json` |
+| `--full` | flag | false | Emit the raw MCP tool payload |
+
+### Examples
+
+```bash
+repowise why "why is auth using JWT?" # question
+repowise why src/api/auth.py # governing decisions + origin story
+repowise why "why the retry cap?" --target src/api/client.py
+repowise why # decision health dashboard
+```
+
+Falls back to git archaeology when a path has no decisions, so it is never
+empty. Also available as `/repowise:why`. Use `repowise decision` /
+`/repowise:decision` to manage the records themselves.
+
---
## `reindex`
@@ -598,7 +756,7 @@ See [CLAUDE.md Generator →](claude-md-generator) for how the file is structure
## `export`
-Export wiki pages to files.
+Export wiki pages to files, or emit a Structurizr DSL architecture model.
```bash
repowise export [PATH] [OPTIONS]
@@ -608,8 +766,13 @@ repowise export [PATH] [OPTIONS]
| Flag | Type | Default | Description |
|------|------|---------|-------------|
-| `--format` / `-f` | choice | markdown | `markdown`, `html`, or `json` |
-| `--output` / `-o` | string | `.repowise/export` | Output directory |
+| `--format` | choice | markdown | `markdown`, `html`, `json`, or `structurizr` |
+| `--output` / `-o` | string | `.repowise/export` | Output directory (for structurizr, a path ending in `.dsl` names the file) |
+| `--full` | flag | false | JSON: include tombstones plus decisions, dead code, and hotspot metadata |
+| `--standalone` | flag | false | Structurizr: emit a complete workspace with default views |
+| `--components` | flag | false | Structurizr: include the component level (one box per directory) |
+| `--force` | flag | false | Structurizr: overwrite the output file even if Repowise did not write it |
+| `--no-externals` | flag | false | Structurizr: leave third-party dependencies out of the model |
### Examples
@@ -617,8 +780,13 @@ repowise export [PATH] [OPTIONS]
repowise export # Export all pages as markdown
repowise export --format html -o ./site # HTML export to ./site
repowise export --format json # Machine-readable JSON dump
+repowise export --format json --full # Archival JSON with decisions / dead code
+repowise export --format structurizr --standalone --components
+repowise export --format structurizr -o architecture.dsl
```
+Also available as the Claude Code slash command `/repowise:export`.
+
---
## Configuration