@bradheitmann/odin-sentinel 0.4.5 → 0.4.7

package/docs/guides/quickstart-prompts.md

@@ -1,132 +1,65 @@
 # ODIN Sentinel Quickstart Prompts
 
-Two prompts that take a fresh machine from *"agents installed"* to *"team running under the Sentinel Coordination Protocol."* Paste each one into a capable coding agent (Claude Code or Codex) at the indicated moment. The agents do the rest.
+These prompts are starter material for a fresh machine and a fresh CMUX session.
+Adjust harnesses and models to what you actually have installed.
 
-The prompts are opinionated. They assume you want a working team in the smallest number of steps, not a customized one. Swap rosters or hosts at the end if you have different agents available.
+## Prompt 1 - Setup
 
----
+Paste into a capable coding agent on the target machine.
 
-## Prompt 1 — Setup
+```text
+Set up @bradheitmann/odin-sentinel for this machine.
 
-**When to use:** once per machine. Paste into Claude Code or Codex on the target machine. The agent will detect what's missing, install only what's needed (Homebrew, git, Node.js, pnpm, CMUX, and the `@bradheitmann/odin-sentinel` MCP server), and wire the server into every agent host you actually have installed.
+Rules:
+- Detect first; install only missing prerequisites.
+- Required runtime: Node.js >=22.13.0.
+- Install or use @bradheitmann/odin-sentinel@latest.
+- Configure only MCP hosts that already exist on this machine.
+- Do not ask me to paste API keys, tokens, or OAuth values.
+- Verify provider/auth status without printing secret values.
+- If local inference is used, smoke-test actual visible content within timeout, not endpoint reachability alone.
+- Install or prepare SCP native skill context where supported; otherwise prepare the full prompt fallback from odin.get_bootstrap_skill.
+- Print configured hosts, skipped hosts, package version, and warnings.
 
-```
-Set up the @bradheitmann/odin-sentinel MCP server on this machine. Detect what's missing, install only what's needed, configure only the agent hosts that exist on this machine.
-
-# Plan
-Make a 5-task plan and execute in order:
-  1. Prereqs (Homebrew, git, node, pnpm, cmux — install only if missing)
-  2. Install MCP server with explicit @latest tag
-  3. Smoke test the server
-  4. Detect installed agent hosts and wire each one
-  5. Print final report
-
-# Rules
-- Detect first, install only if missing: `command -v <tool>` for CLIs; `test -e <path>` for config dirs.
-- After installing pnpm fresh, run `pnpm setup && source ~/.zshrc` once.
-- Ignore pnpm warnings of the form "Failed to create bin … @pnpm/exe" — benign Homebrew vs pnpm self-install conflict.
-- Always install with `pnpm add -g @bradheitmann/odin-sentinel@latest` — the bare name can return a stale version from registry cache.
-- The MCP server has no `--version` flag. To verify, send a JSON-RPC initialize on stdin and parse the response.
-- For every JSON / TOML / YAML config file: read, merge the odin-sentinel entry, write back. Never overwrite a whole file. Preserve comments in JSONC. Create the file if missing.
-- Do not install agent CLIs the user doesn't have.
-- Do not enable telemetry, deploy Cloudflare resources, or edit anything outside the host config files listed below plus one optional line in ~/.zshrc.
-
-# Smoke test (use this exact form)
+Smoke test:
 printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}\n' | odin-sentinel-mcp
 
