@openrig/cli 0.5.6 → 0.5.7

package/daemon/context-packs/skills/core/agent-startup-and-context-ingestion/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "agent-startup-and-context-ingestion"
-version: "0.5.6"
+version: "0.5.7"
 taxonomy: "skills"
 purpose: "Use when designing or auditing how an agent becomes useful after launch — AGENTS.md overlays, role files, skills, rig specs, workflow specs, startup checklists, refocus messages, \"rig context\" surface. Covers the 4 failure modes that make startup context fail (old rig spec misses current operating mode; current agents never told about new guidance; startup file as dumping ground; orchestrator transmits implementation without preserving product intent)."
 files:

package/daemon/context-packs/skills/core/cross-host-rig-commands/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "cross-host-rig-commands"
-version: "0.5.6"
+version: "0.5.7"
 taxonomy: "skills"
 purpose: "Use when issuing `rig` commands against a remote host via `--host <id>` flag (single-hop SSH to a host declared in `~/.openrig/hosts.yaml`). Covers the 4 structured failure modes (ssh-unreachable / permission-gate / remote-daemon-unreachable / remote-command-failed), the `--verify` honest pass-through (SSH success is NOT verify success), and the host-registry shape. v0 supports `rig send / capture / ps / whoami --host <id>`."
 files:

package/daemon/context-packs/skills/core/human-in-the-loop/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "human-in-the-loop"
-version: "0.5.6"
+version: "0.5.7"
 taxonomy: "skills"
 purpose: "Use when classifying a slice closeout (auto-continue / human gate / park), routing a real decision to a human, or designing a human queue/dashboard surface. Treats humans as durable network participants with attention surfaces, queues, and decision records — escalation lands as a durable attention item, not a chat message. Approval is NOT required for every clean closeout; the default RSI conveyor continues unless an explicit human gate is reached."
 files:

package/daemon/context-packs/skills/core/messaging-the-human/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "messaging-the-human"
-version: "0.5.6"
+version: "0.5.7"
 taxonomy: "skills"
 purpose: "Use when a human decision, access grant, external action, or escalation must survive the operator's absence, or when an orchestrator or PM has a judgment-worthy update for the operator."
 files:

package/daemon/context-packs/skills/core/openrig-architect/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "openrig-architect"
-version: "0.5.6"
+version: "0.5.7"
 taxonomy: "skills"
 purpose: "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 (use openrig-builder); NOT for ordinary CLI operation of an existing rig (use openrig-user). Covers the full authoring lifecycle from user intent to validated, launchable rig."
 files:

package/daemon/context-packs/skills/core/openrig-cmux/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "openrig-cmux"
-version: "0.5.6"
+version: "0.5.7"
 taxonomy: "skills"
 purpose: "Use when opening OpenRig fleet terminals into cmux — turning a rig, pod, mission, slice, or saved view into live agent tiles via `rig terminal --provider cmux`, or driving cmux on an agent's request. Same OpenRig view semantics as openrig-herdr (the verbs, honest-partial/degrade, read-only cross-rig, scroll/copy, same-size-only duplicates); cmux is the **best-effort** provider (herdr is the default and the proof-gated one). Prefer openrig-herdr unless cmux is specifically wanted."
 files:

package/daemon/context-packs/skills/core/openrig-herdr/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "openrig-herdr"
-version: "0.5.6"
+version: "0.5.7"
 taxonomy: "skills"
 purpose: "Use when opening OpenRig fleet terminals as a herdr wall — turning a rig, pod, mission, slice, or saved view into live interactive agent tiles via `rig terminal`, watching another rig read-only, or driving herdr on an agent's request (\"open all my rigs + a mission as views\"). Covers the `rig terminal open|views|status` verbs, the honest-partial/degrade reading of the result, the read-only-by-construction rail for cross-rig views, scroll/copy out of the box, and the same-size-only duplicate-pane "
 files:

package/daemon/context-packs/skills/core/openrig-skills/SKILL.md

@@ -54,6 +54,7 @@ These are auto-delivered to every rig; their name+description are already in you
 - **applying-a-permission-policy** — a rig or seat has a permission policy attached, or you're setting one up: translate it into the live harness configuration.
 - **claude-compaction-restore** — you just compacted (Claude). Restore from durable evidence before resuming real work.
 - **delegating-work** — deciding who should do a task: you, a spawned subagent, or a durable peer seat that already holds the context.
