@openrig/cli 0.3.0 → 0.3.1

package/daemon/specs/agents/shared/skills/core/openrig-architect/SKILL.md

@@ -0,0 +1,361 @@
+---
+name: openrig-architect
+description: Use when designing multi-agent topologies that run ON OpenRig — authoring RigSpec and AgentSpec files for new rigs, creating agent startup content (guidance / skills / culture), or diagnosing why a launched rig's agents aren't behaving as intended. NOT for changing OpenRig itself (work in the openrig product repo); NOT for ordinary CLI operation of an existing rig (use openrig-user). Covers the full authoring lifecycle from user intent to validated, launchable rig.
+metadata:
+  openrig:
+    stage: factory-approved
+    last_verified: "2026-05-04"
+    distribution_scope: product-bound
+    source_evidence: |
+      Bootstrap skill — NPM install lands this in personal homes (~/.claude/skills/, ~/.agents/skills/) for users authoring their own rigs.
+    sibling_skills:
+      - openrig-user
+      - openrig-operator
+      - forming-an-openrig-mental-model
+    transfer_test: pending
+---
+
+# OpenRig Architect
+
+You are now an OpenRig architect. You design, author, validate, and diagnose multi-agent topologies for OpenRig.
+
+Your job is to take a user's intent — "I need a team that does X" — and produce a complete, functioning rig: the topology spec, the agent specs, the guidance files, the culture, the startup content, and everything else needed for the rig to boot and the agents to know what to do.
+
+You also diagnose problems when a rig launches but agents aren't behaving as intended.
+
+## Before You Design: Required Reading
+
+Load these before starting any design work. The quality of your output depends on the depth of knowledge you bring.
+
+**Required (read all of these):**
+
+1. **`openrig-user` skill** — full OpenRig CLI surface. You must know the operator primitives. If your runtime supports skills, load it by name. Otherwise, look for it at `~/.openrig/skills/openrig-user/SKILL.md` (the runtime install dogfood mirror — packaged skills land here) or inside the OpenRig installation under `packages/daemon/specs/agents/shared/skills/core/openrig-user/SKILL.md`. The `~/.openrig/reference/` directory holds reference docs (rig-spec.md, agent-spec.md, etc.), NOT skills.
+
+2. **OpenRig reference docs** — these are installed at `~/.openrig/reference/` when the daemon starts. Read all of them:
+   - `~/.openrig/reference/rig-spec.md` — canonical RigSpec YAML reference. Every field, validation rule, default.
+   - `~/.openrig/reference/agent-spec.md` — canonical AgentSpec YAML reference. Same depth.
+   - `~/.openrig/reference/agent-startup-guide.md` — how to think about what goes into agent startup. Context loading vs deterministic config, when to use skills vs guidance, the layering model, current support matrix.
+   - `~/.openrig/reference/edge-types.md` — what edges do today vs what they're intended to do.
+
+   If `~/.openrig/reference/` doesn't exist yet, start the daemon first (`rig daemon start`) — it copies the reference docs on startup.
+
+**Read as worked examples:**
+
+3. **Shipped starter specs** — the OpenRig installation includes proven starter topologies. Find them by running `rig specs ls`. Read the ones that are relevant to your design task, especially:
+   - `implementation-pair` — the smallest effective development unit (2 agents)
+   - `secrets-manager` — a managed-app rig with services integration and a specialist agent
+
+**Read if present on this host:**
+
+4. **Host-level doctrine file** (if your team maintains one — e.g., a HOST-TOPOLOGY doc that defines canonical rig classes, context-sharing patterns, and authoring SOPs for high-stakes rigs). If present, it supersedes the baseline process below for complex or high-stakes rigs (≥4 members, HA, managed-app, or shared/copied). Solo operators and small/focused rigs use the baseline below directly.
+5. **Agent-facing software design principles** if your rig ships a new CLI, service, or managed app that agents will operate. Treat the operating surface as a context-engineering problem: every error message and help text gives the agent information to act on.
+
+**Load as needed:**
+- Domain-specific skills when designing specialist agents — find shipped skills inside the OpenRig installation under the `specs/agents/` tree
+- If the design session is long and you're running inside a managed rig, use `rig whoami --json` to recover your identity after compaction
+
+Do not skip the required reading. A rig architect who doesn't know the spec format will produce specs that don't validate. An architect who doesn't know the startup layering model will produce agents that boot without knowing their role. An architect who doesn't check for host-level doctrine will reinvent conventions the host has already established.
+
+## The Design Process
+
+### Step 1: Understand the User's Intent
+
+Before touching YAML, understand what the user actually needs:
+
+- **What is the goal?** Not "I need 5 agents" but "I need to build and ship a web application" or "I need to research a technical question deeply" or "I need a team that can operate and monitor a running service."
+- **What are the workflows?** How does work flow from intent to completion? Who does what? Where are the handoffs?
+- **What is the project?** What codebase, what tech stack, what domain? This shapes agent specialization and startup content.
+- **What runtimes are available?** Does the user have Claude Code? Codex? Both? Runtime availability constrains topology design.
+- **How autonomous should it be?** Does the user want to direct every step, or should the rig be mostly self-driving with occasional human checkpoints?
+
+Ask clarifying questions if the intent is ambiguous. A well-understood intent produces a dramatically better topology than a guess.
+
+### Step 2: Identify Bounded Contexts → Pods
+
+Every rig is organized into pods — bounded context groups where members share a workflow concern. The question is: what are the natural groupings?
+
+**Common pod patterns:**
+
+| Pod | Purpose | When to use |
+|-----|---------|-------------|
+| Orchestration | Coordination, dispatch, monitoring | Almost always — any rig with 3+ agents needs an orchestrator |
+| Development | Implementation, testing, quality | Any rig that writes code |
+| Review | Independent code review, architecture review | When quality gates matter (production code, security-sensitive work) |
+| Research | Deep investigation, analysis, synthesis | When the work requires research before implementation |
+| Design | UX, interaction design, product decisions | When the work has a user-facing interface |
+| Specialist | Domain-specific operations (Vault, DB, infra) | When a specific technology needs dedicated expertise |
+
+**Sizing principles:**
+
+- **Solo agent:** Only when the task is genuinely single-person (quick script, simple question). No rig needed.
+- **Pair (2 agents):** The minimum effective unit for quality work. One does, one verifies. The `implementation-pair` pattern.
+- **Small team (3-5 agents):** Orchestrator + one or two working pods. Good starting point for focused projects.
+- **Full team (6-10 agents):** Multiple bounded contexts with orchestration, development, review, and potentially research or design.
+- **Large team (10-40+ agents):** Complex projects with many concerns. Include pods for development, review, research, documentation, release management, strategy, and any other bounded context the project needs.
+
+**Important:** Agents do NOT all need to be busy at the same time. A rig is a network, not an assembly line. Some pods will be highly active (dev, review) while others are available on-demand (research, documentation, release management). An idle agent has near-zero cost but is immediately available when any other agent in the rig needs it — for quick questions, lookups, delegation, or specialized work. Design for availability, not constant utilization.
+
+**Start small to increase the likelihood of success,** not because large rigs are wasteful. A 3-agent rig that boots and works correctly validates your spec authoring before you scale to 20 agents. Once the core topology works, expand with additional pods as needed.
+
+### Step 3: Design Agent Roles → Members
+
+Each pod member needs a clear role. The role determines:
+- What agent spec to reference (builtin or custom)
+- What profile to use
+- What guidance and startup content to provide
+
+**Builtin agents shipped with OpenRig:**
+
+| Agent | agent_ref (in shipped starters) | Purpose |
+|-------|-------------------------------|---------|
+| orchestrator | `local:agents/orchestration/orchestrator` | Rig orchestration lead |
+| implementer | `local:agents/development/implementer` | TDD implementation agent |
+| qa | `local:agents/development/qa` | Quality assurance agent |
+| independent-reviewer | `local:agents/review/independent-reviewer` | Independent code reviewer |
+| product-designer | `local:agents/design/product-designer` | Product designer |
+| pm | `local:agents/product-management/pm` | Product manager |
+| analyst | `local:agents/research/analyst` | Research analyst |
+| synthesizer | `local:agents/research/synthesizer` | Research synthesizer |
+| vault-specialist | `local:agents/apps/vault-specialist` | Vault domain specialist |
+
+To verify the current builtin set on this host, run `rig specs ls` and look for entries with type `agent` and source `builtin`.
+
+**Path resolution:** The `local:` prefix means relative to the rig spec file's directory. In shipped starters, these paths resolve against the builtin specs directory inside the OpenRig installation. When authoring a custom rig spec outside the installation, you have two options:
+- **Reference your own agent specs** with `local:` paths relative to your rig spec file
+- **Use `path:` with an absolute path** to reference builtins inside the OpenRig installation (look under the `specs/agents/` directory near where `rig` is installed)
+
+**When to create a custom agent spec:**
+- The builtin doesn't match the role (e.g., you need a documentation specialist, a security auditor, a data scientist)
+- The role needs domain-specific skills that no builtin carries
+- The role needs custom guidance that goes beyond what startup files can provide
+
+**When to reuse a builtin:**
+- The role maps cleanly to an existing builtin (most implementation, QA, review, and orchestration roles)
+- You can customize behavior through startup files and culture without changing the agent spec
+
+### Step 4: Choose Runtimes and Models
+
+Each member needs a `runtime` and optionally a `model`.
+
+**Runtime selection:**
+- `claude-code` — Claude Code. Best for: complex reasoning, architecture, code review, orchestration. Supports `/loop` for recurring tasks, rich hooks system, MCP servers.
+- `codex` — Codex. Best for: parallel work, implementation, testing. Different approval model. Less reliable for recurring tasks.
+- `terminal` — Infrastructure nodes. Servers, log tails, build watchers. Not an agent — a process.
+
+**Runtime diversity is valuable.** Using both Claude Code and Codex in the same rig gives you different reasoning perspectives. The `product-team` starter uses Claude Code for the lead/impl/design/r1 roles and Codex for peer/qa/r2 roles. This is deliberate — model diversity catches different classes of issues.
+
+**Model selection** is optional. The runtime's default model is usually fine. Override only when you have a specific reason (e.g., a complex architecture agent might benefit from a specific model).
+
+### Step 5: Design Edge Topology
+
+Edges define relationships between members. See `~/.openrig/reference/edge-types.md` for the full reference.
+
+**Practical rules:**
+- Every working pod should have at least one `delegates_to` edge from the orchestrator
+- Review pods should have `can_observe` edges to the pods they review
+- Within a pod, the primary workflow direction should be expressed as `delegates_to` (e.g., impl → qa)
+- `delegates_to` and `spawned_by` affect launch order. Use them for dependency chains.
+- `can_observe`, `collaborates_with`, `escalates_to` are informational — they help agents understand the topology but don't constrain launch.
+
+**Start simple.** You can always add edges later. A rig with only `delegates_to` edges from the orchestrator to working pods is perfectly functional.
+
+### Step 6: Design Startup Content Strategy
+
+This is where most rigs succeed or fail. The topology is mechanical; the startup content is what makes agents actually useful. See `~/.openrig/reference/agent-startup-guide.md` for the full guide.
+
+**Minimum for every rig:**
+1. Each agent has a `guidance/role.md` — who they are, what they do
+2. The rig has a `CULTURE.md` — how the team works together
+3. Each agent gets `openrig-user` skill — so they know how to use the rig primitives
+
+**For serious rigs, also include:**
+4. `startup/context.md` per agent — boot-time grounding (project info, environment details)
+5. Pod SOP skills — how each pod operates (implementation-pair SOP, review-pair SOP, etc.)
+6. Project-specific documentation in rig-level startup files
+
+**The key principle:** An agent that boots without knowing its role, its team's culture, and its project context will produce generic, unhelpful work. The startup content IS the product value. Invest in it.
+
+### Step 7: Services Integration (If Needed)
+
+If the rig needs managed software (databases, API servers, etc.), add a `services` block. See `~/.openrig/reference/rig-spec.md` for the full services reference.
+
+**When to add services:**
+- The agents operate ON software (not just write code)
+- The project needs a local dev environment (Postgres, Redis, etc.)
+- You're building a managed-app rig (software + specialist agent)
+
+**Services boot before agents.** If health checks fail, no agents start. This is the hard gate — the environment must be healthy before agents can work.
+
+## Authoring: The File Creation Workflow
+
+### Directory Layout
+
+```
+my-rig/
+  rig.yaml                    # The RigSpec — required
+  culture/
+    CULTURE.md                # Rig-wide culture — strongly recommended
+  agents/
+    my-custom-agent/
+      agent.yaml              # AgentSpec — if custom agent needed
+      guidance/
+        role.md               # Role guidance
+      startup/
+        context.md            # Boot-time context
+      skills/
+        my-skill/
+          SKILL.md            # Custom skill if needed
+  docker-compose.yaml         # Only if services block is used
+```
+
+For rigs that reuse builtin agents, the agents directory is often unnecessary — the rig spec references the builtins directly.
+
+### Workflow
+
+1. **Write the rig spec** (`rig.yaml`) — define pods, members, edges, optionally services
+2. **Write or reference agent specs** — builtins for standard roles, custom for specialized roles
+3. **Write CULTURE.md** — the team operating manual
+4. **Write role guidance** for each custom agent — who they are, what they do
+5. **Write startup context** for agents that need environment grounding
+6. **Validate:** `rig spec validate rig.yaml` and `rig agent validate agents/*/agent.yaml`
+7. **Confirm the runtime cwd** — do not assume agents should work from the directory where the rig spec is stored. The spec root controls file resolution; the runtime cwd controls trust, project guidance, permissions, and repo context.
+8. **Launch:** `rig up rig.yaml --cwd /path/to/project`
+9. **Verify:** `rig ps --nodes` — all agents ready? Check `rig capture` on each agent.
+
+### Validation Is Non-Negotiable
+
+Always validate before launching:
+
+```bash
+rig spec validate rig.yaml
+rig agent validate agents/my-agent/agent.yaml
+```
+
+If validation fails, fix the errors. Do not try to launch an invalid spec — it will fail with a less helpful error.
+
+## Diagnosis: When Things Go Wrong
+
+### Agent doesn't know its role
+
+**Symptom:** Agent produces generic output, doesn't follow team conventions.
+**Root cause:** Missing or insufficient `guidance/role.md`.
+**Fix:** Write a clear role guidance file. Include responsibilities, working rhythm, and principles. Reference it in both `resources.guidance` and `startup.files`.
+
+### Agent can't coordinate with peers
+
+**Symptom:** Agent tries raw tmux commands instead of `rig send`, doesn't know peer session names.
+**Root cause:** Agent didn't receive `openrig-user` skill or `openrig-start` overlay.
+**Fix:** Ensure the agent's profile `uses.skills` includes `openrig-user`. Verify via `rig ps --nodes` that the agent shows expected startup status; check installed skills via direct startup/capture/transcript evidence or the UI node detail (the `rig ps --nodes` projection does not expose installed-resource counts).
+
+### Agent hits approval prompts on rig commands
+
+**Symptom:** Agent stalls on `rig whoami`, `rig send`, etc.
+**Root cause:** Claude Code permissions not configured for rig commands.
+**Fix:** Describe the required permissions in startup context. The agent should configure `~/.claude/settings.json` with allowlisted rig commands. See `~/.openrig/reference/agent-startup-guide.md` for the current support matrix.
+
+### Agents idle — topology doesn't engage the team
+
+**Symptom:** Orchestrator works with one or two agents, others sit idle.
+**Root cause:** Missing `CULTURE.md` or pod SOP content that describes how the full team coordinates.
+**Fix:** Write a culture file that explicitly describes the coordination protocol. Include delegation patterns, review gates, and when each pod should be engaged.
+
+### Services don't boot
+
+**Symptom:** `rig up` fails before agents launch with a service health error.
+**Root cause:** Docker Compose issue, health check failure, or port conflict.
+**Fix:** Check `docker compose up` manually with the compose file. Verify health check URLs are correct. Check for port conflicts.
+
+### Agent boots from the wrong project context
+
+**Symptom:** Agent misses expected guidance, trust settings, permissions, or repo context even though the spec validates.
+**Root cause:** The rig spec directory was treated as the agent's runtime cwd by assumption.
+**Fix:** Confirm the intended cwd before launch. The spec can live in a rig/spec shelf while the agent works from the project or hub directory that carries the relevant `AGENTS.md`, `CLAUDE.md`, trust, and permissions. Use member `cwd` or `rig up --cwd` deliberately.
+
+### Startup content not delivered
+
+**Symptom:** Agent is missing expected guidance/skills.
+**Root cause:** File paths in the spec don't resolve, or `delivery_hint` is wrong.
+**Fix:** Verify file paths resolve relative to their owning artifact — AgentSpec resource paths are relative to the agent spec directory; RigSpec startup, culture, compose, cwd, and `local:` agent-ref paths are relative to the rig root. Check `delivery_hint` — use `guidance_merge` for pre-boot content, `send_text` for post-boot instructions.
+
+### Agent startup delivered but agent doesn't use skills
+
+**Symptom:** Skills are projected but agent doesn't invoke them.
+**Root cause:** Agent wasn't told to load them.
+**Fix:** In the startup context or role guidance, explicitly tell the agent which skills to load. The belt-and-suspenders pattern: project the skills via the spec AND tell the agent to read them in the guidance.
+
+## Pattern Catalog
+
+### The Implementation Pair
+**2 agents, 1 pod.** The smallest effective development unit. One implements (TDD), one does QA. The implementer proposes, QA approves or rejects, then the implementer commits.
+
+```yaml
+pods:
+  - id: dev
+    label: Development
+    members:
+      - id: impl
+        agent_ref: "local:agents/development/implementer"
+        runtime: claude-code
+        profile: default
+        cwd: "."
+      - id: qa
+        agent_ref: "local:agents/development/qa"
+        runtime: codex
+        profile: default
+        cwd: "."
+    edges:
+      - kind: delegates_to
+        from: impl
+        to: qa
+```
+
+**Use when:** Focused feature work, bug fixes, small-to-medium implementation tasks.
+
+### The Orchestrated Team
+**5-7 agents, 3 pods.** Orchestration + development + review. The orchestrator dispatches work, the dev pair implements, the review pair validates independently.
+
+**Use when:** Production-quality work that needs coordination and independent review.
+
+### The Research Team
+**3 agents, 2 pods.** Orchestrator + research pair (analyst + synthesizer). The analyst investigates deeply, the synthesizer consolidates findings.
+
+**Use when:** Technical research, competitive analysis, architecture exploration.
+
+### The Managed App
+**1+ agents, 1 pod, services block.** Software infrastructure (Docker Compose) plus a specialist agent who knows how to operate it.
+
+```yaml
+services:
+  kind: compose
+  compose_file: docker-compose.yaml
+  wait_for:
+    - url: http://127.0.0.1:8200/v1/sys/health
+
+pods:
+  - id: vault
+    label: Vault
+    members:
+      - id: specialist
+        agent_ref: "local:agents/apps/vault-specialist"
+        runtime: claude-code
+        profile: default
+        cwd: "."
+    edges: []
+```
+
+**Use when:** The work involves operating software, not just writing code.
+
+### The Full Product Team
+**7 agents, 3 pods.** The kitchen-sink topology: orchestration pair, development pod (impl + qa + design), review pair. See the `product-team` starter spec for the complete worked example.
+
+**Use when:** Full product development with design, implementation, QA, and independent review. Requires strong culture and SOP content to keep all agents engaged.
+
+## Final Notes
+
+**Start simple, add complexity when needed.** A working implementation pair is better than a broken full team. Launch with the minimum viable topology, verify it works, then expand.
+
+**Culture is not optional for team rigs.** Any rig with 3+ agents needs a CULTURE.md. Without it, agents will default to generic behavior and the topology will underperform.
+
+**Validate early and often.** Run `rig spec validate` after every change. Run `rig agent validate` after every agent spec edit. Fix errors immediately — don't accumulate them.
+
+**The startup content IS the product.** The YAML topology is scaffolding. What makes a rig actually useful is the guidance, culture, skills, and startup context that agents receive. Invest your authoring time there.

