@bradheitmann/odin-sentinel 0.4.4 → 0.4.6

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.6`
+- 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.

package/docs/reference/public-surface-audit.md

@@ -2,132 +2,53 @@
 
 This document records the current public-release audit scope for ODIN Sentinel.
 
-## Current Tree Result
-
-Current tracked source, docs, protocol files, tests, and package metadata pass
-the public-surface audit:
+## Audit Commands
 
 ```bash
 pnpm run audit:public
+pnpm run test:package
+pnpm run validate
 ```
 
-The audit checks for:
-
-- local home-directory paths
-- local agent configuration paths
-- legacy extension terminology from adjacent agent systems
-- secret-looking assignments
-
-## Named External Concepts
-
-ODIN Sentinel intentionally names these external concepts:
-
-- MCP / Model Context Protocol
-- stdio
-- Node.js
-- TypeScript / JavaScript
-- pnpm / npm / npx
-- Codex CLI
-- Claude Code
-- Droid
-- Crush
-- Goose
-- Zed
-- OpenCode
-- Cursor
-- Rust
-- Go
-- Zig
-- WebAssembly / WASM
-- Homebrew
-
-These are examples, runtimes, package managers, languages, or harnesses. They
-are not bundled dependencies unless listed in `package.json`.
-
-## Named ODIN Concepts
-
-- ODIN Sentinel
-- ODIN
-- SCP / Sentinel Coordination Protocol
-- CMUX-compatible terminal-pane teams
-- EXEC PM
-- EXEC ODIN
-- EXEC ASST
-- EXEC RSCH
-- EXEC QA
-- TEAM PM
-- TEAM ODIN
-- DEV WORKER
-- QA WORKER
-- SHADOW REVIEWER
-
-## Local Paths
-
-ODIN Sentinel intentionally mentions these project-local paths:
-
-- `docs/handoffs/`
-- `.odin/handoffs/`
-- `.odin/audit/`
-
-These are caller-created paths for projects that use ODIN. They are not bundled
-private state.
-
-Docs also use placeholder install paths such as:
+The audits check public distribution files for local home paths, private project
+markers, local evidence paths, stale public versions, missing package metadata,
+telemetry wording drift, and package contents that should not ship.
 
-- `/absolute/path/to/odin-sentinel/dist/src/bin/index.js`
-- `/path/to/odin-sentinel/dist/src/bin/index.js`
+## Public Distribution Files
 
-These are examples, not real local paths.
+The intended public package includes:
 
-## Scripts Mentioned
+- `dist/`
+- `docs/`
+- `protocol/`
+- `templates/`
+- `scripts/audit/`
+- `AGENTS.md`
+- `CLAUDE.md`
+- `README.md`
+- `LICENSE`
+- `package.json`
 
-Repo scripts in `package.json`:
+Private planning workspaces and local evidence directories are optional local
+operator spaces. They are not public product internals and must not be packaged.
 
-- `pnpm run clean`
-- `pnpm run build`
-- `pnpm run dev`
-- `pnpm run audit:public`
-- `pnpm run test:package`
-- `pnpm test`
-- `pnpm run typecheck`
-- `pnpm run validate`
-
-Referenced local script files:
-
-- `scripts/audit/public-surface.mjs`
-- `scripts/audit/verify-pack.mjs`
-
-No missing repo-local scripts are known.
-
-External commands mentioned in docs:
-
-- `node`
-- `pnpm`
-- `npm`
-- `npx`
-- `codex mcp add`
-- `droid mcp add`
-
-These are external user-installed tools, not files this repository must provide.
-
-## Snapshot Tools
-
-Current MCP snapshot tool:
-
-- `odin.export_protocol_snapshot`
+## Named External Concepts
 
-No external local extension is required for ODIN Sentinel to work.
+ODIN Sentinel intentionally names MCP, stdio, Node.js, TypeScript, pnpm, npm,
+npx, CMUX, Codex, Claude Code, Droid, Crush, Goose, Zed, OpenCode, Cursor,
+Rust, Go, Zig, and WebAssembly as examples, runtimes, package managers,
+languages, or harnesses.
 
-## Git History Warning
+## Current Public Surface
 
-The current tree is sanitized, but this private development repository has older
-commits that contain removed terminology and experimental paths.
+- Public package/server version: `0.4.6`
+- Minimum compatible child MCP version: `0.4.5`
+- MCP resources: 9
+- MCP tools: 23
+- Optional telemetry tools: user-invoked, not automatic collection
 
-Do not make this private development history public as-is. For an open-source
-release, publish from a fresh repository, a squashed root commit, or a sanitized
-history rewrite after re-running:
+## Release Drift Rule
 
-```bash
-pnpm run validate
-pnpm run audit:public
-```
+Public repo/package/plugin/skill artifacts must be updated together when public
+protocol semantics change. Private local skill copies may differ, but release
+checks must not depend on private local paths.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bradheitmann/odin-sentinel",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "publishConfig": {
     "access": "public"
   },
@@ -27,7 +27,10 @@
     "dist",
     "docs",
     "protocol",
+    "templates",
     "scripts",
+    "AGENTS.md",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],
@@ -41,9 +44,9 @@
   "author": "ODIN Sentinel contributors",
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "yaml": "^2.8.2",
-    "zod": "^4.1.12"
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "yaml": "2.8.4",
+    "zod": "4.4.3"
   },
   "devDependencies": {
     "@types/node": "^24.10.1",
@@ -55,6 +58,18 @@
   "engines": {
     "node": ">=22.13.0"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bradheitmann/odin-sentinel.git"
+  },
+  "homepage": "https://github.com/bradheitmann/odin-sentinel#readme",
+  "bugs": {
+    "url": "https://github.com/bradheitmann/odin-sentinel/issues"
+  },
+  "odin": {
+    "publicVersion": "0.4.6",
+    "minimumCompatibleChildMcpVersion": "0.4.5"
+  },
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "pnpm run clean && tsc -p tsconfig.build.json",

package/protocol/SCP.md

@@ -1,6 +1,9 @@
 # ODIN Sentinel Coordination Protocol
 
-Version: 0.3.0
+Version: 0.4.6
+
+SCP_PUBLIC_VERSION: 0.4.6
+MIN_COMPATIBLE_CHILD_MCP: 0.4.5
 
 ODIN Sentinel is a portable coordination layer for visible multi-agent teams.
 SCP means Sentinel Coordination Protocol in this repository. It is not Secure
@@ -10,6 +13,10 @@ manifest validation, native visible-role delegation packets, closeout
 checklists, surface layout rules, and fallback protocol snapshots through an
 MCP server.
 
+## Public Release And Readiness
+
+Public repo, npm package, plugin, bootstrap skill, templates, and docs must be updated together when public protocol semantics change. Private local skill copies may differ intentionally, but release checks must not depend on private local paths. Governed team mode requires CMUX; without CMUX, ODIN may still expose MCP resources and validation tools, but the visible team-management experience is not active governed mode. MCP supplies tools/resources; native skills improve automatic invocation; plugin install paths may package both; full prompt injection is fallback only.
+
 ## Principles
 
 - Visible role slots are the audit surface.