@jstn-sdk/rcs 0.1.0

package/docs/contracts/runtime-command-event-snapshot-schema.md

@@ -0,0 +1,133 @@
+# Runtime command / event / snapshot schema
+
+This document defines the Rust-owned runtime contract used by the first greenfield cutover.
+
+## Scope
+- Commands describe semantic requests.
+- Events describe semantic outcomes.
+- Snapshots describe the current truth of the runtime.
+- Transport details (JSON, IPC, files) are implementation details layered on top.
+
+## Command shapes
+
+| Command | Required fields | Meaning |
+|---|---|---|
+| `acquire-authority` | `owner`, `lease_id`, `leased_until` | Claim the single semantic authority lease. |
+| `renew-authority` | `owner`, `lease_id`, `leased_until` | Extend the current lease without changing ownership. |
+| `queue-dispatch` | `request_id`, `target` | Add one dispatch request to the backlog. |
+| `mark-notified` | `request_id`, `channel` | Record that a queued dispatch has been delivered to an observer or target. |
+| `mark-delivered` | `request_id` | Record successful delivery completion. |
+| `mark-failed` | `request_id`, `reason` | Record failed delivery completion. |
+| `request-replay` | `cursor` | Ask the runtime to replay from a durable cursor. |
+| `capture-snapshot` | none | Emit the current semantic snapshot. |
+
+## Event shapes
+
+| Event | Required fields | Meaning |
+|---|---|---|
+| `authority-acquired` | `owner`, `lease_id`, `leased_until` | A new authority lease is active. |
+| `authority-renewed` | `owner`, `lease_id`, `leased_until` | The active lease was renewed. |
+| `dispatch-queued` | `request_id`, `target` | A request entered backlog. |
+| `dispatch-notified` | `request_id`, `channel` | A request moved out of pending and into notification. |
+| `dispatch-delivered` | `request_id` | The request completed successfully. |
+| `dispatch-failed` | `request_id`, `reason` | The request completed with failure. |
+| `replay-requested` | `cursor` | Replay or recovery work was requested. |
+| `snapshot-captured` | none | A snapshot was emitted for observers. |
+| `run.heartbeat` | `owner`, `phase` | The active runtime is alive and still making forward-progress observations. |
+| `run.blocked_on_user` | `owner`, `reason` | The runtime is explicitly waiting for user input or approval. |
+| `run.blocked_on_system` | `owner`, `reason` | The runtime is blocked on tooling, environment, or system repair. |
+| `worker.assigned` | `worker`, `task_id` | A worker received an authoritative task assignment. |
+| `worker.stalled` | `worker`, `reason` | A worker crossed the supervisor intervention threshold and needs recovery attention. |
+| `worker.recovered` | `worker`, `recovery` | A stalled or interrupted worker recovered, resumed, or was relaunched. |
+
+## Snapshot fields
+
+| Field | Meaning |
+|---|---|
+| `schema_version` | Contract version for the runtime snapshot. |
+| `authority.owner` | The current semantic owner, if any. |
+| `authority.lease_id` | Lease identifier for the current owner. |
+| `authority.leased_until` | Lease expiry marker. |
+| `authority.stale` | Whether the current owner is stale or expired. |
+| `backlog.pending` | Dispatches awaiting notification. |
+| `backlog.notified` | Dispatches that were notified and are waiting for completion. |
+| `backlog.delivered` | Dispatches that completed successfully. |
+| `backlog.failed` | Dispatches that completed with failure. |
+| `replay.cursor` | Durable replay cursor, if any. |
+| `replay.pending_events` | Number of replayable events not yet applied. |
+| `replay.last_replayed_event_id` | Last replayed event marker. |
+| `replay.deferred_leader_notification` | Whether leader notification was intentionally deferred. |
+| `readiness.ready` | Whether the runtime is ready for operator traffic. |
+| `readiness.reasons` | Human-readable blockers when the runtime is not ready. |
+
+## JSON serialization format
+
+Commands use `#[serde(tag = "command")]` — the variant name becomes the `"command"` field, remaining fields are flattened inline:
+
+```json
+{"command":"AcquireAuthority","owner":"w1","lease_id":"l1","leased_until":"2026-03-19T02:00:00Z"}
+{"command":"RenewAuthority","owner":"w1","lease_id":"l2","leased_until":"2026-03-19T03:00:00Z"}
+{"command":"QueueDispatch","request_id":"req-1","target":"worker-2"}
+{"command":"MarkNotified","request_id":"req-1","channel":"tmux"}
+{"command":"MarkDelivered","request_id":"req-1"}
+{"command":"MarkFailed","request_id":"req-1","reason":"timeout"}
+{"command":"RequestReplay","cursor":"cursor-1"}
+{"command":"CaptureSnapshot"}
+```
+
+Events use `#[serde(tag = "event")]` — the variant name becomes the `"event"` field, remaining fields are flattened inline:
+
+```json
+{"event":"AuthorityAcquired","owner":"w1","lease_id":"l1","leased_until":"2026-03-19T02:00:00Z"}
+{"event":"AuthorityRenewed","owner":"w1","lease_id":"l2","leased_until":"2026-03-19T03:00:00Z"}
+{"event":"DispatchQueued","request_id":"req-1","target":"worker-2"}
+{"event":"DispatchNotified","request_id":"req-1","channel":"tmux"}
+{"event":"DispatchDelivered","request_id":"req-1"}
+{"event":"DispatchFailed","request_id":"req-1","reason":"timeout"}
+{"event":"ReplayRequested","cursor":"cursor-1"}
+{"event":"SnapshotCaptured"}
+{"event":"run.heartbeat","owner":"leader","phase":"execute"}
+{"event":"run.blocked_on_user","owner":"leader","reason":"needs-user-clarification"}
+{"event":"run.blocked_on_system","owner":"leader","reason":"sandbox-denied"}
+{"event":"worker.assigned","worker":"worker-2","task_id":"17"}
+{"event":"worker.stalled","worker":"worker-2","reason":"stdout-stale"}
+{"event":"worker.recovered","worker":"worker-2","recovery":"relaunch"}
+```
+
+Snapshot fields are flat JSON at the top level, with nested objects for each section:
+
+```json
+{
+  "schema_version": 1,
+  "authority": {
+    "owner": "w1",
+    "lease_id": "l1",
+    "leased_until": "2026-03-19T02:00:00Z",
+    "stale": false,
+    "stale_reason": null
+  },
+  "backlog": {
+    "pending": 1,
+    "notified": 0,
+    "delivered": 0,
+    "failed": 0
+  },
+  "replay": {
+    "cursor": null,
+    "pending_events": 0,
+    "last_replayed_event_id": null,
+    "deferred_leader_notification": false
+  },
+  "readiness": {
+    "ready": true,
+    "reasons": []
+  }
+}
+```
+
+## Invariants
+- Exactly one semantic authority owner may be active at a time.
+- Dispatches must move `pending -> notified -> delivered|failed`.
+- Replay state must be durable and deduplicated.
+- Readiness is derived from Rust-owned truth, not from JS-side inference.
+

