ActiveMemory · josealekhine · May 24, 2026 · May 23, 2026 · May 23, 2026 · May 23, 2026
@@ -3,6 +3,7 @@
 <!-- INDEX:START -->
 | Date | Decision |
 |----|--------|
+| 2026-05-23 | Skill body text uses capability-first language with canonical tools as examples; install-guide docs name canonical implementations; `allowed-tools` frontmatter stays MCP-specific |
 | 2026-05-23 | MCP gateway not worth the coupling cost; companion tools stay peer-MCP and remain not-vouched-for-by-ctx |
 | 2026-05-23 | Keep `i18n.Fold` strict; add `i18n.MatchKey` as the separate diacritic-insensitive primitive |
 | 2026-05-22 | OpenCode plugin: agent shell tool not anchored to project root under cwd-anchored |
@@ -150,6 +151,48 @@ For significant decisions:
 
 -->
 
+## [2026-05-23-030000] Skill body text uses capability-first language with canonical tools as examples; install-guide docs name canonical implementations; `allowed-tools` frontmatter stays MCP-specific
+
+**Status**: Accepted
+
+**Context**: The 2026-05-23 "MCP gateway not worth the coupling cost" decision rejected pluggable abstraction over companion tools at the code/protocol layer (no gateway, no plugin registry). But that decision left an open question: skill body text was still hard-coding specific tool names (GitNexus, Gemini Search), and so were several `docs/` pages. The hard-coding is *its own* form of vouching — just static prescription instead of dynamic dispatch. A user with Firecrawl / sourcegraph-cody / vLLM read the skill and saw instructions naming tools they don't have; the agent couldn't self-route because the skill text told it to use specific MCP server names.
+
+Three rule choices were considered for the body-text layer:
+
+1. Pluggable abstraction with `.ctxrc`-declared capability mapping — rejected by the prior decision (it IS the interface-contract ownership cost we ruled out).
+2. Per-tool skill variants (`ctx-architecture-enrich-gitnexus`, `…-sourcegraph`, …) — explodes the skill count without removing the prescription, just sliced thinner.
+3. **Capability-first body text with canonical tools as examples** — chosen.
+
+A parallel question existed for `docs/`: an install guide LEGITIMATELY names tools (its job is "tell me what to install"). Genericizing install commands would harm newcomers. The right split: operational/descriptive docs use the same capability-first phrasing as skills; install-guide docs name canonical implementations explicitly, with a one-liner noting equivalents work.
+
+The `allowed-tools` frontmatter is a separate concern. Genericizing to `mcp__*` would grant skills access to EVERY connected MCP — a permission expansion, not a cosmetic change. Operators with different toolchains edit `allowed-tools` in their local skill copy or fork. A separate spec can revisit if needed.
+
+**Decision**: Three layered rules.
+
+1. **Skill body text** uses capability-first language ("a code-intelligence MCP", "a web-search-with-citations MCP") with the canonical implementation listed as an example ("canonical: GitNexus; equivalents include sourcegraph-cody"). Operational example calls (e.g. `mcp__gitnexus__impact({…})`) stay as canonical-impl illustrations.
+2. **Install-guide docs** (`docs/home/getting-started.md`, `docs/recipes/multi-tool-setup.md`) name canonical implementations directly and provide concrete setup commands. A preamble notes that equivalents work for non-canonical toolchains.
+3. **`allowed-tools` frontmatter** stays MCP-specific. Skills ship with `mcp__gitnexus__*`, `mcp__gemini-search__*` in the allowlist. Operators using different MCP servers edit the allowlist in their local skill copies.
+
+**Rationale**: Three reinforcing properties:
+
+- **Manifesto-aligned.** ctx no longer prescribes specific tools in skill bodies. Agents self-route based on what's connected.
+- **No new abstraction layer.** Pure text rewrite. Zero code change, zero interface contract, zero coupling.
+- **Discoverability preserved.** Canonical tools stay first-listed in every section so newcomers immediately learn what to install if they're starting from zero.
+
+Alternatives explicitly rejected: code-level pluggability (2026-05-23 MCP-gateway decision); per-tool skill variants (maintenance explosion without solving the smell); "remove all tool names" (loses discoverability for new users who do want a recommendation).
+
+**Consequence**:
+
+- Eight skill files updated (commit f554f758): ctx-refactor, ctx-explain, ctx-code-review, ctx-remember (claude + copilot-cli), ctx-architecture, ctx-architecture-enrich, ctx-architecture-failure-analysis. Prescriptive references to specific tools rewritten as capability-first with canonical examples.
+- Six docs updated alongside (this commit): architecture-exploration runbook, architecture-deep-dive recipe, skills.md reference, cli/index.md schema, getting-started.md install guide, multi-tool-setup.md recipe.
+- `specs/skill-audit-companion-tool-neutrality.md` documents the per-file rewrites and the install-guide-vs-operational split for future contributors.
+- New skill authors follow this rule: describe the capability, name the canonical implementation as an example, leave `allowed-tools` MCP-specific.
+- If a real second-viable graph-tool ecosystem emerges and operators consistently ask for pluggable `allowed-tools`, the prior MCP-gateway decision can be revisited; the present decision doesn't preclude that future evolution.
+
+See also: `specs/skill-audit-companion-tool-neutrality.md`, `specs/ctx-remember-silent-companion-fallback.md` (the install-nag fix that preceded this audit), the 2026-05-23 "MCP gateway not worth the coupling cost" decision above.
+
+---
+
 ## [2026-05-23-020000] MCP gateway not worth the coupling cost; companion tools stay peer-MCP and remain not-vouched-for-by-ctx
 
 **Status**: Accepted

