docs: extend plugin doctrine — component stances, native-first, official-docs index

CLAUDE.md

@@ -27,6 +27,7 @@ from a fetched page this session, treat it as unverified and say so.
 | MCP | https://code.claude.com/docs/en/mcp |
 | Tools reference (monitors) | https://code.claude.com/docs/en/tools-reference |
 | Docs index (discover any other page) | https://code.claude.com/docs/llms.txt |
+| Official-doc index (all plugin-relevant pages) | docs/OFFICIAL-DOCS.md |
 
 Machine-readable JSON Schemas (editor validation for the JSON in this repo; Claude Code ignores the
 `$schema` field at load time): `marketplace.json` →

docs/MIGRATION-PLAYBOOK.md

@@ -257,15 +257,17 @@ The **adopted** rule for how a plugin settles a value at runtime, applied to eve
 No baked repo assumptions, ever. A plugin never hardcodes a consumer's layout; it reads a declared
 value, infers-and-records, or asks — never guesses silently.
 
-## Setup action — every configurable plugin ships one
-
-Every plugin that carries any `userConfig` or tracked-config seam ships a re-runnable `setup` /
-`configure` action (a skill) that interviews the consumer and writes the tracked config. It is
-idempotent — safe to re-run to reconfigure. The Thariq `config.json` first-run pattern is **rejected**
-for plugins: it is not an official mechanism, and it writes into `${CLAUDE_PLUGIN_ROOT}`, which is
-replaced on every update (the plugins-reference caching note), so its state does not survive. Setup
-writes only the consumer configuration the plugin owns. Claude Code's native configuration surface
-collects `userConfig` and owns `pluginConfigs`; a setup skill never edits that key directly.
+## Setup action — required iff the criteria hold
+
+Whether a plugin needs a `setup` skill, and the uniform contract it follows (`setup` name,
+`disable-model-invocation: true`, `check` + `apply` actions, non-interactive completion), is owned
+by [PLUGIN-PHILOSOPHY.md § Setup is explicit and repeatable](PLUGIN-PHILOSOPHY.md). Migration work
+applies it as-is. Playbook-specific additions: the Thariq `config.json` first-run pattern is
+**rejected** for plugins — it is not an official mechanism, and it writes into
+`${CLAUDE_PLUGIN_ROOT}`, which is replaced on every update (the plugins-reference caching note), so
+its state does not survive. Setup writes only the consumer configuration the plugin owns; Claude
+Code's native configuration surface collects `userConfig` and owns `pluginConfigs` — a setup skill
+never edits that key directly.
 
 ## Upstream sync — every upstream-sourced plugin ships an update path
 
@@ -565,15 +567,22 @@ For each skill/hook/agent being migrated:
 3. **De-couple from the source repo.** Remove hardcoded paths/names; route project-specifics to the
    consumer's context.
 4. **Bundle + isolate.** Move required assets inside the plugin; reference via `${CLAUDE_PLUGIN_ROOT}`.
-5. **Expose extensibility.** Declare `userConfig` for consumer choices; document each option.
+5. **Expose extensibility.** Declare `userConfig` for consumer choices; document each option. Apply
+   the userConfig full-potential criterion and the exec-form hook rule from
+   [PLUGIN-PHILOSOPHY.md § Configuration ownership and scope](PLUGIN-PHILOSOPHY.md): no custom
+   config channel where the native schema fits, and no `${user_config.*}` in shell-form hooks.
 6. **Strip PII / secrets.** Hard gate — before the first commit.
-7. **Idempotent, modular, extensible.** Re-running is safe; pieces compose; variability is declared.
-8. **Validate.** `claude plugin validate`; test with `--plugin-dir` in a clean repo that is NOT the
+7. **Check component stances.** Every component the plugin ships conforms to the component stance
+   table in [PLUGIN-PHILOSOPHY.md](PLUGIN-PHILOSOPHY.md) — no `commands/`, no unjustified
+   `settings.json` `agent`, wait-listed components absent; setup criteria applied per its setup
+   section; runtime prerequisites degrade per its failure-behavior rules.
+8. **Idempotent, modular, extensible.** Re-running is safe; pieces compose; variability is declared.
+9. **Validate.** `claude plugin validate`; test with `--plugin-dir` in a clean repo that is NOT the
    source repo (proves repo-agnosticism).