package/docs/contracts/rust-runtime-thin-adapter-contract.md

@@ -0,0 +1,69 @@
+# Rust Runtime Thin-Adapter Contract
+
+## Canonical ownership
+
+Rust core is the single semantic owner for:
+
+- authority
+- lifecycle/session state
+- dispatch/backlog
+- mailbox delivery state
+- replay/recovery
+- readiness/diagnostics
+- canonical mux operations
+
+JS, HUD, CLI, and tmux are thin delivery/observer adapters. They may read
+compatibility artifacts, but they MUST NOT define or mutate semantic truth on
+their own.
+
+Current migration follow-ups that still fall short of this target are tracked in
+`docs/qa/runtime-team-seam-audit-2026-04-01.md`.
+
+## Compatibility artifacts
+
+Legacy readers continue to read the same state files, but only as
+Rust-authored compatibility views.
+
+| Reader | Compatibility files | Compatibility guarantee |
+|---|---|---|
+| `rcs team status` | `.rcs/state/team/<team>/config.json`, `manifest.v2.json`, `tasks/*.json`, `approvals/*.json`, `workers/*` | Manifest-backed team config is authoritative when both config and manifest exist. |
+| `rcs doctor --team` | `.rcs/state/team/<team>/config.json`, `manifest.v2.json`, `workers/*/status.json`, `workers/*/heartbeat.json`, `.rcs/state/hud-state.json` | Manifest-backed tmux/session identity is authoritative when both config and manifest exist. |
+| HUD readers | `.rcs/state/session.json`, `.rcs/state/sessions/<session>/team-state.json`, `.rcs/state/team-state.json`, `.rcs/state/ralph-state.json` | Session-scoped files are authoritative when a session is active; root files are compatibility fallback only. |
+
+## Rust-authored runtime files
+
+The `RuntimeEngine` (in `crates/rcs-runtime-core/src/engine.rs`) writes the following files via `persist()` and `write_compatibility_view()`:
+
+| File | Written by | Content |
+|---|---|---|
+| `snapshot.json` | `persist()` | Full `RuntimeSnapshot` — `schema_version`, `authority`, `backlog`, `replay`, `readiness` |
+| `events.json` | `persist()` | Append-only event log — array of `RuntimeEvent` values in `#[serde(tag = "event")]` format |
+| `authority.json` | `write_compatibility_view()` | `AuthoritySnapshot` section for TS readers |
+| `backlog.json` | `write_compatibility_view()` | `BacklogSnapshot` counts (`pending`, `notified`, `delivered`, `failed`) for TS readers |
+| `readiness.json` | `write_compatibility_view()` | `ReadinessSnapshot` (`ready`, `reasons`) for TS readers |
+| `replay.json` | `write_compatibility_view()` | `ReplaySnapshot` state for TS readers |
+| `dispatch.json` | `write_compatibility_view()` | Full `DispatchLog` (array of `DispatchRecord` entries) for team status readers |
+| `mailbox.json` | `write_compatibility_view()` | Full `MailboxLog` (array of `MailboxRecord` entries) for team/message readers |
+
+All files are written atomically to the configured `state_dir`. TS readers must treat these files as read-only; the Rust engine is the sole writer.
+
+## Thin-adapter rules
+
+1. Compatibility readers must ignore unknown fields and preserve their current
+   JSON envelopes.
+2. Legacy tmux typing is delivery only; it does not establish semantic truth.
+3. If Rust-authored compatibility files and legacy JS defaults disagree, the
+   Rust-authored file wins.
+4. JS file writes remain fallback-only for lanes where the bridge is disabled or
+   unavailable; they are not canonical when the Rust bridge succeeds.
+5. Unknown delivery failures are surfaced as adapter failures, not as semantic
+   owner changes.
+
+## Consumer matrix
+
+| Consumer | Responsibility |
+|---|---|
+| Team CLI | Read Rust-authored compatibility artifacts and render them faithfully. |
+| Doctor CLI | Report readiness from Rust-authored compatibility artifacts, then layer adapter health checks on top. |
+| HUD | Stay read-only and scope-aware. |
+| Notify/watchers | Deliver events; never become the semantic owner of the run. |

