buddy-agent-harness 0.5.0 → 0.7.0

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "buddy-agent-harness",
-	"version": "0.5.0",
+	"version": "0.7.0",
 	"description": "Initialize standards-based agent configuration across agent harnesses",
 	"author": {
 		"name": "repobuddy"

package/skills/doctor/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: doctor
-description: Use this skill when a repository loads no project skills, when skills are missing after a clone, or when checking whether the agent configuration bridges into .claude/skills and the other harness directories still resolve.
+description: Use this skill when a repository loads no project skills, when skills are missing after a clone, when a harness appears to be ignoring AGENTS.md, or when checking whether the agent configuration bridges into .claude/skills, CLAUDE.md, and the other harness files still resolve.
 ---
 
 <!-- Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-skills.ts. Do not edit by hand. -->
 
 # Harness Doctor
 
-`.agents/skills` is the canonical skill directory. Harnesses that cannot read it — Claude Code and Gemini CLI — get a bridge pointing at it, normally a directory symlink. A bridge that stops resolving is silent: the harness finds nothing and loads zero project skills, with no warning anywhere.
+A repository keeps one canonical configuration: `.agents/skills` for its skills and `AGENTS.md` for its instructions. Harnesses that cannot read those get bridges pointing at them: Claude Code needs both, and Gemini CLI needs the instruction bridge only — it reads `.agents/skills` itself. A bridge that stops resolving is silent: the harness finds nothing and loads zero project skills, with no warning anywhere. An instruction bridge fails the same way and costs more, because the harness then reads none of the repository's instructions at all.
 
 Diagnose it:
 
@@ -15,44 +15,48 @@ Diagnose it:
 node scripts/doctor.mjs
 ```
 
-That path is relative to this skill's own directory. The launcher runs the CLI that shipped beside it against the current working directory, so nothing is downloaded. Fall back to `npx -y buddy-agent-harness@^0.5.0 doctor` when the launcher cannot be resolved or run, which is the case when the plugin was installed from git rather than npm and its dependencies were never installed.
+That path is relative to this skill's own directory. The launcher runs the CLI that shipped beside it against the current working directory, so nothing is downloaded. Fall back to `npx -y buddy-agent-harness@^0.7.0 doctor` when the launcher cannot be resolved or run, which is the case when the plugin was installed from git rather than npm and its dependencies were never installed.
 
 The command is read-only. It never repairs anything, so it is safe to run at any point, including from a session-start hook.
 
 ## Reading the report
 
-`bridges` lists every bridge `init` would create for this repository, each with a `status` of `ok`, `missing`, `degraded`, `stale`, or `diverged`. `findings` explains each problem and `help` names its repair. Apply the repair from the table below, then re-run `doctor`.
+`bridges` lists every skills bridge `init` would create for this repository, each with a `status` of `ok`, `missing`, `degraded`, `stale`, or `diverged`.
 
-`help` names the `init` command for a person at a shell. Do not run it yourself. Rebuilding a bridge can move skills a user wrote, and that judgment belongs to the `init` skill — hand the repair to `/buddy-agent-harness:init` instead.
+`instructions` lists every instruction bridge into `AGENTS.md`, with a `status` of `ok`, `missing`, `unbridged`, or `unreadable`. They are a separate section because nothing about them is shared: a different `kind`, a different status vocabulary, and a repair that is never a command.
 
-When every bridge resolves, `findings` says so outright rather than being empty.
+`findings` explains each problem and carries more than the two sections above: the configuration, MCP, and non-standard findings have no section of their own, because they are about files rather than about bridges. `help` carries each repair, one row per distinct repair, with two columns:
 
-The default output is TOON, which is what you parse. Add `--format text` when you need to show the same report to a person, or `--format json`.
+- `command` — a shell invocation that, run exactly as given, **completes** the repair.
+- `instruction` — the same repair in the imperative, always present and complete on its own.
+
+`command` is empty whenever no single invocation does the job, and that emptiness is the signal: act on `instruction` and do not assemble a command out of it. A runnable invocation quoted *inside* an `instruction` is not the repair either — `diverged-both` names `git diff --no-index` because the diff shows you what differs, not because running it reconciles anything. Apply the repair, then re-run `doctor`.
 
-## Findings and their repairs
+Nothing in `help` is wrapped. An earlier version prefixed every repair with `Run`, which read as an instruction to paste prose into a shell.
 
-| Finding | What it means | Repair |
-| --- | --- | --- |
-| `no-canonical` | the canonical skill directory does not exist, so no bridge can resolve | run `/buddy-agent-harness:init`, which creates `.agents/skills` and the bridges |
-| `missing` | no bridge at this path — the harness sees zero project skills | run `/buddy-agent-harness:init` |
-| `degraded` | expected a directory but found a regular file — checkout without core.symlinks | run `/buddy-agent-harness:init --copy --force` |
-| `stale` | symlink does not resolve to .agents/skills | run `/buddy-agent-harness:init --force` |
-| `diverged-bridge` | only the bridge changed since the two last agreed — an agent wrote through the copy | replace .agents/skills with <path> to keep the newer edit, then run `/buddy-agent-harness:init --force` |
-| `diverged-canonical` | only .agents/skills changed since the two last agreed — the copy is stale | run `/buddy-agent-harness:init --copy --force` |
-| `diverged-both` | both sides changed since they last agreed — rebuilding would discard one of them | run `git diff --no-index .agents/skills <path>` and reconcile by hand |
-| `diverged-unknown` | contents differ and no commit where they agreed was found — which side moved is unknown | run `git diff --no-index .agents/skills <path>` and reconcile by hand |
-| `unpinned-copy` | tracked copy without the skip-worktree bit — the tree is dirty with content that must not be committed | run `git ls-files -z <path> \| xargs -0 git update-index --skip-worktree` |
+Do not run an `init` command yourself. Rebuilding a skills bridge can move skills a user wrote, and rewriting an instruction file touches prose a person authored — both are the `init` skill's judgment, so hand the repair to `/buddy-agent-harness:init` instead. Every such repair carries an empty `command`: a skill invocation has no shell equivalent at all.
 
-Substitute the reported bridge path for `<path>`.
+When every bridge resolves, `findings` says so outright rather than being empty.
+
+The default output is TOON, which is what you parse. Add `--format text` when you need to show the same report to a person, or `--format json`.
 
-## The Windows case
+## Where the detail is
 
-The common failure is `degraded`. Creating a symlink on Windows needs a privilege most accounts do not have, and Git for Windows gates it separately with `core.symlinks`, which its installer leaves off. With `core.symlinks=false` git does not error — it writes the symlink out as a regular file whose contents are the target path. `/buddy-agent-harness:init --copy --force` rebuilds the bridges as real directories on that machine.
+Every `problem` name routes to exactly one page. Load the page for the finding in front of you and leave the rest unread — the tables are long, and reading four families to act on one is what this split exists to stop.
 
-A copy is a snapshot rather than a live projection, and an agent that edits a skill through it writes into the copy instead of into `.agents/skills`. That is what the `diverged` findings catch.
+| Page | Load it for |
+| --- | --- |
+| `references/bridges.md` | any `bridges` row that is not `ok` |
+| `references/instructions.md` | any `instructions` row that is not `ok` |
+| `references/configuration.md` | a finding about the configuration around the bridges rather than a bridge |
+| `references/mcp.md` | any finding whose path is an MCP locator — **always** before acting on a credential finding |
+| `references/nonstandard.md` | a finding about configuration only one harness can read |
+| `references/harnesses/<name>.md` | the paths and files one named harness uses |
 
 ## Rules
 
 - Never repair a `diverged-both` or `diverged-unknown` bridge by re-running `init`. Rebuilding overwrites whichever side holds the newer edit. Reconcile the two directories first.
 - Edit skills at `.agents/skills/<name>/SKILL.md`. Editing through a bridge is only safe when that bridge is a symlink.
 - Do not add bridges to `.gitignore`. An untracked bridge swallows a real edit silently.
+- Never repeat a value from a file an `mcp-literal-secret` or `mcp-committed-secret` finding points at. The report withheld it on purpose, and quoting it back puts it in the transcript anyway.
+- Write instructions in `AGENTS.md`, never in `CLAUDE.md`. A bridge file holds the import and any harness-specific notes; content written there reaches one harness and drifts from the canonical file.

package/skills/doctor/references/bridges.md

@@ -0,0 +1,23 @@
+<!-- Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-skills.ts. Do not edit by hand. -->
+
+# Skills bridge findings
+
+| Finding | What it means | Repair |
+| --- | --- | --- |
+| `no-canonical` | the canonical skill directory does not exist, so no bridge can resolve | run `/buddy-agent-harness:init`, which creates `.agents/skills` and the bridges |
+| `missing` | no bridge at this path — the harness sees zero project skills | run `/buddy-agent-harness:init` |
+| `degraded` | expected a directory but found a regular file — checkout without core.symlinks | run `/buddy-agent-harness:init --copy --force <path>` |
+| `stale` | symlink does not resolve to .agents/skills | run `/buddy-agent-harness:init --force <path>` |
+| `diverged-bridge` | only the bridge changed since the two last agreed — an agent wrote through the copy | replace .agents/skills with <path> to keep the newer edit, then run `/buddy-agent-harness:init --force <path>` |
+| `diverged-canonical` | only .agents/skills changed since the two last agreed — the copy is stale | run `/buddy-agent-harness:init --copy --force <path>` |
+| `diverged-both` | both sides changed since they last agreed — rebuilding would discard one of them | run `git diff --no-index .agents/skills <path>` and reconcile by hand |
+| `diverged-unknown` | contents differ and no commit where they agreed was found — which side moved is unknown | run `git diff --no-index .agents/skills <path>` and reconcile by hand |
+| `unpinned-copy` | tracked copy without the skip-worktree bit — the tree is dirty with content that must not be committed | run `git ls-files -z <path> \| xargs -0 git update-index --skip-worktree` |
+
+Substitute the reported bridge path for `<path>`.
+
+## The Windows case
+
+The common failure is `degraded`. Creating a symlink on Windows needs a privilege most accounts do not have, and Git for Windows gates it separately with `core.symlinks`, which its installer leaves off. With `core.symlinks=false` git does not error — it writes the symlink out as a regular file whose contents are the target path. `/buddy-agent-harness:init --copy --force` rebuilds every bridge as a real directory on that machine; name one bridge to rebuild only that one.
+
+A copy is a snapshot rather than a live projection, and an agent that edits a skill through it writes into the copy instead of into `.agents/skills`. That is what the `diverged` findings catch.

package/skills/doctor/references/configuration.md

@@ -0,0 +1,12 @@
+<!-- Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-skills.ts. Do not edit by hand. -->
+
+# Configuration findings
+
+The bridges resolve, and the configuration around them is still wrong: a superseded harness name, a git-ignored bridge, a local-override file nothing reads, a skill whose frontmatter makes every harness skip it. None of these is an `init` flag — `init` consolidates and creates, and will not correct a file the user already wrote. They go to the `repair` skill, which offers each correction with its before and after and writes only what is approved.
+
+| Finding | What it means | Repair |
+| --- | --- | --- |
+| `deprecated-harness` | a projection under a harness name that has been superseded — the replacement reads .agents/skills natively and needs no projection at all | run `/buddy-agent-harness:repair` |
+| `ignored-bridge` | a .gitignore rule matches this bridge — an untracked bridge swallows a real edit silently | run `/buddy-agent-harness:repair` |
+| `unread-local-override` | no harness reads this filename, so everything in it is invisible to every agent | run `/buddy-agent-harness:repair` |
+| `unloadable-skill` | frontmatter that does not parse, or no description — either one makes a harness skip the skill outright | run `/buddy-agent-harness:repair` |

package/skills/doctor/references/harnesses/claude-code.md

@@ -0,0 +1,39 @@
+<!-- Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-skills.ts. Do not edit by hand. -->
+
+# claude-code
+
+## Project scope
+
+Where `doctor` looks inside a repository.
+
+| What | Path |
+| --- | --- |
+| detection directory | `.claude` |
+| skills projection | `.claude/skills` — written by `init` |
+| instruction bridge | `CLAUDE.md` — an import of `AGENTS.md` |
+| MCP configuration | `.mcp.json` — the `mcpServers` key, json |
+
+## User scope
+
+Described, never written: `init` and `doctor` both work inside a repository.
+
+| What | Path |
+| --- | --- |
+| detection directory | `.claude` |
+| skills projection | `.claude/skills` — written by `init` |
+| instruction bridge | none |
+| MCP configuration | none |
+
+## Configuration only this harness reads
+
+Reported by `doctor` so it can be converted; see `../nonstandard.md` for what each conversion is.
+
+| Path | Kind | Converts to |
+| --- | --- | --- |
+| `.claude/commands/` | command | `.agents/skills/<name>/SKILL.md` |
+| `.claude/rules/` | rule | a skill, where the path scoping is incidental |
+| `.claude/agents/` | subagent | nothing yet — no cross-harness format exists |
+
+## Judgment about this harness
+
+What to generate for it, what to leave alone, and which claims are contested: `../../../init/references/harnesses/claude-code.md`. That page is hand-written and is the one to read before writing anything for this harness.

package/skills/doctor/references/harnesses/codex.md

@@ -0,0 +1,37 @@
+<!-- Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-skills.ts. Do not edit by hand. -->
+
+# codex
+
+## Project scope
+
+Where `doctor` looks inside a repository.
+
+| What | Path |
+| --- | --- |
+| detection directory | `.codex` |
+| skills projection | none — reads `.agents/skills` natively |
+| instruction bridge | none |
+| MCP configuration | `.codex/config.toml` — the `mcp_servers` key, toml |
+
+## User scope
+
+Described, never written: `init` and `doctor` both work inside a repository.
+
+| What | Path |
+| --- | --- |
+| detection directory | `.codex` |
+| skills projection | none — reads `.agents/skills` natively |
+| instruction bridge | none |
+| MCP configuration | none |
+
+## Configuration only this harness reads
+
+Reported by `doctor` so it can be converted; see `../nonstandard.md` for what each conversion is.
+
+| Path | Kind | Converts to |
+| --- | --- | --- |
+| `.codex/skills/` | skill | `.agents/skills`, projected back if needed |
+
+## Judgment about this harness
+
+What to generate for it, what to leave alone, and which claims are contested: `../../../init/references/harnesses/codex.md`. That page is hand-written and is the one to read before writing anything for this harness.

package/skills/doctor/references/harnesses/copilot-cli.md

@@ -0,0 +1,39 @@
+<!-- Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-skills.ts. Do not edit by hand. -->
+
+# copilot-cli
+
+## Project scope
+
+Where `doctor` looks inside a repository.
+
+| What | Path |
+| --- | --- |
+| detection directory | `.github/skills` |
+| skills projection | none — reads `.agents/skills` natively |
+| instruction bridge | none |
+| MCP configuration | none |
+
+## User scope
+
+Described, never written: `init` and `doctor` both work inside a repository.
+
+| What | Path |
+| --- | --- |
+| detection directory | `.copilot` |
+| skills projection | none — reads `.agents/skills` natively |
+| instruction bridge | none |
+| MCP configuration | none |
+
+## Configuration only this harness reads
+
+Reported by `doctor` so it can be converted; see `../nonstandard.md` for what each conversion is.
+
+| Path | Kind | Converts to |
+| --- | --- | --- |
+| `.github/copilot-instructions.md` | instructions | `AGENTS.md`, with a generated bridge left behind |
+| `.github/instructions/` | instructions | `AGENTS.md`, with a generated bridge left behind |
+| `.github/skills/` | skill | `.agents/skills`, projected back if needed |
+
+## Judgment about this harness
+
+What to generate for it, what to leave alone, and which claims are contested: `../../../init/references/harnesses/copilot-cli.md`. That page is hand-written and is the one to read before writing anything for this harness.

package/skills/doctor/references/harnesses/cursor.md

@@ -0,0 +1,40 @@
+<!-- Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-skills.ts. Do not edit by hand. -->
+
+# cursor
+
+## Project scope
+
+Where `doctor` looks inside a repository.
+
+| What | Path |
+| --- | --- |
+| detection directory | `.cursor` |
+| skills projection | none — reads `.agents/skills` natively |
+| instruction bridge | none |
+| MCP configuration | `.cursor/mcp.json` — the `mcpServers` key, json |
+
+## User scope
+
+Described, never written: `init` and `doctor` both work inside a repository.
+
+| What | Path |
+| --- | --- |
+| detection directory | `.cursor` |
+| skills projection | none — reads `.agents/skills` natively |
+| instruction bridge | none |
+| MCP configuration | none |
+
+## Configuration only this harness reads
+
+Reported by `doctor` so it can be converted; see `../nonstandard.md` for what each conversion is.
+
+| Path | Kind | Converts to |
+| --- | --- | --- |
+| `.cursorrules` | instructions | `AGENTS.md`, with a generated bridge left behind |
+| `.cursor/rules/` | rule | a skill, where the path scoping is incidental |
+| `.cursor/commands/` | command | `.agents/skills/<name>/SKILL.md` |
+| `.cursor/skills/` | skill | `.agents/skills`, projected back if needed |
+
+## Judgment about this harness
+
+What to generate for it, what to leave alone, and which claims are contested: `../../../init/references/harnesses/cursor.md`. That page is hand-written and is the one to read before writing anything for this harness.

package/skills/doctor/references/harnesses/devin-desktop.md

@@ -0,0 +1,20 @@
+<!-- Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-skills.ts. Do not edit by hand. -->
+
+# devin-desktop
+
+## Project scope
+
+Where `doctor` looks inside a repository.
+
+| What | Path |
+| --- | --- |
+| detection directory | `.devin` |
+| skills projection | none — reads `.agents/skills` natively |
+| instruction bridge | none |
+| MCP configuration | none |
+
+No user-scope paths are primary-sourced for this harness, so `doctor` describes none.
+
+## Judgment about this harness
+
+What to generate for it, what to leave alone, and which claims are contested: `../../../init/references/harnesses/devin-desktop.md`. That page is hand-written and is the one to read before writing anything for this harness.

package/skills/doctor/references/harnesses/gemini-cli.md

@@ -0,0 +1,38 @@
+<!-- Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-skills.ts. Do not edit by hand. -->
+
+# gemini-cli
+
+## Project scope
+
+Where `doctor` looks inside a repository.
+
+| What | Path |
+| --- | --- |
+| detection directory | `.gemini` |
+| skills projection | none — reads `.agents/skills` natively |
+| instruction bridge | `.gemini/settings.json` — `AGENTS.md` in the `context.fileName` entry |
+| MCP configuration | `.gemini/settings.json` — the `mcpServers` key, json, shared with other settings |
+
+## User scope
+
+Described, never written: `init` and `doctor` both work inside a repository.
+
+| What | Path |
+| --- | --- |
+| detection directory | `.gemini` |
+| skills projection | none — reads `.agents/skills` natively |
+| instruction bridge | none |
+| MCP configuration | none |
+
+## Configuration only this harness reads
+
+Reported by `doctor` so it can be converted; see `../nonstandard.md` for what each conversion is.
+
+| Path | Kind | Converts to |
+| --- | --- | --- |
+| `GEMINI.md` | instructions | `AGENTS.md`, with a generated bridge left behind |
+| `.gemini/skills/` | skill | `.agents/skills`, projected back if needed |
+
+## Judgment about this harness
+
+What to generate for it, what to leave alone, and which claims are contested: `../../../init/references/harnesses/gemini-cli.md`. That page is hand-written and is the one to read before writing anything for this harness.

package/skills/doctor/references/harnesses/windsurf.md

@@ -0,0 +1,27 @@
+<!-- Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-skills.ts. Do not edit by hand. -->
+
+# windsurf
+
+> **Superseded by `devin-desktop`.** The legacy paths still work, so a projection here keeps resolving and `doctor` reports the name as deprecated rather than broken. New repositories should enable `devin-desktop`.
+
+## Project scope
+
+Where `doctor` looks inside a repository.
+
+| What | Path |
+| --- | --- |
+| detection directory | `.windsurf` |
+| skills projection | `.windsurf/skills` — written by `init` |
+| instruction bridge | none |
+| MCP configuration | none |
+
+No user-scope paths are primary-sourced for this harness, so `doctor` describes none.
+
+## Configuration only this harness reads
+
+Reported by `doctor` so it can be converted; see `../nonstandard.md` for what each conversion is.
+
+| Path | Kind | Converts to |
+| --- | --- | --- |
+| `.windsurfrules` | instructions | `AGENTS.md`, with a generated bridge left behind |
+| `.windsurf/rules/` | rule | a skill, where the path scoping is incidental |

package/skills/doctor/references/instructions.md

@@ -0,0 +1,14 @@
+<!-- Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-skills.ts. Do not edit by hand. -->
+
+# Instruction bridge findings
+
+| Finding | What it means | Repair |
+| --- | --- | --- |
+| `no-instructions` | no AGENTS.md at the repository root, so every instruction bridge points at nothing | run `/buddy-agent-harness:init`, which derives AGENTS.md and the bridges to it |
+| `instructions-missing` | no instruction bridge at this path — the harness reads none of AGENTS.md | run `/buddy-agent-harness:init` |
+| `instructions-unbridged` | the file is present but names AGENTS.md nowhere — the harness reads none of it | run `/buddy-agent-harness:init`, which adds the bridge without discarding what the file already says |
+| `instructions-unreadable` | the settings file does not parse, so the harness reads none of it | fix the JSON by hand, then run `/buddy-agent-harness:init` |
+
+`unbridged` is the one to read carefully. The file is there and looks fine, and it names `AGENTS.md` nowhere — a `CLAUDE.md` someone overwrote with real content, or a `.gemini/settings.json` another tool rewrote without `AGENTS.md` in `context.fileName`. Never fix it by replacing the file: the content that displaced the bridge may be the only copy of something.
+
+An instruction bridge is reported per file, so a monorepo gets one row per `AGENTS.md` in the tree. Each nested `AGENTS.md` needs its own stub — an import bridges the file beside it and nothing deeper.

package/skills/doctor/references/mcp.md

@@ -0,0 +1,31 @@
+<!-- Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-skills.ts. Do not edit by hand. -->
+
+# MCP findings
+
+A repository may keep a **golden MCP server set** at `.agents/buddy-agent-harness/mcp.toml` — one canonical entry per server, in the superset of fields the supported hosts accept, written by the user. Where it exists, `doctor` compares it against each harness's own MCP configuration and reports how the two have drifted. **No golden set means no MCP drift findings at all**, and a harness with no MCP file yet has nothing that could have drifted.
+
+Comparison is semantic. Six config keys across three file formats means no two of these files are ever byte-equal, so each side is parsed into one model and the models are compared. A field the golden set leaves unset is never a difference, however a harness fills it in: a host restating its own default and a user's deliberate edit are indistinguishable there, and treating both as changes is what makes a golden set accumulate noise.
+
+Each finding names a **locator**, not a file: `.cursor/mcp.json#servers.linear.command` is the server and field, and that is what you route on.
+
+| Finding | What it means | Repair |
+| --- | --- | --- |
+| `mcp-golden-unreadable` | the golden MCP set does not parse — the locator gives the line and column, and nothing else can be said about it | fix the TOML at <path> by hand — the reported line and column are all that can be quoted, because the parser's own message repeats the offending line and that line is the one holding the credential |
+| `mcp-target-unreadable` | this harness config does not parse, so the harness starts none of its servers and nothing in it can be compared | fix the syntax of <path> by hand |
+| `mcp-unprojected` | the golden set declares this server and the harness config does not carry it | add the server at <path> to that file from its golden entry, or drop it from the golden set |
+| `mcp-undeclared` | the harness config carries this server and the golden set does not declare it | copy the server at <path> into .agents/buddy-agent-harness/mcp.toml, refusing any literal credential it carries, or drop it from <path> |
+| `mcp-diverged-target` | only the harness config changed since the two last agreed — the edit was made through the copy | reconcile the value at <path> back into .agents/buddy-agent-harness/mcp.toml, field by field |
+| `mcp-diverged-golden` | only the golden set changed since the two last agreed — the harness copy is stale | update <path> from the golden entry |
+| `mcp-diverged-both` | both sides changed since they last agreed — merging either way would discard the other | reconcile <path> against .agents/buddy-agent-harness/mcp.toml by hand — never merge a three-way conflict automatically |
+| `mcp-diverged-unknown` | the two disagree and no baseline says which side moved — neither history nor a last-projected record covers this server | compare <path> against .agents/buddy-agent-harness/mcp.toml by hand |
+| `mcp-literal-secret` | a credential-bearing field holds a literal rather than a reference to an environment variable | move the value at <path> into an environment variable and reference it — read the value from the file, never from this report, and never repeat it back |
+| `mcp-committed-secret` | a credential-bearing field holds a literal in a git-tracked file — the credential is committed, and moving it does not un-commit it | rotate the credential behind <path> at its issuer, then reference it from an environment variable — it is in the repository's history, so moving it is not enough |
+
+## Credentials
+
+The two secret findings are the ones to handle carefully.
+
+- **The report never contains the value.** It gives you the locator and stops. Read the value out of the file named in the locator, and do not repeat it into your reply, into a commit message, or into any other file. There is no truncated preview to work from because a truncated credential is a leaked credential in the same transcript.
+- **`mcp-committed-secret` is not `mcp-literal-secret` with worse wording.** The file is tracked, so the value is in the repository's history and every clone already has it. Moving it into an environment variable fixes the working tree and changes nothing about that. Rotate it at its issuer first.
+- **A reference passes.** `${LINEAR_TOKEN}` and `Bearer ${LINEAR_TOKEN}` are the documented ways to write these fields and are never reported. The test is that shape, not how random the value looks.
+- **An unreadable golden set is reported by position only.** The parser's own message quotes the line it failed on, and in this file that line is the one holding the credential — so neither the message nor the offending line is ever carried into the report. Open the file at the reported line and column.

package/skills/doctor/references/nonstandard.md

@@ -0,0 +1,27 @@
+<!-- Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-skills.ts. Do not edit by hand. -->
+
+# Non-standard configuration
+
+Configuration only one harness can read. Nothing here is broken — a Cursor rule does exactly what it says — which is why none of it is in the other four families. What these findings report is **reach**: guidance that lands in one tool and nowhere else, where nobody finds out except by noticing an agent behave differently somewhere else.
+
+Each finding names the canonical form it converts to. The direction is always the same: move the content to a canonical source, and let the harness file be **generated** from it rather than authored beside it. A repository with none of these is the target; it is a direction to walk, not a gate to pass.
+
+| Finding | What it means | Repair |
+| --- | --- | --- |
+| `nonstandard-instructions` | instruction content only one harness reads — AGENTS.md carries the same prose to all of them | hand <path> to `/buddy-agent-harness:init`, which consolidates it into AGENTS.md |
+| `nonstandard-rule` | a path-scoped rule only one harness reads — a skill reaches every harness where the scoping is incidental | hand <path> to `/buddy-agent-harness:init` to convert into a skill, unless the path scoping is load-bearing |
+| `nonstandard-command` | a harness command file — a skill is the portable form, and this harness reads skills too | hand <path> to `/buddy-agent-harness:init`, which moves it to .agents/skills |
+| `nonstandard-skill` | a skill under a harness directory rather than the canonical one, where only that harness finds it | hand <path> to `/buddy-agent-harness:init`, which moves it to .agents/skills |
+| `nonstandard-subagent` | a subagent definition with no cross-harness form — nothing outside this harness can read it, and no canonical form exists yet | leave <path> in place — no portable form exists yet, so this is work for a person rather than a skill |
+
+## Two of them need judgment, not a move
+
+**A path-scoped rule may have nowhere to go.** `AGENTS.md` scopes by directory nesting and a skill is loaded on relevance, so neither reproduces "these globs and no others". Where the scoping is incidental — a rule that happens to name paths but says something generally true — a skill carries it everywhere. Where the scoping is the point, leave it, and the finding stays as the record of why.
+
+**A subagent has no portable form at all.** No cross-harness format exists, so the finding is the gap rather than a repair. It names no skill, and it is work for a person if it is work at all.
+
+## What is not reported
+
+A harness directory that is a **symlink** is a projection someone already made, not configuration authored here. An artifact is reported whether or not its harness is enabled: a `.cursorrules` in a repository nobody opens in Cursor is still instruction content `AGENTS.md` does not carry, and filtering by the enabled set would hide exactly the drift worth converting.
+
+Hooks, LSP settings, and output styles are not covered yet. Their event names and shapes differ by harness with no safe projection, and half-reporting them would be worse than the silence.

package/skills/doctor/scripts/doctor.mjs

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
 // Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-skills.ts. Do not edit by hand.
 import { dirname, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 
 // <package>/skills/<skill>/scripts/doctor.mjs: four levels up is the package root.
 const packageRoot = dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))))