-Expect `"serverInfo":{"name":"odin-sentinel","version":"<X.Y.Z>"}`. If absent, stop and report.
-
-# Hosts to detect and configure
-For each: detect → if installed, merge the entry into the listed config file (idempotent). Every entry uses `command = "odin-sentinel-mcp"` with no args.
-
-  - Claude Code:   `command -v claude`        → `claude mcp add odin-sentinel -- odin-sentinel-mcp`
-  - Codex:         `command -v codex`         → `~/.codex/config.toml` [mcp_servers.odin-sentinel] command = "odin-sentinel-mcp"
-  - Cursor:        `command -v cursor-agent`  → `~/.cursor/mcp.json` mcpServers.odin-sentinel = { command: "odin-sentinel-mcp" }
-  - Factory Droid: `command -v droid`         → `~/.factory/mcp.json` mcpServers.odin-sentinel = { type: "stdio", command: "odin-sentinel-mcp", disabled: false }
-  - Kilo Code:     `command -v kilocode`      → `~/.kilocode/mcp.json` (same shape as Cursor)
-  - Pi:            `command -v pi`            → `~/.pi/mcp.json` (same shape as Cursor)
-  - OpenCode:      `command -v opencode`      → `~/.config/opencode/opencode.json` mcp.odin-sentinel = { type: "local", command: ["odin-sentinel-mcp"], enabled: true }
-  - Crush:         `command -v crush`         → `~/.config/crush/crush.json` mcp.odin-sentinel = { type: "stdio", command: "odin-sentinel-mcp" }
-  - Goose:         `command -v goose`         → `~/.config/goose/config.yaml` extensions.odin-sentinel = { type: stdio, cmd: odin-sentinel-mcp, enabled: true }
-  - OpenHands:     `command -v openhands`     → `~/.openhands/config.toml` [mcp.stdio_servers.odin-sentinel] name = "odin-sentinel", command = "odin-sentinel-mcp"
-  - Zed:           `test -e ~/.config/zed`    → `~/.config/zed/settings.json` context_servers.odin-sentinel = { source: "custom", command: "odin-sentinel-mcp", enabled: true }
-  - VS Code:       `command -v code`          → `~/Library/Application Support/Code/User/mcp.json` servers.odin-sentinel = { type: "stdio", command: "odin-sentinel-mcp" }
-
-# Final report
-Print:
-  - installed odin-sentinel version
-  - which hosts were configured
-  - which hosts were skipped (one line each, with reason "not installed")
-  - any non-fatal warnings
-
-Then print these three lines and stop:
-
-  Setup complete.
-  Restart any agent host you configured (their MCP config is cached at startup).
-  To boot a team: open CMUX, launch your Executive PM agent in the first surface, paste your team-roster prompt.
+Expected version: 0.4.7.
 ```
 
-After it finishes, **restart any agent host it touched** — each one caches MCP server configs at startup. Skipping the restart is the most common reason "the MCP server isn't showing up" after a clean install.
-
----
-
-## Prompt 2 — Team Bootstrap
+Restart any host whose MCP config changed.
 
-**When to use:** every time you spin up a new project. Open CMUX, launch Codex in the first surface, paste this. Codex acts as `A/EXEC-PM`, reads the Sentinel Coordination Protocol from the bundled skill, and stages a two-team layout (executive office + one development pod). The roster below is opinionated — substitute models or hosts you actually have.
+## Prompt 2 - Governed Team Bootstrap
 
-```
-You are A/EXEC-PM. Bootstrap a 2-team Sentinel Coordination Protocol session in this CMUX workspace.
-
-# Procedure
-1. Call odin.get_version. Confirm >= 0.4.4.
-2. Call odin.get_bootstrap_skill. Read the full SCP contract. Follow it for the remainder of this session — particularly: you are the sole staffing authority, sole CMUX surface custodian, and you must complete the pre-staffing gate before every spawn.
-3. Call odin.compute_surface_layout with teamCount=2. Confirm the canonical layout is [A] [B].
-4. Call odin.compute_surface_layout_gate with fromTeamCount=1, toTeamCount=2. Execute the cmux operations it lists.
-5. Stage the team per the roster below. For each surface: create it via cmux, confirm it exists and is empty, send the agent launch command, then send the occupant boot prompt requesting an SCP_BOOT_RECEIPT.
-
-# Roster (substitute hosts/models if you have different agents available)
-
-Team A — Executive Office (column 0, 5 surfaces stacked as tabs):
-  | Slot          | Agent host    | Model           |
-  |---------------|---------------|-----------------|
-  | A/EXEC-PM     | Codex         | (you)           |
-  | A/EXEC-ODIN   | Codex         | high-reasoning  |
-  | A/EXEC-ASST   | Kilo Code     | Composer-2      |
-  | A/EXEC-RSCH   | Cursor        | Kimi-K-2.5      |
-  | A/EXEC-QA     | OpenCode      | Kimi-K-2.5      |
-
-Team B — Development Pod (column 1, 5 surfaces stacked as tabs):
-  | Slot          | Agent host    | Model           |
-  |---------------|---------------|-----------------|
-  | B/TEAM-PM     | Claude Code   | Opus-4.7        |
-  | B/ODIN        | Codex         | high-reasoning  |
-  | B/DEV-1       | Droid (Factory) | Kimi-K-2.6    |
-  | B/QA-1        | Crush         | GLM-5.1         |
-  | B/SHADOW-1    | Claude Code   | Haiku           |
-
-# Constraints
-- You are the only role permitted to invoke cmux surface operations (new-split, new-surface, move-surface, close-surface).
-- No hidden subagents. Every agent must occupy a visible CMUX surface.
-- TEAM PMs do not staff their own pods. All staffing is yours.
-- A/EXEC-ODIN holds binding HALT authority over you. Honor HALT directives.
-- Context window soft threshold 70% / hard 90% per agent. Force handoff or lockdown on hard breach.
-
-# Closeout signal
-After all 10 surfaces are spawned, all 10 boot receipts received, and odin.validate_team_manifest passes, emit a single line:
-
-  STAGED_AND_IDLE: 2 teams, 10 occupants, layout=[A] [B]
-
-Then wait for the user's first product directive. Do not begin work until dispatched.
-```
+Open CMUX first. Paste into the agent that will act as EXEC PM.
 
-When `STAGED_AND_IDLE` appears, the team is ready for your first directive.
+```text
+You are A/EXEC-PM. Bootstrap a Sentinel Coordination Protocol governed team in this CMUX workspace.
 