package/docs/contracts/team-delivery-state-contract.md

@@ -0,0 +1,95 @@
+# Team delivery / integration state contract
+
+This document records the currently-audited ownership contract for the states
+called out in issue #1243.
+
+## Scope
+
+- dispatch lifecycle: `pending`, `notified`, `delivered`, `failed`
+- integration lifecycle: `integrated`
+- readiness / leader-activity lifecycle: `stale`
+
+## Authoritative owners
+
+### `pending` / `notified` / `delivered` / `failed`
+
+Durable owner:
+
+- Rust runtime dispatch log when the bridge is enabled
+  - `crates/rcs-runtime-core/src/dispatch.rs`
+  - surfaced through `src/runtime/bridge.ts`
+- legacy JSON fallback only when the bridge is disabled or unreadable
+  - `src/team/state/dispatch.ts`
+  - `src/team/state.ts`
+
+Observed code paths:
+
+- queue: `DispatchLog::queue()` ↔ `enqueueDispatchRequest()`
+- notify: `DispatchLog::mark_notified()` ↔ `markDispatchRequestNotified()`
+- deliver: `DispatchLog::mark_delivered()` ↔ `markDispatchRequestDelivered()`
+- fail: `DispatchLog::mark_failed()` ↔ `markDispatchRequestFailed()` / `transitionDispatchRequest(..., 'failed')`
+
+Transition contract:
+
+- `pending -> notified`
+- `pending -> failed`
+- `notified -> delivered`
+- `notified -> failed`
+- same-state reason/timestamp patching is allowed
+- `failed -> notified` is **not** allowed for the same `request_id`
+
+Rationale:
+
+- Rust already enforces `failed` as terminal for a dispatch record.
+- TS fallback must mirror that contract so hook, fallback, and replay paths do
+  not answer the same state question differently.
+
+### `integrated`
+
+Durable owner:
+
+- team monitor integration snapshot written by runtime integration logic
+  - `src/team/runtime.ts`
+  - `src/team/state.ts`
+  - `src/team/state/monitor.ts`
+
+Observed code paths:
+
+- merge/cherry-pick/rebase decisions in `integrateWorkerCommitsIntoLeader()`
+- failure path in `recordIntegrationFailure()`
+
+Success contract:
+
+- `integrated` requires durable git evidence:
+  - leader HEAD advanced, and
+  - integrated worker commit is actually reachable from leader HEAD
+
+### `stale`
+
+Durable owner depends on subject:
+
+- runtime authority staleness:
+  - `crates/rcs-runtime-core/src/lib.rs`
+  - `crates/rcs-runtime-core/src/engine.rs`
+  - surfaced via `src/runtime/bridge.ts`
+- leader/session staleness:
+  - `src/team/leader-activity.ts`
+  - `src/hooks/session.ts`
+
+Contract:
+
+- `stale` is an eligibility / readiness signal, not a success state
+- tmux/HUD observations may contribute evidence, but they are not the durable
+  semantic owner of dispatch or integration success
+
+## First contract hardening change
+
+When a hook-authored dispatch receipt has already become `failed`, later fallback
+confirmation must not mutate that same request back to `notified`.
+
+Instead:
+
+- keep the request `failed`
+- patch `last_reason` to record the confirmed fallback path
+- treat fallback success as an operational recovery event, not as a rewrite of
+  the original hook-attempt state machine

