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: generate the agent support matrix, and stop publishing a wrong tool count (#1455)

Raghav Chamadiyaac437b32f55c
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index a84c27af3..72589cdf6 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -6,7 +6,7 @@
"url": "https://repowise.dev"
},
"metadata": {
- "description": "The codebase intelligence layer for AI coding agents — graph, git, docs, decisions, and a defect-validated code-health score, exposed to Claude through ten task-shaped MCP tools.",
+ "description": "The codebase intelligence layer for AI coding agents — graph, git, docs, decisions, and a defect-validated code-health score, exposed to Claude through eleven task-shaped MCP tools.",
"homepage": "https://repowise.dev"
},
"plugins": [
diff --git a/README.md b/README.md
index 3cd8a49c5..45ad39b06 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,7 @@
<a href="#see-all-of-it">Dashboard</a> ·
<a href="#past-one-repo">Workspaces</a> ·
<a href="#quickstart-under-5-minutes-no-api-key">Quickstart</a> ·
+ <a href="#supported-agents">Agents</a> ·
<a href="#the-ten-mcp-tools">MCP tools</a> ·
<a href="#measured-against-the-field">Benchmarks</a> ·
<a href="#how-it-compares-on-capability">Comparison</a> ·
@@ -65,7 +66,7 @@ Free and self-hosted, runs on your machine, and the first index needs no API key
<picture>
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/one-index-dark.svg" />
- <img src=".github/assets/one-index.svg" alt="One index producing code health, a dependency graph, git history, generated docs, architectural decisions, and eleven MCP tools" width="100%" />
+ <img src=".github/assets/one-index.svg" alt="One index producing code health, a dependency graph, git history, generated docs, architectural decisions, and ten MCP tools" width="100%" />
</picture>
</div>
@@ -365,6 +366,39 @@ Set Up This Repository**. Guide: **[docs/agent/VSCODE.md →](docs/agent/VSCODE.
---
+## Supported agents
+
+**Three agents wired end to end · two at the Full tier · every other MCP host one
+paste away.**
+
+<p>
+ <strong>Full tier &nbsp;</strong>
+ <img src="https://img.shields.io/badge/Claude_Code-D97757?style=flat-square&logo=claude&logoColor=white" alt="Claude Code" />
+ <img src="https://img.shields.io/badge/Codex_CLI-000000?style=flat-square&logo=openai&logoColor=white" alt="Codex CLI" />
+</p>
+<p>
+ <strong>Good tier &nbsp;</strong>
+ <img src="https://img.shields.io/badge/VS_Code-007ACC?style=flat-square&logo=visualstudiocode&logoColor=white" alt="VS Code" />
+</p>
+
+**Full** is every surface repowise has: MCP tools, skills, slash commands, a managed
+instructions file, hook-level interception of tool calls, and transcript mining after
+the session. **Good** is the honest half of that: MCP tools and the config to reach
+them, but no hook-level interception and no transcript mining. A Good-tier agent can
+ask repowise anything; repowise never sees the tool calls in between. The tier is
+computed from what each integration actually wires, so this list cannot claim a depth
+the code does not have.
+
+Everything else that speaks MCP is one snippet away. `repowise agents print-config
+claude-code` prints a stdio server entry to paste into Cursor, Cline, Windsurf, Zed,
+Gemini CLI or any other host that keys on `mcpServers`, and repowise writes nothing.
+
+Adding an agent takes **one descriptor file and one registry line**, with no changes to
+the orchestrators. Full matrix and the contributor recipe:
+**[docs/agent/INTEGRATIONS.md →](docs/agent/INTEGRATIONS.md)**
+
+---
+
## Supported languages
**18 languages parsed to AST · 13 at the Full tier · framework-aware across all of them.**
@@ -509,7 +543,7 @@ Full walkthrough: **[docs/start/QUICKSTART.md →](docs/start/QUICKSTART.md)**
---
-## The eleven MCP tools
+## The ten MCP tools
Every response carries an `_meta` envelope with `index_age_days`, `indexed_commit`, and
a `stale_warning` that fires only when the indexed HEAD diverges from live `.git/HEAD`,
@@ -527,9 +561,8 @@ so your agent always knows how much to trust what it just read.
| `get_why(query?, targets?)` | Architectural decisions and their verbatim evidence spans, stamped exact / fuzzy / unverified. Falls back to git archaeology when no decisions exist. |
| `get_dead_code(...)` | Unreachable code by confidence tier with cleanup-impact estimates, and cross-repo consumer detection in workspace mode. |
| `get_health(targets?, include?)` | Per-file marker scores across all three signals. `include` opens coverage, trends, per-file signals, the accuracy self-check, and structured refactoring plans. |
-| `list_repos()` | Repo aliases this server is serving. Discover `repo=` targets (especially in a workspace). |
-Eleven is a deliberate ceiling rather than a limit we ran into: a small, task-shaped
+Ten is a deliberate ceiling rather than a limit we ran into: a small, task-shaped
surface is easier for an agent to choose from than a large one. Worked example (*"add
rate limiting to all API endpoints"* in 5 calls instead of ~30 greps and reads), the
opt-in tools, and the full reference: **[docs/agent/MCP_TOOLS.md →](docs/agent/MCP_TOOLS.md)**
diff --git a/docs/README.md b/docs/README.md
index c2d363bb9..56a8fd33c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -16,7 +16,7 @@ your agent in under five minutes, with no API key.
| You are | Start here | Then |
|---|---|---|
-| **A developer wiring up an AI agent** | [Quickstart](start/QUICKSTART.md) | [MCP tools](agent/MCP_TOOLS.md) · [Hooks](agent/HOOKS.md) · [Distill](agent/DISTILL.md) |
+| **A developer wiring up an AI agent** | [Quickstart](start/QUICKSTART.md) | [Supported agents](agent/INTEGRATIONS.md) · [MCP tools](agent/MCP_TOOLS.md) · [Hooks](agent/HOOKS.md) · [Distill](agent/DISTILL.md) |
| **Living in an editor** | [VS Code extension](agent/VSCODE.md) | [Codex](agent/CODEX.md) · [opencode](agent/OPENCODE.md) |
| **A team lead watching what ships** | [Change risk](layers/CHANGE_RISK.md) | [Code health](layers/CODE_HEALTH.md) · [Bug history](layers/BUG_HISTORY.md) |
| **Running many repos** | [Workspaces](scale/WORKSPACES.md) | [Worktrees](scale/WORKTREES.md) · [Auto-sync](scale/AUTO_SYNC.md) |
@@ -37,6 +37,7 @@ your agent in under five minutes, with no API key.
| Doc | What it covers |
|-----|----------------|
+| [agent/INTEGRATIONS.md](agent/INTEGRATIONS.md) | Which agents are supported at what depth, generated from the code, plus the recipe for adding one |
| [agent/MCP_TOOLS.md](agent/MCP_TOOLS.md) | The ten task-shaped tools, what each answers, and worked multi-tool examples |
| [agent/HOOKS.md](agent/HOOKS.md) | Proactive delivery: context and warnings that arrive without the agent asking |
| [agent/DISTILL.md](agent/DISTILL.md) | `repowise distill`: compress noisy command output before your agent reads it |
diff --git a/docs/agent/INTEGRATIONS.md b/docs/agent/INTEGRATIONS.md
new file mode 100644
index 000000000..7758f0ee0
--- /dev/null
+++ b/docs/agent/INTEGRATIONS.md
@@ -0,0 +1,106 @@
+# Agent integrations
+
+<!-- Generated by scripts/gen_agent_matrix.py. Do not edit by hand: run
+ `python scripts/gen_agent_matrix.py` after changing a descriptor. -->
+
+Anything that speaks MCP can read a repowise index. This page is about how
+*deeply* each agent is wired, which is a different question, and the one
+every breadth claim in this space gets wrong.
+
+## Tiers
+
+The tier is **derived from the code, never declared**. A descriptor reaches
+Full only by naming both a hook adapter and a transcript adapter, so no
+document can claim a depth the integration does not have.
+
+- **Full.** MCP tools, a managed instructions file, skills, slash commands, hook-level interception of tool calls, and transcript mining after the fact. Every surface repowise has.
+- **Good.** MCP tools, and a managed instructions file or skills where the host reads them. **No hook-level interception and no transcript mining.** The agent can ask repowise questions; repowise cannot see or annotate what the agent does in between.
+- **Paste-config.** `repowise agents print-config <id>` emits the MCP server snippet and we write nothing. Zero code and zero maintenance per host.
+
+## The matrix
+
+`Yes` means repowise wires it. `Plugin` means the host's own plugin ships
+it and repowise does not write it. `No` means the surface does not exist
+for that agent.
+
+| Agent | Tier | MCP | Hooks | Skills | Commands | Instructions | Transcripts |
+|---|---|---|---|---|---|---|---|
+| [Claude Code](https://docs.claude.com/en/docs/claude-code) | Full | Yes | Yes | Plugin | Plugin | Yes | Yes |
+| [Codex CLI](https://developers.openai.com/codex/cli) | Full | Yes | Yes | Plugin | Yes | Yes | Yes |
+| [VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) | Good | Yes | No | No | No | No | No |
+
+Target ids for `--target=`: `claude-code`, `codex`, `vscode`.
+
+### What Good tier does not include
+
+VS Code sits at Good, and the honest version of that is worth stating
+plainly. These agents get the MCP tools and the config repowise writes.
+They do **not** get hook-level interception: repowise never sees a tool
+call before it runs, never rewrites a noisy command, and never annotates
+a result afterwards. Nor is there transcript mining, so nothing learns
+from the session after it ends.
+
+That is a real integration and it is most of the value. It is not the
+same product Full-tier agents get, and breadth that overclaims depth is
+worse than narrower breadth.
+
+## Paste-config
+
+Every other MCP host is served without writing a descriptor for it. Print
+the server entry and paste it into whatever config that host reads:
+
+```bash
+repowise agents print-config claude-code # prints, writes nothing
+```
+
+That emits an `mcpServers` block, which is the shape Cursor, Cline, Windsurf,
+Zed and most others read. Ask for `vscode` instead when the host follows VS
+Code: that one keys on `servers` and adds a `type` field inside each entry, so
+it is not the same text with a different wrapper. Print the one that matches
+your host rather than editing either by hand. Hosts people ask about most,
+none of which repowise writes config for today:
+
+Cursor, Cline, Windsurf, Zed, Continue, Gemini CLI, OpenCode, JetBrains AI Assistant, Amp.
+
+`print-config` takes one of the target ids above; there is no descriptor to
+name for a host at this tier, which is the point of the tier.
+
+## The MCP surface
+
+repowise registers **seventeen MCP tools**. A single-repo server advertises
+**eleven** of them by default, and workspace mode adds two more automatically for
+**thirteen**. A further **four** are off by default, enabled through the `mcp.tools`
+config block or `--tools +name`. The `lean` profile trims the default surface to
+**six** tools (seven in workspace mode) for agents on a tight context budget.
+
+Per-tool detail: [MCP_TOOLS.md](MCP_TOOLS.md).
+
+## Adding an agent
+
+**Adding an agent takes one descriptor file and one registry line.**
+
+1. Write `packages/cli/src/repowise/cli/agent_targets/targets/<id>.py`
+ exporting a `TARGET` that satisfies the `AgentTarget` protocol in
+ [`types.py`](../../packages/cli/src/repowise/cli/agent_targets/types.py).
+ `vscode.py` is the smallest working example, at one install method and
+ one config file.
+2. Add one line to `_TARGET_MODULES` in
+ [`registry.py`](../../packages/cli/src/repowise/cli/agent_targets/registry.py).
+ Order there is the order agents appear in prompts, in `--target=all` and
+ in listings, so keep it stable.
+3. Run `python scripts/gen_agent_matrix.py` to add the row here.
+
+There is no third file for anything derived. The tier, this matrix and the
+`repowise agents` listing all read the descriptor, and the contract tests in
+`tests/unit/cli/test_agent_targets.py` are parameterized over the registry,
+so a new target inherits them.
+
+The README badge rows are the exception: a brand colour and a logo per agent
+are not derivable, and the README is not generated, so a new agent needs a
+badge added by hand and the count above them updated. That is checked rather
+than trusted. `tests/unit/cli/test_agent_matrix.py` fails when the badge rows
+and the registry disagree, and names what to add.
+
+Declare only what the agent genuinely has. `derive_tier` reads the adapter
+names, so a descriptor that names a hook adapter it has not implemented
+publishes a Full-tier claim on this page.
diff --git a/docs/agent/VSCODE.md b/docs/agent/VSCODE.md
index e034e2561..e331d815b 100644
--- a/docs/agent/VSCODE.md
+++ b/docs/agent/VSCODE.md
@@ -106,6 +106,15 @@ assistants query the index through purpose-built tools instead of guessing from
open files. For editors that read a config file, run **Repowise: Configure MCP
for this Workspace** to write `.vscode/mcp.json`.
+VS Code sits at the **Good** support tier, and the honest version of that is
+worth knowing before you compare it to the Claude Code or Codex setup. You get
+the MCP tools and the config to reach them. You do not get hook-level
+interception: repowise never sees a tool call before it runs, never rewrites a
+noisy command, and never annotates a result afterwards, and there is no
+transcript mining after the session. What the extension itself surfaces in the
+gutter, on hover and in the dashboards is unaffected. Full comparison:
+[INTEGRATIONS.md](INTEGRATIONS.md).
+
## Settings
The fastest way to tune everything is **Repowise: Open Settings**, a panel
diff --git a/docs/architecture/pluggable-storage.md b/docs/architecture/pluggable-storage.md
index ed3c2f321..05bca78ff 100644
--- a/docs/architecture/pluggable-storage.md
+++ b/docs/architecture/pluggable-storage.md
@@ -216,7 +216,7 @@ broken plugin cannot derail the pipeline.
The seams add a layer of indirection but no behavior change for users
of the OSS defaults: `repowise init` still writes to
`.repowise/wiki.db`, the in-process graph still owns ingestion, the
-ten MCP tools still expose the same surface, and `repowise --help`
+eleven MCP tools still expose the same surface, and `repowise --help`
lists the same commands in the same order. Plugins extend the
defaults; they don't replace them unless an integration explicitly
swaps an implementation in.
diff --git a/docs/business/COMMERCIAL.md b/docs/business/COMMERCIAL.md
index 82c1547ed..016433f55 100644
--- a/docs/business/COMMERCIAL.md
+++ b/docs/business/COMMERCIAL.md
@@ -19,7 +19,7 @@ models. Specific pricing figures are provided in a separate proposal.
## 1. Who the commercial license is for
The open-source distribution covers the full developer-experience surface — the five
-intelligence layers, the ten MCP tools, multi-repo workspaces, the local dashboard,
+intelligence layers, the eleven MCP tools, multi-repo workspaces, the local dashboard,
auto-sync, and auto-generated `CLAUDE.md`. That is everything an engineer or a team
needs to make their AI coding agents codebase-aware.
@@ -121,7 +121,7 @@ the items that matter most to you can be prioritized.
| Capability | Open Source (AGPL) | Commercial License |
|------------|:------------------:|:------------------:|
| Five intelligence layers | ✅ | ✅ |
-| Ten MCP tools | ✅ | ✅ |
+| Eleven MCP tools | ✅ | ✅ |
| Multi-repo workspaces | ✅ | ✅ |
| Full-tier language support (incl. C# / .NET) | ✅ | ✅ |
| Local dashboard (incl. local security pattern scan) | ✅ | ✅ |
diff --git a/docs/start/USER_GUIDE.md b/docs/start/USER_GUIDE.md
index c8a225639..26db592dc 100644
--- a/docs/start/USER_GUIDE.md
+++ b/docs/start/USER_GUIDE.md
@@ -208,7 +208,7 @@ for Codex, `repowise init --codex` writes project-local config. Setup per client
is in [Quickstart](QUICKSTART.md#3-connect-your-agent), and
[Codex](../agent/CODEX.md) / [opencode](../agent/OPENCODE.md) have their own guides.
-**Ten tools, task-shaped.** Your agent gets architecture summaries, per-file
+**Eleven tools, task-shaped.** Your agent gets architecture summaries, per-file
triage cards with callers and ownership, symbol source with exact bounds, risk
assessment for a set of changed files, decision lookups and health scores, each in
one call rather than a chain. What each one answers, and worked multi-tool
diff --git a/scripts/gen_agent_matrix.py b/scripts/gen_agent_matrix.py
new file mode 100644
index 000000000..54c9ba94c
--- /dev/null
+++ b/scripts/gen_agent_matrix.py
@@ -0,0 +1,466 @@
+"""Render the agent support matrix at ``docs/agent/INTEGRATIONS.md`` from the code.
+
+Two numbers in this repo have a long history of being wrong in public: which
+agents we support at what depth, and how many MCP tools we expose. Both were
+hand-written in a dozen places, so both drifted the moment a target or a tool
+landed. Six artifacts said "ten MCP tools" against a live surface of eleven, and
+the README contradicted itself two hundred lines apart.
+
+So neither is written by hand here. The tiers come from
+:func:`repowise.cli.agent_targets.types.derive_tier`, the capability columns come
+from each descriptor's declared install methods, and the tool counts come from
+the live MCP registry. A new agent or a new tool changes this document by being
+registered, and :mod:`tests.unit.cli.test_agent_matrix` fails when the file on
+disk disagrees.
+
+Render discipline, the same as ``scripts/gen_plugin_content.py`` and for the same
+reason: fixed section order, sorted iteration where the order is not already
+declared, LF newlines, and never a timestamp, a version or a generator banner in
+the output. A file that changes when nothing changed cannot be a golden.
+
+Run ``python scripts/gen_agent_matrix.py`` to write, ``--check`` to report drift
+without writing.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import textwrap
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+OUTPUT = ROOT / "docs" / "agent" / "INTEGRATIONS.md"
+
+#: Prose width. Only paragraphs whose text is computed are wrapped here; the
+#: hand-authored lines are wrapped as written, because reflowing them through
+#: ``textwrap`` would rewrite the file every time a sentence changed length.
+_WRAP = 84
+
+# The script runs standalone as well as under pytest, so make the workspace
+# packages importable either way. Harmless when they are already installed.
+for _pkg in ("cli", "core", "server"):
+ _src = ROOT / "packages" / _pkg / "src"
+ if _src.is_dir() and str(_src) not in sys.path:
+ sys.path.insert(0, str(_src))
+
+
+# ---------------------------------------------------------------------------
+# Hand-authored copy
+# ---------------------------------------------------------------------------
+
+#: Hosts served by the Paste-config tier: we write nothing and maintain nothing,
+#: ``repowise agents print-config`` emits a snippet they can paste. There is no
+#: descriptor to derive this from, by definition. The golden test does check
+#: that nothing here collides with a registered target, so promoting one of
+#: these to a real integration and forgetting to delete the line is caught.
+PASTE_CONFIG_HOSTS: tuple[str, ...] = (
+ "Cursor",
+ "Cline",
+ "Windsurf",
+ "Zed",
+ "Continue",
+ "Gemini CLI",
+ "OpenCode",
+ "JetBrains AI Assistant",
+ "Amp",
+)
+
+#: Default-surface tools the README's curated list leaves out. ``list_repos``
+#: answers "which repos is this server serving", which is discovery rather than
+#: one of the task-shaped tools the README is selling, and a reader counting
+#: capabilities should not have it padding the number. Everything downstream of
+#: the README states the real surface instead.
+NON_FLAGSHIP_TOOLS: frozenset[str] = frozenset({"list_repos"})
+
+TIER_BLURBS: dict[str, tuple[str, str]] = {
+ "full": (
+ "Full",
+ "MCP tools, a managed instructions file, skills, slash commands, "
+ "hook-level interception of tool calls, and transcript mining after "
+ "the fact. Every surface repowise has.",
+ ),
+ "good": (
+ "Good",
+ "MCP tools, and a managed instructions file or skills where the host "
+ "reads them. **No hook-level interception and no transcript mining.** "
+ "The agent can ask repowise questions; repowise cannot see or annotate "
+ "what the agent does in between.",
+ ),
+ "paste-config": (
+ "Paste-config",
+ "`repowise agents print-config <id>` emits the MCP server snippet and "
+ "we write nothing. Zero code and zero maintenance per host.",
+ ),
+}
+
+
+# ---------------------------------------------------------------------------
+# Derived data
+# ---------------------------------------------------------------------------
+
+
+def agent_rows() -> list[dict]:
+ """One row per registered target, in registry order.
+
+ Only the static fields. ``registry.describe_agents`` is the projection the
+ CLI reads, and it deliberately reports ``present`` / ``method`` /
+ ``registrations``, which describe the machine the command ran on. A checked
+ in document rendered from those would differ per developer and fail its own
+ ``--check`` on the next machine.
+ """
+ from repowise.cli.agent_targets import registry
+ from repowise.cli.agent_targets.types import Capability, derive_tier
+
+ rows: list[dict] = []
+ for target in registry.all_targets():
+ # Split by who manages the method rather than unioning every
+ # capability, because "Claude Code has slash commands" and "repowise
+ # installs Claude Code's slash commands" are different claims and only
+ # the first is true. The host plugin ships those.
+ by_manager: dict[str, set[Capability]] = {"repowise": set(), "host": set()}
+ for method in target.methods:
+ key = "host" if method.managed_by == "host" else "repowise"
+ by_manager[key] |= set(method.provides)
+ rows.append(
+ {
+ "id": target.id,
+ "display_name": target.display_name,
+ "docs_url": target.docs_url,
+ "tier": derive_tier(target).value,
+ "direct": by_manager["repowise"],
+ "host": by_manager["host"],
+ "hook_adapter": target.hook_adapter,
+ "session_adapter": target.session_adapter,
+ }
+ )
+ return rows
+
+
+def tool_counts() -> dict[str, int]:
+ """The live MCP tool surface, straight from the registry.
+
+ ``ensure_full_surface`` is what makes the count honest: tool modules import
+ lazily, so a registry read without it reports however many tools happened to
+ be imported already.
+ """
+ from repowise.core.registry import mcp_tool_registry
+ from repowise.server.mcp_server import ensure_full_surface
+ from repowise.server.mcp_server._tool_selection import LEAN, resolve_enabled_tools
+
+ ensure_full_surface()
+ entries = mcp_tool_registry.entries()
+ default_names = resolve_enabled_tools(entries, is_workspace=False)
+ # Every count goes through the resolver the server itself uses, including
+ # the lean ones. Counting ``LEAN_TOOLS`` directly looks equivalent and is
+ # not: the resolver drops a lean name the registry no longer carries, so a
+ # renamed tool would leave the published "six tools" claiming a surface the
+ # server had quietly trimmed to five.
+ single_repo = len(default_names)
+ workspace = len(resolve_enabled_tools(entries, is_workspace=True))
+ return {
+ "total": len(entries),
+ "single_repo": single_repo,
+ # The README and the hero image count the *flagship* tools, which is a
+ # narrower and deliberate claim: the task-shaped ones the pitch is
+ # about. It is the default surface minus the discovery utilities, and
+ # it is derived here rather than typed, so a twelfth default tool moves
+ # the README too. Docs keep the precise surface numbers.
+ "flagship": len(default_names - NON_FLAGSHIP_TOOLS),
+ "workspace": workspace,
+ # The delta is published in its own right ("adds two more"), so it is
+ # derived rather than written as a literal next to a derived total.
+ "workspace_extra": workspace - single_repo,
+ "opt_in": len([entry for entry in entries if not entry.default]),
+ "lean": len(resolve_enabled_tools(entries, is_workspace=False, override=LEAN)),
+ "lean_workspace": len(resolve_enabled_tools(entries, is_workspace=True, override=LEAN)),
+ }
+
+
+#: Complete through twenty, not just the values in use today. A partial map is
+#: a landmine: the counts here feed a module-scope constant and a parametrize
+#: argument in the golden test, so a missing entry is a *collection* error that
+#: takes down the very drift guards that exist to say which files to edit. The
+#: first tool to push a count to twelve, or the renamed lean tool this file
+#: warns about elsewhere, would have hit exactly that.
+_WORDS = {
+ 0: "zero",
+ 1: "one",
+ 2: "two",
+ 3: "three",
+ 4: "four",
+ 5: "five",
+ 6: "six",
+ 7: "seven",
+ 8: "eight",
+ 9: "nine",
+ 10: "ten",
+ 11: "eleven",
+ 12: "twelve",
+ 13: "thirteen",
+ 14: "fourteen",
+ 15: "fifteen",
+ 16: "sixteen",
+ 17: "seventeen",
+ 18: "eighteen",
+ 19: "nineteen",
+ 20: "twenty",
+}
+
+
+def spell(count: int) -> str:
+ """*count* as an English word, for prose that spells small numbers out.
+
+ Raises past twenty rather than falling back to the digits: the artifacts
+ this guards say "eleven MCP tools", and a silent switch to "21 MCP tools"
+ mid-sentence is the kind of drift that goes unnoticed for twenty-four
+ releases. Past twenty the prose wants rewriting by a person anyway.
+ """
+ if count not in _WORDS:
+ raise ValueError(
+ f"no spelled form for {count}. Prose that spells a number this large reads "
+ "badly; rewrite the sentence, or extend _WORDS in scripts/gen_agent_matrix.py."
+ )
+ return _WORDS[count]
+
+
+# ---------------------------------------------------------------------------
+# Render
+# ---------------------------------------------------------------------------
+
+#: Column caption, and the capability it reads. ``None`` means the column is
+#: derived from an adapter name rather than from a declared capability.
+_COLUMNS: tuple[tuple[str, str | None], ...] = (
+ ("MCP", "mcp"),
+ ("Hooks", "hooks"),
+ ("Skills", "skills"),
+ ("Commands", "commands"),
+ ("Instructions", "instructions"),
+ ("Transcripts", None),
+)
+
+
+def _cell(row: dict, capability: str | None) -> str:
+ if capability is None:
+ return "Yes" if row["session_adapter"] else "No"
+ from repowise.cli.agent_targets.types import Capability
+
+ wanted = Capability(capability)
+ if wanted in row["direct"]:
+ return "Yes"
+ if wanted in row["host"]:
+ return "Plugin"
+ return "No"
+
+
+def _matrix_table(rows: list[dict]) -> str:
+ header = "| Agent | Tier | " + " | ".join(name for name, _ in _COLUMNS) + " |"
+ rule = "|---|---|" + "---|" * len(_COLUMNS)
+ lines = [header, rule]
+ for row in rows:
+ name = row["display_name"]
+ if row["docs_url"]:
+ name = f"[{name}]({row['docs_url']})"
+ cells = [_cell(row, capability) for _, capability in _COLUMNS]
+ tier = TIER_BLURBS[row["tier"]][0]
+ lines.append(f"| {name} | {tier} | " + " | ".join(cells) + " |")
+ return "\n".join(lines)
+
+
+def _tier_list() -> str:
+ return "\n".join(
+ f"- **{title}.** {body}" for title, body in (TIER_BLURBS[key] for key in TIER_BLURBS)
+ )
+
+
+def render() -> str:
+ rows = agent_rows()
+ counts = tool_counts()
+ ids = ", ".join(f"`{row['id']}`" for row in rows)
+ good = [row["display_name"] for row in rows if row["tier"] == "good"]
+
+ parts = [
+ "# Agent integrations",
+ "",
+ "<!-- Generated by scripts/gen_agent_matrix.py. Do not edit by hand: run",
+ " `python scripts/gen_agent_matrix.py` after changing a descriptor. -->",
+ "",
+ "Anything that speaks MCP can read a repowise index. This page is about how",
+ "*deeply* each agent is wired, which is a different question, and the one",
+ "every breadth claim in this space gets wrong.",
+ "",
+ "## Tiers",
+ "",
+ "The tier is **derived from the code, never declared**. A descriptor reaches",
+ "Full only by naming both a hook adapter and a transcript adapter, so no",
+ "document can claim a depth the integration does not have.",
+ "",
+ _tier_list(),
+ "",
+ "## The matrix",
+ "",
+ "`Yes` means repowise wires it. `Plugin` means the host's own plugin ships",
+ "it and repowise does not write it. `No` means the surface does not exist",
+ "for that agent.",
+ "",
+ _matrix_table(rows),
+ "",
+ f"Target ids for `--target=`: {ids}.",
+ "",
+ ]
+
+ if good:
+ names = " and ".join(good) if len(good) < 3 else ", ".join(good)
+ parts += [
+ "### What Good tier does not include",
+ "",
+ f"{names} sits at Good, and the honest version of that is worth stating",
+ "plainly. These agents get the MCP tools and the config repowise writes.",
+ "They do **not** get hook-level interception: repowise never sees a tool",
+ "call before it runs, never rewrites a noisy command, and never annotates",
+ "a result afterwards. Nor is there transcript mining, so nothing learns",
+ "from the session after it ends.",
+ "",
+ "That is a real integration and it is most of the value. It is not the",
+ "same product Full-tier agents get, and breadth that overclaims depth is",
+ "worse than narrower breadth.",
+ "",
+ ]
+
+ parts += [
+ "## Paste-config",
+ "",
+ "Every other MCP host is served without writing a descriptor for it. Print",
+ "the server entry and paste it into whatever config that host reads:",
+ "",
+ "```bash",
+ "repowise agents print-config claude-code # prints, writes nothing",
+ "```",
+ "",
+ "That emits an `mcpServers` block, which is the shape Cursor, Cline, Windsurf,",
+ "Zed and most others read. Ask for `vscode` instead when the host follows VS",
+ "Code: that one keys on `servers` and adds a `type` field inside each entry, so",
+ "it is not the same text with a different wrapper. Print the one that matches",
+ "your host rather than editing either by hand. Hosts people ask about most,",
+ "none of which repowise writes config for today:",
+ "",
+ ", ".join(PASTE_CONFIG_HOSTS) + ".",
+ "",
+ "`print-config` takes one of the target ids above; there is no descriptor to",
+ "name for a host at this tier, which is the point of the tier.",
+ "",
+ "## The MCP surface",
+ "",
+ textwrap.fill(
+ f"repowise registers **{spell(counts['total'])} MCP tools**. A single-repo "
+ f"server advertises **{spell(counts['single_repo'])}** of them by default, "
+ f"and workspace mode adds {spell(counts['workspace_extra'])} more "
+ f"automatically for **{spell(counts['workspace'])}**. A further "
+ f"**{spell(counts['opt_in'])}** are off by default, enabled through the "
+ "`mcp.tools` config block or `--tools +name`. The `lean` profile trims the "
+ f"default surface to **{spell(counts['lean'])}** tools "
+ f"({spell(counts['lean_workspace'])} in workspace mode) for agents on a "
+ "tight context budget.",
+ width=_WRAP,
+ ),
+ "",
+ "Per-tool detail: [MCP_TOOLS.md](MCP_TOOLS.md).",
+ "",
+ "## Adding an agent",
+ "",
+ "**Adding an agent takes one descriptor file and one registry line.**",
+ "",
+ "1. Write `packages/cli/src/repowise/cli/agent_targets/targets/<id>.py`",
+ " exporting a `TARGET` that satisfies the `AgentTarget` protocol in",
+ " [`types.py`](../../packages/cli/src/repowise/cli/agent_targets/types.py).",
+ " `vscode.py` is the smallest working example, at one install method and",
+ " one config file.",
+ "2. Add one line to `_TARGET_MODULES` in",
+ " [`registry.py`](../../packages/cli/src/repowise/cli/agent_targets/registry.py).",
+ " Order there is the order agents appear in prompts, in `--target=all` and",
+ " in listings, so keep it stable.",
+ "3. Run `python scripts/gen_agent_matrix.py` to add the row here.",
+ "",
+ "There is no third file for anything derived. The tier, this matrix and the",
+ "`repowise agents` listing all read the descriptor, and the contract tests in",
+ "`tests/unit/cli/test_agent_targets.py` are parameterized over the registry,",
+ "so a new target inherits them.",
+ "",
+ "The README badge rows are the exception: a brand colour and a logo per agent",
+ "are not derivable, and the README is not generated, so a new agent needs a",
+ "badge added by hand and the count above them updated. That is checked rather",
+ "than trusted. `tests/unit/cli/test_agent_matrix.py` fails when the badge rows",
+ "and the registry disagree, and names what to add.",
+ "",
+ "Declare only what the agent genuinely has. `derive_tier` reads the adapter",
+ "names, so a descriptor that names a hook adapter it has not implemented",
+ "publishes a Full-tier claim on this page.",
+ "",
+ ]
+ return "\n".join(parts).rstrip("\n") + "\n"
+
+
+def rendered_files() -> dict[Path, str]:
+ """Every generated file, mapped to the text it should hold."""
+ return {OUTPUT: render()}
+
+
+# ---------------------------------------------------------------------------
+# Write
+# ---------------------------------------------------------------------------
+
+
+def write_if_changed(path: Path, text: str) -> bool:
+ """Write *text* as LF, and report whether it moved the file.
+
+ Normalises the file's line endings before comparing, because this repo is
+ checked out with ``core.autocrlf`` on Windows and an untouched generated
+ file reads back as CRLF. Git stores LF either way.
+ """
+ if path.exists() and path.read_text(encoding="utf-8").replace("\r\n", "\n") == text:
+ return False
+ path.parent.mkdir(parents=True, exist_ok=True)
+ with open(path, "w", encoding="utf-8", newline="\n") as handle:
+ handle.write(text)
+ return True
+
+
+def main(argv: list[str] | None = None) -> int:
+ parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+ parser.add_argument(
+ "--check",
+ action="store_true",
+ help="report drift and exit non-zero instead of writing",
+ )
+ args = parser.parse_args(argv)
+
+ files = rendered_files()
+ drifted: list[Path] = []
+ for path in sorted(files):
+ text = files[path]
+ if args.check:
+ current = (
+ path.read_text(encoding="utf-8").replace("\r\n", "\n") if path.exists() else None
+ )
+ if current != text:
+ drifted.append(path)
+ elif write_if_changed(path, text):
+ drifted.append(path)
+
+ verb = "stale" if args.check else "wrote"
+ for path in drifted:
+ print(f"{verb}: {path.relative_to(ROOT).as_posix()}")
+ if args.check and drifted:
+ print(
+ f"\n{len(drifted)} generated file(s) disagree with the agent registry. "
+ "Run: python scripts/gen_agent_matrix.py",
+ file=sys.stderr,
+ )
+ return 1
+ if not drifted:
+ print("up to date" if args.check else "no changes")
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/scripts/gen_readme_hero.py b/scripts/gen_readme_hero.py
index 9329b1e22..6543cada7 100644
--- a/scripts/gen_readme_hero.py
+++ b/scripts/gen_readme_hero.py
@@ -254,6 +254,8 @@ add(f'<text x="{ex+22}" y="{ey+RH-25}" class="outsub">Captured nowhere else.</te
fx0, fy0 = ex + ew + GAP, ROW2
fw = W - PAD - fx0
card(fx0, fy0, fw, RH, "SERVED TO YOUR AGENT", "10 MCP tools")
+# All eleven of the single-repo default surface. The card headline counts them,
+# so a chip missing here is a picture that contradicts its own title.
tools = ["get_overview", "get_answer", "get_context", "get_symbol", "search_codebase",
"get_risk", "get_change_risk", "get_why", "get_dead_code", "get_health"]
tx, ty = fx0 + 20, fy0 + 54
diff --git a/server.json b/server.json
index 11da350dc..855a5e945 100644
--- a/server.json
+++ b/server.json
@@ -8,12 +8,12 @@
"source": "github"
},
"websiteUrl": "https://www.repowise.dev",
- "version": "0.17.1",
+ "version": "0.41.0",
"packages": [
{
"registryType": "pypi",
"identifier": "repowise",
- "version": "0.17.1",
+ "version": "0.41.0",
"transport": {
"type": "stdio"
},
@@ -26,8 +26,8 @@
{
"type": "positional",
"valueHint": "repo_path",
- "description": "Absolute path to the repository to serve (must be indexed first with `repowise init`)",
- "isRequired": true,
+ "description": "Path to the repository to serve, indexed first with `repowise init`. Optional: if omitted, the server serves the nearest indexed repository at or above the working directory, falling back to the working directory itself when there is none.",
+ "isRequired": false,
"format": "filepath"
},
{
diff --git a/tests/unit/cli/test_agent_matrix.py b/tests/unit/cli/test_agent_matrix.py
new file mode 100644
index 000000000..d494a4d03
--- /dev/null
+++ b/tests/unit/cli/test_agent_matrix.py
@@ -0,0 +1,411 @@
+"""The agent support matrix and every published tool count stay true to the code.
+
+Two guards, and they cover different failure modes.
+
+The first is the ordinary golden: ``docs/agent/INTEGRATIONS.md`` on disk must equal
+what ``scripts/gen_agent_matrix.py`` renders. Asserted against the **file**, never
+against the generator's return value, for the reason the plugin-content golden
+already writes down: a renderer can be perfectly correct about text nobody ever
+wrote to disk.
+
+The second is the one this whole exercise exists for. A generated doc protects
+itself and nothing else, and the tool count was never wrong in one place. It was
+wrong in six, including twice in the README two hundred lines apart, because every
+mention was hand-typed and no two were checked against each other. So the counts
+are computed from the live MCP registry and asserted **as exact phrases** against
+the artifacts in ``COUNT_CLAIMS``. Add a tool and this test names each file to edit.
+
+``COUNT_CLAIMS`` covers each sentence individually, not each file, so a file
+appearing in it is not evidence that every count it publishes is guarded. Adding a
+new count sentence anywhere means adding a row here. Release changelogs are
+excluded on purpose: they record what was true at the time.
+
+Accepted cost: the rows that match source docstrings are pinned to the current
+hard wrap, so re-flowing one of those docstrings turns this red. That is cheap to
+fix and the failure names the file and the exact phrase, which is a better trade
+than matching loosely enough to miss a real stale count.
+
+Phrases rather than a regex on purpose: several artifacts correctly say "the ten
+flagship tools", which is a deliberate subset of the eleven-tool default surface
+and not a stale count. A pattern loose enough to catch drift is loose enough to
+condemn those, and a test that cries wolf gets its assertion deleted.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import re
+import sys
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[3]
+
+
+def _generator():
+ """Load the generator by path; ``scripts/`` is not an importable package."""
+ path = ROOT / "scripts" / "gen_agent_matrix.py"
+ spec = importlib.util.spec_from_file_location("gen_agent_matrix", path)
+ assert spec and spec.loader
+ module = importlib.util.module_from_spec(spec)
+ sys.modules["gen_agent_matrix"] = module
+ spec.loader.exec_module(module)
+ return module
+
+
+GEN = _generator()
+COUNTS = GEN.tool_counts()
+
+
+def _on_disk(path: Path) -> str:
+ """Read *path* with line endings normalised.
+
+ The repo is checked out with ``core.autocrlf`` on Windows, so a generated
+ file reads back as CRLF while the generator renders LF. Git stores LF.
+ """
+ return path.read_text(encoding="utf-8").replace("\r\n", "\n")
+
+
+# ---------------------------------------------------------------------------
+# The generated matrix
+# ---------------------------------------------------------------------------
+
+
+ "path", sorted(GEN.rendered_files()), ids=lambda p: p.relative_to(ROOT).as_posix()
+)
+def test_the_generated_matrix_matches_the_registry(path: Path) -> None:
+ expected = GEN.rendered_files()[path]
+ assert path.exists(), (
+ f"{path.relative_to(ROOT).as_posix()} is missing. "
+ "Run: python scripts/gen_agent_matrix.py"
+ )
+ assert _on_disk(path) == expected, (
+ f"{path.relative_to(ROOT).as_posix()} has drifted from the agent registry. "
+ "Run: python scripts/gen_agent_matrix.py"
+ )
+
+
+def test_rendering_is_idempotent() -> None:
+ """``--check`` against a clean tree, which is what a contributor runs."""
+ assert GEN.main(["--check"]) == 0
+
+
+def test_every_registered_target_has_a_row() -> None:
+ """The table is the registry, not a subset of it."""
+ from repowise.cli.agent_targets import registry
+
+ text = _on_disk(GEN.OUTPUT)
+ for target in registry.all_targets():
+ assert f"| {target.display_name} |" in text or f"[{target.display_name}](" in text, (
+ f"{target.id} is registered but has no row in the matrix"
+ )
+ assert f"`{target.id}`" in text, f"{target.id} is missing from the target id list"
+
+
+def test_no_paste_config_host_is_secretly_a_registered_target() -> None:
+ """A host promoted to a real integration must leave the Paste-config list.
+
+ The Paste-config names are hand-authored, because a host we write no code
+ for has no descriptor to derive them from. This is the one way that list can
+ go stale: Phase 5 adds Cursor as a target and the doc keeps advertising it as
+ something we do not wire.
+ """
+ from repowise.cli.agent_targets import registry
+
+ known = {t.display_name.casefold() for t in registry.all_targets()}
+ known |= {t.id.casefold() for t in registry.all_targets()}
+ collisions = [name for name in GEN.PASTE_CONFIG_HOSTS if name.casefold() in known]
+ assert not collisions, (
+ f"{collisions} are registered targets and must be removed from "
+ "PASTE_CONFIG_HOSTS in scripts/gen_agent_matrix.py"
+ )
+
+
+def _readme_badge_rows() -> dict[str, set[str]]:
+ """Tier label to the set of badge alt texts under it, from README.md.
+
+ Scoped to the ``## Supported agents`` section, which is load-bearing rather
+ than tidy. A plain search of the whole README is satisfied by a badge
+ sitting anywhere at all, so it passes on a VS Code badge moved into the
+ Full-tier row, and it collides with the language block below (``alt="Go"``,
+ ``alt="Java"``), which would pre-satisfy any future agent sharing a name
+ with a language.
+ """
+ readme = _on_disk(ROOT / "README.md")
+ start = readme.index("## Supported agents")
+ section = readme[start : readme.index("\n## ", start + 1)]
+ rows: dict[str, set[str]] = {}
+ for block in re.findall(r"<p>(.*?)</p>", section, re.S):
+ label = re.search(r"<strong>(.*?)\s*(?:tier)?\s*&nbsp;</strong>", block)
+ if label is None:
+ continue
+ rows[label.group(1).strip()] = set(re.findall(r'alt="([^"]+)"', block))
+ return rows
+
+
+def test_the_readme_badge_rows_match_the_registry() -> None:
+ """The README badges are hand-maintained, so something has to check them.
+
+ Everything else about the tiers is derived, which makes the badges the one
+ place a fourth agent can be silently missing, or an old one can sit under
+ the wrong tier. They cannot be generated: a brand colour and a logo slug
+ per agent are editorial, and the README is not a generated file.
+ """
+ from repowise.cli.agent_targets import registry
+ from repowise.cli.agent_targets.types import derive_tier
+
+ expected: dict[str, set[str]] = {}
+ for target in registry.all_targets():
+ label = GEN.TIER_BLURBS[derive_tier(target).value][0]
+ expected.setdefault(label, set()).add(target.display_name)
+
+ found = _readme_badge_rows()
+ assert found == expected, (
+ f"README.md's agent badge rows are {found}, the registry says {expected}. "
+ "Every registered agent needs exactly one badge, under its own tier row, "
+ "in the '## Supported agents' section."
+ )
+
+
+def test_the_readme_agent_headline_counts_the_registry() -> None:
+ """The sentence above the badges is a count, and counts drift.
+
+ This is the same failure the tool count spent twenty-four releases in. A
+ headline that says three while the registry holds four is the version of it
+ that a reader meets first.
+ """
+ from repowise.cli.agent_targets import registry
+ from repowise.cli.agent_targets.types import Tier, derive_tier
+
+ targets = registry.all_targets()
+ full = [t for t in targets if derive_tier(t) is Tier.FULL]
+ expected = (
+ f"**{GEN.spell(len(targets)).capitalize()} agents wired end to end · "
+ f"{GEN.spell(len(full))} at the Full tier"
+ )
+ assert expected in _on_disk(ROOT / "README.md"), (
+ f"README.md does not open the agent section with {expected!r}. "
+ f"The registry holds {len(targets)} targets, {len(full)} of them Full tier."
+ )
+
+
+def test_the_hooks_column_cannot_lie() -> None:
+ """A target's declared HOOKS capability agrees with its hook adapter.
+
+ The matrix reads the capability; ``derive_tier`` reads the adapter name.
+ Nothing forced those two to agree, so a descriptor could publish a Hooks
+ column of `Yes` at Good tier, or Full tier with an empty Hooks column, and
+ both would render without complaint.
+ """
+ from repowise.cli.agent_targets import registry
+ from repowise.cli.agent_targets.types import Capability, capabilities_of
+
+ for target in registry.all_targets():
+ declares = Capability.HOOKS in capabilities_of(target)
+ assert declares == bool(target.hook_adapter), (
+ f"{target.id}: HOOKS capability is {declares} but hook_adapter is "
+ f"{target.hook_adapter!r}"
+ )
+
+
+# ---------------------------------------------------------------------------
+# Published tool counts
+# ---------------------------------------------------------------------------
+
+#: Every artifact that publishes an MCP tool count, and the exact phrase it must
+#: carry. ``{n}`` is the count as digits, ``{w}`` spelled out, ``{W}``
+#: capitalised. Keys name the count from :func:`gen_agent_matrix.tool_counts`.
+#:
+#: Deliberately not exhaustive over the repo: release changelogs record what was
+#: true at the time and must not be retro-edited, and the several artifacts that
+#: say "the ten flagship tools" are describing a documented subset rather than
+#: the default surface.
+COUNT_CLAIMS: tuple[tuple[str, str, str], ...] = (
+ # The README and the image at the top of it count the flagship tools, a
+ # narrower claim than the advertised surface. See NON_FLAGSHIP_TOOLS.
+ ("README.md", "flagship", "**{w} task-shaped MCP tools**"),
+ ("README.md", "flagship", "## The {w} MCP tools"),
+ ("README.md", "flagship", "#the-{w}-mcp-tools"),
+ ("README.md", "flagship", "decisions, and {w} MCP tools"),
+ ("README.md", "flagship", "{W} is a deliberate ceiling"),
+ ("docs/README.md", "flagship", "decisions, and {w} MCP tools"),
+ ("docs/README.md", "flagship", "The {w} task-shaped tools,"),
+ ("docs/agent/MCP_TOOLS.md", "total", "{n} tools are registered in total"),
+ ("docs/agent/MCP_TOOLS.md", "single_repo", "advertises {n} by default"),
+ ("docs/business/COMMERCIAL.md", "single_repo", "the {w} MCP tools,"),
+ ("docs/business/COMMERCIAL.md", "single_repo", "| {W} MCP tools |"),
+ ("docs/start/USER_GUIDE.md", "single_repo", "**{W} tools, task-shaped.**"),
+ ("docs/architecture/pluggable-storage.md", "single_repo", "{w} MCP tools still expose"),
+ ("website/mcp-server.md", "total", "It registers {n} tools:"),
+ ("website/mcp-server.md", "single_repo", "a curated {n}-tool default surface"),
+ ("packages/server/README.md", "total", "registers {n} MCP tools"),
+ ("packages/server/README.md", "single_repo", "advertises **{n} by default**"),
+ (".claude-plugin/marketplace.json", "single_repo", "{w} task-shaped MCP tools"),
+ (
+ "plugins/claude-code/.claude-plugin/plugin.json",
+ "single_repo",
+ "{w} task-shaped MCP tools",
+ ),
+ ("docs/agent/MCP_TOOLS.md", "single_repo", "**Default (single-repo):** {n} tools"),
+ ("docs/agent/MCP_TOOLS.md", "single_repo", "those {n} plus"),
+ ("docs/architecture/ARCHITECTURE.md", "single_repo", "advertises **{n}** tools by default"),
+ ("docs/reference/CLI_REFERENCE.md", "lean", "the {w}-tool agent-lean profile"),
+ ("packages/server/README.md", "total", "{n} registered MCP tools"),
+ ("packages/server/README.md", "single_repo", "({n} advertised by default"),
+ # The CLI help text is the copy every user reads, and it was the only place
+ # publishing the opt-in and lean counts outside a doc.
+ (
+ "packages/cli/src/repowise/cli/commands/mcp_cmd.py",
+ "single_repo",
+ "{w} by default in single-repo mode",
+ ),
+ (
+ "packages/cli/src/repowise/cli/commands/mcp_cmd.py",
+ "workspace_extra",
+ "plus {w} more by default",
+ ),
+ ("packages/cli/src/repowise/cli/commands/mcp_cmd.py", "opt_in", "{W} more are opt-in"),
+ # The lean count is written twice in this file, in the --tools help and in
+ # the worked example. One row matching either would let the other go stale,
+ # so each occurrence is pinned by the text around it.
+ (
+ "packages/cli/src/repowise/cli/commands/mcp_cmd.py",
+ "lean",
+ "{w}-tool agent-lean profile. Overrides",
+ ),
+ (
+ "packages/cli/src/repowise/cli/commands/mcp_cmd.py",
+ "lean",
+ "--tools lean # {w}-tool agent-lean profile",
+ ),
+ ("scripts/gen_readme_hero.py", "flagship", '"{n} MCP tools"'),
+ ("scripts/gen_readme_hero.py", "flagship", "decisions, and {w} MCP tools"),
+ (".github/assets/one-index.svg", "flagship", "{n} MCP tools"),
+ (".github/assets/one-index.svg", "flagship", "decisions, and {w} MCP tools"),
+ (".github/assets/one-index-dark.svg", "flagship", "{n} MCP tools"),
+ (".github/assets/one-index-dark.svg", "flagship", "decisions, and {w} MCP tools"),
+)
+
+
+def test_the_flagship_set_is_a_real_subset_of_the_default_surface() -> None:
+ """Removing a name that is not there would silently do nothing.
+
+ ``flagship`` is the default surface minus :data:`NON_FLAGSHIP_TOOLS`. If a
+ tool in that set is renamed or made opt-in, the subtraction stops removing
+ anything and the README's ten quietly becomes the surface's eleven, which
+ is precisely the drift this file exists to catch.
+ """
+ from repowise.core.registry import mcp_tool_registry
+ from repowise.server.mcp_server import ensure_full_surface
+ from repowise.server.mcp_server._tool_selection import resolve_enabled_tools
+
+ ensure_full_surface()
+ default = resolve_enabled_tools(mcp_tool_registry.entries(), is_workspace=False)
+ absent = GEN.NON_FLAGSHIP_TOOLS - default
+ assert not absent, (
+ f"{sorted(absent)} are excluded from the flagship count but are not in the "
+ "default surface, so excluding them does nothing. Update NON_FLAGSHIP_TOOLS "
+ "in scripts/gen_agent_matrix.py."
+ )
+ assert COUNTS["flagship"] == COUNTS["single_repo"] - len(GEN.NON_FLAGSHIP_TOOLS)
+
+
+def test_the_readme_tool_table_lists_exactly_the_flagship_tools() -> None:
+ """The count above the table and the rows in it are one claim, not two.
+
+ This is how the README drifted: a row was added for `list_repos` and the
+ heading followed it to eleven while the pitch above stayed at ten. A phrase
+ guard on the heading alone would have called that consistent.
+ """
+ readme = _on_disk(ROOT / "README.md")
+ heading = f"## The {GEN.spell(COUNTS['flagship'])} MCP tools"
+ start = readme.index(heading)
+ section = readme[start : readme.index("\n## ", start + 1)]
+ listed = re.findall(r"^\| `([a-z_]+)\(", section, re.M)
+ assert len(listed) == COUNTS["flagship"], (
+ f"README.md's tool table lists {len(listed)} tools ({listed}) but the "
+ f"flagship count is {COUNTS['flagship']}."
+ )
+ excluded = sorted(set(listed) & GEN.NON_FLAGSHIP_TOOLS)
+ assert not excluded, (
+ f"{excluded} is excluded from the README's count but has a row in its table."
+ )
+
+
+ "relpath", [".github/assets/one-index.svg", ".github/assets/one-index-dark.svg"]
+)
+def test_the_hero_image_draws_as_many_tools_as_it_claims(relpath: str) -> None:
+ """The card headline and the chips under it are the same claim.
+
+ They came apart once already: the headline moved and the chip list did not,
+ so the first image in the README said eleven over ten chips.
+ """
+ svg = _on_disk(ROOT / relpath)
+ chips = re.findall(r'<text[^>]*class="mono"[^>]*>([^<]+)</text>', svg)
+ assert len(chips) == COUNTS["flagship"], (
+ f"{relpath} draws {len(chips)} tool chips ({chips}) against a headline of "
+ f"{COUNTS['flagship']}. Fix the list in scripts/gen_readme_hero.py and "
+ "regenerate both themes."
+ )
+
+
+def _phrase(template: str, count: int) -> str:
+ word = GEN.spell(count)
+ return template.format(n=count, w=word, W=word.capitalize())
+
+
+def _appears(phrase: str, text: str) -> bool:
+ """Whether *phrase* occurs in *text* as a whole token, not as a tail.
+
+ A plain substring test reports "7 tools are registered in total" inside "17
+ tools are registered in total", which condemns the correct sentence for
+ containing the digits of a wrong one.
+ """
+ return re.search(r"(?<![0-9A-Za-z])" + re.escape(phrase), text) is not None
+
+
+ ("relpath", "key", "template"),
+ COUNT_CLAIMS,
+ ids=[f"{rel}:{tmpl}" for rel, _, tmpl in COUNT_CLAIMS],
+)
+def test_a_published_tool_count_matches_the_registry(
+ relpath: str, key: str, template: str
+) -> None:
+ path = ROOT / relpath
+ assert path.exists(), f"{relpath} is named in COUNT_CLAIMS but does not exist"
+ expected = _phrase(template, COUNTS[key])
+ assert expected in _on_disk(path), (
+ f"{relpath} does not say {expected!r}. The live MCP surface is "
+ f"{COUNTS['total']} tools registered, {COUNTS['single_repo']} advertised in "
+ f"single-repo mode, {COUNTS['workspace']} in workspace mode. Update the file, "
+ "then regenerate docs/agent/INTEGRATIONS.md and the README hero SVGs."
+ )
+
+
+ ("relpath", "key", "template"),
+ COUNT_CLAIMS,
+ ids=[f"{rel}:{tmpl}" for rel, _, tmpl in COUNT_CLAIMS],
+)
+def test_no_artifact_still_carries_a_superseded_tool_count(
+ relpath: str, key: str, template: str
+) -> None:
+ """The same sentence with a different number must not survive alongside it.
+
+ The README held both "ten task-shaped MCP tools" and "The eleven MCP tools"
+ at once, so asserting the right phrase is present would have passed on it.
+ A stale count is usually a second copy of a sentence, not a missing one.
+ """
+ text = _on_disk(ROOT / relpath)
+ stale = [
+ _phrase(template, other)
+ # Every count the generator can spell, which is the set a hand-edit
+ # could plausibly have left behind.
+ for other in sorted(GEN._WORDS)
+ if other != COUNTS[key] and _appears(_phrase(template, other), text)
+ ]
+ assert not stale, f"{relpath} still carries a superseded count: {stale}"
diff --git a/tests/unit/test_release_manifests.py b/tests/unit/test_release_manifests.py
new file mode 100644
index 000000000..a7a6d8e6d
--- /dev/null
+++ b/tests/unit/test_release_manifests.py
@@ -0,0 +1,116 @@
+"""The manifests a release has to bump stay in step with the package version.
+
+``server.json`` is the MCP registry manifest, and it sat at 0.17.1 against a
+0.41.0 package for roughly twenty-four releases. The cause was not carelessness:
+nothing in the release process named it, so there was no moment at which anyone
+was supposed to notice. This test is the half of the fix that does not depend on
+anyone reading a checklist. The files below are the complete set that must move
+with ``pyproject.toml``, so a red run here names exactly what to bump.
+
+Deliberately out of scope:
+
+* ``plugins/codex/.codex-plugin/plugin.json`` rides its own cadence by decision,
+ bumped only in releases where the Codex plugin shipped changes, so it is
+ correct for it to differ here.
+* ``packages/vscode/package.json`` is an independent version line with its own
+ tag namespace.
+
+``server.json`` also has to stay factually true about the CLI it describes, not
+just current. It told installers the repository path was required while
+``repowise mcp`` has accepted no argument since long before, so the registry
+published a stricter invocation than the ``.mcp.json`` we generate, the README
+and both plugins. A version bump would not have caught that.
+"""
+
+from __future__ import annotations
+
+import json
+import tomllib
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def _read_json(relpath: str) -> dict:
+ return json.loads((ROOT / relpath).read_text(encoding="utf-8"))
+
+
[email protected](scope="module")
+def package_version() -> str:
+ with open(ROOT / "pyproject.toml", "rb") as handle:
+ return tomllib.load(handle)["project"]["version"]
+
+
+def _versions_under_test() -> list[tuple[str, str]]:
+ """(label, dotted lookup) for every manifest that tracks the package."""
+ return [
+ ("server.json", "version"),
+ ("server.json", "packages.0.version"),
+ (".claude-plugin/marketplace.json", "plugins.0.version"),
+ ("plugins/claude-code/.claude-plugin/plugin.json", "version"),
+ ]
+
+
+def _dig(data: object, dotted: str) -> object:
+ for part in dotted.split("."):
+ data = data[int(part)] if part.isdigit() else data[part] # type: ignore[index]
+ return data
+
+
[email protected](("relpath", "dotted"), _versions_under_test())
+def test_a_release_manifest_tracks_the_package_version(
+ relpath: str, dotted: str, package_version: str
+) -> None:
+ found = _dig(_read_json(relpath), dotted)
+ assert found == package_version, (
+ f"{relpath} {dotted} is {found!r}, pyproject.toml is {package_version!r}. "
+ "Every file this module names has to move together in a release commit."
+ )
+
+
+ "module_path",
+ [
+ "packages/cli/src/repowise/cli/__init__.py",
+ "packages/core/src/repowise/core/__init__.py",
+ "packages/server/src/repowise/server/__init__.py",
+ ],
+)
+def test_a_package_dunder_version_tracks_pyproject(
+ module_path: str, package_version: str
+) -> None:
+ text = (ROOT / module_path).read_text(encoding="utf-8")
+ assert f'__version__ = "{package_version}"' in text, (
+ f"{module_path} does not carry __version__ = {package_version!r}"
+ )
+
+
+def test_the_registry_manifest_describes_the_cli_it_ships() -> None:
+ """Every argument ``server.json`` publishes matches ``repowise mcp``.
+
+ An installer reading the registry gets this manifest and nothing else, so a
+ stale claim here is not a doc bug, it is a wrong install command.
+ """
+ from repowise.cli.commands.mcp_cmd import mcp_command
+
+ params = {param.name: param for param in mcp_command.params}
+ arguments = _dig(_read_json("server.json"), "packages.0.packageArguments")
+ assert isinstance(arguments, list)
+
+ subcommand = arguments[0]
+ assert subcommand["value"] == mcp_command.name, (
+ "server.json invokes a different subcommand than the CLI registers"
+ )
+
+ repo_path = next(arg for arg in arguments if arg.get("valueHint") == "repo_path")
+ assert repo_path["isRequired"] == params["path"].required, (
+ "server.json and the CLI disagree on whether the repository path is required"
+ )
+
+ transport = next(arg for arg in arguments if arg.get("name") == "--transport")
+ assert transport["value"] == params["transport"].default, (
+ "server.json pins a --transport value the CLI does not default to"
+ )
+ assert transport["value"] in params["transport"].type.choices