From 5823d2ec7a82df6d5f3b136a69bf614b4f6f76f5 Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Wed, 9 Sep 2026 10:57:28 -0400 Subject: [PATCH] docs(#4484): correct native-plugin-install's install-time-config parity claim (#4579) * docs(#4484): correct native-plugin-install's install-time-config parity claim The doc claimed the plugin path and the npm installer "differ in namespace and lifecycle only." False: the native plugin path (claude plugin install, marketplace discovery, and the skills-dir zero-friction load) materializes the repository tree directly and never runs GSD's install engine, so install-time config baked into generated artifact files at install time never applies there -- confirmed for agent_tools (#4238/#4032, reproduced live in #4484: 35/35 files granted via npm install, 0/35 via plugin install, even after `claude plugin update`). model_overrides is the same architectural class (install-time-only logic on the npm-install call tree, per src/install-model-override-resolver.cts) but hedged, not claimed confirmed, matching the issue's own hedging. Reporter explicitly frames this as a docs-only fix: the code behavior (zero install step on the plugin path) is presumably intentional design; the bug is the doc's incorrect parity claim, not the missing functionality. No code changed. Co-Authored-By: Claude Sonnet 5 * docs(#4484): backfill changeset PR number Co-Authored-By: Claude Sonnet 5 --------- Co-authored-by: sim Co-authored-by: Claude Sonnet 5 --- .changeset/silly-voles-climb.md | 5 +++++ docs/how-to/install-on-your-runtime.md | 4 +++- 2 files changed, 8 insertions(+), 1 deletion(-) create mode 100644 .changeset/silly-voles-climb.md diff --git a/.changeset/silly-voles-climb.md b/.changeset/silly-voles-climb.md new file mode 100644 index 000000000..f261170fd --- /dev/null +++ b/.changeset/silly-voles-climb.md @@ -0,0 +1,5 @@ +--- +type: Fixed +pr: 4579 +--- +**Corrected the native-plugin-install docs' parity claim** — the doc previously said the plugin path and the npm installer differ only in namespace and lifecycle. They also differ in whether install-time config applies at all: the native plugin path never runs GSD's install engine, so config like `agent_tools` that the npm installer bakes into generated artifacts at install time silently never applies there, even after `claude plugin update`. (#4484) diff --git a/docs/how-to/install-on-your-runtime.md b/docs/how-to/install-on-your-runtime.md index 9dc286e3b..2b92ad7ca 100644 --- a/docs/how-to/install-on-your-runtime.md +++ b/docs/how-to/install-on-your-runtime.md @@ -64,7 +64,9 @@ The `FileChanged` hook is always-on and a no-op when `.planning/config.json` doe ### Claude Code — native plugin install -GSD Core ships a `.claude-plugin/plugin.json` manifest, which enables installation and lifecycle management through the Claude Code plugin system. This path is **additive** — the npm installer above remains fully supported, and the two approaches differ in namespace and lifecycle only. +GSD Core ships a `.claude-plugin/plugin.json` manifest, which enables installation and lifecycle management through the Claude Code plugin system. This path is **additive** — the npm installer above remains fully supported, and the two approaches differ in namespace and lifecycle. + +**Install-time config does not apply here.** The native plugin path (this section, the skills-dir load below, and marketplace discovery) materializes the repository tree directly — there is no install step. Install-time config that the npm installer bakes into generated artifact files at install time (confirmed for `agent_tools`; the same applies architecturally to `model_overrides` and other install-time-only keys) is never applied on this path, and running `claude plugin update` does not change that. If your setup relies on install-time config, use the npm installer above. **Install paths**