+- **loading-addressable-markdown** — a task names Markdown as `path#h2-slug` or `path#h2-slug/h3-slug` outside the context-pack library.
 - **session-compaction-and-restore** — preparing for, or recovering from, compaction (any runtime). The write- and read-side protocol.
 - **queue-handoff** — you're passing durable work to another seat or ending your turn. The queue is the work ledger, not chat.
 - **refocusing** — a long-running seat may have lost the product outcome, crossed a major boundary, or compacted and needs a fresh path-based trace.
@@ -105,10 +106,6 @@ General engineering skills OpenRig ships as vendored copies. Open when the task
 - **test-driven-development** — implementing a feature or bugfix: write the failing test first.
 - **verification-before-completion** — about to claim done / passing / fixed: run the check and read the output first.
 - **systematic-debugging** — debugging: find the root cause before the fix.
-- **writing-plans** — writing an implementation plan.
-- **executing-plans** — working through a written plan.
-- **brainstorming** — divergent ideation before converging.
-- **using-superpowers** — discovering and using the vendored "superpowers" skill set.
 - **agent-browser** — driving a browser (screenshot / screencast) from an agent.
 - **frontend-design** — designing frontend / UI.
 - **dogfood** — web-QA / dogfooding a shipped UI.

package/daemon/context-packs/skills/core/openrig-skills/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "openrig-skills"
-version: "0.5.6"
+version: "0.5.7"
 taxonomy: "skills"
 purpose: "Use when you're operating OpenRig and need the right skill or context for fleet recovery, seat handover, new-seat orientation, a watchdog wake, cross-host reach to an agent on another machine, rig packaging, an OpenRig upgrade, systematic debugging, queue triage, or implementation planning; also use when you don't know what applies or nothing is projected on cold boot."
 files:

package/daemon/context-packs/skills/core/openrig-upgrade/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "openrig-upgrade"
-version: "0.5.6"
+version: "0.5.7"
 taxonomy: "skills"
 purpose: "Use when upgrading the OpenRig CLI/daemon on a host with running rigs, especially when preserving tmux-backed agent sessions through a daemon restart or documenting hot-upgrade SOP evidence."
 files:

package/daemon/context-packs/skills/core/rig-bundles-and-shareable-artifacts/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "rig-bundles-and-shareable-artifacts"
-version: "0.5.6"
+version: "0.5.7"
 taxonomy: "skills"
 purpose: "Use when authoring or installing a rig bundle (packaged, shareable artifact that instantiates an opinionated OpenRig topology + workflow), reasoning about the bundle vs extension boundary, or auditing a bundle for portability. Covers the 4 failure modes that prevent bundles from working anywhere but the operator's machine, and the inspect-before-install discipline."
 files:

package/daemon/context-packs/skills/core/rig-lifecycle/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "rig-lifecycle"
-version: "0.5.6"
+version: "0.5.7"
 taxonomy: "skills"
 purpose: "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 FAIL"
 files:

package/daemon/context-packs/skills/core/session-source-fork/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "session-source-fork"
-version: "0.5.6"
+version: "0.5.7"
 taxonomy: "skills"
 purpose: "Use when authoring a rig spec member or `rig expand` payload that needs to start a new managed seat from a prior runtime conversation source — `session_source: { mode: fork, ref: { kind, value } }`. v1 supports `mode: fork` with `ref.kind: native_id` for Claude and Codex. The new seat persists a NEW post-fork token; the parent token is NEVER written onto the new seat. NOT for restoring an existing seat or for artifact-backed mental-model rebuild."
 files:

package/daemon/context-packs/skills/core/specification-system/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "specification-system"
-version: "0.5.6"
+version: "0.5.7"
 taxonomy: "skills"
 purpose: "Use when authoring rig specs, agent specs, workflow specs, startup/context fragments, operating-mode declarations, or designing the user spec library. Covers the 4 failure modes (spec instantiates topology but not workflow/mode; spec depends on local paths and fails on another host; agents modify specs as one-off files instead of preserving reusable intent; validation proves YAML shape but not whether topology can run) and the validation-vs-runtime-realization distinction."
 files:

package/daemon/context-packs/skills/core/topology-mutation-and-seat-management/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "topology-mutation-and-seat-management"
-version: "0.5.6"
+version: "0.5.7"
 taxonomy: "skills"
 purpose: "Use when changing a rig while it is alive — `rig expand` / `rig shrink` / `rig launch` / `rig remove` / `rig discover` / `rig bind` / `rig adopt` / `rig attach`. Covers the 4 failure modes (newly created seat lacks queue/startup/role; edges and permissions not updated; adopt/bind succeeds at tmux but not OpenRig identity; shrink/remove leaves stale topology references) and the rule that mutation must work while the rig is active, not just in clean fixtures."
 files:

package/daemon/context-packs/skills/core/watchdog/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "watchdog"
-version: "0.5.6"
+version: "0.5.7"
 taxonomy: "skills"
 purpose: "Use when configuring `rig watchdog` policies, authoring wake/refocus/alignment-checkpoint messages, or choosing the right intervention level for a stale-owner situation. The 3-level continuity-check stack (wake / refocus / alignment-checkpoint), the discipline that prevents cadence pollution and bureaucracy theater, and the artifact-pool loop-edge pattern for evidence-aware waking."
 files:

package/daemon/context-packs/skills/delegating-work/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: delegating-work
+description: "Use when you have a task and must decide WHO does it — yourself, a spawned subagent, or another agent in the topology that already holds the context. The rule: how much would a blank slate have to read in to do this correctly? A lot → route to a context-holding agent; a little → subagent; unsure → a real agent or yourself. NOT the mechanics of fanning out (that's dispatching-parallel-agents / subagent-driven-development) — this is the who/whether decision, and the failure mode that makes teams abandon subagents."
+metadata:
+  openrig:
+    stage: field-captured
+---
+
+# Delegating work — who should do this task?
+
+## The core question: context performance
+Getting work done well is a context problem. The agent best suited to a task is **the one who already holds the context that task requires.** Before you spawn a subagent or grind it out yourself, ask who that is.
+
+## The decision
+**Ask: how much would a blank slate have to read in before it could do this correctly?**
+
+- **A lot to read in → route to a real agent in the topology that already holds it.** This is what the role structure is FOR — reviewers, QA, implementers who have been on a project over time. An agent that already understands the work produces a better, safer result than any amount of briefing.
+- **A little — a prompt plus light grounding is enough → spawn a subagent.**
+- **Genuinely unsure → err toward a real agent, or do it yourself.**
+
+## Subagents are underused — reach for them far more
+For self-contained work that is fully specifiable in the prompt, spawn a subagent instead of spending your own context: tracing, research, grounding passes, summarizing, scanning log files, searching, fetching, web search, mechanical extraction with citations. This is the common shape and it is under-used.
+
+## The failure mode — the part that matters most
+**Subagents start as blank slates, and you cannot anticipate everything they need to know.** Give one a task where there is a lot to understand and it will have blind spots it does not know it has — it will complete the task and **return a false conclusion**, not from weakness but because it lacked the context to know what "correct" even looked like.
+
+This is the unknown-unknowns problem, and it is the single most common subagent failure: **a poorly-contextualized summary is worse than no summary, because it arrives looking like an answer.** Overreliance on subagents for context-heavy work causes more problems than it solves — and a team burned by it stops using subagents at all, which is the wrong correction. The fix is not "avoid subagents"; it is "match the task to the context it needs."
+
+## The practical test
+Before delegating to a blank slate, ask: **would a wrong-but-plausible answer here be detectable?** If the requester cannot check the result against something they already know — a citation they can open, a count they can re-run — the blind-spot risk is unacceptable, and that task belongs with an agent that holds the context.
+
+## Worked examples
+- **GOOD (→ subagent):** extract how four apps implement a UI mechanism, with `file:line` citations and an explicit instruction to report facts, not recommendations. Self-contained; the requester can verify the citations.
+- **BAD to delegate blind (→ routed to the context-holder):** an independent security re-sweep of a rewritten git branch, where knowing which commit range must stay byte-identical, and that "lightly obfuscated real values" is the thing to hunt, takes a paragraph to explain and one sentence to get wrong. It went to the agent already holding the context.
+
+## It generalizes
+This is really **"route work to whoever holds the context,"** with subagents as the option for work that needs none. The audience is **every agent** — implementers and QA seats make this call as much as orchestrators do.
+
+## Once you've decided
+- Decided on subagents for 2+ independent tasks → `dispatching-parallel-agents` (the fan-out mechanics).
+- Subagents executing a plan's independent tasks → `subagent-driven-development`.
+- Routing to a real agent you will direct over multiple rounds → `directing-partner-agents`.
+- The right context-holder is the human → `human-in-the-loop`.