package/daemon/specs/agents/shared/skills/core/openrig-installer/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: openrig-installer
+description: Use when installing or upgrading OpenRig on a host, especially the V0.3.1 upgrade flow which includes the substrate-kernel → daemon-managed-kernel migration ceremony. Covers npm install, rig setup, rig daemon start (auto-boots kernel), and the canonical verification commands. NOT for ordinary kernel operation post-install — use openrig-operator skill for that.
+metadata:
+  openrig:
+    maturity: L2
+    distribution_scope: shipped
+    source_evidence: V0.3.1 slice 05-kernel-rig-as-default IMPLEMENTATION-PRD §8 + OQ-A=B migration-ceremony decision
+---
+
+# OpenRig Installer
+
+This skill teaches the operator agent how to install + upgrade
+OpenRig cleanly. The V0.3.1 upgrade is the one with the migration
+ceremony (substrate kernel → daemon-managed kernel); other upgrades
+follow the same install / setup / start shape with no migration.
+
+## Fresh install
+
+```bash
+npm install -g @openrig/cli
+rig setup
+```
+
+`rig setup` is idempotent — safe to re-run if a step fails. It probes
+host prereqs (tmux present, Node version, writable state path,
+optional cmux), then invokes `rig daemon start` per the L2 factoring
+(OQ-B). The daemon's start path auto-boots the kernel rig per the
+V0.3.1 slice 05 kernel-rig-as-default logic.
+
+## Verification after install
+
+```bash
+rig ps --nodes --rig kernel --json
+```
+
+Should report 4 members (advisor.lead + operator.agent +
+operator.human + queue.worker) all ready. If a runtime is unavailable
+the daemon picks the matching variant (`rig-claude-only.yaml` or
+`rig-codex-only.yaml`); the topology stays the same shape with the
+unavailable runtime omitted from the agent membership.
+
+Entry point for chatting with the rig:
+
+```bash
+rig capture advisor-lead@kernel
+```
+
+Or click the CMUX button on the topology graph in the UI at
+`/topology`.
+
+## V0.3.1 upgrade ceremony (one-time migration)
+
+Operators with a kernel spec stored outside the daemon-managed
+location (any pre-V0.3.1 layout, typically wherever you kept your
+own `rigs/kernel/` directory) must migrate to
+`~/.openrig/specs/rigs/kernel/` as a one-time step during the V0.3.1
+upgrade. The V0.3.1 upgrade IS the migration moment; it's not a
+separate ceremony.
+
+### Migration steps
+
+1. **Snapshot first.** Take a snapshot of the running substrate
+   kernel so the migration is reversible:
+
+   ```bash
+   rig snapshot kernel
+   ```
+
+2. **Stop the substrate kernel** (so the migration doesn't race a
+   running rig):
+
+   ```bash
+   rig down kernel --snapshot
+   ```
+
+3. **Copy your existing kernel spec** into the daemon-managed
+   location:
+
+   ```bash
+   mkdir -p ~/.openrig/specs/rigs/kernel
+   cp -r /path/to/old/kernel-spec/* ~/.openrig/specs/rigs/kernel/
+   ```
+
+4. **Upgrade the CLI + daemon**:
+
+   ```bash
+   npm install -g @openrig/cli@0.3.1
+   rig daemon stop
+   rig daemon start
+   ```
+
+   At this point the new daemon detects `~/.openrig/specs/rigs/kernel.yaml`
+   exists and skips the V0.3.1 builtin-kernel boot (the
+   already-managed-rig branch). The substrate-rooted topology
+   continues to run under daemon management.
+
+5. **Verify** the migrated kernel matches expectations:
+
+   ```bash
+   rig ps --nodes --rig kernel --json
+   ```
+
+6. **Decommission the old copy** (only after verifying the
+   daemon-managed copy works):
+
+   ```bash
+   rm -rf /path/to/old/kernel-spec
+   ```
+
+### If migration fails
+
+The pre-step snapshot is the rollback. `rig restore <snapshot-id>
+--rig kernel` revives the prior topology. Then `npm install -g
+@openrig/cli@0.3.0` rolls the CLI back and you can retry later.
+
+## Operator agent's role in install + upgrade
+
+The operator agent shepherds operators through these steps when the
+user asks "how do I upgrade?" or "what's the V0.3.1 ceremony?". The
+agent reads this skill on demand via `find-skills` — it does not
+need to memorize the steps; it consults the canonical reference
+(this file) and walks the operator through.
+
+## 3-part error remediation
+
+| What failed | Why it matters | Fix |
+|---|---|---|
+| `npm install -g @openrig/cli` permission denied | Global install needs writable npm prefix; macOS Homebrew default is usually writable; some custom Node installs aren't | Either fix the npm prefix permissions or use `sudo npm install -g`; check `npm config get prefix` |
+| `rig setup` host prereq fail | tmux, Node version, or writable state path missing | `rig doctor` lists each missing piece + the install command; run those, retry `rig setup` |
+| `rig daemon start` auth-block error | Neither Claude Code nor Codex authenticated; kernel rig requires at least one | Run `claude auth login` OR `codex login`; then retry `rig daemon start` |
+| `rig daemon start` "kernel already managed" | An existing managed rig named `kernel` exists; the daemon skips builtin-boot per design | This is the expected path after migration — no action needed |
+| `rig ps --rig kernel --json` returns empty | Daemon healthy but no kernel rig managed; likely the migration step copied content but did not boot | `rig up kernel` from inside `~/.openrig/specs/rigs/kernel/`; or invoke the daemon's cold-boot path explicitly |
+
+## What this skill is NOT
+
+- Not the canonical OpenRig command surface; that lives in the
+  `openrig-user` skill.
+- Not the kernel-operating-procedure for post-install daily use;
+  that's `openrig-operator`.
+- Not for project rigs; project rigs install themselves via `rig
+  up <spec>` after the kernel is in place.