+const { run } = await import(pathToFileURL(join(packageRoot, 'dist', 'cli.mjs')).href)
 
-process.argv.splice(2, 0, 'doctor')
-await import(join(packageRoot, 'bin', 'buddy-agent-harness.mjs'))
+// The subcommand is composed into a fresh argv rather than spliced into the global one, so nothing
+// outside this file observes the rewrite. Applied only when non-zero, so a usage code clibuilder
+// recorded itself is not overwritten by the zero `run` returns on that path.
+const code = await run([...process.argv.slice(0, 2), 'doctor', ...process.argv.slice(2)])
+if (code !== 0) process.exitCode = code

package/skills/enhance/SKILL.md

@@ -38,6 +38,8 @@ Judge by meaning, not by heading or wording. A repository covering delegation un
 
 When in doubt, treat it as covered and say why. A missing offer costs the user nothing; a duplicate section teaches every future agent that this file repeats itself.
 
+**A heading inside a fenced code block is not a heading.** Text between ``` or ~~~ fences is an example of a file, not part of this one, and an addition quoted inside a fence is being shown rather than adopted. This is not hypothetical: every addition here is offered as a fenced block containing its own heading, so a repository documenting this tool — or an `AGENTS.md` that quotes one — carries the exact heading the addition would write, inside a fence, while remaining entirely uncovered. Judge only the prose the agent actually reads as instruction.
+
 ## 4. Offer
 
 Where an addition is uncovered, show its text **verbatim** — the whole thing, not a summary — say where it would go, and ask.
@@ -48,6 +50,8 @@ Do not argue for it past one sentence. The user is reading the actual text; that
 
 On approval, append the section to the root `AGENTS.md`, outside the managed region, preserving the surrounding file exactly.
 
+Strip the fence when you write. The ``` markers around the addition in its reference file are there so you can see where the text begins and ends; the section goes into `AGENTS.md` as prose, not as a code block.
+
 On a decline, write nothing.
 
 ## 6. Report

package/skills/init/README.md

@@ -6,7 +6,7 @@ Give a repository one canonical agent configuration — a root `AGENTS.md` and a
 
 The skill runs a five-phase workflow: survey the repository, classify what it finds, confirm the plan with you, apply it, then verify.
 
-It detects agent configuration you already have — instruction files, skills, commands, subagents, rules, MCP servers, hooks — and either consolidates it into the canonical source, links it back out, or reports it as canonical-only where no safe cross-harness mapping exists. It never removes or rewrites a file you authored without asking first.
+It detects agent configuration you already have — instruction files, skills, commands, subagents, rules, MCP servers, hooks — and either consolidates it into the canonical source, links it back out, or reports it as canonical-only where converting it would mean inventing configuration you did not write. It never removes or rewrites a file you authored without asking first.
 
 ## Why the projection step is small