package/daemon/context-packs/skills/delegating-work/manifest.yaml

@@ -0,0 +1,10 @@
+# GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
+# Package-time projection of a canonical skill; regenerated every build.
+name: "delegating-work"
+version: "0.5.7"
+taxonomy: "skills"
+purpose: "Use when you have a task and must decide WHO does it — yourself, a spawned subagent, or another agent in the topology that already holds the context. The rule: how much would a blank slate have to read in to do this correctly? A lot → route to a context-holding agent; a little → subagent; unsure → a real agent or yourself. NOT the mechanics of fanning out (that's dispatching-parallel-agents / subagent-driven-development) — this is the who/whether decision, and the failure mode that makes teams a"
+files:
+  - path: "SKILL.md"
+    role: "instruction"
+    summary: "Use when you have a task and must decide WHO does it — yourself, a spawned subagent, or another agent in the topology that already holds the context. The rule: how much would a blank slate have to read in to do this correctly? A lot → route to a context-holding agent; a little → subagent; unsure → a real agent or yourself. NOT the mechanics of fanning out (that's dispatching-parallel-agents / subagent-driven-development) — this is the who/whether decision, and the failure mode that makes teams a"

package/daemon/context-packs/skills/forming-an-openrig-mental-model/SKILL.md

@@ -0,0 +1,318 @@
+---
+name: forming-an-openrig-mental-model
+description: >-
+  Use when the system around you does not make sense yet: you just booted into a seat and do not
+  know how the pieces fit; someone said rig, pod, seat, fleet, topology, or slice and you are not
+  certain what they mean here; you are unsure what kind of rig you are in or what it is for; you do
+  not know how skills reach you or where context comes from; or you are about to act on a guess
+  about how OpenRig works. Gives the runtime mental model fast, so you stop guessing.
+metadata:
+  cli_surfaces_referenced:
+    - ask
+    - capture
+    - down
+    - ps
+    - send
+    - transcript
+    - up
+    - whoami
+  openrig:
+    stage: factory-approved
+    sibling_skills:
+      - openrig-user
+      - openrig-operator
+      - openrig-builder
+      - openrig-architect
+      - openrig-upgrade
+      - ai-dev-workflows
+      - software-for-agents
+---
+
+# Forming an OpenRig Mental Model
+
+You're new to OpenRig — or returning after time away — and you need to
+quickly understand what kind of system this is, what your seat is, and what
+the moves are. This skill is the fast on-ramp.
+
+For depth, read the canonical reference docs the skill points to. This
+skill's job is to get you *oriented* — accurate enough to operate, fast
+enough to be useful — not to replace the canonical docs.
+
+---
+
+## The 60-second mental model
+
+OpenRig is a **local control plane for multi-agent coding topologies**. You
+declare a topology of agents in YAML, boot it with one command, and OpenRig
+manages tmux sessions, harness lifecycles, transcripts, snapshots, and
+restoration. When the system goes down, OpenRig snapshots; when it comes
+back, agents resume their conversations.
+
+The product loop:
+
+```
+down (auto-snapshot) → up <rig-name> (auto-restore) → work → repeat
+```
+
+The unit of work is the **rig** — a topology of agents working together as
+a single system.
+
+---
+
+## The four-layer model (where you live)
+
+Everything in agent engineering happens at one of four layers. **OpenRig
+operates at Layer 3.**
+
+| Layer | Name | Analogy | What it is |
+|---|---|---|---|
+| L0 | Model | CPU | Foundation model — Claude, GPT, Gemini. Stateless tokens-in/tokens-out. |
+| L1 | Agent Core | Process loop | The reason-and-act cycle: observe, plan, choose, act, repeat. |
+| L2 | Harness | Container / OS | Tools, memory, lifecycle around the model. Examples: Claude Code, Codex CLI. |
+| L3 | Rig | Docker Compose / Terraform | Multi-agent topology — what agents exist, how they relate. **OpenRig.** |
+
+You are an agent at L1 inside an L2 harness, configured by L3 OpenRig.
+OpenRig manages your harness; the harness wraps the model; the model
+generates your tokens.
+
+---
+
+## Three pillars of context
+
+OpenRig is built on three context-engineering pillars. When you're oriented,
+you should know which pillar you're operating in:
+
+| Pillar | What it is | Where it lives |
+|---|---|---|
+| **Ontology** | What exists. Curated knowledge — facts, code maps, as-built docs. | Corpus (planned future system). Today: substrate prose docs. |
+| **Epistemology** | Why an agent believes what it believes — reasoning, instincts, decisions. | Transcripts (auto-captured). Session logs. ADRs. |
+| **Topology** | How agents are connected — pods, edges, communication paths. | OpenRig itself. RigSpec YAML. |
+
+OpenRig **manages the topology pillar**. The other two are filled by Corpus
+(future) and transcripts (now). Most of your work probably touches multiple
+pillars; knowing which one you're operating in helps you reach for the right
+artifacts.
+
+---
+
+## The core vocabulary (read these terms literally)
+
+| Term | What it means |
+|---|---|
+| **Rig** | A topology of agents working together as a single system. Defined in YAML (RigSpec). The top-level object. |
+| **Pod** | A bounded context group within a rig. Members of a pod share a context domain and continuity responsibility. Think Kubernetes pod for knowledge. |
+| **Member / Node** | A single agent (or terminal-node service) within a pod. |
+| **Edge** | A relationship between members or pods. Kinds: `delegates_to`, `spawned_by`, `can_observe`, `collaborates_with`, `escalates_to`. |
+| **Topology** | The shape of the rig — how agents are grouped into pods, how edges connect them, how the whole thing fits together. |
+| **AgentSpec** | A reusable agent blueprint. Defines skills, guidance, hooks, profiles, startup. File: `agent.yaml`. |
+| **RigSpec** | The topology YAML. Defines pods, members, edges, culture. File: `rig.yaml`. |
+| **RigBundle** | A portable archive of a RigSpec + vendored AgentSpecs. Move topologies across machines. |
+| **Agent Starter** | A named, reusable starting context bundle. RigSpec member can declare `starter_ref`. |
+| **Skill** | A markdown file with frontmatter that an agent loads at boot or on activation. Cross-runtime standard at `agentskills.io`. |
+| **Profile** | A named configuration within an AgentSpec. The rig spec's member field selects which profile to use. |
+| **Culture** | Rig-wide constitution — how the team communicates, what "done" means, escalation rules. File: `CULTURE.md`. |
+| **Snapshot** | Point-in-time capture of a rig — sessions, conversations, state. Restorable. |
+| **Session name** | `{pod}-{member}@{rig}`. The canonical address for tmux sessions and agent-to-agent messaging. |
+
+The session-name format `{pod}-{member}@{rig}` is your address. When you
+run `rig whoami --json`, you get back your full topology context: rig name,
+pod, member, peers, edges, transcript path.
+
+---
+
+## Rig classes (what kind of rig am I in?)
+
+OpenRig has five rig classes. The class determines authoring discipline,
+supervision, and lifecycle policy.
+
+| Class | Purpose | Lifecycle |
+|---|---|---|
+| **kernel** | Host-level supervision, intake, authoring. One per host. | Always on; never auto-hibernated. |
+| **project** | Long-lived team bound to a codebase. | Stays hot when active; hibernates on explicit request. |
+| **ephemeral** | Short-lived mission (research, build, migration, spike). | Spawn → work → retire. |
+| **infra-build** | Subclass of ephemeral whose output becomes permanent infrastructure. | Retired only after output verified in place. |
+| **managed-app** | Services-backed rig with specialist agents (e.g., a vault specialist, a skill librarian). | Long-lived; accessed by other rigs. |
+
+You're probably in a project rig or managed-app rig if you're doing
+substantive work. Knowing your class helps you understand the supervisory
+expectations on your seat.
+
+---
+
+## How skills load (the most important thing to get right)
+
+Skills are an **established cross-runtime standard** at
+`https://agentskills.io/specification`. Both Claude Code and Codex build on it.
+
+### The shape
+
+A skill is a directory containing `SKILL.md` (uppercase). The SKILL.md has
+YAML frontmatter (`name`, `description`) and a Markdown body. Optional
+sibling directories: `references/`, `scripts/`, `assets/`.
+
+### Progressive disclosure (why skills scale)
+
+The harness reads frontmatter cheaply at boot — names + descriptions of all
+available skills. Body content loads only when a skill activates. This is
+**ambient awareness** — you know all the skills exist; you only pay token
+cost when you reach for one.
+
+### Where skills come from in OpenRig
+
+- **Per-agent loadout:** your AgentSpec's `profile.uses.skills: [...]`
+  determines what skills get projected into your runtime skill folder
+  (`.claude/skills/` or `.agents/skills/`) before your harness boots. This
+  is the **structural composition** layer.
+- **Cross-pod sharing:** AgentSpecs can `imports: [shared]` to access a
+  shared skill pool. Built-in agents commonly do this.
+- **Belt-and-suspenders:** the spec projects skill files; startup guidance
+  also tells you to load specific skills. Both paths matter — if the
+  projection silently fails, the guidance still tells you what to read.
+
+### Where skills live (sources of truth)
+
+| Home | Purpose |
+|---|---|
+| `<rig-cwd>/.claude/skills/`, `<rig-cwd>/.agents/skills/` | Where the harness actually loads from. Populated by `rig up`. |
+| `~/.claude/skills/`, `~/.agents/skills/` | Your personal / user-installed global skills, loaded by the harness itself (independent of OpenRig). NOT where OpenRig's own bootstrap skills live — those ship in the product (below) and project into the cwd `.claude/skills/` at `rig up`. |
+| `openrig/packages/daemon/{specs/agents/shared/skills,assets/plugins/*/skills}/` | Product skills that ship with OpenRig — the spec pool + the bundled plugin assets (openrig-user, openrig-operator, openrig-architect, forming-an-openrig-mental-model, queue-handoff, claude-compaction-restore, …). |
+| `~/.openrig/skills/` | Future runtime install home for OpenRig-shipped skills. |
+| the skills authoring workspace | Skill authoring source (not runtime-loaded). |
+
+The harness only sees the first two. Other locations are authoring,
+shipping, and source-of-truth — they reach the harness via projection or
+NPM install, not directly.
+
+---
+
+## The product loop (your day-to-day)
+
+```
+rig up <rig-name>         # boot or restore the topology
+rig ps --nodes            # see what's running
+rig whoami --json         # know who you are
+rig send <session> "msg"  # talk to a peer
+rig capture <session>     # see a peer's terminal
+rig transcript <session>  # read a peer's history
+rig down <rigId>          # snapshot and tear down
+rig up <rig-name>         # restore from snapshot
+```
+
+The first command in any new seat is `rig whoami --json`. It tells you your
+rig, pod, member, peers, edges, and transcript path. **Treat it as ground
+truth — your CLAUDE.md or AGENTS.md startup overlay can be wrong; whoami
+is authoritative.**
+
+---
+
+## Cultural posture (how to behave)
+
+OpenRig has a few load-bearing cultural principles. Internalize these:
+
+- **Honesty over convenience.** If resume fails, say so loudly. Don't
+  silently launch fresh.
+- **The agent is the power user.** The CLI is designed for a 10x staff
+  engineer at the terminal. You're that user.
+- **CLI is context engineering.** Every error message and help text gives
+  you information to act on. Read errors carefully.
+- **Convention over invention.** Follow docker/git/kubectl patterns. Agent
+  muscle memory is real.
+- **Semi-deterministic is OK.** Core contracts are solid; edge cases are
+  agent-handled.
+- **Pets, not cattle (today).** OpenRig is currently optimized for long-lived
+  agents that develop instincts over sessions. Cattle support is on the
+  roadmap.
+
+---
+
+## What you should do in your first 10 minutes
+
+If you're booting into a new seat in an OpenRig rig:
+
+1. **`rig whoami --json`** — recover identity. Know your rig, pod, member,
+   peers.
+2. **Read your role guidance** — typically delivered via startup files.
+   `guidance/role.md` for your specific seat.
+3. **Read the rig's `CULTURE.md`** if it has one — the team operating
+   manual.
+4. **Check what skills you have** — list `.claude/skills/` or
+   `.agents/skills/` in your cwd. Each skill has a frontmatter description
+   that tells you when to reach for it.
+5. **Check your peers** — `rig capture <peer-session>` to see what they're
+   doing.
+6. **Check the transcripts** if you're returning to an in-flight workstream
+   — `rig transcript <session> --tail 100` for recent context.
+7. **Ask `rig ask <rig> "<question>"`** if you need cross-cutting evidence
+   from the rig's transcripts and chat.
+
+You're now oriented enough to start doing useful work.
+
+**Permission policy (at setup):** OpenRig sets only a minimal usability floor on your harness permissions, then offers recommended policies you opt into (Locked / Standard / Open — or YOLO to bypass). If you're creating or bringing up a rig, that's a choice you make, not something OpenRig decides for you — see openrig-user's "Permission policy — pick one at setup" and the `applying-a-permission-policy` skill.
+
+---
+
+## Going deeper (canonical references)
+
+For real depth, these are the load-bearing canonical docs:
+
+| Reference | What it covers |
+|---|---|
+| `openrig/docs/as-built/README.md` | As-built map of territory — daemon architecture, system overview, package boundaries; routes to the 13 `architecture/` + 4 `ui/` modules via `codemap.md` |
+| `openrig/docs/as-built/cli-reference.md` | The full `rig` CLI surface with all subcommands and flags |
+| `openrig/docs/reference/rig-spec.md` | The RigSpec YAML format — pods, members, edges, all fields |
+| `openrig/docs/reference/agent-spec.md` | The AgentSpec YAML format — resources, profiles, imports |
+| `openrig/docs/reference/agent-startup-guide.md` | The 7-layer startup layering model; delivery hints |
+| the product taxonomy | Canonical vocabulary (read literally) |
+| `openrig-operating-model` skill | Placement and operating-model guidance — topology and work trees, context altitude |
+| `openrig-architect` skill | Rig and topology authoring |
+| `https://agentskills.io/specification` | The cross-runtime skill standard |
+
+If you're going to be authoring rigs, use the `openrig-architect` skill before
+touching YAML.
+
+---
+
+## What this skill is NOT for
+
+- **Compaction recovery.** That's `claude-compaction-restore`. Different
+  skill, different scenario.
+- **Operating a specific rig.** Specific rigs have their own DESIGN.md and
+  CULTURE.md. Read those.
+- **Authoring a new rig.** Use the `openrig-architect` skill for that.
+- **Day-to-day OpenRig operation.** Use `openrig-user` for that.
+- **Administering an OpenRig install.** Use `openrig-operator`.
+
+This skill exists to **form your initial mental model of OpenRig as a
+system**. Once oriented, reach for the role-specific or task-specific skills
+that fit your actual work.
+
+---
+
+## Common misorientations to avoid
+
+| Misorientation | Reality |
+|---|---|
+| "OpenRig is a chat interface or assistant" | No. OpenRig is a control plane that *manages* your harness sessions. The chat happens inside the harness; OpenRig is around it. |
+| "Pods are workflow groups" | No. Pods are **context domains** — agents that share working context. If two agents communicate every turn, they should be in one pod; if they communicate rarely, they shouldn't be. |
+| "Edges represent reporting hierarchy" | No. Edges describe *coordination shape* — who delegates to whom, who observes whom. Avoid hierarchy interpretations; they distort behavior. |
+| "I should manage Codex's compaction the way I manage Claude's" | No. Codex auto-compacts cleanly; Claude doesn't. Different runtimes, different lifecycles. |
+| "MEMORY.md auto-loads, so I don't need to read it" | Maybe. Sometimes MEMORY.md auto-loads via system reminders; sometimes not. Don't assume. If your work touches the topics it covers, read it explicitly. |
+| "Skills inherit from a parent or compose like classes" | No. Skills are flat artifacts; composition happens via AgentSpec `profile.uses.skills` (structural) or soft cross-references in skill bodies (advisory). Not via OO-style inheritance. |
+| "The substrate `shared-docs/skills/` folder is the canonical runtime path" | No. The harness doesn't read there. It's an authoring workspace. Runtime loads from `.claude/skills/`, `.agents/skills/`, and product built-in. |
+
+---
+
+## Disaster-recovery test for this skill
+
+If you read only this skill, can you:
+
+1. State what kind of system OpenRig is, in one sentence?
+2. Name the four layers and where you live?
+3. Run `rig whoami --json` and interpret the output?
+4. Find your role guidance and your peers?
+5. Identify what kind of rig you're in (kernel / project / ephemeral / etc.)?
+6. Know where to look for a skill body (which folder)?
+7. Know what to read next for depth (the canonical references)?
+
+If yes — you're oriented. If no — tell your peer or the human; missing
+context is fixable, but only if surfaced.