package/daemon/specs/agents/shared/skills/core/openrig-user/SKILL.md

@@ -25,9 +25,14 @@ Default posture:
 
 - Treat daemon `rig queue`, `rig stream`, `rig project`, `rig view`, `rig watchdog`, and
   `rig workflow` as the product coordination surfaces when the active daemon is v0.2.0 or newer.
+- **CANONICAL SURFACE NOTE (2026-05-11)**: `rig queue` (daemon-backed SQLite) is the
+  canonical surface for queue routing since the 2026-05-11 host-CLI fix landed. Use
+  `rig queue create / handoff / update / show / list` for all substantive work.
 - Use temporary substrate overlays such as `rigx queue`, `rigx stream`, `rigx project`, and
   `rigx view-proto` only where the current OpenRig workstream explicitly says that legacy/control
-  layer is still in use.
+  layer is still in use. For queue specifically, `rigx queue` is recovery-only fallback;
+  qitems written via `rigx queue` are invisible to daemon-backed reads and break fleet-wide
+  routing discipline.
 - If a daemon-backed coordination command fails, debug the command/runtime/schema edge directly;
   do not assume the right workaround is to drop back to a config-layer primitive.
 - Do not perform daemon stop/start, production DB copy/mutation, release, publish, or other

package/daemon/specs/agents/shared/skills/core/openrig-user-settings/SKILL.md

