@mmerterden/multi-agent-pipeline 13.5.0 → 14.0.0

package/CHANGELOG.md

@@ -16,6 +16,249 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [14.0.0] - 2026-07-29
+
+The `--dev` family reviews its own work, and review now checks the code against the
+criteria it was supposed to be built to instead of general good taste.
+
+Major because a command was renamed: `/multi-agent:finish` is now `/multi-agent:ship`.
+No alias is kept  -  `installCommands()` replaces the command tree wholesale, so a clean
+cut leaves nothing half-migrated.
+
+### Added
+
+- **Phase 4 Review runs in `dev`, `dev-autopilot`, `dev-local` and `dev-local-autopilot`.**
+  Phase sets become `0/3/4/5/6/7` for `dev` and `0/3/4/6/7` for the three variants, in
+  `gen-mode-dispatch.mjs` (the generator is the source of truth; the tracker sections are
+  regenerated from it, never hand-edited). Analysis and planning are still skipped: they
+  shape work that has not happened yet, so a task the user has already scoped can do
+  without them, while review judges work that now exists and has no substitute. Accepted
+  blocking findings return to Phase 3 under the existing 3-iteration hard kill; the
+  autopilot variants auto-fix without prompting and halt on the existing rework-storm
+  circuit breaker rather than committing. No new machinery for either  -  both were already
+  built and became reachable the moment Phase 4 entered the phase set.
+- **Phase 4 Step 1.78, criteria resolution** (`skill-conformance.mjs`, zero LLM). Resolves
+  which rule registries apply to this diff, scoped to its languages and paths, and writes
+  `criteria-manifest.json` BEFORE the reviewers run. That file is the denominator: reviewers
+  return one verdict per selected rule ID, so "did it apply this completely" is answerable
+  rather than inferred. A reviewer that opened nothing and one that checked everything
+  produce identical `findings` arrays, which is why the checklist exists.
+- **Registry discovery is declared, never sniffed by name.** A skill opts in with
+  `standards-registry: <path>` in its frontmatter, so the pipeline names no stack-specific
+  skill and a future UIKit, Objective-C, Kotlin or backend registry drops in with zero
+  pipeline change.
+- **Every registry declares its own `scope`** (`languages`, `paths`, `excludePaths`,
+  `notCovered`), and per-rule `scope` narrows it further. Measured before this landed: only
+  2 of the iOS registry's 99 rules carried any applicability field, and the rest wrote their
+  scope as English prose inside `mechanism`  -  so an Objective-C or UIKit diff would have
+  collected all 99 SwiftUI-shaped rules, manufacturing findings and burying the real ones.
+- `references/rules.yml` for `apple-archive-compliance` (18 rules) and
+  `google-play-compliance` (21), converted from their existing SKILL.md tables with IDs and
+  severities preserved. Registry count goes 1 -> 3, so discovery is genuinely
+  capability-based rather than one skill with extra steps.
+- **Exception-marker audit**: expired, reason-less, expiry-less, or unknown-ID
+  `standard:exception(...)` markers become rule-ID-bearing findings. The marker template is
+  read from the registry, never hardcoded, so a registry with different comment syntax works.
+- `state.telemetry.skillCalls[]`  -  Phase 3 records each skill, plugin skill and guide it
+  consulted, with the files it applied them to.
+- `prefs.global.skillConformance.blockOnCoverageGap` (default **false**) and
+  `prefs.global.ship.autoFix`, the latter referenced by the tail command's spec since it
+  shipped but never actually declared. Prefs schema 2.4.0 -> 2.5.0 with a migration that
+  carries any existing `finish.autoFix` value across the rename.
+- Gates: `smoke-dev-mode-review.sh`, `smoke-skill-conformance.sh` (26 checks),
+  `smoke-skills-root-resolution.sh`. `smoke-subagent-validators.sh` grew 10 checks for the
+  conformance contract; `smoke-mode-dispatch-drift.sh` grew a step that asserts the negative,
+  because its per-phase `grep -Fq` could not catch an ABSENT phase.
+
+### Changed
+
+- **`/multi-agent:finish` -> `/multi-agent:ship`.** "Finish" never said what it did. The
+  command takes work already sitting on a branch through review, a build+test gate, PR and
+  report; `ship` says that. With review now inside the dev modes, its remaining job is work
+  that had no pipeline run behind it, rather than a patch for a mode that skipped review.
+- **Reviewers cite rule IDs.** `reviewer-output.schema.json` 1.0.0 -> 1.1.0 adds `ruleId`,
+  `criteriaSource` and the per-rule `conformance[]` array; `triage-output.schema.json`
+  3.2.0 -> 3.3.0 carries both through triage. `code-reviewer.md` gains a `${CRITERIA}`
+  injection slot  -  the phase doc had claimed for some time that "skills are injected into
+  reviewer prompt context" while the agent definition had no slot for them, which is exactly
+  why review could not cite a rule.
+- `validate-reviewer.mjs` enforces the checklist with `--criteria`: a selected ID with no
+  verdict, a verdict for an ID that was never selected, a `conformant` row with no file
+  evidence, and a `violated` row with no matching finding all fail. Without this the field
+  would be decoration  -  the validator is hand-written and does not apply
+  `additionalProperties`, so any array at all would have passed.
+- `${CRITERIA}` lives in the shared cacheable prefix, identical for every reviewer.
+  Subsetting it per reviewer would invalidate the prefix for the whole panel and re-bill the
+  largest block in the phase.
+- Phase 4 no longer transcribes SwiftUI interaction and accessibility rules inline; they
+  resolve from the registry that declares SwiftUI scope, so criteria and severities live in
+  one place. This removed the drift the release exists to close, and reclaimed budget.
+- Phase 3's pre-flight no longer aborts unconditionally on a missing analysis document.
+  Steps that read that document are recorded `not-applicable (no Phase 1 in this mode)`,
+  which is what the `--dev` family always needed and never had.
+- `migrate-prefs.mjs` derives its migratable-version set instead of enumerating one
+  `else if` per version. The old chain had to be extended by hand whenever
+  `TARGET_VERSION` moved, and forgetting made the migrator throw `unknown schemaVersion`
+  on the exact version it had just been released to migrate from.
+- Token budget 51500 -> 52200, after 820 tokens were compressed first, per the note in
+  `token-budget.json`.
+
+### Fixed
+
+- **`ios-coding-standard` in the repo was a version behind the installed copy** (95 rules
+  v1.0.0 vs 99 rules v1.1.0). Because `installSkills()` copies the repo over the
+  destination, the next `/multi-agent:update` would have downgraded a user's registry  - 
+  harmless while nothing read it, a correctness regression the moment Phase 4 blocks on rule
+  IDs. Resynced to 99 rules.
+- `modules/*.yml` overlays and `references/EXAMPLES.md` are deliberately NOT shipped: they
+  quote real module paths, symbol names and call-site counts from one codebase, so a shipped
+  overlay would bind another project's dialect slots to the wrong dialect. `modules/_TEMPLATE.yml`
+  carries the shape instead, and the skill states that an unbound slot disables its rules
+  rather than defaulting silently.
+- `tracker-contract.md` contradicted itself on skipped phases: one section said to
+  `TaskCreate` every phase "even if it will be skipped in this mode", another said omitted
+  phases get no `TaskCreate` at all. The mode files and the generator follow the second, so
+  the example now matches it.
+- Three docs disagreed on whether `--dev` runs Phase 5. They now agree with the generator.
+- The dispatcher's modular-loading table had no row for `dev` or `dev-autopilot`.
+
+## [13.6.0] - 2026-07-28
+
+A review pass across the pipeline, the plugin marketplace and the companion MCP server.
+Every gate was green before it started: each defect below was invisible to the suite,
+and most were invisible because a gate asserted the wrong half of the contract. New
+gates are named per item.
+
+### Fixed
+
+- **The Tier 2 Figma PAT could not be found on any migrated install.** `migrate-prefs.mjs`
+  consolidated `keychainMapping.figma_pat` into `.figma` and deleted the old key, but the
+  setup wizard kept *writing* `figma_pat` (so the next migration deleted the mapping it
+  had just created), both Tier 2 fetchers kept *reading* it, and the failure text told the
+  user to map the one key guaranteed not to survive. Tier 2 reported `missing-token` while
+  a valid PAT sat under the new name. Claude Code's MCP tier masked it; Copilot and Codex,
+  which serve no Figma MCP tools at all, fell straight to Tier 3. The lookup now lives once
+  in `lib/figma-token.sh` (canonical `figma`, legacy `figma_pat` as a fallback) rather than
+  duplicated per fetcher, which is what let the two copies drift from the migration.
+  Gate: `smoke-credential-key-alignment.sh`.
+- **Claude Code installs registered no MCP server**, so every skill that reaches for a
+  `dev-toolkit` tool - `design-check`, the `ios_*` / `android_*` calls, the archive audits -
+  had nothing to call. Codex had registration from day one and Copilot gained it later;
+  Claude Code was last and easiest to miss, because a maintainer who registered it by hand
+  once sees a working tree forever. `--scope user` is not optional: `claude mcp add`
+  defaults to project scope, binding the server to whichever directory the installer ran
+  in. Uninstall now deregisters it too. The gate that existed to catch this iterated
+  `codex copilot`, so it structurally could not; the host list is now derived from the
+  installers on disk.
+- **`@mmerterden/dev-toolkit-mcp` was not on the public npm registry**, while all three
+  installers register `npx -y @mmerterden/dev-toolkit-mcp`, which resolves from it. GitHub
+  Packages answers 401 to unauthenticated reads even for public packages, so pointing npx
+  there is not an alternative. Registration never failed - it only writes host config - so
+  the break surfaced later as an E404 on first tool use, and only for users whose `~/.npmrc`
+  lacked a scope redirect. Published; `publishConfig` now matches the pipeline's.
+  Gate: `smoke-mcp-package-resolvable.sh`.
+- **157 instruction paths resolved only from a repo checkout.** `node pipeline/scripts/x.mjs`
+  works when cwd is this repo's root, which is never true during a run: the pipeline works
+  inside a worktree of the user's project. The class covered 85 script invocations (bare,
+  `node`-prefixed, env-prefixed, `&&`-chained), 16 skill references, 12 rules references,
+  and 4 files invoking `"$REPO_ROOT/pipeline/scripts/..."` where `$REPO_ROOT` was never
+  assigned anywhere in the pipeline. Gate: `smoke-install-relative-paths.sh`, which
+  enumerates the whole class rather than the instances.
+- **`dynamicSkillLoading` had never worked on an installed tree.** Three breaks stacked: a
+  full install did not ship `.skills-index.json` (while the schema said it always did),
+  `match-skills.mjs` resolved its default index to `$HOME/pipeline/skills/...` from
+  `~/.claude/scripts/`, and the runtime contract in the orchestrator invoked a
+  repo-relative path. Its own smoke passed `--index` explicitly and ran from the repo, so
+  it never exercised either failure. The index now ships on every install for all three
+  hosts via one shared helper.
+- **Two compliance skills were unreachable on Codex.** `apple-archive-compliance` and
+  `google-play-compliance` live in `skills/shared/core`, and Codex's installer copied only
+  `shared/external`. `smoke-compliance-skills.sh` asserted both were wired to four
+  consumers - reading the source tree, with no host awareness - so it passed while the host
+  had nothing to load. Gate: cross-host reachability parity in `smoke-install-layout.sh`.
+- **A plugin skill whose name a pipeline skill also owns was dropped on the copy hosts.**
+  Claude Code reaches both because its loader namespaces plugin skills; Copilot and Codex
+  copy flat, so the iOS toolkit's `architecture` (that stack's structural rules) was
+  silently unreachable behind the pipeline's generic ADR skill, as was its `backlog` and
+  the common toolkit's `index`. Clashes are now plugin-prefixed, the flat analogue of what
+  the loader does, so the pipeline keeps the bare name and nothing is lost.
+- **Plugin skills were frozen after their first install.** `skipNames` was a snapshot of
+  the destination, so a plugin skill matched its own previous copy and was skipped forever,
+  outliving every upstream fix in it. It is now the pipeline-owned set derived from the
+  source tree, and each plugin skill dir is wiped before refill so a file dropped upstream
+  does not linger.
+- **Copilot skills referenced trees Copilot does not install.** Its skills were copied
+  byte-for-byte, so 15 references pointed at `~/.claude/scripts` and `~/.claude/lib` -
+  absent on a Copilot-only machine. Codex has had this rewrite since its installer was
+  written. Copilot now rewrites the trees it owns, and installs `rules/` as well, closing
+  the same silent-nothing fallback Codex's installer already documented.
+- **`phase-tracker.sh` never reclaimed a stale lock on Linux.** It tried `stat -f %m`
+  before `stat -c %Y`, and on GNU coreutils `stat -f` is a *valid* flag (`--file-system`,
+  where `%m` is the mount point): it succeeds, returns something like `/`, the `||` never
+  fires, and the age arithmetic runs on a path. Every tracker call then spun the full ~5s
+  bound and fell open with a warning. Every other `stat` call site in the repo already had
+  the order right.
+- **The portability gate accepted any file containing `||` anywhere in it**, which is every
+  shell script in the repo, so an unguarded BSD/GNU construct shipped green - the
+  `phase-tracker` bug above rode through that hole for releases. The guard is now checked
+  on the hit's own line, plus a dedicated `stat` ordering rule.
+- **Model IDs were a generation behind.** 21 references dispatched `claude-opus-4-8` and
+  `claude-sonnet-4-6` on the opus/sonnet rungs. Both are still valid upstream, so nothing
+  errored - Phase 4's reviewer panel, the dev phase and the whole fallback ladder simply ran
+  the previous generation. Now `claude-opus-5` and `claude-sonnet-5`, with the rung/ID split
+  stated in the fallback contract. Gate: a generation guard in `smoke-model-fallback.sh`.
+- **`rules/pipeline-output-formatting.md` did not exist.** Two shipped skills named it as
+  the PR-body contract to follow. The install-layout smoke had been *reporting* paths that
+  exist on no host as a note rather than failing on them, which is how it survived; that
+  claim is now strict.
+- **A pre-migration preferences file failed validation before the migration could fix it.**
+  `firebase_sa`, `firebase_project` and `servicePatMap.figma_pat` are deleted by
+  `migrate-prefs.mjs` but were undeclared under `additionalProperties: false`. Declared as
+  deprecated tolerance slots, and the deprecated/deleted sets are now checked against each
+  other in both halves of the schema.
+- `state.figmaAccess` was a BLOCKING pipeline-wide contract that the state schema never
+  declared. Declared, including the new `tier1Unavailable` cause.
+- Four credential-store corrections: the resolver overwrote a pre-set `CRED_STORE` while
+  documenting it as an override; `doctor` advertised an env-var fallback that `get` does not
+  implement; `resolve_key` read `keychainMapping` with python3 only, so on a Windows box
+  without it the mapping was skipped in silence and a present token read as missing (node
+  is now the second reader, and node is guaranteed wherever this installs); and macOS
+  `list` read the item LABEL rather than the SERVICE attribute `get` looks up.
+- `lint-mcp-refs.mjs` printed one checkmark for two different claims - "the server name is
+  recognised" and "its tools were verified to exist" - so Figma and XcodeBuildMCP read as
+  verified when nothing had probed them. Verified and declared are now distinguished.
+- 15 orphan `<name>.md` files from a pre-directory install layout sat in a real
+  `~/.copilot/skills`, shadowing the proper directory form. Pruned, on both copy hosts.
+
+### Changed
+
+- Figma Tier 1 availability is now host-aware. Absent tools (the normal case on Copilot and
+  Codex, where the installer registers only `dev-toolkit`) record
+  `figmaAccess.tier1Unavailable = "host"` and fall straight to Tier 2 - no probe, no
+  re-auth retry, and no "recreate the MCP token" question the user cannot act on. Tools
+  present but failing auth is `"auth"`, where the retry does apply. On those two hosts a
+  mapped `figma` PAT is the primary path, not a fallback.
+- Phase-doc token budgets recalibrated. The path correction above cost 196 tokens of pure
+  correctness; 149 were reclaimed first by compression (Phase 1's Figma tier table now
+  points at the Phase 0 probe that already resolved it; Phase 4's Codex constraints point
+  at the always-loaded AGENTS.md block). Five warn lines had been permanently amber, which
+  makes the amber tier useless as a signal - every warn reset to the documented
+  current+10%, the four maxes the new warn would have collided with to current+25%,
+  aggregate 51000 -> 51500.
+- The install summary told users to register the Claude Code MCP server by hand. It no
+  longer does, because the installer does it.
+
+## [13.5.1] - 2026-07-28
+
+### Fixed
+
+- `ios-coding-standard`'s local lint runner defaulted its scratch root to
+  `~/.claude/local/...`. On a Copilot- or Codex-only machine that made the script create
+  a stray `.claude` directory belonging to a host that is not installed, just to hold
+  lint output. It now picks whichever host tree exists and falls back to `$TMPDIR`.
+  Found by the Codex sync verification, which flags any `$HOME/.claude/...` reference
+  that reaches the Codex tree.
+
 ## [13.5.0] - 2026-07-28
 
 ### Fixed