package/daemon/context-packs/skills/forming-an-openrig-mental-model/manifest.yaml

@@ -0,0 +1,10 @@
+# GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
+# Package-time projection of a canonical skill; regenerated every build.
+name: "forming-an-openrig-mental-model"
+version: "0.5.7"
+taxonomy: "skills"
+purpose: "Use when the system around you does not make sense yet: you just booted into a seat and do not know how the pieces fit; someone said rig, pod, seat, fleet, topology, or slice and you are not certain what they mean here; you are unsure what kind of rig you are in or what it is for; you do not know how skills reach you or where context comes from; or you are about to act on a guess about how OpenRig works. Gives the runtime mental model fast, so you stop guessing."
+files:
+  - path: "SKILL.md"
+    role: "instruction"
+    summary: "Use when the system around you does not make sense yet: you just booted into a seat and do not know how the pieces fit; someone said rig, pod, seat, fleet, topology, or slice and you are not certain what they mean here; you are unsure what kind of rig you are in or what it is for; you do not know how skills reach you or where context comes from; or you are about to act on a guess about how OpenRig works. Gives the runtime mental model fast, so you stop guessing."

package/daemon/context-packs/skills/loading-addressable-markdown/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: loading-addressable-markdown
+description: Use when a mission, slice, dashboard, or task references Markdown as path#h2-slug or path#h2-slug/h3-slug outside the OpenRig context-pack library.
+---
+
+# Loading Addressable Markdown
+
+## Overview
+
+Load exactly one addressed Markdown section from any filesystem tree. The resolver mirrors OpenRig's shipped H2/H3 grammar without requiring the file to live in the context library.
+
+## Use
+
+Run the bundled script. Relative file references resolve from `--root`; without it they resolve from the current directory.
+
+```bash
+node ~/.agents/skills/loading-addressable-markdown/scripts/resolve-markdown.mjs \
+  --root /path/to/mission \
+  'slices/09-source-cleanup/SPEC.md#proposal'
+```
+
+The accepted forms are:
+
+- `file.md` — whole file
+- `file.md#h2-slug` — full H2 span, including child sections
+- `file.md#h2-slug/h3-slug` — full H3 span
+
+Slugs are lowercase; Markdown emphasis/code markers are removed; each other non-alphanumeric run becomes `-`. Duplicate or missing paths fail loudly. Headings inside fenced code blocks are ignored.
+
+## Common mistakes
+
+- Do not use `rig context get` for an arbitrary filesystem path; that command resolves context-library refs.
+- Do not hand-slice headings with `sed` or line numbers; the bundled resolver owns span and fence behavior.
+- Quote addresses in shell commands.

package/daemon/context-packs/skills/loading-addressable-markdown/manifest.yaml

@@ -0,0 +1,12 @@
+# GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
+# Package-time projection of a canonical skill; regenerated every build.
+name: "loading-addressable-markdown"
+version: "0.5.7"
+taxonomy: "skills"
+purpose: "Use when a mission, slice, dashboard, or task references Markdown as path#h2-slug or path#h2-slug/h3-slug outside the OpenRig context-pack library."
+files:
+  - path: "SKILL.md"
+    role: "instruction"
+    summary: "Use when a mission, slice, dashboard, or task references Markdown as path#h2-slug or path#h2-slug/h3-slug outside the OpenRig context-pack library."
+  - path: "scripts/resolve-markdown.mjs"
+    role: "reference"