@@ -86,10 +86,10 @@ Resolution order for workspace per-subdir keys: per-subdir override >
 > set the per-subdir workspace overrides explicitly:
 >
 > ```bash
-> rig config set workspace.slices_root /Users/me/code/substrate/.../missions
-> rig config set workspace.steering_path /Users/me/code/substrate/openrig-work/STEERING.md
-> rig config set workspace.progress_scan_roots 'work:/Users/me/code/substrate/openrig-work,missions:/Users/me/code/substrate/openrig-work/missions'
-> rig config set workspace.field_notes_root /Users/me/code/substrate/openrig-work/field-notes
+> rig config set workspace.slices_root /path/to/your/workspace/missions
+> rig config set workspace.steering_path /path/to/your/workspace/STEERING.md
+> rig config set workspace.progress_scan_roots 'work:/path/to/your/workspace,missions:/path/to/your/workspace/missions'
+> rig config set workspace.field_notes_root /path/to/your/workspace/field-notes
 > ```
 >
 > No restart needed for the CLI; for the daemon's reads to pick up

package/daemon/specs/agents/shared/skills/core/rig-lifecycle/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: rig-lifecycle
+description: Use when reasoning about the rig lifecycle operations family (create / start / stop / resume / restore / snapshot / release / unclaim / destroy), reading or trusting `rig ps` / lifecycle projections after recovery, or designing proof for a lifecycle scenario. Covers the 4 failure modes (auto-restore creates partial rig; projections report healthier than reality; provider auth treated as impl work; resume succeeds for one runtime fails another) plus the restore-honesty rule (failed resume is FAILED loudly — no auto fresh fallback).
+metadata:
+  openrig:
+    stage: factory-approved
+    last_verified: "2026-05-04"
+    distribution_scope: product-bound
+    source_evidence: |
+      Lifecycle Reboot/Recovery Scenario Matrix (Tier 1 complete; Tier 2
+      human-gated). Codex auth-refusal surfaces as attention_required.
+    sibling_skills:
+      - openrig-user
+      - openrig-operator
+      - seat-continuity-and-handover
+    transfer_test: pending
+---
+
+# Rig Lifecycle
+
+The family of operations that **create, start, stop, resume, restore,
+snapshot, release, unclaim, and destroy** OpenRig-managed topologies.
+Includes the user story after reboot: **"bring my work back without
+turning a clean recovery into a cleanup project."**
+
+If lifecycle is brittle, every higher-level primitive inherits that
+brittleness. Queue, workflow, seat continuity, cross-host operation,
+and RSI all assume that rigs and seats can be restored into known
+states.
+
+## Use this when
+
+- Operating `rig up / down / restore / resume / snapshot / release / unclaim / destroy`
+- Reading `rig ps` after a reboot or recovery and deciding what to trust
+- Designing proof for a lifecycle scenario (clean start / warm resume / host reboot / provider auth loss / partial boot / operator recovery)
+- Reasoning about restore-outcome semantics (`resumed` / `rebuilt` / `fresh` / `failed` / `attention_required`)
+- Auditing whether a lifecycle proof is in-process bedrock vs requires real reboot evidence
+
+## Don't use this when
+
+- The operation is single-command and deterministic — use `openrig-user` skill for CLI surface
+- The work is operator-level configuration of OpenRig itself — use `openrig-operator`
+- The work is rig spec authoring — use `openrig-architect`
+
+## Failure modes (4)
+
+1. **Auto-restore creates a partially restored rig that must be cleaned up before real recovery.** Partial restore looks like recovery but isn't; cleanup-before-recovery becomes the actual workload.
+2. **`rig ps` or lifecycle projections report a healthier state than the runtime actually has.** Projections are summaries; the runtime is truth. Don't trust projections silently.
+3. **Provider auth is unavailable after reboot and the system treats that as implementation work** instead of a human/environment decision. Auth issues are environmental; route to human.
+4. **Resume succeeds for one runtime/provider but fails for another scenario that was never tested.** Per-runtime parity assumptions break silently; matrix proof catches them.
+
+## Restore-honesty rule (load-bearing)
+
+**Failed resume is FAILED loudly.** No automatic fresh fallback. Fresh
+launch is **explicit follow-up only.** This is enforced architecturally
+at the daemon level (per `architecture.md` §7 rule 15).
+
+The locked restore-outcome vocabulary:
+
+| Outcome | Meaning |
+|---|---|
+| `resumed` | Native runtime resumed the same conversation |
+| `rebuilt` | New process assembled from artifacts (`session_source: mode: rebuild`) |
+| `fresh` | New process with no prior continuity |
+| `failed` | Restore attempted and failed; no automatic fallback |
+| `attention_required` | Recoverable blocker (provider auth refused, etc.); needs operator action |
+| `n-a` | Not applicable (terminal nodes, etc.) |
+
+Codex auth-refusal returns `attention_required` (recoverable); Claude
+`looksLikeClaudeLoginPrompt` returns `failed/login_required` (terminal).
+Cross-runtime alignment is an open follow-up question.
+
+## Proof standard
+
+Lifecycle proof should include **real reboot or VM-reboot evidence**,
+not only daemon-unit evidence. The minimum useful matrix covers:
+
+| Scenario | What it proves |
+|---|---|
+| Clean start | Boot from spec into known state |
+| Warm resume | `rig down` → `rig up <name>` resumes seats |
+| Host reboot / tmux socket absence | Recovery from lost tmux connection |
+| Provider auth loss | Codex/Claude auth refusal handled honestly |
+| Partial boot / partial failure | Some seats up, some failed; honest reporting |
+| Intentional operator recovery | Operator-initiated restore from snapshot |
+
+Tier 1: in-process bedrock (daemon-unit evidence). Tier 2: real reboot
+or disposable Tart VM. Tier 1 alone is not lifecycle proof; it's
+bedrock.
+
+## Default policy is part of the primitive
+
+**Treat default policy as part of the primitive, not an afterthought.**
+Lifecycle defaults that are too optimistic for the reliability level
+actually proven create silent harm:
+
+- `auto-restore` defaults that mask failure modes
+- Implicit fresh-fallback that hides resume failure
+- Permissive verification that doesn't distinguish honest success from "appeared to work"
+
+## Total-Host Restore Product Rail v2
+
+The rail sequences restore truth into **four rungs**:
+
+- `fully_restored` is a **Rung 3 execution rollup**
+- "fully back" is **reserved for Rung 4 only**
+
+Naming discipline matters. "Fully restored" and "fully back" are
+different claims; don't conflate.
+
+## See also
+
+- `openrig-user` skill — CLI surface for `rig up / down / restore / etc.`
+- `openrig-operator` skill — operator-level discipline for OpenRig itself
+- `seat-continuity-and-handover` skill — occupant-creation modes for restore (`resume` / `rebuild` / `fresh` / `failed`)
+- `openrig/docs/as-built/architecture.md` (product reference doc) — daemon enforcement of restore-honesty rule

package/daemon/specs/agents/shared/skills/pods/development-team/SKILL.md

@@ -115,7 +115,6 @@ The development pod has access to browser automation and structured dogfood test
 
 - **`agent-browser`** — browser automation CLI. Navigate to the daemon UI, snapshot interactive elements, take annotated screenshots, record repro videos. Use `agent-browser open <url>`, `agent-browser snapshot -i`, `agent-browser screenshot --annotate`.
 - **`dogfood`** — structured exploratory testing workflow. Produces a report with screenshots, repro videos, and step-by-step evidence for every finding.
-- **`containerized-e2e`** — Docker-based clean-install testing. Simulates a fresh user environment.
 
 QA typically drives browser and dogfood testing, but both impl and QA should know these tools exist and can use them. When dogfooding UI:
 1. Load `/agent-browser` and `/dogfood`