feat(portable): record third-party clients in the pinned capability table (#721)

* feat(portable): record third-party clients in the pinned capability table

Add an optional `clients` block to the portable capability table: per client,
the artifact paths it reads, the manifests that shadow them, its verbatim
install commands, and a dated row per surface it does and does not load.
One validator over the existing records holds a tier to its rows, and
INSTALL.md plus the generated en/zh host reference print those records
instead of an unsourced list of native clients.

* chore: point the changeset at its PR

* fix(portable): hold client records to their paths, evidence, and emitted bundle

* fix(portable): declare install roles, per-surface shadowing, and planned paths

* fix(portable): keep the documented precedence order of shadowing files

* fix(portable): render shadows the build wrote as fact, bind surfaces to paths

Author: ScriptedAlchemy

.changeset/portable-client-records.md

@@ -0,0 +1,5 @@
+---
+"agent-bundle": patch
+---
+
+Record third-party clients of the emitted Agent Plugins artifact in the pinned portable capability table (`clients`), with the paths each client reads, per-file precedence naming the surfaces each shadow takes, install commands carrying the role its own documentation gives them, and a dated row per surface it does and does not load. `INSTALL.md` names, per client, only the discovery paths the build actually planned, prints the action declared `install` rather than whichever command is listed first, marks a client whose documentation shows no local-directory form as marketplace-only, and prints the reason behind every narrowed surface. The generated host reference renders the same records through the same validator instead of an unsourced list of native clients. `INSTALL.md` also reads a precedence file the same build wrote as fact rather than hypothetically: the surfaces that file takes are dropped from what the client reads here, and a file that takes every read surface means this root is read as that plugin instead. A record fails the build when it claims a tier its own rows and paths do not support, loads a surface without reading the file that surface comes from, marks a surface degraded or supported without dated evidence, names an artifact path with no evidence that it is read, shadows a path without naming the surfaces it takes, or declares an install block without a source and exactly one install action. (#721)

README.md

@@ -53,7 +53,7 @@ npx agent-bundle dev --root .                   # local workbench with live rebu
 
 `agent-bundle build` writes one composite plugin root (`artifact/` by default; `--output` or `output.distPath` relocates it), and `targets` selects which host projections it carries: the `.claude-plugin/`, `.codex-plugin/`, and `.cursor-plugin/` manifests and the portable `plugin.json` sit at the root over shared `skills/`, `hooks/`, `mcp/`, and `scripts/` directories, emitted once. Every selected host installs from that same directory, and the generated `INSTALL.md` explains how. Omitting `targets` emits only the `portable` projection.
 
-The `portable` target is the [Agent Plugins open standard](https://agent-plugins.org/specification) (specification 1.0.0) adapter — the default projection, and the layout Cursor, Codex, VS Code, GitHub Copilot, Kiro, and ChatGPT load natively (Claude Code consumes it only through CLI translation). It emits the closed root `plugin.json` (canonical `$schema`, `name`, `version`, `description`, plus `author`, `homepage`, `repository`, `license`, `keywords`, and reverse-domain `extensions` authored under the `portable` config key), `skills/<name>/SKILL.md`, and `mcp.json` with stdio and Streamable HTTP servers whose `args`, `env` values, and `cwd` use the standard's `${PLUGIN_ROOT}`/`${PLUGIN_DATA}` placeholders. Rules, commands, hooks, marketplaces, and client extension directories are honestly unavailable there because the v1 standard packages only skills and MCP servers. Both documents are validated against the vendored, hash-pinned 1.0.0 schemas and the normative text at plan time (`portable.mcp.*.standard`), after every ordinary build and `validate --artifact` (`AB6011`/`AB6012` plus the Agent Plugins byte lane `AB6035`–`AB6037`), under `validate --artifact --host-validation` (same lane with the `AB6038` provenance note), and by `agent-bundle doctor` for installed Cursor local plugins that declare the standard's `$schema` (`AB7320`); see [Diagnostics](docs/diagnostics.md#agent-plugins-portable-validation-ab6035ab6038). Pins live in `packages/agent-bundle/src/adapters/schemas/portable/PROVENANCE.json`; the capability table `packages/agent-bundle/src/adapters/capabilities/portable-1.0.0.json` carries a dated row for every standard feature.
+The `portable` target is the [Agent Plugins open standard](https://agent-plugins.org/specification) (specification 1.0.0) adapter — the default projection, and the layout Cursor loads natively (Claude Code consumes it only through CLI translation). Every other client that reads this artifact is recorded with its tier, install command, and dated evidence in the `clients` section of that same capability table, rendered as the [hosts reference](https://scriptedalchemy.github.io/agent-bundle/reference/hosts). It emits the closed root `plugin.json` (canonical `$schema`, `name`, `version`, `description`, plus `author`, `homepage`, `repository`, `license`, `keywords`, and reverse-domain `extensions` authored under the `portable` config key), `skills/<name>/SKILL.md`, and `mcp.json` with stdio and Streamable HTTP servers whose `args`, `env` values, and `cwd` use the standard's `${PLUGIN_ROOT}`/`${PLUGIN_DATA}` placeholders. Rules, commands, hooks, marketplaces, and client extension directories are honestly unavailable there because the v1 standard packages only skills and MCP servers. Both documents are validated against the vendored, hash-pinned 1.0.0 schemas and the normative text at plan time (`portable.mcp.*.standard`), after every ordinary build and `validate --artifact` (`AB6011`/`AB6012` plus the Agent Plugins byte lane `AB6035`–`AB6037`), under `validate --artifact --host-validation` (same lane with the `AB6038` provenance note), and by `agent-bundle doctor` for installed Cursor local plugins that declare the standard's `$schema` (`AB7320`); see [Diagnostics](docs/diagnostics.md#agent-plugins-portable-validation-ab6035ab6038). Pins live in `packages/agent-bundle/src/adapters/schemas/portable/PROVENANCE.json`; the capability table `packages/agent-bundle/src/adapters/capabilities/portable-1.0.0.json` carries a dated row for every standard feature.
 
 Claude Code language servers are declared under `claude.lspServers`; the `claude` projection emits the record as plugin-root `.lsp.json`. Agent Bundle expands path tokens only in `command`, `args`, `env`, and `workspaceFolder`, and it does not include the language-server binary — install that separately so the declared command is available on `PATH`. Codex, Cursor, and the portable format do not currently receive this host-scoped configuration.
 

docs/framework-mode.md

@@ -592,9 +592,11 @@ management but no non-interactive plugin install verb.
 The `portable` projection emits the [Agent Plugins open standard](https://agent-plugins.org)
 (specification 1.0.0), with schema hashes and the specification repository
 revision pinned in `src/adapters/schemas/portable/PROVENANCE.json`. Cursor loads
-this format natively alongside Cursor Plugins; Codex, VS Code, GitHub Copilot,
-Kiro, and ChatGPT are native clients too. Claude Code consumes the standard
-only through CLI translation, so its dedicated projection remains necessary. The
+this format natively alongside Cursor Plugins; every other client that reads
+the emitted package is recorded, with its tier and dated evidence, in the
+`clients` section of `src/adapters/capabilities/portable-1.0.0.json`. Claude
+Code consumes the standard only through CLI translation, so its dedicated
+projection remains necessary. The
 standard packages only skills and MCP servers, leaving rules, commands, and
 hooks honestly unavailable on the portable projection. The standard's manifest
 metadata (`author`, `homepage`, `repository`, `license`, `keywords`) and