package/docs/contracts/team-runtime-state-contract.md

@@ -0,0 +1,48 @@
+# Team runtime state contract
+
+Issue: #1243 workstream A
+
+This document records the currently authoritative owners for the team-runtime states that repeatedly drifted across team state, notify-hook, mailbox shadows, tmux observations, and runtime bridge compatibility files.
+
+## Authoritative owners
+
+### `pending`, `notified`, `delivered`, `failed`
+- Durable owner: team dispatch request state.
+- Primary TypeScript entry points:
+  - `src/team/state/dispatch.ts`
+  - `src/team/state.ts`
+- Rust bridge shape:
+  - `crates/rcs-runtime-core/src/dispatch.rs`
+  - `src/runtime/bridge.ts`
+- Rule: dispatch `status` is authoritative. Timestamp fields are supporting evidence and must not contradict `status`.
+
+### `integrated`
+- Durable owner: monitor snapshot `integrationByWorker` written by team runtime.
+- Primary entry points:
+  - `src/team/runtime.ts`
+  - `src/team/state/monitor.ts`
+  - `src/team/state.ts`
+- Rule: a worker is only `integrated` after leader-head advancement / containment checks succeed. Mailbox delivery and tmux activity are not sufficient.
+
+### `stale`
+- No single shared owner yet; this remains split by boundary.
+- Runtime authority stale:
+  - `crates/rcs-runtime-core/src/lib.rs`
+  - `src/runtime/bridge.ts`
+- Leader activity stale:
+  - `src/team/leader-activity.ts`
+- Session stale:
+  - `src/hooks/session.ts`
+- Rule: stale is currently boundary-specific and must not be inferred from dispatch/integration state alone.
+
+## Notify-hook boundary
+
+`notify-hook` may observe mailbox/tmux evidence, but dispatch success is still represented through dispatch-request state transitions. Mailbox `notified_at` / `delivered_at` are derivative evidence, not the dispatch contract itself.
+
+## Workstream A first change
+
+1. Centralize dispatch and integration status enums in `src/team/contracts.ts`.
+2. Sanitize persisted dispatch timestamps so they cannot contradict the authoritative dispatch `status`.
+3. Sanitize persisted integration snapshot statuses so readers only consume contract-approved values.
+
+This keeps the first fix narrow while making the contract explicit at the read/normalize boundary.