----
+Procedure:
+1. Call odin.get_version and confirm version 0.4.7 or newer.
+2. Call odin.get_bootstrap_skill and read the public SCP contract.
+3. Confirm CMUX is active and you are in the same workspace as the team slots.
+4. Compute the target layout with odin.compute_surface_layout using profile=human_cmux_quad.
+5. Use human-readable spatial/pod organization. Do not use tab-only layout as the canonical surface.
+6. Check each planned role for MCP readiness, skill or prompt fallback readiness, auth/account readiness, and local inference readiness if used.
+7. Do not launch occupants until readiness passes or you record a waiver/substitution.
+8. Ask each launched role for a boot receipt.
+9. Validate the team manifest before dispatching work.
 
-## Scaling beyond 2 teams
+Role policy:
+- PM owns routing, activation, scope, acceptance criteria, waivers, and escalation.
+- DEV implements only assigned write scope and cannot QA-accept its own work.
+- QA starts fresh, verifies independently, and does not fix during QA.
+- ODIN monitors actively by default and intervenes on health, scope, delivery, or drift.
+- Agents without MCP/skill/full-protocol proof are NON_GOVERNED_ONE_SHOT_ONLY, not persistent governed roles.
 
-To add a third development pod (Team C), tell `A/EXEC-PM`:
+After readiness passes, emit:
+STAGED_AND_IDLE: <team-count> teams, manifest validated, awaiting first directive.
+```
 
-> Stage Team C as a new development pod identical in role shape to Team B. Call `odin.compute_surface_layout_gate fromTeamCount=2 toTeamCount=3` first and follow its checklist. The canonical layout becomes `[A] [B/C]` — Team A in the tall column, B and C stacked in the right column.
+## Scaling
 
-The same pattern scales out to 4, 5, 6, 7, 8 teams. The packing rule is in `odin://protocol/topology`.
+Add pods only after EXEC PM recomputes the CMUX layout and records readiness for
+the new role slots. Keep EXEC PM in the same workspace as the governed team by
+default.

package/docs/guides/recommended-starter-team.md

@@ -1,35 +1,53 @@
 # Recommended Starter Team
 
-ODIN is opinionated, but not rigid.
-
-The profiles below are a good starting point for a visible multi-agent session.
-They are not bundled dependencies. Install and configure the harnesses you want,
-then point them at ODIN Sentinel through MCP.
+This is a small, visible starter shape for ODIN Sentinel. It is not a dependency
+list and not a guarantee that every named harness is ready on your machine.
 
 ## Executive Office
 
-| Role | Suggested Harness | Suggested Model Class | Why |
-| --- | --- | --- | --- |
-| `A/EXEC-PM` | Codex CLI | GPT-5.5-class frontier reasoning model | Stable coordination, claim-bound reporting, and careful instruction handling. |
-| `A/EXEC-ODIN` | Codex CLI | GPT-5.5-class frontier reasoning model | Sentinel work: staying awake, polling, quality control, and closeout hygiene. |
-| `A/EXEC-ASST` | Claude Code | Claude Haiku-class fast assistant model | Low-latency ledger work, reminders, artifact indexing, and simple checks. |
-| `A/EXEC-RSCH` | Droid | Kimi K2.6-class orchestration model | Research, alternatives, synthesis, and context recovery. |
-| `A/EXEC-QA` | Droid | Kimi K2.6-class review model | Independent process review, evidence checks, and drift detection. |
+| Role | Suggested Harness Type | Responsibility |
+| --- | --- | --- |
+| `A/EXEC-PM` | Strong coordination agent | Routing, activation, assignments, waivers, escalation. |
+| `A/EXEC-ODIN` | Strong monitoring agent | Health, scope, drift, permission waits, closeout hygiene. |
+| `A/EXEC-ASST` | Fast assistant | Ledger notes, reminders, artifact index, delivery checks. |
+| `A/EXEC-RSCH` | Research/synthesis agent | Alternatives, context recovery, risk analysis. |
+| `A/EXEC-QA` | Independent reviewer | Process review and drift detection. |
 
 ## Development Pod
 