package/README.md

@@ -60,9 +60,9 @@ The discipline behind all of this - bounded loops, evidence gates, token-budgete
 |---|---|---|
 | Full | `/multi-agent "task"` | All 8 phases, interactive |
 | Autopilot | `/multi-agent:autopilot "task"` | All 8 phases, no confirmations |
-| Dev | `/multi-agent:dev "task"` | Init → Dev → Commit → Report |
+| Dev | `/multi-agent:dev "task"` | Init → Dev → Review → Test → Commit → Report |
 | Local | `/multi-agent:local "task"` | Full pipeline, current branch (no worktree) |
-| Finish | `/multi-agent:finish` | Run the review→test→commit→report tail over local work |
+| Finish | `/multi-agent:ship` | Run the review→test→commit→report tail over local work |
 | Audit | `/multi-agent:design-check` | Mock-mode vs Figma conformance, local-only |
 | Audit | `/multi-agent:testflight-validation` | Pre-submission gates for a TestFlight build: static archive audit → Apple's `altool --validate-app` → Review-Guidelines check. Validates only, never uploads |
 
@@ -131,7 +131,7 @@ Runs on **macOS**, **Linux**, and **Windows** (Git Bash / WSL). Shell and creden
 | Repo | What it is |
 |---|---|
 | [`mmerterden/multi-agent-plugins`](https://github.com/mmerterden/multi-agent-plugins) | Marketplace of per-stack skill toolkits (iOS / Android / Frontend / Backend + common). `/multi-agent:stack` enables the matching plugin. |
-| [`mmerterden/dev-toolkit-mcp`](https://github.com/mmerterden/dev-toolkit-mcp) | MCP server for UI testing / simulator capture / xcodebuild - powers the Phase 5 UI Bug Hunter. `npx @mmerterden/dev-toolkit-mcp` |
+| [`mmerterden/dev-toolkit-mcp`](https://github.com/mmerterden/dev-toolkit-mcp) | MCP server for UI testing / simulator capture / xcodebuild - powers the Phase 5 UI Bug Hunter. Published on the public npm registry as [`@mmerterden/dev-toolkit-mcp`](https://www.npmjs.com/package/@mmerterden/dev-toolkit-mcp); the installer registers it with each CLI for you, so `npx` resolves it with no extra configuration. |
 
 ## License
 

package/docs/features.md

@@ -26,7 +26,7 @@ Each phase reads its own spec file under `pipeline/multi-agent-refs/phases/phase
 | Flag        | Effect                                                                              |
 | ----------- | ----------------------------------------------------------------------------------- |
 | `autopilot` | Skip all confirmation prompts; still fails safe on review blockers + build retries. |
-| `--dev`     | Strip to Init → Dev(Opus self-contained) → Commit → Report. No Phase 1/2/4/5.       |
+| `--dev`     | Strip to Init → Dev(Opus self-contained) → Review → Test → Commit → Report. No Phase 1/2.       |
 | `--local`   | No worktree - works directly in `$PROJECT_ROOT` on a local branch.                  |
 
 Compose freely: `--dev --local autopilot` = shortest, least-friction path.

package/install/_common.mjs

@@ -321,6 +321,79 @@ export function copyFile(src, dest) {
   cpSync(src, dest, { force: true });
 }
 
+/**
+ * Remove `<name>.md` files left at the root of a skills tree by the
+ * pre-directory install layout.
+ *
+ * Skills have been `<name>/SKILL.md` for a long time, but an older layout wrote
+ * `<name>.md` flat. Nothing ever pruned those, so 15 of them sat in
+ * `~/.copilot/skills` indefinitely: dead duplicates of skills that also existed in
+ * their proper directory form, inflating the skill count and offering the host a
+ * second, stale copy of the same guidance.
+ *
+ * The prune condition is deliberately narrow: a file is removed ONLY when a
+ * directory of the same name sits beside it. That is unambiguous evidence of the old
+ * layout, and it cannot touch a note a user dropped in the tree - a loose `.md` is
+ * not a discoverable skill on any host, so there is no valid file this rule can hit.
+ *
+ * @param {string} skillsDir
+ * @returns {number} files removed
+ */
+export function pruneOrphanSkillFiles(skillsDir) {
+  if (!existsSync(skillsDir)) return 0;
+  let entries;
+  try {
+    entries = readdirSync(skillsDir, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+  const dirNames = new Set(entries.filter((e) => e.isDirectory()).map((e) => e.name));
+  let removed = 0;
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+    const base = entry.name.slice(0, -3);
+    if (!dirNames.has(base)) continue;
+    if (dryRun) {
+      console.log(`    [dry-run] would prune stale flat skill file ${join(skillsDir, entry.name)}`);
+      removed++;
+      continue;
+    }
+    try {
+      rmSync(join(skillsDir, entry.name), { force: true });
+      removed++;
+    } catch {
+      /* non-fatal */
+    }
+  }
+  return removed;
+}
+
+/**
+ * Ship the skills index into a host's skills tree.
+ *
+ * `.skills-index.json` is what `match-skills.mjs` reads when
+ * `prefs.global.dynamicSkillLoading` is on; `skills-index.md` is the human-readable
+ * twin. Both used to be copied ONLY under `--index-only`, while the preferences
+ * schema stated that a full install always ships the index. It did not, so turning
+ * the pref on after a normal install produced `cannot read index` and a silent
+ * fall back to eager loading. One helper, called from every target, so the two
+ * install modes cannot disagree about it again.
+ *
+ * @param {string} pipelineSrc - the repo's `pipeline/` directory
+ * @param {string} skillsDest - the host's skills directory
+ * @returns {number} files copied
+ */
+export function copySkillsIndex(pipelineSrc, skillsDest) {
+  let copied = 0;
+  for (const name of [".skills-index.json", "skills-index.md"]) {
+    const src = join(pipelineSrc, "skills", name);
+    if (!existsSync(src)) continue;
+    copyFile(src, join(skillsDest, name));
+    copied++;
+  }
+  return copied;
+}
+
 /**
  * Write a file, honouring dry-run mode.
  * @param {string} path

package/install/_mcp-register.mjs

@@ -3,15 +3,20 @@
  *
  * WHY THIS IS SHARED
  *
- * Codex got MCP registration when its installer was written; Copilot never did. The
- * result was a host that carried all 257 pipeline skills and could not call a single
- * one of the 80 dev-toolkit tools those skills depend on - `design-check`, every
- * `ios_*` / `android_*` simulator call, the archive audits. Nothing failed at install
- * time, and the skills only fail when a run actually reaches for a tool.
+ * Codex got MCP registration when its installer was written; Copilot never did, and
+ * neither did Claude Code. The result was a host that carried the full pipeline skill
+ * set and could not call a single one of the 80 dev-toolkit tools those skills depend
+ * on - `design-check`, every `ios_*` / `android_*` simulator call, the archive audits.
+ * Nothing failed at install time, and the skills only fail when a run actually reaches
+ * for a tool.
  *
- * Both CLIs take the same shape (`<cli> mcp add <name> -- <command> [args...]`) and
- * both write their own user-level config, so the difference was purely that one
- * installer called it and the other did not. One implementation, two callers.
+ * Claude Code was the longest-lived instance of that bug and the easiest to miss,
+ * because a maintainer who registered the server by hand once sees a working tree
+ * forever while every fresh install ships without it.
+ *
+ * All three CLIs take the same shape (`<cli> mcp add [scope] <name> -- <command>
+ * [args...]`), so the difference was purely which installers called it. One
+ * implementation, three callers.
  *
  * @module install/_mcp-register
  */
@@ -27,17 +32,35 @@ export const MCP_SERVER_NAME = "dev-toolkit";
 export const MCP_SERVER_PACKAGE = "@mmerterden/dev-toolkit-mcp";
 
 /**
- * Where each host's CLI might live.
+ * Per-host CLI invocation details.
  *
- * A bare name is resolved through PATH by execFileSync. The explicit paths matter for
- * Copilot: `copilot` is frequently a *shell alias* for `gh copilot`, and an alias is
- * invisible to execFileSync - so a PATH-only lookup reports "not on PATH" on a machine
- * where the user runs `copilot` every day. `gh` installs the real binary under
+ * `candidates`: where the CLI might live. A bare name is resolved through PATH by
+ * execFileSync. The explicit paths matter for Copilot: `copilot` is frequently a
+ * *shell alias* for `gh copilot`, and an alias is invisible to execFileSync - so a
+ * PATH-only lookup reports "not on PATH" on a machine where the user runs
+ * `copilot` every day. `gh` installs the real binary under
  * ~/.local/share/gh/copilot/.
+ *
+ * `scopeArgs`: options inserted before the server name. Only Claude Code needs
+ * them, and it needs them badly: `claude mcp add` defaults to `--scope local`,
+ * which binds the server to whichever directory the installer happened to run
+ * in. Every other project would then see no dev-toolkit server at all. Codex
+ * writes `~/.codex/config.toml` and Copilot writes `~/.copilot/mcp-config.json`,
+ * both already user-global, so both take no scope flag - passing one errors.
  */
-const CLI_CANDIDATES = Object.freeze({
-  codex: ["codex"],
-  copilot: ["copilot", join(homedir(), ".local", "share", "gh", "copilot", "copilot")],
+const HOSTS = Object.freeze({
+  claude: {
+    candidates: ["claude", join(homedir(), ".local", "bin", "claude")],
+    scopeArgs: ["--scope", "user"],
+  },
+  codex: {
+    candidates: ["codex"],
+    scopeArgs: [],
+  },
+  copilot: {
+    candidates: ["copilot", join(homedir(), ".local", "share", "gh", "copilot", "copilot")],
+    scopeArgs: [],
+  },
 });
 
 /**
@@ -45,28 +68,36 @@ const CLI_CANDIDATES = Object.freeze({
  * try. Returning a bare name rather than null keeps the "not on PATH" diagnosis in one
  * place: the execFileSync catch.
  *
- * @param {"codex"|"copilot"} host
+ * @param {"claude"|"codex"|"copilot"} host
  * @returns {string}
  */
 function resolveCli(host) {
-  const candidates = CLI_CANDIDATES[host] || [host];
+  const candidates = HOSTS[host]?.candidates || [host];
   for (const c of candidates) {
     if (c.includes("/") && existsSync(c)) return c;
   }
   return candidates[0];
 }
 
+/** Does this output say the server was already registered? */
+function saysAlreadyExists(text) {
+  return /already exists/i.test(text);
+}
+
 /**
- * Register the MCP server. Idempotent from the caller's point of view, though the two
- * CLIs get there differently:
+ * Register the MCP server. Idempotent from the caller's point of view, though the
+ * three CLIs get there by three different routes:
  *
  * - `codex mcp add` replaces an existing entry and exits 0.
  * - `copilot mcp add` refuses, printing `Server "<name>" already exists` and exiting 1.
+ * - `claude mcp add` refuses, printing `MCP server <name> already exists in <scope>
+ *   config` and exiting **0**.
  *
- * So a non-zero exit is not automatically a failure. An already-registered server is
- * the desired end state, and reporting it as "skipped MCP registration (Command
- * failed)" would send the user to fix something that is already correct - which is
- * exactly what the first version of this did.
+ * So neither the exit code nor the stream tells you on its own. A non-zero exit is not
+ * automatically a failure, and a zero exit is not automatically a fresh write - which
+ * is why the "already exists" test runs on both paths. Reporting an existing server as
+ * "skipped MCP registration (Command failed)" would send the user to fix something that
+ * is already correct, and that is exactly what the first version of this did.
  *
  * The existing entry is left alone rather than removed and re-added: a user may have
  * added env vars or switched the command to a local checkout, and an installer has no
@@ -75,13 +106,14 @@ function resolveCli(host) {
  * Never fatal: a missing CLI or a failed write must not fail the install, because the
  * rest of the tree is still correct and useful. It prints the manual command instead.
  *
- * @param {"codex"|"copilot"} host
+ * @param {"claude"|"codex"|"copilot"} host
  * @param {string} label - host label for log lines
  * @returns {{registered: boolean, alreadyPresent?: boolean, reason?: string}}
  */
 export function registerMcpServer(host, label) {
   const cli = resolveCli(host);
-  const manual = `${host} mcp add ${MCP_SERVER_NAME} -- npx -y ${MCP_SERVER_PACKAGE}`;
+  const scopeArgs = HOSTS[host]?.scopeArgs || [];
+  const manual = `${host} mcp add ${scopeArgs.join(" ")}${scopeArgs.length ? " " : ""}${MCP_SERVER_NAME} -- npx -y ${MCP_SERVER_PACKAGE}`;
 
   if (isDryRun()) {
     console.log(`    [dry-run] would run: ${manual}`);
@@ -100,17 +132,24 @@ export function registerMcpServer(host, label) {
   try {
     // Bounded: an installer must never hang on a child process. This is a local config
     // write and returns in milliseconds.
-    execFileSync(cli, ["mcp", "add", MCP_SERVER_NAME, "--", "npx", "-y", MCP_SERVER_PACKAGE], {
-      stdio: "pipe",
-      timeout: 20_000,
-    });
+    const stdout = execFileSync(
+      cli,
+      ["mcp", "add", ...scopeArgs, MCP_SERVER_NAME, "--", "npx", "-y", MCP_SERVER_PACKAGE],
+      { stdio: "pipe", timeout: 20_000 },
+    );
+    // Claude Code refuses a duplicate on the SUCCESS path (exit 0), so the check
+    // cannot live in the catch alone.
+    if (saysAlreadyExists(stdout?.toString() ?? "")) {
+      console.log(`    -> ${label}: ${MCP_SERVER_NAME} MCP server already registered, left as-is`);
+      return { registered: true, alreadyPresent: true };
+    }
     console.log(`    -> ${label}: registered the ${MCP_SERVER_NAME} MCP server`);
     return { registered: true };
   } catch (e) {
     // The CLI writes its diagnosis to stderr, which execFileSync parks on the error
     // rather than in `message`. Read both, or "already exists" is invisible.
     const out = `${e?.stderr?.toString() ?? ""}\n${e?.stdout?.toString() ?? ""}\n${e?.message ?? ""}`;
-    if (/already exists/i.test(out)) {
+    if (saysAlreadyExists(out)) {
       console.log(`    -> ${label}: ${MCP_SERVER_NAME} MCP server already registered, left as-is`);
       return { registered: true, alreadyPresent: true };
     }