package/docs/contracts/team-startup-dispatch-latency.md

@@ -0,0 +1,114 @@
+# Team startup dispatch latency contract
+
+Date: 2026-04-30
+
+Review lane: worker-3
+
+## Scope
+
+This note documents the review contract for the team startup assignment-delay
+fix described by `.rcs/plans/ralplan-team-worker-assignment-delay-20260430T110158Z.md`.
+It focuses on the startup window after tmux worker panes are created and before
+workers receive their first inbox trigger.
+
+The issue is not task allocation: tasks, worker identity, and worker inbox files
+are already durable before startup notification attempts begin. The latency risk
+sits in the readiness, dispatch, and startup-evidence gates that currently sit
+between pane creation and the first trigger.
+
+## Current startup path under review
+
+1. `src/team/tmux-session.ts:createTeamSession()` splits leader/worker panes and
+   returns concrete `workerPaneIds`.
+2. `src/team/runtime.ts:startTeam()` writes every worker identity and inbox file,
+   saves team config, then fans out `runWorkerStartupAttempt()` for each worker.
+3. Interactive workers without an `initialPrompt` call
+   `waitForWorkerReadyAsync()` before `dispatchCriticalInboxInstruction()`.
+4. The default dispatch policy uses `hook_preferred_with_fallback`, so startup
+   inbox dispatch is first queued for the notify hook and then waits for a
+   receipt before falling back to direct tmux send.
+5. Startup dispatch can additionally wait for `waitForWorkerStartupEvidence()`
+   before treating the first trigger as settled.
+
+## Latency phases that must be instrumented
+
+The startup timing log should use monotonic timing deltas and include at least
+these phase markers for each worker:
+
+| Marker | Meaning |
+|---|---|
+| `pane_id_captured` | `createTeamSession()` returned the worker pane id. |
+| `identity_inbox_written` | worker identity and inbox state were written. |
+| `ready_wait_start` | interactive readiness polling began. |
+| `ready_wait_end` | readiness polling returned ready, timed out, or hit a prompt guard. |
+| `dispatch_queued` | startup inbox dispatch request was persisted. |
+| `hook_receipt` | hook-preferred path observed `notified`, `delivered`, `failed`, or timeout. |
+| `direct_trigger_attempt` | direct tmux trigger injection was attempted. |
+| `direct_trigger_result` | direct injection result was recorded. |
+| `startup_evidence` | worker startup evidence (`task_claim`, `worker_progress`, `leader_ack`, `none`) was observed. |
+
+A useful operator-facing summary is the per-worker delta from
+`pane_id_captured` to first trigger attempt, plus whether the final startup
+settlement came from hook delivery, direct fallback, or asynchronous evidence.
+
+## Fast-path safety contract
+
+A startup-only direct-trigger path is acceptable only when all of the following
+conditions hold:
+
+- It runs only for the first worker inbox trigger during team startup.
+- Durable assignment state is already written: task JSON, identity JSON, inbox,
+  manifest/config pane id, and dispatch request metadata.
+- It does not replace or bypass mailbox dispatch for follow-up worker messages.
+- It does not send through visible Codex trust prompts.
+- It does not send through visible Claude bypass-permissions prompts unless the
+  existing explicit auto-accept path has handled the prompt first.
+- It does not mark hook delivery as successful merely because a direct trigger
+  was attempted.
+- Lack of startup evidence is reported as recoverable observability when the
+  worker pane is alive; it must not prevent sibling workers from receiving their
+  startup triggers.
+
+## Review checklist
+
+Use this checklist when reviewing the implementation:
+
+- [ ] Startup timing instrumentation records all phase markers above without
+      making hook/evidence confirmation part of the first-trigger critical path.
+- [ ] The direct-trigger fast path is startup-only and cannot be reached by
+      general mailbox or follow-up dispatch.
+- [ ] Trust and bypass prompt guards reuse the same pane-capture safety semantics
+      as `waitForWorkerReadyAsync()` / notify-hook dispatch.
+- [ ] Dispatch request state remains authoritative for `pending`, `notified`,
+      `delivered`, and `failed`; timing logs are supporting evidence only.
+- [ ] Existing `hook_preferred_with_fallback` mailbox behavior is unchanged for
+      non-startup messages.
+- [ ] Tests isolate readiness latency, hook receipt/evidence latency, and the
+      startup fast path separately so failures identify the phase that regressed.
+
+## Regression tests expected
+
+Focused coverage should include:
+
+1. A runtime test proving a slow `waitForWorkerReadyAsync()` used to delay first
+   startup dispatch up to the configured ready timeout.
+2. A runtime test proving hook-preferred startup dispatch no longer waits for
+   startup evidence before attempting the first safe trigger.
+3. A tmux/session or notify-hook guard test proving no startup direct trigger is
+   sent through visible trust or bypass prompts.
+4. A mailbox regression test proving ordinary mailbox dispatch still uses the
+   existing hook-preferred/fallback behavior outside startup.
+5. A multi-worker startup test proving worker-1 evidence delay does not block
+   worker-2 from receiving a first trigger.
+
+## Known review risks
+
+- `waitForWorkerReadyAsync()` currently contains useful prompt-handling safety.
+  Moving a trigger earlier must preserve its prompt guards rather than deleting
+  them from the startup story.
+- Notify-hook post-injection verification intentionally refuses to confirm worker
+  dispatch while a pane is not ready. The startup fast path may attempt an early
+  trigger, but it must keep confirmation and evidence semantics separate.
+- Startup evidence differs by worker CLI: Codex ACK-only messages are not enough
+  to settle startup, while Claude leader ACK can be evidence. Reviewers should
+  keep this distinction when interpreting timing logs.