@@ -198,7 +198,7 @@ hooks:                       # Hook system configuration
 | `archive_after_days`    | `int`      | `7`            | Days before completed tasks are archived                                                                       |
 | `scratchpad_encrypt`    | `bool`     | `true`         | Encrypt scratchpad with AES-256-GCM                                                                            |
 | `event_log`             | `bool`     | `false`        | Enable local hook event logging to `.context/state/events.jsonl`                                               |
-| `companion_check`       | `bool`     | `true`         | Check companion tool availability (Gemini Search, GitNexus) during `/ctx-remember`                             |
+| `companion_check`       | `bool`     | `true`         | Check companion tool availability (canonical: Gemini Search, GitNexus; equivalents work) during `/ctx-remember`|
 | `entry_count_learnings` | `int`      | `30`           | Drift warning when `LEARNINGS.md` exceeds this count                                                           |
 | `entry_count_decisions` | `int`      | `20`           | Drift warning when `DECISIONS.md` exceeds this count                                                           |
 | `convention_line_count` | `int`      | `200`          | Line count warning for `CONVENTIONS.md`                                                                        |

@@ -314,27 +314,34 @@ or previous session topics.
 
 ### 7. Set Up Companion Tools (Highly Recommended)
 
-`ctx` works on its own, but two companion MCP servers unlock significantly
-better agent behavior. The investment is small and the benefits compound
-over sessions:
-
-* **[Gemini Search](https://github.com/nicobailon/gemini-code-search-mcp)**
-: grounded web search with citations. Skills like `/ctx-code-review`
-  and `/ctx-explain` use it for up-to-date documentation lookups instead
-  of relying on training data.
-
-* **[GitNexus](https://github.com/nicobailon/gitnexus-mcp)**: code
-  knowledge graph with symbol resolution, blast radius analysis, and
-  domain clustering. Skills like `/ctx-refactor` and `/ctx-code-review`
+`ctx` works on its own, but two MCP capabilities unlock significantly
+better agent behavior. ctx names canonical implementations below as
+its tested defaults; if your toolchain provides the same capabilities
+through different MCP servers (Firecrawl / Exa / Tavily for web
+search; sourcegraph-cody for the code graph), use those instead.
+The investment is small and the benefits compound over sessions:
+
+* **Web search with citations** — canonical:
+  **[Gemini Search](https://github.com/nicobailon/gemini-code-search-mcp)**.
+  Skills like `/ctx-code-review` and `/ctx-explain` use it for
+  up-to-date documentation lookups instead of relying on training data.
+
+* **Code knowledge graph** — canonical:
+  **[GitNexus](https://github.com/nicobailon/gitnexus-mcp)**.
+  Provides symbol resolution, blast radius analysis, and domain
+  clustering. Skills like `/ctx-refactor` and `/ctx-code-review`
   use it for impact analysis and dependency awareness.
 
 ```bash
 # Index your project for GitNexus (run once, then after major changes)
 npx gitnexus analyze
 ```
 
-Both are optional MCP servers: if they are not connected, skills degrade
-gracefully to built-in capabilities. See
+(For non-GitNexus code-intelligence MCPs, apply that tool's own
+indexing step instead.)
+
+Both capabilities are optional: if no compatible MCP is connected,
+skills degrade gracefully to built-in capabilities. See
 [Companion Tools](../recipes/multi-tool-setup.md#companion-tools-highly-recommended)
 for setup details and verification.
 

@@ -27,7 +27,8 @@ workspace directory (e.g., `~/WORKSPACE/`).
 **Companion skills**:
 
 - `/ctx-architecture`: structural baseline and principal analysis
-- `/ctx-architecture-enrich`: code intelligence enrichment via GitNexus
+- `/ctx-architecture-enrich`: code intelligence enrichment via a
+  code-intelligence MCP (canonical: GitNexus)
 - `/ctx-architecture-failure-analysis`: adversarial failure analysis
 
 ---
@@ -109,7 +110,7 @@ Each repo progresses through these phases in order:
 |-------|-------|-------------|
 | `bootstrap` | `ctx init` + `/ctx-architecture` | None |
 | `principal` | `/ctx-architecture principal` | bootstrap done |
-| `enriched` | `/ctx-architecture-enrich` | principal done, GitNexus indexed |
+| `enriched` | `/ctx-architecture-enrich` | principal done, code-intelligence MCP indexed (canonical: GitNexus) |
 | `frontier-N` | `/ctx-architecture` (re-run) | enriched done |
 
 **`bootstrap` is a single composite unit:** `ctx init` followed by
@@ -166,10 +167,12 @@ focus as input upfront.
     - Run `/ctx-architecture` (add `principal` argument for principal phase).
     - The skill will read existing artifacts and build on them.
 5. If phase is `enriched`:
-    - Verify GitNexus is connected: call `mcp__gitnexus__list_repos`.
+    - Verify a code-intelligence MCP is connected. Canonical
+      smoke test: `mcp__gitnexus__list_repos` (or the equivalent
+      smoke test for your configured tool).
     - Success = non-empty list returned with no error.
-    - If GitNexus unavailable, log as `enriched-skipped` and advance
-      to `frontier-1`.
+    - If no code-intelligence MCP is available, log as
+      `enriched-skipped` and advance to `frontier-1`.
     - Run `/ctx-architecture-enrich`.
 6. If phase is a lens run (`lens-security`, etc.):
     - Run `/ctx-architecture` with lens focus prepended as instruction
@@ -255,8 +258,9 @@ it, produce no further output. Execution is complete.
    already recorded as completed, skip it.
 4. **Log everything.** Every run gets a run-log entry, even failures
    and skips.
-5. **Fail gracefully.** If a skill fails (missing GitNexus, broken repo,
-   etc.), log the failure with reason and advance to the next phase or
+5. **Fail gracefully.** If a skill fails (no code-intelligence MCP
+   connected, broken repo, etc.), log the failure with reason and
+   advance to the next phase or
    repo. Don't retry in the same invocation.
 6. **Respect `ctx` conventions.** Each repo gets its own `.context/`
    directory. Never write architecture artifacts outside `.context/`.
@@ -326,9 +330,10 @@ right project root.
 
 - **Start small**: list 1-2 repos in the manifest first. Add more
   once you're confident in the output quality.
-- **GitNexus is optional**: the enrichment phase is skipped
-  gracefully if GitNexus isn't connected. You still get structural
-  and principal analysis.
+- **The code-intelligence MCP is optional**: the enrichment phase
+  is skipped gracefully if no such MCP is connected (canonical:
+  GitNexus; equivalents work). You still get structural and
+  principal analysis.
 - **Review between batches**: check the run-log and generated
   artifacts between batch runs. The agent is additive-only, but
   early course correction saves wasted runs.

@@ -84,7 +84,8 @@ dependencies).
 ```
 
 Takes the Pass 1 artifacts as baseline and layers on verified,
-graph-backed data from GitNexus:
+graph-backed data from a code-intelligence MCP (canonical:
+GitNexus; equivalents include sourcegraph-cody):
 
 - Blast radius numbers for key functions
 - Execution flow traces through hot paths
@@ -99,7 +100,9 @@ Z would affect 12 downstream consumers."
 **When to run**: After Pass 1, when you need quantified
 confidence for refactoring decisions or risk assessment.
 
-**Requires**: GitNexus MCP server connected.
+**Requires**: a code-intelligence MCP connected (canonical:
+GitNexus; equivalents work if they expose symbol-index,
+blast-radius, and execution-flow queries).
 
 ### Pass 3: Hunt for Failure Modes
 

@@ -403,6 +403,14 @@ benefits compound. Skills like `/ctx-code-review`, `/ctx-explain`,
 and `/ctx-refactor` all become noticeably better with these tools
 connected.
 
+The two sections below name **canonical implementations** that ctx has
+tested against — Gemini Search for web-search-with-citations and
+GitNexus for the code knowledge graph. If your toolchain provides
+equivalent capabilities through different MCP servers (Firecrawl,
+Exa, Tavily for web search; sourcegraph-cody for code graph), use
+those instead. ctx skills describe capabilities, not specific tools —
+the agent self-routes based on what's connected.
+
 ### Gemini Search
 
 Provides grounded web search with citations. Used by skills and the

@@ -618,8 +618,10 @@ Produces `.context/DANGER-ZONES.md` with ranked findings split
 into Critical (risk >= 7, silent/cascading) and Elevated tiers.
 
 **Wraps**: reads architecture artifacts, source code; writes
-`DANGER-ZONES.md`. Optionally uses GitNexus for blast radius
-and Gemini Search for cross-referencing known failure patterns.
+`DANGER-ZONES.md`. Optionally uses a code-intelligence MCP
+(canonical: GitNexus) for blast radius and a
+web-search-with-citations MCP (canonical: Gemini Search) for
+cross-referencing known failure patterns.
 
 **Relationship**:
 

@@ -30,8 +30,10 @@ to questions never asked.
 
 - After `/ctx-architecture` or `/ctx-architecture principal` has
   produced artifacts
-- After `npx gitnexus analyze --embeddings` completes on a project
-  that already has architecture artifacts
+- After a code-intelligence MCP has indexed the project
+  (canonical: GitNexus via `npx gitnexus analyze --embeddings`;
+  equivalents apply their own indexing step) and architecture
+  artifacts already exist
 - When the user says "enrich the architecture", "run enrichment
   pass", "add graph data", "quantify the danger zones"
 - When DANGER-ZONES.md exists but lacks blast radius numbers
@@ -42,8 +44,8 @@ to questions never asked.
 
 - As a substitute for `/ctx-architecture` - if no architecture
   artifacts exist, run `/ctx-architecture` first
-- When GitNexus MCP is not connected or the index is stale -
-  preflight will catch this
+- When no code-intelligence MCP is connected, or the index is
+  stale — preflight will catch this
 - Immediately after `/ctx-architecture` in the same session without
   user request - let the user review the base artifacts first
 
@@ -83,25 +85,36 @@ to generate the baseline, then run this skill to enrich it.
 
 ### 1.2 Verify Code Intelligence Tools
 
-Check each tool silently:
+Check each capability silently:
 
-**GitNexus** (required):
-- Call `mcp__gitnexus__list_repos` to verify connection
-- Check that the current project is indexed
-- Compare the index timestamp against the latest git commit to
-  detect staleness
+**Code-intelligence MCP** (required for this skill):
 
-If GitNexus is not connected or the project is not indexed:
+This skill's entire purpose is code-graph-verified enrichment,
+so it cannot run without a code-intelligence MCP. The canonical
+implementation is GitNexus (`mcp__gitnexus__list_repos`,
+`mcp__gitnexus__impact`, etc.); equivalents that expose the
+same capabilities (symbol index, blast-radius queries, indexed
+repo state) work equally well.
+
+- Attempt the smoke-test call for whichever code-intelligence
+  MCP your toolchain provides
+- For GitNexus specifically: also check that the current
+  project is indexed and compare the index timestamp against
+  the latest git commit to detect staleness
+
+If no code-intelligence MCP is connected:
 
 ```
-GitNexus is not connected (or this project is not indexed).
-This skill requires a code intelligence graph.
+This skill requires a code-intelligence MCP (e.g., GitNexus,
+sourcegraph-cody, or equivalent). None is connected.
 
-To set up: add the GitNexus MCP server, then run:
+If you have GitNexus, configure the MCP and run:
   npx gitnexus analyze --embeddings
+If you use a different code-intelligence MCP, configure it
+per its docs and re-run this skill.
 ```
 
-If the index is stale (commits after last index):
+For GitNexus, if the index is stale (commits after last index):
 
 - **≤ 5 commits behind**: warn and proceed.
   ```
@@ -117,10 +130,17 @@ If the index is stale (commits after last index):
   Run `npx gitnexus analyze` to update, then re-run this skill.
   ```
 
-**Gemini Search** (optional):
-- Attempt a simple query to verify connection
+(For non-GitNexus code-intelligence MCPs, apply the same
+staleness check using whatever the underlying tool exposes.)
+
+**Web-search-with-citations MCP** (optional):
+
+- Canonical example: Gemini Search
+  (`mcp__gemini-search__search_with_grounding`)
+- Equivalents: Firecrawl, Exa, Tavily, or any MCP that
+  returns grounded results with citations
 - If available: note silently, use for upstream pattern lookups
-- If not available: note silently, proceed without it
+- If not available: silently fall back to built-in web search
 
 ### 1.3 Read Baseline Artifacts