-| Role | Suggested Harness | Suggested Model Class | Why |
-| --- | --- | --- | --- |
-| `<TEAM>/TEAM-PM` | Claude Code | Claude Opus/Sonnet-class coding model | Pod orchestration, task decomposition, dispatch, and worker follow-up. |
-| `<TEAM>/ODIN` | Codex CLI | GPT-5.5-class frontier reasoning model | Lightweight pod sentinel duties, blocker detection, and quality reminders. |
-| `<TEAM>/DEV-1` | Droid | Kimi K2.6-class coding model | Bounded implementation work. |
-| `<TEAM>/QA-1` | Crush | GLM-5.1-class independent review model | Independent QA with a different review style from the implementer. |
-| `<TEAM>/SHADOW-1` | Droid | Kimi K2.6-class review model | Second-pass critique, architectural concerns, and risk surfacing. |
-
-## Notes
-
-Use faster models for ledger work, routine research, and low-risk monitoring.
-Use stronger models for coordination, implementation, QA, and places where the
-cost of a missed detail is high.
-
-The defaults live in `protocol/model-profiles.yaml`. Change them freely.
+| Role | Suggested Harness Type | Responsibility |
+| --- | --- | --- |
+| `<TEAM>/TEAM-PM` | Coding-capable coordinator | Pod assignments, follow-up, blocker routing. |
+| `<TEAM>/ODIN` | Monitor | Polling, scope reminders, unsafe-lane freezes. |
+| `<TEAM>/DEV-1` | Implementer | Bounded code/docs changes inside assigned write scope. |
+| `<TEAM>/QA-1` | Independent reviewer | Fresh-context QA; no self-fixes during QA. |
+| `<TEAM>/SHADOW-1` | Read-only reviewer | Optional second-pass critique and risk surfacing. |
+
+## Readiness Before Launch
+
+Each persistent role should have:
+
+- MCP server proof or an accepted fallback path.
+- Native skill context where supported, or full prompt fallback.
+- Auth/account readiness checked without printing secrets.
+- Local inference smoke-tested if used.
+- CMUX locator recorded in the same workspace.
+- Watcher assignment recorded in the team manifest.
+
+Role slots may exist before readiness. Occupants should wait until readiness
+passes or EXEC PM records a waiver/substitution.
+
+## ODIN Roles Are Active Monitors
+
+ODIN roles are not passive receipt emitters. Their default job is to watch for
+stall, scope drift, missed delivery, permission waits, stale versions, and role
+boundary breaches. Default active-watch cadence is 30 seconds. Treat 5 minutes
+without meaningful progress as `WATCH_WARN` and 10 minutes without heartbeat or
+observable progress as `STALLED`, unless the team manifest explicitly declares a
+known long-running command. ODIN roles must re-arm the next watch tick instead
+of returning to passive idle.
+
+Human-facing translation: ODIN pauses are safety rails. They protect the
+operator from silent failures, surprise costs, secret exposure, and agents going
+off task. A warning or halt should explain the blocker in plain language and
+offer the next safe choice; it should not blame the operator.

package/docs/reference/client-compatibility.md

@@ -1,23 +1,23 @@
 # Client Compatibility
 
-ODIN Sentinel is implemented in TypeScript and runs on Node.js, but MCP clients
-do not need to be TypeScript or JavaScript. Clients interact with the server
-through MCP over stdio, which is JSON-RPC framed over standard input/output.
+ODIN Sentinel is implemented in TypeScript and runs on Node.js `>=22.13.0`.
+Clients can be written in any language that can speak MCP over stdio or consume a
+protocol snapshot.
 
-## Compatibility Contract
+## Compatibility Layers
 