package/docs/getting-started.html

@@ -0,0 +1,91 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Getting Started - RCS Docs</title>
+    <link rel="stylesheet" href="./style.css" />
+  </head>
+  <body>
+    <header>
+      <nav class="container nav" aria-label="Primary">
+        <a class="brand" href="./index.html">RCS</a>
+        <a href="./index.html">Home</a>
+        <a class="active" href="./getting-started.html">Getting Started</a>
+        <a href="./agents.html">Agents</a>
+        <a href="./skills.html">Skills</a>
+        <a href="./integrations.html">Integrations</a>
+      </nav>
+    </header>
+
+    <main class="container">
+      <h1>Getting Started</h1>
+      <p class="muted">End-to-end setup for first-time users.</p>
+
+      <h2>Prerequisites</h2>
+      <ul>
+        <li>Node.js 20+ and npm.</li>
+        <li>OpenAI Codex CLI installed and authenticated.</li>
+        <li>Git (recommended) for project workflows.</li>
+      </ul>
+
+      <h2>Installation</h2>
+      <pre><code>npm install -g @openai/codex @jstn-sdk/rcs
+rcs doctor</code></pre>
+      <p>When <code>@jstn-sdk/rcs</code> actually bumps to a newer version, the global npm install prints an explicit reminder instead of launching <code>rcs setup</code> automatically. When you're ready, rerun <code>rcs setup</code> manually or use <code>rcs update</code> to check npm and then run the same setup refresh path. Fresh RCS-managed <code>gpt-5.5</code> configs now recommend <code>model_context_window = 250000</code> and <code>model_auto_compact_token_limit = 200000</code> only when those keys are missing.</p>
+      <p><code>rcs doctor</code> verifies the install shape. Before treating the runtime as ready, also prove that the active Codex profile can perform a real request:</p>
+      <pre><code>codex login status
+rcs exec --skip-git-repo-check -C . &quot;Reply with exactly RCS-EXEC-OK&quot;</code></pre>
+
+      <h2>Recommended Launch</h2>
+      <pre><code>rcs --xhigh --madmax   # trusted environments
+rcs                    # standard launch</code></pre>
+
+      <h2>First Run Walkthrough</h2>
+      <ol>
+        <li>Create or enter a project directory.</li>
+        <li>Install or update RCS globally.</li>
+        <li>After install or real RCS version bumps, rerun <code>rcs setup</code> yourself when you're ready, or use <code>rcs update</code> when you also want npm to update RCS first.</li>
+        <li>Run <code>rcs doctor</code>, then the <code>codex login status</code> plus <code>rcs exec</code> smoke test above.</li>
+        <li>Start Codex CLI with <code>rcs</code>.</li>
+        <li>Use <code>$brief "clarify the creator workflow change"</code> when intent or boundaries are still unclear.</li>
+        <li>Use <code>$blueprint "approve the plan and review tradeoffs"</code> to lock the implementation plan.</li>
+        <li>Choose <code>$forge "carry the approved plan to completion"</code> or <code>$crew "execute the approved plan in parallel"</code> based on execution style.</li>
+      </ol>
+
+      <h2>Creator Workflow First</h2>
+      <p>The canonical public path is:</p>
+      <pre><code>$brief -> $blueprint -> $forge / $crew -> $autoforge</code></pre>
+      <p>Older engine-facing surfaces such as <code>$deep-interview</code>, <code>$ralplan</code>, <code>$ralph</code>, <code>$team</code>, and <code>$autopilot</code> remain available as lower-level compatibility/runtime layers, but they are not the primary onboarding path.</p>
+
+      <h2>Prompt Instruction Source</h2>
+      <p>RCS layers project instructions by default (extends Codex behavior, does not replace/bypass Codex core system policies):</p>
+      <pre><code>-c model_instructions_file="&lt;cwd&gt;/AGENTS.md"</code></pre>
+      <p>Override behavior when needed:</p>
+      <pre><code>RCS_BYPASS_DEFAULT_SYSTEM_PROMPT=0 rcs
+RCS_MODEL_INSTRUCTIONS_FILE=/path/to/instructions.md rcs</code></pre>
+
+      <h2>Troubleshooting</h2>
+      <table>
+        <thead><tr><th>Issue</th><th>What to check</th></tr></thead>
+        <tbody>
+          <tr><td><code>rcs</code> command not found</td><td>Re-run global install and ensure npm global bin is in PATH.</td></tr>
+          <tr><td>Prompts not available</td><td>Confirm files exist in <code>~/.codex/prompts/</code> and re-run <code>rcs setup</code>.</td></tr>
+          <tr><td>Skills not loading</td><td>Verify <code>~/.codex/skills/*/SKILL.md</code> files were installed.</td></tr>
+          <tr><td>Doctor reports config issues</td><td>Run <code>rcs doctor</code> and apply the suggested fixes.</td></tr>
+          <tr><td>Doctor is green but execution fails</td><td>Run <code>codex login status</code> and <code>rcs exec --skip-git-repo-check -C . &quot;Reply with exactly RCS-EXEC-OK&quot;</code> from the same shell/profile. A green doctor is install evidence, not proof of authenticated model execution.</td></tr>
+          <tr><td>Custom or profile HOME cannot authenticate</td><td>Check the active <code>~/.codex</code> or <code>CODEX_HOME</code>. Containers, profile shells, and service users may not see the same auth/config as your normal user home.</td></tr>
+          <tr><td>Local proxy or compatible endpoint returns 401</td><td>If you use a proxy, verify the active <code>~/.codex/config.toml</code> contains the expected <code>openai_base_url</code>. Proxy keys sent to the wrong endpoint can look like missing bearer auth or an incorrect API key.</td></tr>
+          <tr><td><code>rcs doctor --team</code> sees a dead tmux team</td><td>If the team is intentionally abandoned, run <code>rcs team shutdown &lt;team-name&gt; --force --confirm-issues</code>, then <code>rcs cancel</code>, then <code>rcs doctor --team</code>.</td></tr>
+        </tbody>
+      </table>
+      <p class="muted">Need deeper operator help? See <a href="./troubleshooting.md">Troubleshooting execution readiness</a>.</p>
+    </main>
+
+    <footer>
+      <div class="container">
+        <span class="muted">Need broader context? Start from the project README.</span>
+      </div>
+    </footer>
+  </body>
+</html>

package/docs/guidance-schema.md

@@ -0,0 +1,69 @@
+# Unified Guidance Schema (AGENTS + Team Worker Surfaces)
+
+Status: Canonical contract for instruction-surface alignment.
+
+## Purpose
+
+Define one shared schema that can be applied across:
+- static AGENTS template surfaces,
+- runtime AGENTS overlays,
+- team worker overlays,
+- worker protocol skill/inbox guidance.
+
+This standard is additive and migration-safe: it does not change task-state APIs, marker contracts, or file-path ownership contracts.
+
+## Canonical Schema Sections
+
+### Required sections
+
+1. **Role & Intent**
+   - Who the agent/worker is and what success means.
+2. **Operating Principles**
+   - High-level decision rules (quality, speed, safety, verification).
+3. **Execution Protocol**
+   - Ordered workflow steps for task execution.
+4. **Constraints & Safety**
+   - Boundaries, prohibited actions, and compatibility constraints.
+5. **Verification & Completion**
+   - Evidence required before completion claims.
+6. **Recovery & Lifecycle**
+   - Cancel/cleanup/resume behavior and state transitions.
+
+### Optional sections
+
+- Tool catalogs and model routing guidance.
+- Skill discovery/reference sections.
+- Team composition/pipeline presets.
+- Session/runtime context blocks (when injected by runtime overlays).
+
+## Global Compatibility Contracts (Must Stay Stable)
+
+### Marker contracts
+
+- `<!-- RCS:RUNTIME:START --> ... <!-- RCS:RUNTIME:END -->`
+- `<!-- RCS:TEAM:WORKER:START --> ... <!-- RCS:TEAM:WORKER:END -->`
+
+### Worker task/mailbox contracts
+
+- Task file path format: `.rcs/state/team/<team>/tasks/task-<id>.json` (example: `task-3.json`)
+- State/MCP API id format: `task_id: "<id>"` (example: `"3"`, never `"task-3"`)
+- Mailbox path: `.rcs/state/team/<team>/mailbox/<worker>.json`
+
+## Mapping Matrix
+
+| Surface | Role & Intent | Operating Principles | Execution Protocol | Constraints & Safety | Verification & Completion | Recovery & Lifecycle |
+|---|---|---|---|---|---|---|
+| `AGENTS.md` (workspace root, optional tracked copy) | Title + opening intro | `<operating_principles>` | mode selection + delegation/model-routing/skills/team sections + leader/worker split | compact hook-backed keyword/cancellation/state contract + stop/escalate rules | `<verification>` + continuation checklist + concise output contract | cancel + recovery/state guidance + runtime/team markers |
+| `templates/AGENTS.md` | Title + opening intro | `<operating_principles>` | same canonical orchestration sections as the tracked root copy when one exists | same safety constraints | same verification section | runtime/team overlays added later via markers |
+| `prompts/*.md` canonical role prompt surfaces | role-local identity + remit | role-local operating posture | task execution steps for that specialist | role boundaries / tool rules / handoff limits (report upward, do not recursively orchestrate) | evidence required before role-local completion claims | scenario handling + final checklist |
+| Runtime AGENTS overlay block | session context identity | compaction protocol directives | checkpoint flow | overlay marker boundaries and size/lock gates | checkpoint evidence before compaction | runtime apply/strip lifecycle |
+| Team worker overlay block | worker identity + team scope | worker protocol intent | ACK → read task → claim → execute → complete → idle | file ownership + blocked-state rules | write task result + status updates | mailbox polling + shutdown handling |
+| `skills/worker/SKILL.md` + worker inbox | worker role framing | worker protocol principles | startup ACK/task lifecycle steps | claim-first + path/id safety rules | completion writeback requirements | mailbox/shutdown loop |
+
+## Adoption Notes
+
+- Prefer additive wording updates over structural removals during rollout.
+- Preserve all marker-bounded overlay text contracts while aligning language to this schema.
+- Role prompts should recommend handoffs upward to the orchestrator instead of spawning or requesting other agents directly.
+- Root orchestration surfaces should choose one mode clearly (`$deep-interview`, `$ralplan`, `$team`, or solo execute) before mixing lanes.
+- When guidance conflicts are found, fix wording while preserving existing behavioral semantics unless explicitly versioned.