buddy-agent-harness 0.22.0 → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,745 @@
+# buddy-agent-harness
+
+## 1.0.1
+
+### Patch Changes
+
+- 9a418f5: The `init-buddy-agent-harness` skill now says what it scaffolds, `AGENTS.md` and `.agents/skills/`, and treats other `.agents/` folders such as `.agents/agents/` as the project's choice, instead of forbidding them. `init` still creates none of them and still does not call them standard.
+
+## 1.0.0
+
+### Major Changes
+
+- d8ef1eb: Moves to `cyber-agentkit` 2.0. `reference show` is now `reference load` and `reference select` is now `reference customize`. The `--scope project` option is now `--scope repo`, and references are read from the repository root. `reference load` exits 0 for a name it did not find. `list --trace` rows carry `kind: selection` where they had `selection: true`.
+
+### Minor Changes
+
+- b792140: `enhance` now reads a present section against an addition's retired wordings with `cyber-agentkit`'s `prose-update`, and for an outdated section offers the merged text that keeps the owner's own sentences beside the current wording. The `cyber-agentkit` dependency moves to ^1.2.0.
+- e7efd5c: `init` writes an empty `.gitkeep` into `.agents/skills/` and `.agents/references/` when it leaves them empty, so a commit and clone keep the directories and `.claude/skills` does not dangle.
+
+### Patch Changes
+
+- a461f45: `clibuilder` moves from `dependencies` to an optional peer dependency at `^12.1.0`. The `buddy-agent-harness` bin bundles its own copy and needs nothing installed; a host CLI that imports `activate` or a `*Command` export supplies its own `clibuilder`, at 12.1.0 or later so its copy and this package's work together.
+- 5a5b61b: Documents the `reference` command as `cyber-agentkit` 2.0 defines it: `reference load`, `reference customize --extends`, `--in <folder>` for a folder's project section, `--scope repo|user`, and the merge operations `replace`, `patch`, `combine`, and `remove`. The docs, the spec, and `llms.txt` no longer name `reference show`, `reference select`, `--scope project`, or `merge-sections`, and the library page lists only the reference exports the package has.
+- ef03223: Include `CHANGELOG.md` in the published package.
+
+## 0.22.0
+
+### Minor Changes
+
+- dad15c5: Moves to clibuilder 12 and `@cyberuni/agent-harness` 0.7. The package no longer uses `@clibuilder/axi`, and its skill scripts and `dist/cli.mjs` no longer carry clibuilder's runtime plugin and config loader: the three skill scripts shrink from 693 KB to 386 KB and `dist/cli.mjs` from 1.1 MB to 689 KB.
+  
+  Command interfaces and documented output are unchanged. What a caller can see:
+  
+  - A usage error (an unknown option or command, an unsupported `--format`) is now a coded report on stdout (`error`, `code`, and `help` lines in the chosen format) with exit code `2`. It was prose and help on stderr.
+  - `--format` is clibuilder's global option, so every command, including `mcp` and `reference`, lists it in `--help` the same way. `reference show|create|delete` and `governance show` still default to `text`, and every other command to `toon`; the default is chosen from the command named in argv.
+  - `initCommand`, `doctorCommand`, `governanceCommand`, `referenceCommand`, `harnessCommand`, and `activate` are clibuilder 12 command objects. A host that mounts them needs `clibuilder` `^12.0.0`; `^11` no longer works.
+- 832fa4f: Moves from `@cyberuni/agent-harness` to `cyber-agentkit` 1.0, and the plugin dependency from `cyber-agent-harness` to `cyber-agentkit`; install that plugin on harnesses that read no plugin dependencies.
+  
+  The `reference` command and its exports no longer read `governances/` folders (project, user, and the machine-wide ones). Move those documents to the `references/` folder of the same tier. The `governance` command is unchanged and still reads them. The machine-wide `/etc/buddy-agent-harness/references` folder is no longer read: the managed tier is a `references/` folder beside the managed files of each detected harness.
+  
+  The package no longer exports `managedReferencesDir`, `MergeMode`, `ReferenceRow`, `TraceEntry`, or `UsedLayer`. `referenceLayers` now resolves to `ReferenceLayers`, and `ReferenceListing` holds `references` and `layers` in place of `rows`. `ReferenceListLayerRow` and `ReferenceListRow` are exported.
+
+### Patch Changes
+
+- 9728e92: Makes the shipped skills self-contained, for channels that link or copy one skill alone (pnpm 12.11 links each as `pnpm-buddy-agent-harness-<skill>`). The `npx` fallback is pinned to the exact release rather than a `^` range. A page one skill read from a sibling (`agents-md.md`, `detection.md`, `global-instructions.md`, the per-harness judgment pages) is now copied into the skill that reads it, and checked against its source. Every `/buddy-agent-harness:<skill>` reference, in the skills and in `doctor` output, carries the pnpm name beside it.
+
+## 0.21.0
+
+### Minor Changes
+
+- 0e4d7c0: `--format` now comes from [`@clibuilder/axi`](https://github.com/clibuilder/clibuilder/tree/main/packages/axi), the output contract clibuilder CLIs share, in place of this package's own copy. `toon`, `json`, and `text` output is byte-identical: axi's TOON encoder and text renderer are the same code.
+  
+  An unknown `--format` value is now a usage error, the same as an unknown option. Before, `doctor --format yaml` (and every other command) wrote `error: --format must be toon, json, or text.` to stderr and exited `1`. Now clibuilder rejects it before the command runs, with `invalid value for option --format: expected one of: toon, json, text, received "yaml"` and the command's usage text, and exits `2`. A script that checked for exit `1` on a bad format should check for `2`.
+  
+  The `--format` help line now reads `Output format: toon (default), json, text — toon for agents, json to pipe, text for humans`. `governance show` keeps its own wording and its `text` default.
+
+### Patch Changes
+
+- 9588c86: Fix the `enhance` and `repair` skills citing `../init/references/…`, a path that does not exist; they now point at `init-buddy-agent-harness`. Drop a migration-relative sentence from the `doctor-buddy-agent-harness` skill.
+
+## 0.20.0
+
+### Minor Changes
+
+- bc2b8bb: The `reference` command and the reference exports now come from `@cyberuni/agent-harness`. The same tiers, output, and exit codes, and the same library exports and options. The command gains `reference delete`, which removes the project or user copy of a reference and reports which copy answers the name afterwards; it never deletes a plugin-shipped or managed copy.
+- f7fa605: The `reference` skill moved to the `cyber-agent-harness` plugin, and the `buddy-agent-harness` plugin no longer ships it. The plugin now declares a dependency on `cyber-agent-harness`, which Claude Code resolves from the marketplace `buddy-agent-harness` is installed from, so installing `buddy-agent-harness` installs `cyber-agent-harness` and its `reference` skill with it. Cursor, Codex, and GitHub Copilot CLI read no plugin dependencies, so install `cyber-agent-harness` there yourself.
+  
+  A calling skill's line changes from "in the `buddy-agent-harness` plugin" to "in the `cyber-agent-harness` plugin":
+  
+  ```text
+  Load `skill-design` and `agent-tool-output` with the `reference` skill in the `cyber-agent-harness` plugin.
+  ```
+  
+  In Claude Code, the typed form changes from `/buddy-agent-harness:reference` to `/cyber-agent-harness:reference`. The `buddy-agent-harness reference` command is unchanged.
+
+## 0.19.0
+
+### Minor Changes
+
+- adcaa2f: `doctor`'s `globalInstructions` check now reads an empty `CODEX_HOME`, `COPILOT_HOME`, or `CLAUDE_CONFIG_DIR` the way that harness does. Codex and Copilot CLI read an empty value as unset, so nothing changes for them. Claude Code reads an empty `CLAUDE_CONFIG_DIR` as the directory it starts in. Its row now names `./CLAUDE.md`, the file Claude Code reads when started in the repository, and a new `global-instructions-emptied` finding names `$CLAUDE_CONFIG_DIR`, with the step to unset it or set it to the folder you meant. The `repair` and `enhance` skills hand that step over like the others.
+  
+  The library adds a `start` parameter to `diagnoseGlobalInstructions`: the directory Claude Code is taken to start in, defaulting to `process.cwd()`. `diagnoseBridges` passes `root`.
+
+## 0.18.0
+
+### Minor Changes
+
+- 10cbbdd: `doctor`'s `globalInstructions` check now follows the variables that move a harness's directory: `CODEX_HOME`, `COPILOT_HOME`, and `CLAUDE_CONFIG_DIR`. Where one is set and non-empty, the row and the repair name the file under it, written from the variable, such as `$CODEX_HOME/AGENTS.md`.
+  
+  It also catches Codex's `AGENTS.override.md`. Codex reads that file in place of `AGENTS.md` when it holds more than whitespace, so a bridged `AGENTS.md` beside it loads nothing. The row is then `overridden`, and a `global-instructions-overridden` finding names the override, with the step to move what it says into `~/.agents/AGENTS.md` and remove it. The `repair` and `enhance` skills hand that step over like the others.
+  
+  Copilot CLI is confirmed to follow a `copilot-instructions.md` symlink that points outside its directory, so the symlink bridge stands.
+  
+  The library adds an `env` option to `diagnoseBridges` and an `env` parameter to `diagnoseGlobalInstructions`; omitted, no variable is followed.
+- 3468500: `doctor` now reports whether each harness installed for you loads `~/.agents/AGENTS.md`, in a new `globalInstructions` section. No harness reads that file by itself; each loads it only through a user-scope file of its own. On Claude Code that is an `@~/.agents/AGENTS.md` line in `~/.claude/CLAUDE.md`. On Codex, Copilot CLI, and Gemini CLI it is `~/.codex/AGENTS.md`, `~/.copilot/copilot-instructions.md`, or `~/.gemini/GEMINI.md` as a symlink to it. Gemini CLI's `context.fileName` setting cannot do it at user scope, because there it names files inside `~/.gemini/` only.
+  
+  Where `~/.agents/AGENTS.md` exists and a harness does not load it, `doctor` reports `global-instructions-missing` or `global-instructions-unbridged`. The repair names the exact line or symlink, for you to add yourself; nothing writes outside the repository. The `repair` skill passes that step to you unchanged. When the `enhance` skill hands a global placement over, it now says whether the harness in use loads the file, and gives you the bridge beside the text where it does not.
+  
+  The library adds `diagnoseGlobalInstructions`, a `home` option on `diagnoseBridges`, and `import` and `symlink` variants of `InstructionBridge`.
+
+## 0.17.0
+
+### Minor Changes
+
+- 951313d: The `enhance` skill now offers a third addition, `## Session scope`. It tells the agent to keep one session to one subject: finish deciding how something should work before building it, start the build in a new session from what the first one wrote down, and when the user turns to unrelated work, say what the old subject was rather than carrying it into the new one.
+  
+  It is gated like the other two. The skill offers it only where the merged instructions do not already cover the subject, recommends the owner's global instruction file over the repository's `AGENTS.md`, and writes nothing without approval. No harness scores this wording yet, so where the skill cannot tell whether a section already in a file came from here, it offers two answers rather than three.
+
+## 0.16.0
+
+### Minor Changes
+
+- a0e476e: New `reference create <name>` starts a reference in the project tier, or with `--scope user` in `~/.agents/references/`. It copies `--template <path>` as it is, or writes a built-in template of top-level `##` sections with no `#` title. When a lower layer already holds the name, it adds `merge: merge-sections` so the new file overrides section by section, unless the template sets `merge` itself. It never overwrites a file, refuses a copy above that would shadow the new one, warns on a `#` heading or a missing `description`, and `--dry-run` prints the path and content without writing. The `reference` skill's Create and Update modes now write project and user references through it.
+
+### Patch Changes
+
+- 0dc25d9: Link the `diagnoseBridges`, `diagnoseInstructions`, `buildDoctorReport`, `doctorCommand`, `bridgeRepairs`, `instructionRepairs`, `doctorRepairs`, `doctorSkill`, and `renderDoctorSkill` exports and their types in the shipped `llms.txt` to their new documentation page instead of their source.
+- 851cb51: Mark the governance library exports deprecated with a `@deprecated` tag naming each one's `reference` replacement, such as `resolveGovernance` to `resolveReference`. They keep their behavior until the next major version. The shipped `llms.txt` now links them to their new documentation page instead of their source.
+- 03756a3: Link the `run`, `initializeHarnesses`, `initCommand`, `harnessCommand`, and `activate` exports in the shipped `llms.txt` to their new documentation page instead of their source.
+- 6ace999: `llms.txt` now links the harness registry and MCP library exports — `harnessRegistry`, `listMcpServers`, `diagnoseMcp`, `goldenSetPath`, and their types — to their new docs page, Library: MCP and the harness registry, instead of to their source.
+- 67ad576: `llms.txt` links the library's reference exports — `referenceLayers`, `resolveReference`, `listReferences`, `searchReferences`, `referenceCommand`, and their types — to their new docs page, instead of to the source.
+
+## 0.15.0
+
+### Minor Changes
+
+- 37bdd5a: Add `reference where <name>`, which shows where to write an override of a reference: the project file (relative to the reported `root`) and the user file, highest precedence first, with the plugin copy they would override. `--caller <skill folder>` reports that skill's own copy as the Load mode reads it. The `reference` skill's Inspect mode runs it when asked where to put an override.
+
+### Patch Changes
+
+- 42cee2c: Ship a generated `llms.txt` in the package, also served from the docs site at `/llms.txt`: an orientation map of the CLI commands, the skills, the library exports, and the documentation pages, with absolute links to each.
+- 4d3c72d: Hide the `reference` skill from the slash-command menu with `user-invocable: false`. Agents still load it by name.
+
+## 0.14.0
+
+### Minor Changes
+
+- 0ba0099: The `load-reference` skill is now the `reference` skill's Load mode, and the `load-reference` skill is removed. A calling skill's line changes from "with the `load-reference` skill" to "with the `reference` skill":
+  
+  ```text
+  Load `skill-design` and `agent-tool-output` with the `reference` skill in the `buddy-agent-harness` plugin.
+  ```
+  
+  Loading works as before: one `reference show` run from the launcher bundled in the skill folder, no `npx` and no network, and the calling skill's own `references/<name>.md` when the command cannot run or no tier holds the name. The plugin now puts one skill description in every session for references, instead of two.
+- 1071180: New `reference` skill for working with references yourself. It routes what you ask to `reference show`, `list`, or `search`, and it writes a new reference, or updates one, after you approve it, since the command is read-only.
+  
+  When a plugin ships a reference, the skill names the file `<plugin name>.<reference>.md`, so a project's override of one plugin's document does not also replace another plugin's. Updating your own reference edits it in place. Updating a plugin's writes an override, and when more than one plugin holds that name, it warns you first. For a skill that needs a reference, it gives you the line that loads it with the same skill.
+
+## 0.13.1
+
+### Patch Changes
+
+- a5b3580: Cursor reads `AGENTS.md` in every mode, and the skills no longer say otherwise. The previous claim — that Cursor reads it in Agent mode only, and that Chat and Composer would lose instructions consolidated into it — was sourced to third-party comparisons and marked contested. Cursor's own documentation contradicts it: "Project rules, user rules, and team rules apply in Agent, Ask, Plan, and Debug modes. The rules are included in every conversation regardless of which mode you're using." Chat, Composer, and Agent were merged into one interface in v0.46, and "Composer" now names a model, so the surfaces said to lose their instructions had not been separate readers for roughly a year and a half.
+  
+  What changes in practice:
+  
+  - **`init` no longer reports an instruction gap for Cursor.** Nothing is written for it, as before, and the skill no longer tells you a consolidation costs you coverage.
+  - **A Cursor rule is offered on activation, not on readership.** `init` used to offer consolidating a `.cursorrules` or `.cursor/rules/*.mdc` only alongside a generated copy left behind for the other modes. There are no other modes to keep working. The trade it names now is the real one: a rule carrying `globs` or a `description` loads when those match, and the same content in `AGENTS.md` loads on every turn.
+  - **`doctor`'s `nonstandard-instructions` repair drops the generated-bridge wording**, since leaving one behind is a per-harness question rather than what every consolidation does.
+  - **`CLAUDE.md` has a second reason not to exist.** Cursor reads it the same way it reads `AGENTS.md` and applies it to every conversation regardless of `alwaysApply`. Claude Code reads it *instead of* `AGENTS.md`; Cursor loads it *in addition to*. The rule against writing one was argued from Claude Code alone and now holds twice over.
+  
+  Evidence: E-CUR-05, E-CUR-06, E-CUR-07, superseding E-CUR-02. Disclosed under Corrections on the Sources page.
+
+## 0.13.0
+
+### Minor Changes
+
+- e8491dd: The `enhance` skill no longer offers a section that your agent already reads from your global instructions. When the repository's `AGENTS.md` lacks an addition but instructions loaded from outside the repository carry its current text, the verdict is *already global*. Nothing is offered, and the report says a repository copy would reach your team but give you the text twice. The skill writes that copy only if you ask for it. When both places carry the text, the report names the duplicate.
+  
+  The global destination it recommends is now `~/.agents/AGENTS.md`. The skill also says that a harness reads that file only through its own user-scope file, such as `~/.claude/CLAUDE.md` on Claude Code.
+- 1c7ecac: The `enhance` skill now checks the copy of an addition in your global instructions, and says what it found when that copy and the repository's differ:
+  
+  - **Global instructions hold a retired wording, or your own words, and the repository has none.** The skill no longer offers the addition. It hands you the current text to put in place of a retired global wording, and leaves your own words alone.
+  - **Global instructions hold a retired wording, whatever the repository holds.** You get the current text for the global copy, even where the repository's section is already current.
+  - **The repository holds a retired wording, and your global instructions hold the current text.** The replacement is still offered. It now says you would read the text twice, and offers removing the section as the other answer.
+  - **The repository holds your own words, and your global instructions hold the current text.** Nothing is offered, and the report says you read the subject twice.
+- cf26cf9: The `enhance` skill now offers a second addition, `## List identifiers`. It tells the agent to label every list it presents: letters or numbers for a plain list, and a kind prefix for a typed one, such as P1 for proposals, Q1 for questions, or S1 for scenarios. Labels stay stable when the list is revised, and new items continue the sequence.
+  
+  The skill offers it the same way as `## Delegation`. It is offered only where the merged instructions do not already cover the subject, it recommends the owner's global instruction file, and it is written only on approval. Each addition is offered and reported on its own.
+- e538ecc: `init` and `doctor` now work with references instead of governances.
+  
+  - **`init`** creates `.agents/references/` instead of `.agents/governances/`. Its result reports `references`, the number of references the project tier holds, in place of `governances`. Documents in an existing `.agents/governances/` are counted too.
+  - **`doctor`** reports a `references` section in place of `governances`. There is one row per name per layer, `{ name, tier, path, status }`, for the managed, project, and user tiers. `status` is the one `reference list` gives, such as `used` or `shadowed by project (first-wins)`. When no layer holds a reference, the section reads `0 references — no layer outside the plugin tier holds one`.
+  
+  The legacy `governances/` folders are still read by `reference`, so nothing already written stops resolving.
+- f5855ab: New `load-reference` skill: the one way a skill loads a reference. A calling skill writes one line, such as "Load `skill-design` and `agent-tool-output` with the `load-reference` skill in the `buddy-agent-harness` plugin." The skill runs `reference show` for every name at once, from a launcher bundled in its own folder, with no `npx` and no network access. When a name is missing everywhere, or the launcher is absent because the plugin was installed from git, it reads the calling skill's own copy under `references/` and tells you so.
+  
+  The skill's `README.md` lists how each harness names it: `/buddy-agent-harness:load-reference` in Claude Code, `/load-reference` in Cursor and GitHub Copilot CLI, `$load-reference` in Codex. The table is generated from `@cyberuni/agent-harness`.
+  
+  The launchers bundled into the shipped skills no longer break a command that takes several values. Minifying renamed the class the CLI parser uses to recognize them, so `reference show` rejected every name when run from a bundle.
+- 3f850f5: `buddy-agent-harness mcp project` writes your golden MCP server set (`.agents/buddy-agent-harness/mcp.toml`) into each enabled harness's own MCP file: `.mcp.json`, `.cursor/mcp.json`, `.codex/config.toml`, and `.gemini/settings.json`. It is a dry run unless you pass `--write`.
+  
+  ```
+  actions:
+    target                 server  action  detail
+    .mcp.json              fs      add     creates the file
+    .codex/config.toml     old     refuse  transport: Codex supports no SSE transport
+    .gemini/settings.json  linear  add     appends the server
+  ```
+  
+  - **Each harness gets its own spelling.** You write a reference once as `${NAME}`. Cursor gets `${env:NAME}`. Claude Code and Gemini CLI take it as written. Codex gets `env_vars`, `env_http_headers`, or `bearer_token_env_var`. A timeout in milliseconds becomes Codex's `tool_timeout_sec`.
+  - **It refuses rather than guesses.** A server a harness cannot hold as written is refused, and the refusal names the field. So is a golden entry holding a literal credential.
+  - **It never overwrites your edits.** A server changed on the harness side is skipped.
+  - **It keeps the rest of the file.** Every byte outside the entry it writes stays as it was, comments included. That holds when it updates a server already there, in `.gemini/settings.json` and `.codex/config.toml` too. It will not rewrite an entry that holds a comment, or a Codex server written as an inline table. It lists those changes for you to apply instead.
+  - **It records what it wrote.** `--write` writes `.agents/buddy-agent-harness/mcp.projected.json`, which `doctor` already reads to tell which side moved.
+  
+  The `repair` skill now handles `mcp-unprojected` and `mcp-diverged-golden`: it shows the plan and runs the command once you approve.
+  
+  `doctor` now reads each harness's MCP file in that harness's own format:
+  
+  - A Gemini CLI `url` reads as SSE, and `httpUrl` as streamable HTTP.
+  - A Codex server's headers, passed-through variables, and timeout are compared instead of ignored.
+  - A golden field a harness has no place for, such as Cursor and `description`, is no longer reported as drift.
+- bf1dd95: `buddy-agent-harness mcp reconcile` pulls a change made in a harness's MCP file back into your golden set (`.agents/buddy-agent-harness/mcp.toml`), one approved field at a time. It is a dry run unless you name a field with `--accept`.
+  
+  ```
+  fields:
+    path                                          action  value
+    .mcp.json#servers.linear.command              import  command = "bunx"
+    .mcp.json#servers.docs.url                    import  url = "https://docs"
+    .mcp.json#servers.docs.headers.Authorization  refuse
+  ```
+  
+  ```sh
+  buddy-agent-harness mcp reconcile --accept '.mcp.json#servers.linear.command'
+  ```
+  
+  - **One field per approval.** There is no approve-all. A server the golden set lacks is added from the fields you approve, and one of them must be its `command` or `url`.
+  - **Conflicts stay yours.** A field both sides changed, or one no baseline can place, is reported and never imported.
+  - **No credentials.** A literal credential is refused and never shown. The server's other fields are still offered, so you can reference the secret as `${VAR}`.
+  - **Harness defaults are not your edits.** A Codex or Gemini CLI timeout equal to that harness's default is not imported.
+  - **Each harness's spelling comes back as `${NAME}`.** That covers Cursor's `${env:NAME}` and Codex's `bearer_token_env_var`.
+  - **Your comments stay.** The golden set is edited in place, not rewritten. A field it spreads over a sub-table is listed for you to apply by hand.
+  
+  The `repair` skill now handles `mcp-diverged-target` and `mcp-undeclared`. It offers each field on its own and passes only the ones you approve.
+- ba6d264: Add `reference show|list|search`, which reads on-demand reference documents by name. A reference costs no context until it is fetched, unlike a skill, whose description loads in every session.
+  
+  - **Tiers.** A name resolves through the managed, project (`.agents/references/`), user (`~/.agents/references/`), and plugin tiers, highest first. The plugin tier is this package, the plugins your harness has enabled, and the dependencies declared in the nearest `package.json`; ask for `<plugin>/<name>` when two plugins hold a name.
+  - **Your harness.** The command detects the harness it runs under. It reads a `references/` folder beside that harness's managed settings (for example `/etc/claude-code/references`), and the `references/` of each plugin the harness has enabled, from the folder it installed the plugin in. A plugin that is installed but not enabled is never read. Policy kept in MDM, the Windows registry, or the vendor's servers cannot be read locally; `--trace` and `list` show it as `not read`, with the reason.
+  - **Monorepos.** The project tier is read at `--root` and each folder above it up to the repository root (`.git`, `pnpm-workspace.yaml`, or a `package.json` with `workspaces`), nearest first, so a package can override a reference the repository shares.
+  - **Merge modes.** The higher document chooses in its frontmatter: `first-wins` (default), `combine`, or `merge-sections`, which merges by heading and honors `<!-- merge: combine -->` and `<!-- merge: remove -->` under a heading.
+  - **File names.** `<name>.md`, `<name>/README.md`, `<name>/index.md`, or `<name>/SKILL.md`.
+  - **Several names per call.** `show a b c` returns each document between `<reference>` delimiters, in order; `--format json` returns an array. A missing name is reported in place, suggests close names, and makes the exit code 1.
+  - **`--trace`** shows every layer checked and why each was used or shadowed; `list` marks the same.
+  
+  `governance list|show` is deprecated. It works as before and writes one line on stderr pointing to `reference`. `reference` still reads the `governances/` folders, below `references/` in each tier.
+
+### Patch Changes
+
+- e688aef: Read each harness's skills directories from `@cyberuni/agent-harness` instead of keeping a copy. The projection targets `init` and `doctor` use are unchanged: Claude Code is still the only harness projected into.
+- 9176f62: The `enhance` skill's `## Delegation` section now sizes the job rather than the step: a job made of many routine steps, or of waiting on something outside the agent, goes to a subagent as one job. It also splits a job by what each part needs, sending a hard part to whichever model does it best, and has the brief name what the user authorized and what the subagent must not do.
+  
+  A repository holding the previous wording is offered the new one as a replacement.
+- cbeda67: The `enhance` skill no longer assumes that no harness scores the `## List identifiers` wording. When it cannot tell whether an existing List identifiers section is yours, it offers to settle the question by measurement wherever the repository has a harness for that wording. It still offers two answers where there is none.
+- a0d0b0e: The `enhance` skill now states its stale check once, in the skill itself, instead of inside the `## Delegation` reference. Each addition's reference names only its own history file and what is specific to it, so revising one addition's reference no longer changes how the other is judged. The already-current and already-global checks now share one stated containment test. How a section is classified is unchanged.
+- b876ce5: The `init-buddy-agent-harness` skill now states three rules it relied on the reader to infer. Declining one step drops only that write, and the other approved steps go ahead without being asked again. Creating a `.gemini/settings.json` that does not exist yet needs no approval. The report gives the reason each canonical-only artifact was left alone.
+- f2a29ee: `run(argv)` now returns the usage code `2` on an unknown option or command, where it returned `0` and left the code on `process.exitCode`. A caller can assign the result directly:
+  
+  ```js
+  process.exitCode = await run(argv)
+  ```
+  
+  The executable and the skill launchers already exited `2` there and still do. This comes from `clibuilder` 11.3.0, whose `parse()` now returns the code it records.
+
+## 0.12.0
+
+### Minor Changes
+
+- 668e569: Claude Code reads `AGENTS.md` itself from v2.1.277, so the `CLAUDE.md` import bridge is gone from the model.
+  
+  `init` writes no `CLAUDE.md` — not at the root, and not beside a nested `AGENTS.md`. Its instruction work is consolidation instead: a `CLAUDE.md` holding content of its own is now the urgent finding, because Claude Code reads it *instead of* `AGENTS.md`, and it is consolidated and removed on approval rather than left behind as a generated copy. A `CLAUDE.md` that is only `@AGENTS.md`, or a symlink to it, is offered for removal and kept on a no — the import is still the only way in for sessions that cannot read `AGENTS.md` directly, such as a third-party provider or a version before v2.1.277.
+  
+  `doctor` reports two new findings in the `instructions` section: `instructions-shadowing` for a file read instead of the `AGENTS.md` beside it, and `instructions-superseded` for a bridge that still works and is no longer needed. Both are checked per directory holding an `AGENTS.md`, for `CLAUDE.md`, `.claude/CLAUDE.md`, and `CLAUDE.local.md`. It no longer reports a missing `CLAUDE.md`.
+  
+  Gemini CLI is now the only harness in the registry that needs an instruction bridge. Nothing changes about skills projections: Claude Code still needs `.claude/skills`.
+- 7c29ed6: The `enhance` skill now recommends the owner's own global instruction file for the `## Delegation` section, rather than the repository's `AGENTS.md`.
+  
+  Nothing in that text is about the repository in front of it: it says how to work with subagents, which holds in every repository the owner opens. Copying it into each one is a copy per repository to keep in step — the drift this package exists to remove, one level up from the file it removes it in. So an addition now declares where it belongs, the offer leads with that destination, and the alternative is named with what each one buys: the global file reaches every repository the owner opens and nobody else, and the project file reaches everyone who clones it at the cost of a copy per repository.
+  
+  Where the agent's own always-loaded instructions already carry the text, the offer says so — the repository copy then adds the team and nothing else, and the owner carries the text twice. That is stated, not decided.
+  
+  A global placement is handed over rather than written. The skill still writes the root `AGENTS.md` and nothing else, so it gives the text and the path and stops; on Claude Code that path is `~/.claude/CLAUDE.md`. Where the harness in use documents no user-scope instruction file, no path is guessed.
+- fe1a601: Add `buddy-agent-harness governance list` and `governance show <name>`, and own the override layers a governance can be replaced in.
+  
+  A governance is a version-pinned Markdown rule set a skill loads, such as `skill-design` or `agent-tool-output`. Each skill ships its own committed copy, which is the version it was tested against. This command reads the layers someone can override that copy in, in lookup order: the project's `.agents/governances/`, the user's `~/.agents/governances/`, then two machine-wide directories, which are defaults rather than enforcement and therefore sit last. The layered resolver moved here from `universal-plugin` rather than being written again.
+  
+  There are two machine-wide layers on purpose. A new install uses the directory this package owns (`/etc/buddy-agent-harness/governances` on Linux, `/Library/Application Support/BuddyAgentHarness/governances` on macOS, `%ProgramData%\BuddyAgentHarness\governances` on Windows). The directory `universal-plugin` wrote is still read one layer below it, so a machine already carrying governances keeps resolving them. Wherever that layer appears it is reported as deprecated: `governance list` carries a status on its row alone, and `doctor` names the directory each override was read from, so an admin can see both that there is somewhere else to put it and where it is now. Nothing is enforced — the old location still answers, so there is nothing to repair.
+  
+  `governance show` writes the document itself on stdout by default; `--format toon` or `--format json` wraps it with the layer it came from. `governance list` reports every name at the layer that would win, alongside the layers themselves, so a reader knows where to write an override.
+  
+  `--overrides-only` on either subcommand restricts the answer to those three layers and never returns a governance this package ships, exiting non-zero when none of them holds the name. That is what lets a skill decide whether an override exists without paying for a registry lookup: it runs the command only from an already-installed copy, and reads the exit code.
+  
+  `init` now also creates `.agents/governances/` when it is absent and reports how many documents it holds, the same contract it already has for `.agents/skills`. `doctor` now carries a `governances` section naming each override and the layer it came from, or stating the zero. An override is a choice someone made, so it is never a finding: `doctor`'s existing findings, its repairs, its exit code, and its project-scope-only MCP policy are unchanged.
+- aa1b57a: Rename the `init` and `doctor` skills to `init-buddy-agent-harness` and `doctor-buddy-agent-harness`.
+  
+  A plugin-scoped skill named `init` or `doctor` collides with the same names shipped by other plugins, so a harness loading several plugins could not tell which one a bare `init` or `doctor` invocation meant. Invoke them as `/buddy-agent-harness:init-buddy-agent-harness` and `/buddy-agent-harness:doctor-buddy-agent-harness`.
+  
+  The CLI commands `init` and `doctor` keep their names — this only renames the two agent skills that wrap them.
+
+### Patch Changes
+
+- 7d98f7e: The `enhance` skill's `## Delegation` section now also tells the agent how to pick a subagent's reasoning effort: the lowest, unless it could not write down the steps that reach the answer.
+  
+  A repository holding the previous wording is offered the new one as a replacement.
+- 9c2bd77: The `init` skill now weighs a derived `AGENTS.md` line against the work a repository actually does, not only against whether the fact is worth knowing.
+  
+  A line that passes the value test can still serve a minority of sessions, and every session pays for it. So a surviving line is now checked for the share of the repository's work it serves — read off the repository's own commit history — and one serving a minority is folded into a line that already earns its place, or cut with a note saying where the repository already catches it. Before cutting, the line is restated in its universal form: a narrow-sounding line is often a narrow phrasing of a fact that covers everything.
+  
+  Two smaller rules come with it. Where the repository already keeps an index of where facts live, `init` reads it first and then names it in one line, instead of copying its rows into the file that points at it. And a command goes into `AGENTS.md` only after it has been run in the repository and done what the line claims, so a task list read out of a build config — or a second command the first already covers — is caught before it ships.
+
+## 0.11.0
+
+### Minor Changes
+
+- 75a5d3a: `listMcpServers` now also reads VS Code, Windsurf (under `devin-desktop`), OpenCode, and Zed at every scope those hosts document; Claude Code's project-local servers nested in `~/.claude.json`; and the MCP servers an installed Claude Code plugin ships, gated on whether that plugin is enabled for the project. `McpServerEntry.scope` gained `'local'` and `'plugin'`, and `McpServerEntry` gained an optional `plugin` field naming the plugin id. `ListMcpServersOptions` gained an optional `platform` override so the VS Code user directory is testable on every OS.
+
+## 0.10.0
+
+### Minor Changes
+
+- 945a3a5: Export `listMcpServers` — a redaction-safe inventory of every MCP server configured across the supported harnesses, for a project directory and (where a harness documents one) an injectable home directory.
+  
+  It reuses `diagnoseMcp`'s own parsing, model, and secret-redaction rather than re-implementing them, and it never surfaces a credential: `command` is trimmed to its basename, `args` drops any `--flag=value` pair a credential-bearing flag would carry literally, and `url` is trimmed to its origin and path. `env` and `headers` are not returned at all.
+  
+  Unlike `doctor`, which stays project-scope only by design, this export also reads the user-scope MCP configuration each harness documents — Codex and Copilot CLI resolve theirs through `CODEX_HOME`/`COPILOT_HOME` first. It changes nothing about what `doctor` itself reads.
+  
+  This is meant for a consumer that wants to bundle an MCP inventory without pulling in this package's CLI: the module this ships from imports nothing from `clibuilder`.
+
+## 0.9.1
+
+### Patch Changes
+
+- 53b3609: Bundle each shipped skill's script per skill folder, so it runs standalone from a copy of that folder alone — the state an installer that copies only the skill folder (`skills add --skill <name>`, a symlinked or partial install) actually leaves it in.
+  
+  Previously each skill's `scripts/<subcommand>.mjs` walked four directories up from itself to `dist/cli.mjs`, which only resolves when the whole package sits above the skill. Each script is now a self-contained bundle — built from a small `src/skill-scripts/<subcommand>.ts` source, with every runtime dependency inlined — that reaches nothing outside its own file.
+  
+  The bundle is a build artifact distributed through the npm package's `files`, not committed to git: `pnpm build` produces and copies it, and `prepack` runs it before publish. A skill installed from a git source, or a harness that cannot resolve or run the script path, falls back to the pinned `npx -y buddy-agent-harness@^<version> <subcommand>` invocation each `SKILL.md` documents — unchanged from before.
+  
+  `pnpm skill:gen:check` no longer compares the bundle (there is nothing committed left to diff); a new `pnpm pack:check` packs the package the way `npm publish` would, unpacks it, and verifies every shipped script is present and one runs standalone with no `node_modules` above it. It runs as part of `pnpm verify`, after `build`.
+
+## 0.9.0
+
+### Minor Changes
+
+- 38f8b58: `enhance` now spots a section carrying a wording it has since retired, and offers the current one in its place.
+  
+  Coverage was judged by meaning alone, so a repository holding an earlier form of `## Delegation` read as covered and the current text was never surfaced. Coverage is now two questions: the first is unchanged, and only text that reads as covered is asked the second, which is about provenance rather than meaning — did this text come from the addition, at a wording it used to ship?
+  
+  A present section is checked against the text the addition would offer before anything else: a section that already is that text is reported as already current, not as the owner's own, and nothing is offered. Otherwise each addition keeps every wording it has retired, verbatim, beside it; `references/delegation.history.md` is the first. To decide whether a section is stale, it is compared against those — never weighed against the text that would be offered, since differing from it is what a rewrite produces. A section reproducing one, edits and all, gets the replacement offered under the same approval gate as an addition, and on approval only that section changes. A section written from scratch on the same subject is left alone. Where it is honestly neither — part of a retired wording inside prose the owner clearly wrote — the skill says it cannot tell, shows all three texts, and asks rather than guessing.
+  
+  That question carries three answers, and the third is to settle it by measurement: the repository's own evaluation harness, where it has one, scores the existing section against the current wording and reports both. This package's own repository uses its `eval-delegation` skill; a consumer repository has its own or none, and the skill checks before offering it. The replacement is offered only if the current wording wins; a section that scores level or better is kept, and said to be kept. It is never run unasked.
+
+### Patch Changes
+
+- 1c6433e: Bundle the CLI's dependencies into `dist/cli.mjs`, so the shipped skill launchers actually work.
+  
+  The `skills/*/scripts/*.mjs` launchers already preferred the shipped CLI over `npx`, but an installed
+  plugin directory is a copy of a source checkout rather than an npm install, so its `node_modules` is
+  absent or incomplete — running a launcher from one failed with
+  `Cannot find package 'type-plus' imported from .../clibuilder/esm/builder.js`. The published
+  `dist/cli.mjs` now inlines every runtime dependency and runs with no `node_modules` present at all.
+  
+  Bundling also required pointing `jsonc-parser` (reached through clibuilder) at its ESM build. Its
+  `main` is a UMD bundle whose factory calls `require("./impl/format")` and three siblings — specifiers
+  a bundler cannot analyse, so those modules were silently left out and the CLI threw
+  `Cannot find module './impl/format'` at startup.
+  
+  The library entry (`.`) is unchanged. Its dependencies stay external on purpose: it exports
+  `activate` / `*Command` for a host CLI to compose, and host and plugin must share one `clibuilder`
+  instance rather than each holding a private copy.
+
+## 0.8.0
+
+### Minor Changes
+
+- a5d5ddc: Rewrite the Delegation section `enhance` offers so it tells the agent to pick a spawned subagent's model.
+  
+  The previous wording bounded how cheap a subagent may be but never asked for the choice, so an
+  unset model kept inheriting the parent's. The section now names that inheritance, and makes the
+  cheapest model the pick unless the agent cannot say what a right answer looks like or could not
+  cheaply tell a wrong one.
+- c9fd249: Add `dep-plugins`: derive a marketplace catalog for plugins shipped by a repository's dependencies.
+  
+  A dependency that ships an Agent Plugins manifest at its package root is a plugin the consuming
+  repository could use, but no harness discovers one on its own. This command derives a marketplace
+  catalog from the declared dependencies that ship a manifest, so a harness can install them through
+  its own plugin mechanism. It reaches whole plugins — agents, commands, hooks, MCP servers — rather
+  than only skills.
+  
+  ```sh
+  buddy-agent-harness dep-plugins                # write .agents/buddy-agent-harness/.claude-plugin/marketplace.json
+  buddy-agent-harness dep-plugins --check        # report whether it is current; writes nothing
+  buddy-agent-harness dep-plugins --format text  # human-readable report; `toon` is the default, `json` is also available
+  buddy-agent-harness dep-plugins --root ./pkg   # run against a directory other than the current one
+  ```
+  
+  Three decisions worth knowing:
+  
+  - **Resolution, not scanning.** Only declared `dependencies` and `devDependencies` are considered,
+    located through the module resolver. Walking `node_modules` would pull in transitive dependencies
+    nobody vetted, and a plugin is instruction text that steers an agent.
+  - **`npm` sources, not paths.** A path source is resolved against the marketplace root and may not
+    escape it, so a path-based catalog would have to sit at the repository root — where the
+    repository's own public catalog already lives, leaking dependency plugins to anyone adding it. An
+    `npm` source carries no path, so this catalog lives in its own directory. It also means the design
+    is unaffected by pnpm's layout or by a missing `node_modules`.
+  - **Derived in full, never merged.** A plugin added, removed, or moved to a new version all follow
+    from regeneration, so there is no reconciliation logic to get wrong. `--check` compares bytes.
+  
+  The catalog is the committed artifact. Registering it with a harness and installing from it are
+  per-machine actions, so the command **reports** what the harness needs and the command that does it,
+  and never touches harness state itself:
+  
+  ```
+  harness:
+    runtime: claude-code
+    actions:
+      do: claude plugin marketplace update acme-web && claude plugin update review@acme-web --scope project
+      why: installed 1.0.0, catalog pins 2.0.0
+  ```
+  
+  It reads each harness's own state files to compute that delta, covering the three cases a dependency
+  change produces — a plugin appearing, a version moving, and a plugin whose dependency was removed.
+  The last one matters most: nothing else removes it, so the harness leaves it installed and reporting
+  a load failure. Every emitted verb carries `--scope project`, because all of them default to user
+  scope, and user scope is shared across every repository on the machine — two repositories whose
+  catalogs share a marketplace name collide there silently. A registration already pointing elsewhere
+  is reported rather than overwritten.
+  
+  **Runtime support**, each established by running the shipped CLI rather than from documentation:
+  
+  | Runtime | Consumes this catalog | Notes |
+  | --- | --- | --- |
+  | Claude Code | yes | every verb defaults to user scope, so each carries `--scope project`; refresh is `plugin update`, since re-running `install` is a no-op |
+  | Codex | yes | no update verb and no scope — re-running `plugin add` re-reads the catalog and replaces the cached copy; the installed version appears only in the cache directory name |
+  | Copilot CLI | **no** | rejects an npm source (`plugins.0.source: Invalid input`); it accepts a path source, which cannot reach `node_modules` from a subdirectory |
+  | Cursor | no | exposes no plugin subcommand from a terminal |
+  
+  Only runtimes actually present on the machine are reported, so the output names work the reader can
+  actually do.
+
+## 0.7.0
+
+### Minor Changes
+
+- 99db013: Give the CLI a callable entry point, so `bin` owns the process and skills stop mutating `argv`.
+  
+  `src/cli.ts` exported `main()`, which built the app, read `process.argv` and wrote
+  `process.exitCode`. Nothing could invoke a command without going through the process, and the cost
+  showed up in generated code: every skill launcher spliced the subcommand into global `process.argv`
+  and then side-effect-imported the executable.
+  
+  The two boundaries are now separate. `bin/buddy-agent-harness.mjs` is the **process** boundary, the
+  only place that reads `process.argv` or writes `process.exitCode`. `src/cli.ts` is the
+  **application** boundary: it takes an argv and returns an exit code.
+  
+  New export `run(argv: string[]): Promise<number>`. The `clibuilder` application stays internal —
+  exporting it would make `clibuilder`'s builder shape part of this package's public API, so a
+  `clibuilder` major would become a major here. The generated launchers now compose an argv and call
+  `run`, mutating nothing:
+  
+  ```js
+  const code = await run([...process.argv.slice(0, 2), 'doctor', ...process.argv.slice(2)])
+  if (code !== 0) process.exitCode = code
+  ```
+  
+  The code is applied only when non-zero because `clibuilder` reports an unknown option or unknown
+  command by writing `process.exitCode` itself and returning nothing, so `run` reports `0` on a path
+  where the process must still exit `2`.
+  
+  `doctor` and `init` now **return** their exit codes rather than writing `process.exitCode`. A
+  command that writes the code reports its failure past the caller instead of to it, so `run` would
+  have returned `0` for the commonest failure there is. Nothing changes for a shell caller.
+  
+  New export `buildDoctorReport`, with its `DoctorReport` type. `doctor`'s assembled report — the
+  `bin` line, the healthy-answer sentence, the deduped `help` section — was reachable only by running
+  the CLI and re-parsing its own TOON. Three layers are now each reachable on their own:
+  `diagnoseBridges` and its siblings return the raw diagnosis, `buildDoctorReport` returns the report
+  as a value, and `run` returns that report serialized plus an exit code.
+  
+  Two fixes in the lines this touched:
+  
+  - **Errors went to stdout.** `doctor`'s default output is TOON that agents parse, and the error line
+    landed in the stream they were parsing. It goes to `stderr`.
+  - **`--version` was wrong.** It reported `0.1.0` while the package was at `0.6.0`, five minors
+    behind. It is read from the manifest.
+  
+  Also fixed: `skills/repair/`'s launcher was labelled generated but was not on the generator's list,
+  so nothing rewrote it and nothing caught it going stale. The generator now keys each launcher by the
+  subcommand it runs, and a test asserts every shipped launcher is a target it checks.
+- 3550496: The `doctor` skill is split into a lean `SKILL.md` and lazy-loaded reference pages, the way `init` is.
+  
+  Everything `doctor` knows was in one 125-line file, so an agent acting on a single MCP credential finding read the skills-bridge table, the instruction-bridge table, the configuration table and the Windows case to get there. `SKILL.md` is now 62 lines — how to run it, how to read the report, the routing rule, and a pointer table — and the finding tables live one family per page under `references/`, with a page per harness under `references/harnesses/`.
+  
+  The pages are generated from the same guidance table and the harness registry that the command reports from, so they cannot drift from it. Editorial judgment about a harness stays hand-written in the `init` skill, and each generated harness page links to it where one exists; which harnesses have one is read off the filesystem rather than listed.
+  
+  Three checks come with the split: every reference page matches what the generator would write, every page the pointer table names exists, and every cross-reference into the `init` skill resolves.
+- 3550496: `doctor` reports agent configuration that only one harness can read.
+  
+  Four finding families all answered a version of "is something broken". None of them asked how far the configuration that is there actually reaches, so a `.cursor/rules/*.mdc` — which works, in Cursor, and nowhere else — was invisible to the one command that is safe to run from a session-start hook. The guidance in it reaches one tool, and nobody finds out except by noticing an agent behave differently somewhere else.
+  
+  The new family reports each artifact with the canonical form it converts to: legacy instruction files and always-on rules to `AGENTS.md`, harness commands and harness-directory skills to `.agents/skills`. A `.mdc` rule splits on whether its frontmatter binds it to globs — always-on prose is what `AGENTS.md` holds verbatim, while a rule bound to paths converts to a skill only where the scoping is incidental. A subagent names no owner at all: no cross-harness format exists, so the finding reports that gap rather than promising a conversion.
+  
+  Nothing here is repaired by `repair`, which corrects configuration that is wrong; nothing here is wrong. Nothing is offered by `enhance`, which adds guidance a repository is missing; this guidance is present. Every conversion with a destination is `init`'s, and every one is approved before it lands.
+  
+  The artifacts are declared per harness in the registry, beside that harness's other paths, and the per-harness reference pages are generated from the same declaration. Hooks, LSP settings, and output styles are deliberately not covered: their shapes differ per harness with no safe projection, so no canonical form can be named for them.
+- 2927512: `doctor` now reports each repair as a runnable command and a prose instruction, instead of wrapping every repair in `Run`
+  
+  Every `help` entry used to be rendered as ``Run `<repair>` ``, whether or not the repair was a command. Most are not, so the report published lines like ``Run `remove .windsurf/skills and enable the harness that replaced it` `` — an invitation to paste prose into a shell.
+  
+  `help` is now one row per repair with two columns:
+  
+  ```
+  help[3]{command,instruction}:
+    buddy-agent-harness init --copy --force,run `buddy-agent-harness init --copy --force` to rebuild .claude/skills as a real directory
+    buddy-agent-harness init,run `buddy-agent-harness init` to create the bridge at .windsurf/skills
+    "","hand .gemini/settings.json to `/buddy-agent-harness:init`, which writes the bridge into it"
+  ```
+  
+  `command` runs verbatim and completes the repair. It is empty when no single invocation does, which is the signal to act on `instruction` instead — and it stays empty for a repair whose prose quotes a runnable diagnostic, so a caller that executes every non-empty `command` never rebuilds a diverged bridge over the side holding the newer edit.
+  
+  Both keys are always emitted, so TOON renders `help` in its tabular form rather than degrading to a nested list.
+- 3550496: `init` lists the configuration only one harness can read, and asks before migrating any of it.
+  
+  `doctor` now reports these artifacts; `init` is the skill that acts on them. It reads the list from `doctor` rather than deriving a second one, presents each with the canonical form it is a candidate for, and asks per artifact — never for the set, because two rules can be in the list for opposite reasons and one approval would carry a file the owner never looked at.
+  
+  Rules leave the canonical-only bucket. A rule whose paths are incidental to what it says converts to a skill, which every harness reads; a rule whose path scoping is the point has no equivalent and stays. Which one a given rule is cannot be read off the file, so it is offered rather than assumed. Subagents, hooks, output styles and MCP servers stay canonical-only and are reported as having no candidate at all, so the list is not read as a queue of pending work.
+  
+  No conversion is offered that would leave fewer readers than before. Cursor reads `AGENTS.md` in Agent mode only, so consolidating `.cursorrules` and deleting it takes that guidance out of Chat and Composer; the offer is always the consolidation together with the generated copy that keeps them working. The existing rule against rewriting those files is not removed — it is the reason the migration is offered rather than applied.
+  
+  The `init` skill now ships a `doctor` launcher beside its own, the way `repair` already does.
+- 9be4f0b: `doctor` diagnoses a golden MCP server set.
+  
+  A repository may now keep one canonical MCP server per entry at `.agents/buddy-agent-harness/mcp.toml`, in the superset of fields the supported hosts accept. Where that file exists, `doctor` compares it against each harness's own project-scope MCP configuration — Claude Code's `.mcp.json`, Cursor's `.cursor/mcp.json`, Codex's `.codex/config.toml`, and Gemini CLI's `.gemini/settings.json` — and reports how the two have drifted, in either direction. No golden set means no MCP findings, and `init` still converts nothing.
+  
+  Comparison is semantic rather than textual: no two of those files ever share bytes, so each side is parsed into one model. A field the golden set leaves unset is never a difference, because a host restating its own default cannot be told apart from a deliberate edit. Direction comes from a last-projected record where there is one and from git history for a tracked target, and is reported as unknown rather than guessed when neither answers.
+  
+  `doctor` also reports a literal credential sitting in any of those files, including the golden set. A finding carries the file, the server, and the field and never the value — no truncated preview either — and an unreadable golden set is reported by line and column, because a parser's own message quotes the line that holds the secret. A literal in a tracked file is reported as committed, and its repair is to rotate the credential rather than to move it.
+  
+  `doctor` remains read-only. Projecting the golden set into a harness and reconciling a harness-side edit back into it are writes and are not part of this change.
+- 2b3b42d: Add a `repair` skill, and grow `doctor` to detect what it repairs.
+  
+  `init` consolidates what a repository has, `enhance` offers what it is missing, and `doctor`
+  reports what is wrong. Configuration that is present but **wrong** had no home: not missing, so
+  `enhance` would not offer it; user-authored, so `init` would not rewrite it.
+  
+  `doctor` gains a third section alongside its bridge and instruction findings — configuration that
+  resolves fine and is still wrong: `deprecated-harness`, `ignored-bridge`, `unread-local-override`,
+  and `unloadable-skill`. It stays read-only, so it is still safe in a session-start hook.
+  
+  The new `repair` skill runs `doctor` and repairs what it reported, detecting nothing itself, so
+  detection cannot drift into two homes. Every correction is offered with its before and after and
+  written only on approval. Bridge and instruction findings are handed to `init`, which writes both
+  kinds of bridge in the first place — and writes a `CLAUDE.md` stub without asking, where `repair`
+  asks for everything.
+  
+  `doctor`'s `findings` rows now carry a `problem` field naming the finding, alongside `path` and
+  `detail`. Route on `problem`: `detail` is prose meant to be read, and improving its wording must
+  not change what a caller does.
+  
+  `BridgeFinding` gains a required `problem` field. Reading one is unaffected; code that
+  *constructs* one needs the new field. This is the breaking edge of the release.
+  
+  New exports: `diagnoseConfiguration`, and the types `ConfigurationFinding`,
+  `DiagnoseConfigurationOptions`, `ConfigurationFault`, and `ConfigurationProblem`.
+- 46a7b16: `init --force` now takes the targets to replace, so a run cannot reach past the conflict it was invoked for.
+  
+  The flag was a single boolean: the command preflighted every projection target and, when it was set, replaced every conflicting one. Two harnesses whose targets were both occupied were both replaced by a run intended to fix one of them, and `doctor` emitted a bare `init --force` as the repair for a single bridge — so following that repair could silently delete a second harness's user-authored directory.
+  
+  `--force .claude/skills` now replaces that projection and reports any other conflicting target as skipped instead of replacing it. Naming a target no enabled harness projects is an error rather than a run that quietly forces nothing. A bare `--force` still replaces every conflicting target, so existing invocations keep their meaning; the repairs `doctor` prints now name the bridge they are for.
+  
+  The conflict message now prints its targets repo-relative, so what it names is what `--force` accepts back. The initialization result gains a `skipped` field listing the harnesses left untouched.
+
+### Patch Changes
+
+- 990972f: Teach the `enhance` skill that a heading inside a fenced code block is not a heading.
+  
+  Every addition `enhance` offers is a fenced block containing its own heading, so a repository that
+  documents this tool — or an `AGENTS.md` that quotes an addition — carries the exact heading the
+  addition would write while remaining entirely uncovered. Coverage is now judged only against the
+  prose an agent reads as instruction, and the fence is stripped when the approved section is written,
+  so an addition lands as prose rather than as a code block.
+- 804a542: `doctor` reads each file once per commit while deciding which side of a diverged MCP server moved.
+  
+  Naming the side that moved walks git history for the newest commit where the golden set and the harness config agreed on a field. That walk ran once per diverged field and re-read and re-parsed both files at every commit each time: three targets, five servers, two diverged fields each and fifty commits of history is on the order of three thousand `git show` calls and as many parses. Drift is the case the walk exists for, and the shipped `doctor` skill says the command is cheap enough to run from a session-start hook.
+  
+  The parse is now memoized per commit and file, and the commit walk per target, for the lifetime of the one diagnosis. The reported direction is unchanged.
+- 804a542: `doctor` names a dotted MCP server in full in its repair.
+  
+  A finding's locator addresses a place inside a file — `.cursor/mcp.json#servers.linear.command` — and the two membership repairs recovered the server name from it by splitting on `.` and taking the last segment. For `.codex/config.toml#servers.io.github.foo` that gave `foo`, a server present in neither file, so the repair for an `mcp-unprojected` or `mcp-undeclared` finding named something the user could not act on. `io.github.*` is a common way to name an MCP server.
+  
+  The file, server, and field now travel with the finding as parts and are assembled into the locator at the one place that renders it. Nothing splits a locator back apart, because no separator survives the dotted case.
+- 41338f9: Correct the `init` skill's reason for leaving MCP servers alone. It said no safe cross-harness mapping exists; one does, published across fourteen hosts. The reason that survives is that the mapping is not lossless — some servers cannot be expressed for some hosts, and writing one into another host's format means supplying fields the source never carried. `init` still reports MCP configuration rather than converting it, and now says why accurately.
+- 4177091: Route the `repair` skill's family split on the finding's `problem` name.
+  
+  The skill told an agent that every `doctor` finding's repair in `help` names a skill, and to decide the `init`/`repair` split on that name. It does not: `help` carries the command rendering of a repair, which names a shell invocation for every bridge finding and nothing at all for every MCP finding. Only the instruction and configuration families name a skill there — eight of twenty-seven problems — so an agent following the rule literally had no match and no stated fallback for the other nineteen, including the whole MCP family, which the skill never mentioned.
+  
+  Routing is now on `problem`, which every finding carries and which `references/classes.md` is keyed by: a `problem` with a section there is the skill's, and one without it is not. Who a handed-on finding goes to is read off its repair — `init` where the repair names it, a person where it names no skill — and the skill now says outright that an owner is never to be inferred.
+- aa7d27d: Judge a skill bridge by where it resolves, not by how it is spelled.
+  
+  `init` and `doctor` both decided a symbolic link was correct by comparing its text against the one
+  relative path `init` writes. A link that resolves to `.agents/skills` but is spelled differently —
+  one a user wrote as an absolute path, or any repository reached through a symbolic link in a parent
+  directory — was read as a foreign target: `doctor` reported it `stale` and `init` refused to run
+  without `--force`. Both now compare resolved paths, so a bridge that works reports as working.
+  
+  Write the link target the way the platform resolves it. Windows resolves a relative junction target
+  against the process directory rather than the link's own, so the target is now absolute there and
+  stays relative everywhere else, where a relative link survives the repository moving.
+
+## 0.6.0
+
+### Minor Changes
+
+- 74a17e8: Stop projecting `.agents/skills` into `.gemini/skills`. Gemini CLI reads the `.agents/skills` alias at project scope as well as user scope, and that alias takes precedence over `.gemini/skills` in each tier — confirmed against the vendor's own discovery code (`packages/core/src/config/storage.ts`, `packages/core/src/skills/skillManager.ts`) and its skills documentation, recorded as E-GEM-02.
+  
+  `init` now writes nothing for `gemini-cli`, and `doctor` no longer reports a `.gemini/skills` bridge for it. Claude Code is the only harness left with a skills projection. Gemini CLI's instruction bridge is unaffected: it still does not read `AGENTS.md`, so `context.fileName` in `.gemini/settings.json` still has to name it.
+  
+  An existing `.gemini/skills` symlink keeps working — that path is still scanned — so nothing has to be removed from a repository that already has one.
+- 1a33cca: Model user scope as well as project scope in the harness registry. `Harness` now carries a `project` record and an optional `user` record, each with its own `detect` directory and optional `skillsDirectory`, so a harness that answers the canonical-directory question differently at each scope can be recorded truthfully — Gemini CLI needs a projection inside a repository and none at user scope. A missing `user` record means no vendor path is documented, as with Devin Desktop.
+  
+  The published `harnessRegistry` entries change shape: read `harness.project.detect` and `harness.project.skillsDirectory` in place of `harness.detect` and `harness.skillsDirectory`. The `Harness`, `HarnessScope`, and `HarnessScopeName` types are now exported. `init` and `doctor` are unchanged and still act only inside the repository.
+- 0ce8068: `doctor` now verifies the instruction bridges as well as the skill bridges. It reports a new `instructions` section covering the root `CLAUDE.md` import, one stub per nested `AGENTS.md`, and the `context.fileName` entry in `.gemini/settings.json`, gated per harness the same way the skill bridges are. Every repair there is `/buddy-agent-harness:init`: those files carry prose someone wrote, so restoring a bridge without discarding what displaced it is the `init` skill's judgment.
+  
+  The harness registry records an `instructionBridge` per harness scope, so the checked set cannot drift from what the `init` skill writes.
+
+### Patch Changes
+
+- 14a925c: `init` now says how to edit a user-authored settings file: amend it in place rather than round-tripping it through `JSON.parse`, keeping key order, indentation, and comments. `.gemini/settings.json` legally carries comments that a whole-file rewrite would silently delete; `.claude/settings.json` rejects them outright, so nothing may add one.
+
+## 0.5.0
+
+### Minor Changes
+
+- 090bfce: Add an `enhance` skill that offers guidance a repository's `AGENTS.md` is missing.
+  
+  `init` consolidates what a repository already has and bridges the harnesses that cannot read it. It carries no opinions, which is what makes it safe to run anywhere. `enhance` is the other half: it proposes content the repository does not have, one vetted section at a time, and writes only what you approve. `init` now ends by asking whether to run it.
+  
+  Detection decides every run. `enhance` reads the root `AGENTS.md` together with any harness instruction file whose content still belongs in it, because that combined text is what an agent effectively reads — guidance living in a Cursor always-on rule counts as already present. It reads those files and never consolidates them; that stays `init`'s work. Coverage is judged by meaning rather than by heading, so a repository covering the subject under its own wording is left alone.
+  
+  One addition ships: a `## Delegation` section telling an agent when to hand work to a subagent, when to do the work itself, which decisions to keep, and what every brief must carry. It names no model, vendor, or version, so it does not go stale as model lineups change.
+
+## 0.4.1
+
+### Patch Changes
+
+- e40dc14: Name the launcher relative to the skill, without a placeholder.
+  
+  Both skills said `node "<skill>/scripts/<name>.mjs"`, which asked the reader to substitute something the agent already knows. An agent reads the `SKILL.md` from a directory, so `node scripts/<name>.mjs` resolves against that directory on its own.
+  
+  `node` stays in front. The launcher ships as mode `100644`, so its shebang never runs it, and on Windows a shebang does nothing regardless of mode. Naming the file alone would fail on both counts.
+
+## 0.4.0
+
+### Minor Changes
+
+- 9f1ee23: Run the CLI that ships with the skill, and pin the `npx` fallback.
+  
+  Both skills told an agent to run `npx -y buddy-agent-harness`, which downloads the package even when an installed plugin already has it on disk. Each skill now ships a launcher at `skills/<name>/scripts/<name>.mjs` that resolves the CLI from its own location, so it runs against the working directory without fetching anything.
+  
+  `npx` stays documented as the fallback, now pinned to the caret range of the version that generated the skill. Unpinned, a skill from an older install drove whatever npm called latest, and its flags and findings table stopped describing the command it had just run.
+  
+  The fallback is not redundant. A plugin installed from git is a source checkout whose dependencies are never installed, so the launcher cannot resolve `clibuilder` and `npx` is the only path that works. An npm-installed plugin has them and takes the launcher.
+  
+  `renderDoctorSkill` now takes the version to pin, and `scripts/generate-doctor-skill.ts` becomes `scripts/generate-skills.ts` (`pnpm skill:gen`), which writes both launchers, regenerates the `doctor` skill, and rewrites the pinned fallback in the hand-written `init` skill. It runs during `changeset version` so the pin follows the release.
+
+## 0.3.1
+
+### Patch Changes
+
+- bebd1d7: Use "agent harness" as the single term for a coding-agent runtime.
+  
+  The published package description, the three plugin manifests, both READMEs, the project spec, and the `init` skill's `description` all said "coding-agent harness" while the rest of the project said "agent harness". One concept carried two names across exactly the metadata a user reads first, in a package whose own name is `buddy-agent-harness`.
+  
+  Only the wording changes. The clause edited in the skill `description` sits after the harness names that do the trigger matching, so when the skill loads is unaffected.
+
+## 0.3.0
+
+### Minor Changes
+
+- 46d24e6: Teach the `init` skill to take arguments, so `doctor` can hand it a repair verbatim.
+  
+  `doctor` names repairs like `--copy --force`, and until now the `init` skill had no documented way to receive them. It now reads flags and their prose equivalents out of the invocation, passes them through to the command in Phase 4, and still stops for the Phase 3 approval that `--force` would otherwise skip.
+  
+  The mechanism is deliberately not a placeholder. Claude Code appends what the caller typed as `ARGUMENTS: <value>` whenever the body omits `$ARGUMENTS`, Codex skills have no argument mechanism at all, and the Agent Skills spec defines none — so a body that says how to read the invocation is the only form that works everywhere, while a literal `$ARGUMENTS` would resolve on one harness and stay on the page on the rest.
+  
+  `argument-hint` is added for Claude Code's autocomplete. The new references explain why that field is the exception to harness-specific frontmatter being dropped in silence: claude.ai uploads and the Skills API reject it with a hard error.
+- ee027bb: Add a read-only `doctor` command and a generated `doctor` skill.
+  
+  `doctor` reports whether the skill bridges `init` creates still resolve into `.agents/skills`, deriving the bridge list from the same harness registry `init` projects into. It detects the silent Windows failure — a checkout with `core.symlinks=false` materializes a committed symlink as a regular file holding the target path, and the harness loads zero project skills with no warning — along with missing bridges, symlinks pointing elsewhere, and copies that have drifted from the canonical directory.
+  
+  A diverged copy is reported with a direction, computed against the last commit where the two sides agreed, so the report says which side moved rather than only that they differ. A tracked copy is also checked for its `skip-worktree` bit, which some checkout and merge operations clear.
+  
+  The command writes nothing and exits `0` even with findings; each finding names its repair. The command names an `init` invocation for a person at a shell, while the skill hands the same repair to the `init` skill, because rebuilding a bridge can move skills a user wrote. `skills/doctor/SKILL.md` is generated from the same guidance the command prints, with `pnpm skill:doctor:check` in `verify` failing when the committed skill goes stale.
+- 46d24e6: Mount the plugin's commands as `agent-harness` rather than `harness`.
+  
+  `repobuddy` puts every plugin's commands in one namespace, where `harness` is generic enough for a second plugin to want it. The commands are otherwise unchanged: `buddy agent-harness doctor` and `buddy agent-harness init`.
+  
+  This renames the mount point. A consumer running `buddy harness init` has to update the call; the `npx buddy-agent-harness` invocations are unaffected.
+- e46215a: Add `--format text` to `init` and `doctor`.
+  
+  TOON stays the default because it is what an agent parses. `--format text` renders the same result for a person: scalars as `key: value`, each collection of records as a table with its columns aligned, and lists of names as bullets.
+  
+  `--format` now rejects an unknown value with `--format must be toon, json, or text.`
+
+### Patch Changes
+
+- 2992e06: Use `codex,gemini-cli` as the `init --harness` help example, matching `doctor`.
+  
+  The previous example named `windsurf`, which is a deprecated alias for `devin-desktop`, so the one name the help text taught was the one the result reports back as deprecated.
+
+## 0.2.0
+
+### Minor Changes
+
+- 6fc3d80: Adopt the Agent Plugins 1.0.0 canonical manifest. `plugin.json` at the package root is now the single source the vendor manifests are generated from, with skills and per-harness settings under `extensions["org.cyberuni.universal-plugin"]`. The superseded `.plugin/plugin.json` is removed.
+- 2988ece: Tell the `init` skill what belongs in `AGENTS.md`.
+  
+  The skill created the file and said not to invent policy, which left a repository with no existing instruction content getting an empty heading. An empty `AGENTS.md` is worse than none: it looks authoritative and invites the next agent to fill it with guesses.
+  
+  The new `references/agents-md.md` splits the two cases — consolidate existing instruction content preserving its wording, or derive candidates from the repository and confirm each one with the user before writing. Deriving a fact from `package.json` is not invention; asserting a rule nobody agreed to is.
+  
+  It also carries the test for whether a line earns its place. `AGENTS.md` is read every session, so a fact the agent could get in one read costs more than it returns, and anything a linter or type checker already enforces is a second source of truth that goes stale. What survives is the constraint that fails a build in a non-obvious way, the workflow with an unguessable step, and the decision that resolves a real ambiguity. Everything else is pushed into a skill, where only its description stays resident and the body loads on match.
+- 0d1b8af: Align initialization with how harnesses actually discover skills.
+  
+  `.agents/skills/` is read natively by Codex, Cursor, and GitHub Copilot CLI, so those harnesses no longer receive projected files. Only Claude Code, Gemini CLI, and Windsurf are linked, and the link is now a single directory-level symlink to `.agents/skills` rather than one symlink per skill — a skill added later appears in every enabled harness without re-running the command.
+  
+  Claude Code and Cursor are always enabled; other harnesses are added by detection or with the new `--harness` option. The result reports `native` and `linked` harnesses separately so it is clear what was written to disk. Gemini CLI is now a supported harness, and the Cursor, Codex, and Windsurf skill paths have been corrected.
+  
+  The `init` skill is rewritten as a guided survey → classify → confirm → apply → verify workflow. It detects agent configuration a repository already has — instruction files, skills, commands, subagents, rules, MCP servers, hooks — consolidates what has a safe canonical home, reports the rest, and never rewrites a user-authored file without approval. New references cover per-harness support and the cross-harness frontmatter rules that decide whether a shared skill loads at all.
+- 0d1b8af: Add `devin-desktop` and deprecate `windsurf`.
+  
+  Cognition rebranded Windsurf to Devin Desktop on 2026-06-02. More consequentially, Devin scans nine project-scope skill paths and lists `.agents/skills/` first as the recommended one, so it reads the canonical directory natively and needs no projection at all.
+  
+  `devin-desktop` is now a supported harness with no projection target. `windsurf` remains accepted as a deprecated alias and still creates the legacy `.windsurf/skills` symlink, which Devin continues to scan — existing repositories keep working unchanged. The initialization result gains a `deprecated` field listing any enabled superseded names alongside their replacements.
+  
+  This leaves **only Claude Code and Gemini CLI** requiring a skills projection.
+  
+  Documentation adds Antigravity and VS Code as native `.agents/skills` readers. Neither is a registry entry: both need nothing written, and neither has a safe project-scope detection marker — VS Code's `.vscode/` indicates the editor rather than skills support. Harness Support also now records per-claim evidence confidence and the agent list published by `npx skills`.
+- 3fe068e: Support portable plugin manifests for Claude Code, Cursor, Codex, and Copilot CLI.
+
+### Patch Changes
+
+- ab2589a: Update `clibuilder` to v10.
+- 22fe775: Document the Claude Code marketplace as the single install path and drop the `npx skills add` instructions, which vendor a copy of the skill into the consumer's harness directories and make the `init` skill's own projection step fail. Rename the plugin marketplace to `repobuddy` so the documented `buddy-agent-harness@repobuddy` install resolves.