docs: classify README/examples (D4a) and close switcher viewport-coverage gap

README.md

@@ -8,6 +8,16 @@
 
 Install and manage Agent Plugins 1.0 across your AI agents with one CLI.
 
+| Journey | Start here |
+| --- | --- |
+| **Use plugins** | [Install below](#quick-start), then [manage installed plugins](#more-commands). |
+| **Build plugins — unreleased preview** | [Prepare a portable package](#build-plugins--unreleased-preview); release acceptance and public activation are pending. |
+
+## Use plugins
+
+Install, inspect, update, repair, and remove packages with the existing installer.
+The [Use guide source](website/source/en/use/index.md) collects this journey.
+
 ## Quick start
 
 Choose your operating system below. Already have Node.js 22+? You can use `npx`
@@ -105,9 +115,12 @@ The installed package is standard-first:
 plugin.json
 ├── skills/       optional reusable instructions
 ├── mcp.json      optional MCP servers
-└── hooks/        optional client-supported hooks
+└── hooks/        optional client-specific extension
 ```
 
+Skills and MCP are portable components. Hooks and other client-specific
+extensions depend on the target client; they do not imply portable behavior.
+
 You can also install a local package or a pinned GitHub package without adding
 it to the registry. Direct-install examples are collected near the end of this
 README.
@@ -206,24 +219,50 @@ path and package digest are stored for safe replay. Direct full-SHA installation
 remain immutable; use `switch` to move to another exact source. `repair` reapplies
 the recorded source, and `remove` changes only files owned by the CLI.
 
-## Authoring and development
-
-This repository also retains the original plugin-kit-ai authoring tools. Use
-the authoring guide at docs/PLUGIN_KIT_AI_AUTHORING.md when you want to build,
-validate, or export a package rather than install one.
-
-Build one plugin and ship it to many AI agents. The repository includes starter templates for Codex and Claude across Go, Python, and Node/TypeScript.
+## Build plugins — unreleased preview
+
+The [prepared Build guide source](website/source/en/build/index.md) describes
+root `plugin.json` with optional `skills/` and `mcp.json`, followed by the offline
+init → validate → inspect → static test loop and an installer planner handoff.
+`agentplugins author` and `plugin-kit-ai` are the two prepared entrypoints to
+one standard authoring engine. This is unreleased preview documentation, not
+an announcement that `plugin-kit-ai@2` is available on npm. Public deployment
+remains gated on release acceptance; the installer instructions above retain
+their existing behavior.
+
+Authoring validation and project doctor are distinct from installer
+`agentplugins validate` and `agentplugins doctor`. Static checks do not prove
+runtime execution, OAuth, or client activation. Runtime/dev/bootstrap,
+client generation, export/bundle, and publication are deferred from this MVP.
+There is no implicit YAML fallback or second supported YAML engine.
+
+### Historical authoring and development
+
+[Historical plugin-kit-ai v1, baseline 1.2.4](website/source/en/legacy/v1/index.md)
+provides version context. Project migration is not available in v2 yet.
+Maintain legacy projects using the v1 1.2.4 command set.
+The [preserved authoring guide](docs/PLUGIN_KIT_AI_AUTHORING.md) explains the
+historical YAML, generation, and export workflows; it is not the standard MVP.
+
+Build one plugin and ship it to many AI agents was the legacy authoring goal.
+The repository preserves Codex and Claude starters across Go, Python, and
+Node/TypeScript. See the classified [starters](examples/starters/README.md),
+[production examples](examples/plugins/README.md), [local examples](examples/local/README.md),
+and [Skills components](examples/skills/README.md).
 
 <details>
-<summary>Legacy authoring and SDK reference</summary>
+<summary>Historical v1 authoring and SDK reference — baseline 1.2.4</summary>
+
+All commands, stability labels, and supported-output claims in this section
+describe the preserved v1 workflow, not the unreleased standard authoring MVP.
 
 `plugin-kit-ai` keeps authored source under `plugin/`, generates the supported outputs you need, and helps you validate the repo before handoff. This includes supported outputs for Claude, Codex, Gemini, Cursor, and OpenCode where the repo shape allows it. The honest promise is `one repo / many supported outputs`, not fake parity everywhere.
 
-overview: [plugin-kit-ai documentation](https://777genius.github.io/plugin-kit-ai/docs/en/)
-fastest start: [Quickstart](https://777genius.github.io/plugin-kit-ai/docs/en/guide/quickstart.html)
-choose by job first: [Choose What You Are Building](https://777genius.github.io/plugin-kit-ai/docs/en/guide/choose-what-you-are-building.html)
-one repo, many outputs: [What You Can Build](https://777genius.github.io/plugin-kit-ai/docs/en/guide/what-you-can-build.html)
-honest caveat: [Support Boundary](https://777genius.github.io/plugin-kit-ai/docs/en/reference/support-boundary.html)
+overview: [plugin-kit-ai documentation](https://github.com/777genius/universal-agent-plugins/blob/9beca10448ac50fbe526a52101d1433a12471980/website/source/en/index.md)
+fastest start: [Quickstart](https://github.com/777genius/universal-agent-plugins/blob/9beca10448ac50fbe526a52101d1433a12471980/website/source/en/guide/quickstart.md)
+choose by job first: [Choose What You Are Building](https://github.com/777genius/universal-agent-plugins/blob/9beca10448ac50fbe526a52101d1433a12471980/website/source/en/guide/choose-what-you-are-building.md)
+one repo, many outputs: [What You Can Build](https://github.com/777genius/universal-agent-plugins/blob/9beca10448ac50fbe526a52101d1433a12471980/website/source/en/guide/what-you-can-build.md)
+honest caveat: [Support Boundary](https://github.com/777genius/universal-agent-plugins/blob/9beca10448ac50fbe526a52101d1433a12471980/website/source/en/reference/support-boundary.md)
 
 ## Choose What You Are Building
 
@@ -233,12 +272,16 @@ honest caveat: [Support Boundary](https://777genius.github.io/plugin-kit-ai/docs
 
 ### Build custom plugin logic
 
-## Quick Start
+## Historical Quick Start
+
+Use an exact v1 1.2.4 executable for these commands. The Homebrew and fallback
+channels below are retained as historical references, not version-pinned setup.
 
 ```bash
+# Historical Homebrew channel (not version-pinned):
 brew install 777genius/homebrew-plugin-kit-ai/plugin-kit-ai
-npm: `npm i -g plugin-kit-ai` or `npx plugin-kit-ai@latest ...`
-pipx (`public-beta`, only when that release is published to PyPI): `pipx install plugin-kit-ai`
+npm: `npm i -g plugin-kit-ai@1.2.4` or `npx plugin-kit-ai@1.2.4 ...`
+pipx (`public-beta`, only when that release is published to PyPI): `pipx install plugin-kit-ai==1.2.4`
 fallback installer: `curl -fsSL https://raw.githubusercontent.com/777genius/plugin-kit-ai/main/scripts/install.sh | sh`
 plugin-kit-ai init my-plugin --template online-service
 plugin-kit-ai init my-plugin --template local-tool

examples/local/README.md

@@ -1,5 +1,18 @@
 # Repo-Local Plugin Examples
 
+> **Historical plugin-kit-ai v1 managed examples; baseline 1.2.4.**
+> Commands, stability labels, and support claims below describe the preserved v1
+> workflow. These are not root `plugin.json` starters for the standard MVP.
+> Project migration is not available in v2 yet. Maintain legacy projects using
+> the v1 1.2.4 command set. See [historical context](../../website/source/en/legacy/v1/index.md)
+> and the [prepared, unreleased Build guide](../../website/source/en/build/index.md).
+> Public activation remains gated; no v2 npm availability is implied.
+
+All three examples have `plugin/plugin.yaml` targeting `codex-runtime`.
+Their Python, Node, and TypeScript helpers demonstrate historical launcher
+behavior, not the future offline MCP/Skill authoring loop. Preserve those
+helpers and dependencies when consulting these examples.
+
 These examples are reference implementations for the fast local plugin entrance layer.
 For copy-first starter repos, see [../starters/README.md](../starters/README.md).
 

examples/plugins/README.md

@@ -1,6 +1,31 @@
 # Production Plugin Examples
 
-These examples are reference implementations for the current production plugin workflow.
+> **Historical plugin-kit-ai v1 managed examples; baseline 1.2.4.**
+> Commands, stability labels, and support claims below describe the preserved v1
+> workflow. These are not root `plugin.json` starters for the standard MVP.
+> Project migration is not available in v2 yet. Maintain legacy projects using
+> the v1 1.2.4 command set. See [historical context](../../website/source/en/legacy/v1/index.md)
+> and the [prepared, unreleased Build guide](../../website/source/en/build/index.md).
+> Public activation remains gated; no v2 npm availability is implied.
+
+All six checked-in examples are v1 managed projects with `plugin/plugin.yaml`.
+Their generated native outputs remain useful client-specific references:
+
+| Examples | Native output / scope |
+| --- | --- |
+| `claude-basic-prod` | `.claude-plugin/plugin.json`, MCP configuration and hooks |
+| `codex-basic-prod` | `.codex/config.toml`, launcher/notify runtime |
+| `codex-package-prod` | `.codex-plugin/plugin.json`, Skills, MCP and app metadata |
+| `cursor-basic` | `.cursor-plugin/plugin.json`, Skills and MCP |
+| `gemini-extension-package` | `gemini-extension.json`, extension commands/settings/hooks |
+| `opencode-basic` | `opencode.json`, workspace configuration and mirrored Skills |
+
+Native packages/configuration are not root Agent Plugins 1.0 manifests.
+Skills and MCP components may be reusable; hooks, app bindings, themes, and
+client settings retain their client-specific boundaries. The external Context7
+link below is a historical reference, not a locally verified standard package.
+
+These examples are reference implementations for the historical v1 production plugin workflow.
 
 - [`context7` in universal-plugins-for-ai-agents](https://github.com/777genius/universal-plugins-for-ai-agents/tree/main/plugins/context7): canonical multi-target MCP-first example with `plugin/` as the only authored root, package-only Claude, official Codex package output, Gemini extension packaging, and workspace-config output for OpenCode and Cursor
 - [claude-basic-prod](./claude-basic-prod): Claude plugin repo with `plugin/plugin.yaml`, generated native artifacts, and deterministic local smoke path
@@ -14,6 +39,6 @@ Use them together with [../../docs/PRODUCTION.md](../../docs/PRODUCTION.md).
 For copy-first Go/Python/Node starter repos, see [../starters/README.md](../starters/README.md).
 For deeper repo-local Python/Node entrance references, including the checked-in helper-layer examples, see [../local/README.md](../local/README.md).
 
-These reference repos document the current stable production path where Go is the recommended default because it yields the most self-contained plugin delivery story.
+These reference repos document the historical v1 stable production path where Go is the recommended default because it yields the most self-contained plugin delivery story.
 Canonical authoring uses `plugin/plugin.yaml`, `plugin/mcp/servers.yaml`, and `plugin/targets/<platform>/...`; committed native Claude/Codex/Gemini/Cursor/OpenCode files in the plugin root are generated managed artifacts.
 Gemini, Cursor, and OpenCode remain packaging/config-only in this reference set. Gemini's Go hook lane is documented through the generated scaffold README, `plugin-kit-ai inspect`, `plugin-kit-ai capabilities --mode runtime --platform gemini`, the deterministic `make test-gemini-runtime` runtime gate, and the dedicated `make test-gemini-runtime-live` smoke path rather than a checked-in production example repo. Executable `python` and `node` plugins are stable supported repo-local local-runtime lanes and are covered through scaffold/runtime docs plus polyglot smoke tests rather than checked-in production example repos. Those interpreted lanes still require Python or Node to be installed on the machine running the plugin. Launcher-based `shell` authoring remains `public-beta`.

examples/skills/README.md

@@ -1,6 +1,26 @@
 # Skill Examples
 
-These examples are intentionally small, but each one demonstrates a real beta-adoption path for `plugin-kit-ai skills`.
+These are **portable Skills components with historical v1 tooling metadata**,
+not complete root `plugin.json` packages or proof of current standard validation.
+See the [prepared, unreleased Skill guide](../../website/source/en/build/skill.md)
+for package context and [historical v1, baseline 1.2.4](../../website/source/en/legacy/v1/index.md)
+for the preserved generation workflow. Public activation remains gated.
+
+| Component | Source and execution boundary |
+| --- | --- |
+| [go-command-lint](./go-command-lint) | `skills/lint-repo/SKILL.md` invokes Go code that checks required example files exist; it is not a general linter. |
+| [cli-wrapper-formatter](./cli-wrapper-formatter) | `skills/format-changed/SKILL.md` invokes pinned Prettier through npx, may download it, and writes files. |
+| [docs-only-review](./docs-only-review) | `skills/review-checklist/SKILL.md` is instruction-only. |
+
+The instructions are reusable Skills material. Fields such as `execution_mode`,
+`supported_agents`, and `command` describe historical tooling conventions, not
+universal client execution guarantees. The committed Claude/Codex projections
+under `generated/skills/` remain historical examples; v1 Skills generation and
+external Skills lifecycle commands are not part of the standard authoring MVP.
+Project migration is not available in v2 yet. Maintain legacy projects using
+the v1 1.2.4 command set. No examples or generated outputs are removed here.
+
+These examples are intentionally small, but each one demonstrates a historical v1 beta-adoption path for `plugin-kit-ai skills`.
 
 - `go-command-lint`
   - canonical `SKILL.md` plus a Go command entrypoint

examples/starters/README.md

@@ -1,17 +1,31 @@
 # Canonical Starter Repos
 
+> **Historical plugin-kit-ai v1 managed examples; baseline 1.2.4.**
+> Commands, stability labels, and support claims below describe the preserved v1
+> workflow. These are not root `plugin.json` starters for the standard MVP.
+> Project migration is not available in v2 yet. Maintain legacy projects using
+> the v1 1.2.4 command set. See [historical context](../../website/source/en/legacy/v1/index.md)
+> and the [prepared, unreleased Build guide](../../website/source/en/build/index.md).
+> Public activation remains gated; no v2 npm availability is implied.
+
+All eight starters have `plugin/plugin.yaml`: the four Codex starters target
+`codex-runtime`, and the four Claude starters target Claude. Shared-package
+variants preserve their runtime dependencies. Claude Skills and hooks do not
+turn these managed projects into standard packages; hooks are client-specific.
+
 These starter repos are the fastest way to get one working plugin repo that can later expand to more supported outputs.
 
 Use them when you want to pick a stack, copy a template, get to the first green run quickly, and keep the repo open for later expansion.
 For deeper contract examples, see [../local/README.md](../local/README.md) and [../plugins/README.md](../plugins/README.md).
 
 ## Install `plugin-kit-ai`
 
-Use the supported CLI install order:
+The historical channel order is preserved below. Use an exact v1 1.2.4
+executable; Homebrew, fallback, and the action tag are not exact version pins:
 
 1. Homebrew: `brew install 777genius/homebrew-plugin-kit-ai/plugin-kit-ai`
-2. npm: `npm i -g plugin-kit-ai` or `npx plugin-kit-ai@latest ...`
-3. pipx (when that release was published to PyPI): `pipx install plugin-kit-ai` or `pipx run plugin-kit-ai version`
+2. npm: `npm i -g plugin-kit-ai@1.2.4` or `npx plugin-kit-ai@1.2.4 ...`
+3. pipx (when that release was published to PyPI): `pipx install plugin-kit-ai==1.2.4` or `pipx run --spec plugin-kit-ai==1.2.4 plugin-kit-ai version`
 4. Verified fallback: `curl -fsSL https://raw.githubusercontent.com/777genius/plugin-kit-ai/main/scripts/install.sh | sh`
 5. CI: `777genius/universal-agent-plugins/setup-plugin-kit-ai@v1`
 
@@ -121,4 +135,4 @@ Supported alternatives still exist, but they are not encoded into the starter re
 
 - Shared-package variants are for teams that already know they want `plugin-kit-ai-runtime` as a reusable dependency instead of vendored helper files.
 - Starter choice is about the first correct path, not the final limit of the product.
-- If the repo later needs a wider scope, see [One Project, Multiple Targets](https://777genius.github.io/plugin-kit-ai/docs/en/guide/one-project-multiple-targets.html).
+- If the repo later needs a wider scope, see [One Project, Multiple Targets](https://github.com/777genius/universal-agent-plugins/blob/9beca10448ac50fbe526a52101d1433a12471980/website/source/en/guide/one-project-multiple-targets.md).