-9. **Version.** Set an explicit semver `version` in `plugin.json`. A later bump that changes behavior a
+10. **Version.** Set an explicit semver `version` in `plugin.json`. A later bump that changes behavior a
    consumer depends on records the change in the plugin's changelog — see "Version pinning and update
    delivery" above.
-10. **Publish.** Add the entry to `.claude-plugin/marketplace.json` — the plugin `source` is the
+11. **Publish.** Add the entry to `.claude-plugin/marketplace.json` — the plugin `source` is the
     `./`-prefixed relative path (e.g. `./plugins/<name>`). Bare names fail `claude plugin validate --strict`
     even with `metadata.pluginRoot` set, despite the marketplaces-doc example to the contrary (verified
     2026-06-23). Then run `claude plugin validate --strict <repo-root>` to validate the **catalog manifest
@@ -609,7 +618,8 @@ license-gated units to per-item triage rather than a blanket hold. The ordering
 A plugin runs code on the consumer's machine and can wire Claude to external systems. **Every plugin accepted
 here — new, or a version bump that adds a trust surface — passes this review** in addition to the migration
 gate above (whose step 6 gates PII/secrets). **Deny by default** any surface below that can't be justified.
-Facts verified against the plugins/MCP reference 2026-07-09; re-verify per the `CLAUDE.md` fresh-docs mandate.
+Facts verified against the plugins/MCP reference 2026-07-09 and re-verified against the plugins,
+plugins-reference, and hooks pages 2026-07-17; re-verify per the `CLAUDE.md` fresh-docs mandate.
 
 1. **Code execution — hooks & scripts.** A hook command runs on the consumer's machine on matched events,
    with `${CLAUDE_PLUGIN_ROOT}`, `${CLAUDE_PROJECT_DIR}`, `${CLAUDE_PLUGIN_DATA}`, and any `${ENV_VAR}`
