Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
docs: 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.jsonindex 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.mdindex 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 </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 </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 toolsEvery response carries an `_meta` envelope with `index_age_days`, `indexed_commit`, anda `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-shapedsurface is easier for an agent to choose from than a large one. Worked example (*"addrate limiting to all API endpoints"* in 5 calls instead of ~30 greps and reads), theopt-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.mdindex 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.mdnew file mode 100644index 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.mdindex 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 fromopen files. For editors that read a config file, run **Repowise: Configure MCPfor 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).+## SettingsThe fastest way to tune everything is **Repowise: Open Settings**, a paneldiff --git a/docs/architecture/pluggable-storage.md b/docs/architecture/pluggable-storage.mdindex 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 usersof 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 thedefaults; they don't replace them unless an integration explicitlyswaps an implementation in.diff --git a/docs/business/COMMERCIAL.md b/docs/business/COMMERCIAL.mdindex 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 forThe 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 teamneeds 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.mdindex 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 clientis 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-filetriage cards with callers and ownership, symbol source with exact bounds, riskassessment for a set of changed files, decision lookups and health scores, each inone call rather than a chain. What each one answers, and worked multi-tooldiff --git a/scripts/gen_agent_matrix.py b/scripts/gen_agent_matrix.pynew file mode 100644index 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.pyindex 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.</tefx0, fy0 = ex + ew + GAP, ROW2fw = W - PAD - fx0card(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 + 54diff --git a/server.json b/server.jsonindex 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.pynew file mode 100644index 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* </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.pynew file mode 100644index 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