-The server keeps the MCP boundary language-neutral:
+- MCP server: language-neutral JSON-RPC over stdio.
+- Native skill: host-specific context for automatic invocation and role behavior.
+- Plugin: host install path that may bundle MCP config and native skill.
+- Full prompt injection: fallback for hosts without MCP or native skill support.
 
-- tools accept and return JSON-compatible values
-- resources return text, JSON, Markdown, or YAML content
-- no tool requires a JavaScript object prototype, class instance, or local Node-specific object
-- no tool requires filesystem access from the client
-- fallback protocol snapshots are returned as plain filename-to-text maps
+A persistent governed role should have MCP plus native skill or full prompt proof.
+If it does not, mark it `NON_GOVERNED_ONE_SHOT_ONLY`: it can do bounded one-shot
+help, but should not occupy a persistent governed role.
 
-## Rust, Zig, Go, And Native Clients
+## Native And WASM Clients
 
-Native clients that can spawn stdio subprocesses should launch the server as a
-subprocess:
+Native clients that can spawn subprocesses should launch:
 
 ```text
 command: node
@@ -25,35 +25,12 @@ args: [/path/to/odin-sentinel/dist/src/bin/index.js]
 transport: stdio
 ```
 
-Then call normal MCP methods:
+Clients that cannot spawn stdio should use a host bridge or a static snapshot
+from `odin.export_protocol_snapshot`.
 
-- `tools/list`
-- `tools/call`
-- `resources/list`
-- `resources/read`
+## CMUX Boundary
 
-## WebAssembly Clients
-
-WASM runtimes vary. Some can spawn subprocesses through a host capability; many
-cannot. If the WASM client cannot spawn a stdio process, use one of these
-patterns:
-
-1. Host bridge: native host process runs `odin-sentinel` and exposes MCP calls
-   to the WASM guest.
-2. Sidecar bridge: an external local process runs `odin-sentinel` and the WASM
-   client talks to the host through its supported bridge channel.
-3. Snapshot fallback: call `odin.export_protocol_snapshot` from a capable host and
-   provide the generated text files to the WASM agent as static context.
-
-## Portability Limits
-
-The current server runtime requires Node.js 20 or newer. This does not restrict
-the client implementation language; it only means the machine hosting the MCP
-server needs Node available.
-
-Future options if a pure native server is needed:
-
-- Rust MCP server using the same `protocol/` data files.
-- Go MCP server using the same `protocol/` data files.
-- Single-file generated JSON protocol bundle for embedded clients.
-- WASI-compatible read-only server if the target runtime supports stdio.
+CMUX is required for governed team mode because role slots must be visible,
+locatable, and human-readable. Tab-only layouts are degraded. The canonical mode
+is one CMUX workspace with spatial/pod organization and EXEC PM in the same
+workspace by default.

package/docs/reference/cost-and-privacy.md

@@ -1,35 +1,38 @@
 # Cost And Privacy
 
-ODIN Sentinel does not provide inference.
+ODIN Sentinel does not provide inference and does not host a backend. Users pay
+for their own harnesses, model providers, and local inference hardware.
 
-It does not proxy model calls, host a backend, phone home, collect telemetry, or
-ship credentials. It is a local MCP server that returns protocol resources,
-startup packets, validation results, delegation envelopes, closeout checklists,
-and fallback text snapshots.
+## Network And Telemetry Boundary
 
-## Who Pays For What
+Normal MCP operation is local stdio:
 
-The maintainer does not pay when another person runs ODIN Sentinel locally.
-
-Users are responsible for their own harness setup and any model calls those
-harnesses make. ODIN Sentinel only returns coordination data over MCP.
-
-ODIN Sentinel only names preferred harness slots and model capability profiles.
-Those are dispatch preferences, not hosted compute.
+```text
+MCP client <-> local stdio process <-> bundled protocol files
+```
 
-## Network Boundary
+No network call is required for normal protocol reads, validation tools, startup
+packets, delegation packets, or closeout checklists.
 
-The server is stdio-only by default:
+ODIN Sentinel includes optional telemetry/session-report helper tools. They are
+user-invoked, redaction-oriented, and should not be described as automatic
+collection. Do not claim "no telemetry" without the qualifier that telemetry is
+not automatic and requires an explicit tool call/configured destination.
 
-```text
-MCP client  <->  local stdio process  <->  protocol files
-```
+## Secret Handling
 
-No network call is required for normal operation.
+Do not paste API keys, OAuth material, tokens, or passwords into docs/prompts.
+Ask whether providers are configured through Doppler, 1Password CLI,
+environment variables, direnv, mise, or dotenv-style files. Verify status by
+name/count/status only, never by printing secret values.
 