@@ -646,9 +656,15 @@ Facts verified against the plugins/MCP reference 2026-07-09; re-verify per the `
    third-party SaaS is a trust delegation — record accept/deny with rationale. Note the platform already blocks
    plugin-shipped **agents** from declaring `hooks` / `mcpServers` / `permissionMode` "for security reasons" —
    don't design around that.
-
-Record accept/deny + rationale for any plugin touching surfaces 2, 5, or 6; a later version bump that
-introduces a new surface re-triggers this review.
+7. **Main-thread and PATH surfaces.** A plugin `settings.json` `agent` entry takes over the
+   consumer's main thread — prohibited by default per the component stance table in
+   [PLUGIN-PHILOSOPHY.md](PLUGIN-PHILOSOPHY.md); an exception requires the documented justification
+   the stance demands, reviewed here. `bin/` executables join the Bash tool's `PATH` while the
+   plugin is enabled: names must be collision-safe (plugin-prefixed), and each binary's provenance
+   is reviewed like any hook script.
+
+Record accept/deny + rationale for any plugin touching surfaces 2, 5, 6, or 7; a later version bump
+that introduces a new surface re-triggers this review.
 
 ## Local development loop
 

docs/OFFICIAL-DOCS.md

@@ -0,0 +1,107 @@
+# Official docs index
+
+This is a link index into Claude Code's official documentation, scoped to pages relevant to
+authoring, distributing, or consuming plugins in this marketplace. It exists so an agent or
+contributor can jump straight to the current canonical page instead of guessing a URL or trusting
+training-data recall.
+
+> [!WARNING]
+> **This file goes stale. The platform changes constantly.** Always re-fetch the linked page before
+> acting on it — never trust this file's descriptions, and never trust remembered content from a
+> prior fetch. The authoritative, self-updating master list is
+> [`https://code.claude.com/docs/llms.txt`](https://code.claude.com/docs/llms.txt); if a page listed
+> here is missing from it, or a page you need isn't listed here, treat `llms.txt` as the source of
+> truth and update this file. Every row below was verified against a live fetch on the date shown —
+> that date is the ceiling on how current the row still is, not a guarantee.
+
+## Plugin components → doc page
+
+One row per plugin component type, per the current [Plugins reference](https://code.claude.com/docs/en/plugins-reference).
+`Commands` is the legacy flat-markdown form of a skill — the [Skills](https://code.claude.com/docs/en/skills)
+page is authoritative for both. Statusline is not its own plugin component: it is one of the two
+settings keys (`subagentStatusLine`) a plugin's `settings.json` may set. Channels are declared via a
+`channels` manifest field bound to an MCP server, not a separate file location.
+
+| Component | Official doc page | Verified date |
+|---|---|---|
+| Skills (`skills/`) | <https://code.claude.com/docs/en/skills> | 2026-07-17 |
+| Commands — legacy flat-file skills (`commands/`) | <https://code.claude.com/docs/en/commands> | 2026-07-17 |
+| Agents / subagents (`agents/`) | <https://code.claude.com/docs/en/sub-agents> | 2026-07-17 |
+| Hooks (`hooks/hooks.json`) | <https://code.claude.com/docs/en/hooks> | 2026-07-17 |
+| MCP servers (`.mcp.json`) | <https://code.claude.com/docs/en/mcp> | 2026-07-17 |
+| LSP servers (`.lsp.json`) | <https://code.claude.com/docs/en/plugins-reference#lsp-servers> | 2026-07-17 |
+| Output styles (`output-styles/`) | <https://code.claude.com/docs/en/output-styles> | 2026-07-17 |
+| Themes (`themes/`) | <https://code.claude.com/docs/en/plugins-reference#themes> | 2026-07-17 |
+| Monitors (`monitors/monitors.json`) | <https://code.claude.com/docs/en/plugins-reference#monitors> | 2026-07-17 |
+| Channels (`channels` manifest field) | <https://code.claude.com/docs/en/channels> | 2026-07-17 |
+| Executables (`bin/`) | <https://code.claude.com/docs/en/plugins-reference#file-locations-reference> | 2026-07-17 |
+| Settings (`settings.json` defaults) | <https://code.claude.com/docs/en/settings> | 2026-07-17 |
+| Dependencies (`dependencies` manifest field) | <https://code.claude.com/docs/en/plugin-dependencies> | 2026-07-17 |
+
+## Authoring
+
+| Page | Official doc page | Verified date |
+|---|---|---|
+| Create plugins | <https://code.claude.com/docs/en/plugins> | 2026-07-17 |
+| Plugins reference (schemas, variables, CLI) | <https://code.claude.com/docs/en/plugins-reference> | 2026-07-17 |
+| Skills | <https://code.claude.com/docs/en/skills> | 2026-07-17 |
+| Slash commands | <https://code.claude.com/docs/en/commands> | 2026-07-17 |
+| Hooks reference | <https://code.claude.com/docs/en/hooks> | 2026-07-17 |
+| Automate actions with hooks (guide) | <https://code.claude.com/docs/en/hooks-guide> | 2026-07-17 |
+| Subagents | <https://code.claude.com/docs/en/sub-agents> | 2026-07-17 |
+| MCP | <https://code.claude.com/docs/en/mcp> | 2026-07-17 |
+| Connect to MCP servers (quickstart) | <https://code.claude.com/docs/en/mcp-quickstart> | 2026-07-17 |
+| Output styles | <https://code.claude.com/docs/en/output-styles> | 2026-07-17 |
+| Statusline | <https://code.claude.com/docs/en/statusline> | 2026-07-17 |
+| Push events into a session with channels | <https://code.claude.com/docs/en/channels> | 2026-07-17 |
+| Channels reference | <https://code.claude.com/docs/en/channels-reference> | 2026-07-17 |
+| Sandboxing the Bash tool | <https://code.claude.com/docs/en/sandboxing> | 2026-07-17 |
+| Sandbox environments | <https://code.claude.com/docs/en/sandbox-environments> | 2026-07-17 |
+| Run parallel sessions with worktrees | <https://code.claude.com/docs/en/worktrees> | 2026-07-17 |
+| Tools reference (includes the Monitor tool) | <https://code.claude.com/docs/en/tools-reference> | 2026-07-17 |
+
+## Distribution / marketplace
+
+| Page | Official doc page | Verified date |
+|---|---|---|
+| Create & distribute a marketplace | <https://code.claude.com/docs/en/plugin-marketplaces> | 2026-07-17 |
+| Discover & install plugins | <https://code.claude.com/docs/en/discover-plugins> | 2026-07-17 |
+| Plugin dependencies (version constraints) | <https://code.claude.com/docs/en/plugin-dependencies> | 2026-07-17 |
+| Recommend plugins for your org (plugin relevance) | <https://code.claude.com/docs/en/plugin-relevance> | 2026-07-17 |
+| Recommend your plugin from your CLI (plugin hints) | <https://code.claude.com/docs/en/plugin-hints> | 2026-07-17 |
+| Plugins in the Agent SDK | <https://code.claude.com/docs/en/agent-sdk/plugins> | 2026-07-17 |
+
+The Agent SDK's own skills/hooks/subagents/MCP pages (`agent-sdk/skills`, `agent-sdk/hooks`,
+`agent-sdk/subagents`, `agent-sdk/mcp`) describe those concepts for custom SDK-built agent hosts, not
+for authoring or distributing a Claude Code CLI plugin — deliberately out of scope here. Only
+`agent-sdk/plugins` is in scope, because it covers how this repo's plugins behave when loaded by an
+SDK-based host.
+
+## Configuration / settings
+
+| Page | Official doc page | Verified date |
+|---|---|---|
+| Settings | <https://code.claude.com/docs/en/settings> | 2026-07-17 |
+| Server-managed settings | <https://code.claude.com/docs/en/server-managed-settings> | 2026-07-17 |
+| Control MCP server access for your organization | <https://code.claude.com/docs/en/managed-mcp> | 2026-07-17 |
+| Memory — CLAUDE.md, `.claude/rules/`, auto memory | <https://code.claude.com/docs/en/memory> | 2026-07-17 |
+| The `.claude` directory | <https://code.claude.com/docs/en/claude-directory> | 2026-07-17 |
+| Permissions | <https://code.claude.com/docs/en/permissions> | 2026-07-17 |
+| Permission modes | <https://code.claude.com/docs/en/permission-modes> | 2026-07-17 |
+| Environment variables | <https://code.claude.com/docs/en/env-vars> | 2026-07-17 |
+
+## Reference / schemas
+
+| Page | Official doc page | Verified date |
+|---|---|---|
+| Docs index (discover any other page) | <https://code.claude.com/docs/llms.txt> | 2026-07-17 |
+| CLI reference | <https://code.claude.com/docs/en/cli-reference> | 2026-07-17 |
+| Error reference | <https://code.claude.com/docs/en/errors> | 2026-07-17 |
+| Glossary | <https://code.claude.com/docs/en/glossary> | 2026-07-17 |
+
+Machine-readable JSON Schemas (editor validation only; Claude Code ignores the `$schema` field at
+load time — already cited in this repo's `CLAUDE.md`): `marketplace.json` →
+[`https://json.schemastore.org/claude-code-marketplace.json`](https://json.schemastore.org/claude-code-marketplace.json),
+`plugin.json` →
+[`https://json.schemastore.org/claude-code-plugin-manifest.json`](https://json.schemastore.org/claude-code-plugin-manifest.json)
+(published on SchemaStore, sourced from the same plugin system these pages document).