-## Standalone Boundary
+Beginner-safe wording: "Please make sure this tool is signed in or configured
+outside the chat. If it is not, we can pause, use a different harness, or keep
+that role slot empty." Do not ask the user to reveal where the secret value is
+stored unless they volunteer a non-secret path or tool name.
 
-ODIN Sentinel is standalone.
+## Local Inference
 
-The default handoff search list uses `.odin/` paths. A fresh repo does not need
-any separate orchestration system installed for ODIN Sentinel to work.
+Endpoint reachability is not enough. A local model is ready only if it returns
+visible content within the session timeout and does not return only
+`reasoning_content`.

package/docs/reference/distribution.md

@@ -1,27 +1,27 @@
 # Distribution
 
-ODIN Sentinel is a local stdio MCP server. The simplest public distribution is
-an npm package that ships prebuilt JavaScript and protocol files.
+ODIN Sentinel public artifacts are the GitHub repository, npm package, optional
+host plugin, public bootstrap skill/resource, public templates, and docs. When
+public protocol semantics change, update them together.
 
-## Recommended Install Path
+## Current Public Versions
 
-```bash
-npm i -g @bradheitmann/odin-sentinel
-```
+- npm package/server: `0.4.7`
+- minimum compatible child MCP version: `0.4.5`
 
-MCP client configuration can then use the installed binary directly:
+Private local skill copies may differ for personal workflow reasons. Release
+checks must not rely on private local paths and must distinguish intentional
+private-local divergence from repo-internal public artifact drift.
 
-```json
-{
-  "mcpServers": {
-    "odin-sentinel": {
-      "command": "odin-sentinel-mcp"
-    }
-  }
-}
+## Install Paths
+
+Global install:
+
+```bash
+npm i -g @bradheitmann/odin-sentinel
 ```
 
-For zero-install via `npx`:
+Zero-install MCP config:
 
 ```json
 {
@@ -34,9 +34,7 @@ For zero-install via `npx`:
 }
 ```
 
-## Local Clone Path
-
-For source builds:
+Source build:
 
 ```bash
 pnpm install
@@ -44,39 +42,26 @@ pnpm run build
 node dist/src/bin/index.js
 ```
 
-Then point the client at the built file:
-
-```json
-{
-  "mcpServers": {
-    "odin-sentinel": {
-      "command": "node",
-      "args": ["/absolute/path/to/odin-sentinel/dist/src/bin/index.js"]
-    }
-  }
-}
-```
-
-## Advanced Root Override
-
-The server normally finds its bundled `protocol/` directory automatically.
-
-Advanced deployments can set `ODIN_SENTINEL_ROOT` to point at another checked-out
-ODIN Sentinel root that contains the full `protocol/` tree. Most users do not
-need this.
-
-## Binary Strategy
-
-A native binary is possible, but it should not be the first distribution path.
-The server is small, stdio-only, and already fits the package manager workflow
-most MCP clients expect.
-
-Good future binary routes:
-
-- Rust or Go implementation over the same `protocol/` files.
-- Generated single-file protocol bundle for embedded clients.
-- Homebrew formula once the public package name and release cadence are stable.
-
-Avoid a bundled Node executable unless users ask for it. Those bundles tend to
-make asset paths, source maps, and platform support more awkward than the code
-deserves.
+## Release Checklist
+
+Before publishing or updating a plugin/skill listing:
+
+1. Update GitHub source, docs, protocol resources, public templates, and package
+   metadata together.
+2. Confirm npm package metadata includes repository, homepage, bugs, license,
+   engines, and files.
+3. Confirm package contents exclude private planning workspaces and local evidence paths.
+4. Confirm `protocol/SCP.md` and `protocol/bootstrap-skill.md` carry the same
+   public version and minimum compatible child MCP version.
+5. Confirm public docs do not contain stale MCP/server version references.
+6. Confirm telemetry wording explains that session-report submission is optional
+   and user-invoked.
+7. Run offline release validation: `pnpm run validate`.
+8. Run pack dry-run: `pnpm pack --dry-run`.
+9. Tag the release only after GitHub, npm, plugin, public skill/bootstrap, docs,
+   and version tags agree.
+
+## Public Templates
+
+The npm package intentionally ships `templates/` plus `AGENTS.md` and
+`CLAUDE.md`. They are starter templates, not private planning artifacts.