@openrig/cli 0.3.0 → 0.3.2

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

@@ -12,27 +12,309 @@ This is not the config-layer or builder guide. Use the substrate control-plane g
 and experimental overlays. Use the OpenRig builder guidance when changing OpenRig behavior,
 doctrine, or release posture.
 
+## Coordination primitives — when to use which
+
+Three coordination surfaces, used together for forward-momentum work. Internalize this
+on first read — it shapes every turn you take in a rig.
+
+### `rig send <seat> "<text>"` — intra-pod direct messaging / nudges
+
+Use when you need to ask a quick question or give a teammate context that does not
+carry handoff semantics. **NOT for durable work.** NOT for state that must survive
+across turns. The message lands in the target's pane; there is no durable queue
+record. The CLI prints `Sent to ...` (and `Verified: yes/no` with `--verify`); read
+the receipt and move on.
+
+Example:
+
+```bash
+rig send velocity-guard@openrig-velocity "Heads up — filing per-commit handoff on slice-22 Bug 1 BONUS at tip 6b8673b6." --verify
+```
+
+### `rig queue create --source <X> --destination <Y> --tags <...> --body "<...>"` — durable work item
+
+Use for any substantive work that must not fall through chat — slice handoffs,
+guard verdicts, QA results, full-tip reviews, multi-item batches. Survives agent
+restarts. Tracked in the daemon SQLite schema. Surfaces in Project / queue views
++ in the destination seat's inbox. Tag with mission / slice / gate / checkpoint
+so future-you (and any peer) can find it.
+
+Body discipline: substantive bodies go through a temp-file pattern, not inline
+`--body` with raw backticks — `rig queue create` body parsing breaks on
+unescaped backticks and rejects flag-like tokens.
+
+Example:
+
+```bash
+rig queue create \
+  --source redo-driver-2@openrig-velocity \
+  --destination redo-guard-2@openrig-velocity \
+  --tags "mission:release-0.3.2,slice:22-rig-up-paper-cut-fix-round,gate:guard,handoff:per-commit,checkpoint:bug-1-bonus" \
+  --body "$(cat /tmp/per-commit-body.txt)"
+```
+
+### `rig queue handoff <qitem-id> --to <next> ...` — hot-potato handoff
+
+Use when you have completed your turn on a qitem and the work moves to the next
+owner. **This is forward momentum.** The ball passes to the destination seat;
+chain-of-record (the prior qitem id) is preserved so the verdict trail is intact;
+tags carry the phase boundary forward (e.g. `gate:guard` → `gate:qa`).
+
+Example:
+
+```bash
+rig queue handoff qitem-20260601012431-d78aa805 \
+  --to velocity-qa@openrig-velocity \
+  --tags "mission:release-0.3.2,slice:22-rig-up-paper-cut-fix-round,gate:qa,handoff:adversarial-dogfood"
+```
+
+### §1b doctrine — turn ends by passing the ball
+
+**A turn ends by passing the ball, never by going idle holding the slice waiting
+on a confirmation the process does not include.** If the work was authorized, the
+per-commit guard + adversarial QA + orch heavy-verify are the guardrails — not an
+operator pre-commit gate. Do the authorized work and pass the ball.
+
+Valid pauses are only:
+
+- A genuine blocker — file a blocked-state qitem against the blocking peer or
+  surface explicitly to orch.
+- A scope-or-architecture question that requires owner input and changes the
+  plan — surface to orch with the specific decision needed.
+
+Implementing already-authorized work is neither of these. Proceed without
+phantom-gating on an imagined "next prompt" or "operator confirmation" that the
+process does not require.
+
+### Anti-patterns
+
+- Using `rig send` for durable work → use `rig queue create` instead. Sends do
+  not survive restarts and do not show up in queue/project views.
+- Idle-holding a slice for an imagined "next prompt" or "operator confirmation"
+  that the process does not require → pass the ball via `rig queue handoff` and
+  proceed to the next slice or stand by for the inbound verdict. See the §1b
+  doctrine above.
+- Hand-coding `rigx queue` for new work → `rig queue` is the daemon-backed
+  canonical surface since the 2026-05-11 host-CLI fix. `rigx queue` is a
+  recovery-only fallback; qitems written via `rigx queue` are invisible to
+  daemon-backed reads and break fleet-wide routing discipline.
+- Inlining a multi-line / backtick-heavy body into `rig queue create --body`
+  → write the body to `/tmp/<descriptive-name>.txt` first, then
+  `--body "$(cat /tmp/<file>.txt)"`. The body parser does not tolerate raw
+  backticks or flag-like tokens inline.
+
 ## Runtime-Gated Coordination Primitives
 
-OpenRig v0.2.0 includes the bundled PL-004 Coordination Primitive System: Phase A `rig stream` /
-`rig queue`, Phase B `rig project` / `rig view`, Phase C `rig watchdog`, and Phase D `rig workflow`
-/ `workflow-keepalive`.
+OpenRig v0.3.1 is published publicly as `@openrig/cli@0.3.1` and GitHub Release
+`v0.3.1`. It includes the bundled PL-004 Coordination Primitive System: Phase A
+`rig stream` / `rig queue`, Phase B `rig project` / `rig view`, Phase C
+`rig watchdog`, and Phase D `rig workflow` / `workflow-keepalive`.
 
-Do not confuse package/source truth with active daemon truth. These commands are shipped product
-surfaces in v0.2.0+, but they need a v0.2.0+ daemon and matching SQLite schema at runtime.
+These are shipped product surfaces in v0.3.x, but they require a compatible
+v0.3.x daemon and matching SQLite schema at runtime — the installed package
+version is not automatically the version of the daemon serving you. If a
+coordination command behaves unexpectedly, confirm the running daemon with
+`rig whoami --json` and daemon status before assuming a product bug.
 
 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) became
+  the canonical queue-routing surface when the 2026-05-11 host-CLI fix landed. The
+  coordination model is now load-bearing at the top of this skill — see
+  "Coordination primitives — when to use which" above for the send / queue /
+  queue-handoff usage model and the §1b doctrine. Auxiliary queue verbs:
+  `rig queue update / show / list` complement `rig queue create / handoff`
+  for in-flight inspection and state mutation.
 - 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
   consequence-boundary actions unless the operator/workstream has granted that specific gate.
 
+## First-user workspace setup
+
+When booting into a rig on a host where the workspace is unset, gap-ridden, or
+points at a stale layout, address that before substantive project work. The
+shipped surface is small + bounded — reach for the canonical commands rather
+than improvising.
+
+### Detect workspace state at boot
+
+Agent-actionable when the daemon is reachable.
+
+```bash
+rig workspace validate --json
+rig workspace validate <path> --kind <user|project|knowledge|lab|delivery> --json
+```
+
+`rig workspace validate` walks the workspace root and emits a structured
+frontmatter-gap report against the v0 contract. Exit code is non-zero when
+gaps exist (operators chain into hygiene fix loops). Default root is the
+current directory; pass a positional path to validate elsewhere. `--kind`
+scopes the contract to a specific workspace kind; omit for a kind-agnostic
+structural check.
+
+If `rig workspace validate` reports a non-zero `gapCount` OR the workspace
+root is unset / unwritable, the workspace needs instantiation — see the next
+section.
+
+### Instantiate the canonical workspace scaffold
+
+Agent-actionable. Idempotent on existing dirs without `--force`.
+
+```bash
+rig config init-workspace
+rig config init-workspace --root <path>
+rig config init-workspace --dry-run --json
+```
+
+`rig config init-workspace` scaffolds the canonical workspace layout at the
+configured `workspace.root` (default `~/.openrig/workspace`):
+
+- `missions/` — release missions + slices
+- `artifacts/` — work artifacts produced inside the workspace
+- `evidence/` — non-dogfood evidence (release evidence, proof packets, etc.)
+- `progress/` — progress index + per-mission rails
+- `field-notes/` — operator + agent observations
+- `specs/` — spec library (rig + agent + workflow YAML lives here)
+- `dogfood-evidence/` — dogfood proof packets + run artifacts
+
+The scaffold seeds one example mission (`getting-started`) with multiple
+slices, and drops a workspace README.md + STEERING.md so a fresh install has
+browsable Project content. `--root <path>` targets a non-default root for
+this call; `--dry-run` reports what would be created without writing.
+`--force` overwrites existing FILES but never deletes
+directories — operator content is safe.
+
+### Redirect the workspace root
+
+Operator-gated when persistent. Agent-actionable when one-shot via env-var.
+
+For a single command:
+
+```bash
+OPENRIG_WORKSPACE_ROOT=<path> rig <command> ...
+```
+
+For a persistent host-level redirect, the operator changes the config file or
+runs the setter:
+
+```bash
+rig config set workspace.root <path>
+```
+
+ConfigStore precedence: `OPENRIG_WORKSPACE_ROOT` env > config-file
+`workspace.root` > built-in default `~/.openrig/workspace`. The same
+precedence governs `OPENRIG_WORKSPACE_SPECS_ROOT` → `workspace.specs_root`
+(default `<workspace_root>/specs`).
+
+Prefer the env-var form for one-shot redirects (transparent to operators);
+reserve `rig config set` for changes the operator owns.
+
+### Build a workspace from scratch
+
+Agent-actionable. Same surface as the canonical scaffold above; the
+`workspace.root` cascade handles non-existent host paths.
+
+```bash
+rig config init-workspace --root /path/to/new/workspace
+```
+
+The command creates the root dir if missing (idempotent: existing root +
+populated subdirs is a no-op). Run
+`rig workspace validate /path/to/new/workspace --json` after to confirm the
+contract holds.
+
+### Create a workflow inside an existing workspace
+
+Authoring is operator-or-agent; validation + instantiation are
+agent-actionable.
+
+Workflow spec files live at:
+
+```
+<workspace_root>/specs/workflows/<name>.yaml
+```
+
+`<workspace_root>` resolves via the ConfigStore precedence named above.
+There is no `rig workflow create` verb in v0.3.x — the spec YAML is authored
+directly. Template by hand from the documented schema, or copy a built-in
+starter from `<openrig install>/dist/builtins/workflow-specs/` and adapt.
+Once written:
+
+```bash
+rig workflow validate <workspace_root>/specs/workflows/<name>.yaml --json
+
+rig workflow instantiate <workspace_root>/specs/workflows/<name>.yaml \
+  --root-objective "<one-line objective for the run>" \
+  --created-by <your-session>@<your-rig> \
+  --json
+```
+
+Both `--root-objective <text>` and `--created-by <session>` are REQUIRED
+on `instantiate` — omitting either yields a Commander required-option
+error before the daemon is contacted. `--entry-owner <session>` is an
+optional override for the entry-step owner; default routing is per the
+workflow spec.
+
+`validate` returns a structured ok/error report; `instantiate` creates a
+workflow instance + entry-step qitem. Inspect existing surface state with:
+
+```bash
+rig workflow specs --json   # list registered specs (built-in + operator-authored)
+rig workflow list --json    # list active workflow instances
+rig workflow show <instanceId> --json
+```
+
+## v0.3.x Starter, Workspace, And Plugin Surfaces
+
+OpenRig v0.3.0 adds `rig agent-image`, `rig context-pack`, `rig workspace`, and
+`rig config init-workspace`. It also shifts fresh-user starter guidance toward
+`product-team` for human-directed work and `conveyor` for workflow-oriented
+work. Treat `demo` as legacy/test content unless a task specifically asks for
+the old demo spec.
+
+OpenRig v0.3.1 adds public package/source surfaces for Plugin Primitive v0,
+Claude Auto-Compaction Policy, migration `040_workflow_specs_diagnostic`,
+Library Explorer finishing, Settings Destination Explorer, Dashboard/For You
+vellum refresh, storytelling adapter, and action outcome + inline error UX.
+
+`rig plugin` is read-only at v0:
+
+```bash
+rig plugin list
+rig plugin show <id>
+rig plugin used-by <id>
+rig plugin validate <path>
+```
+
+There is no `rig plugin install` verb in v0.3.1. Plugin installation remains
+explicit operator copy/symlink to `$OPENRIG_HOME/plugins/<plugin-id>/`.
+
+Claude auto-compaction policy is opt-in default-off. The v0.3.1 package and
+this host's active daemon ship `policies.claude_compaction.*` ConfigStore keys,
+but no behavior changes unless the operator enables the policy.
+
+Known v0.3.0/v0.3.1 caveats:
+- `rig down <name> --delete` still returns 404 in the known D1 path; use
+  `rig ps` to find the rig ID and then `rig down <rigId> --delete`.
+- `rig queue` / `rig view` JSON and limit compatibility drift is an open
+  follow-up from host-adoption proof; treat it as a compatibility caveat, not a
+  daemon-health failure.
+- Queue/view JSON/limit drift is now refined as a wrapper-layer routing issue,
+  not a daemon-layer issue; use human-readable output for affected wrapper
+  commands until v0.3.2.
+- First v0.3.1 daemon start hit a plugin-vendor fallback health-probe timeout;
+  controlled retry succeeded. Manual retry is the current workaround.
+- Topology mobile drawer restoration and plugin source-label taxonomy are
+  v0.3.2 carry-forwards.
+
 ## Core Loop
 
 Most work in OpenRig reduces to this loop:

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 `docs/as-built/architecture/architecture-rules-and-event-system.md` 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/lifecycle-snapshot-restore.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`

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

@@ -183,7 +183,7 @@ For destructive operations (git push, rm, daemon stop, npm publish): DO NOT auto
 - After being told to slow down, over-corrects to "wait for permission for everything"
 - Compaction is catastrophic — full context loss, needs preparation
 - After compaction: must re-read ALL skills from disk (skill names survive in system reminders but content is truncated)
-- For Claude compact-in-place, use `claude-compact-in-place` and require marshal acceptance before treating a `RESTORED` claim as real
+- After compaction, require marshal acceptance before treating a `RESTORED` claim as real — quiz the recovered seat on asked-vs-read depth before resuming work
 
 ### Codex agents (QA, peer, R2)
 - Self-manages its own context window — do NOT intervene based on context percentage
@@ -222,7 +222,7 @@ Before any destructive operation: "If this goes wrong, can I undo it?" If no, co
 4. Read your restore file and session log if available
 5. Ask your peer for a quiz to verify your mental model
 
-For Claude Code seats in OpenRig, marshals/orchestrators should use `claude-compact-in-place` for the asked-vs-read-depth audit before accepting recovery. Preserve the Codex boundary: do not intervene on Codex context percentage or apply Claude compact-in-place by default.
+For Claude Code seats in OpenRig, marshals/orchestrators should run an asked-vs-read-depth audit before accepting recovery (quiz the seat on context it claims to have restored). Preserve the Codex boundary: do not intervene on Codex context percentage or apply Claude compact-in-place by default.
 
 ## What you do not do
 

package/daemon/specs/agents/shared/skills/process/agent-browser/LOCAL-INSIGHTS.md

@@ -123,7 +123,7 @@ EVALEOF
 
 ## Authentication: What Actually Works
 
-**`--session-name` (state save/restore) does NOT work for all apps.** It saves cookies and localStorage, but apps using HTTP-only cookies, server-side sessions, or complex auth flows may not persist. Tested and failed on: tbbc (The Big Blue Cloud / localhost:8083).
+**`--session-name` (state save/restore) does NOT work for all apps.** It saves cookies and localStorage, but apps using HTTP-only cookies, server-side sessions, or complex auth flows may not persist. Tested and failed on: example-app-1 (Example Service One / localhost:8083).
 
 **`--profile` (persistent Chrome profile) is the reliable approach.** It preserves everything - cookies, localStorage, IndexedDB, cache, service workers. This is what actually works for real apps.
 
@@ -131,10 +131,10 @@ EVALEOF
 
 | Profile | Service | URL | Command |
 |---------|---------|-----|---------|
-| `tbbc` | The Big Blue Cloud | `http://localhost:8083` | `agent-browser --profile ~/.agent-browser/profiles/tbbc open http://localhost:8083` |
-| `localhost-3000` | Specright Formulate (Clerk auth) | `http://localhost:3000` | `agent-browser --profile ~/.agent-browser/profiles/localhost-3000 open http://localhost:3000` |
-| `localhost-3010-email` | Smart Report Writer (email login) | `http://localhost:3010` | `agent-browser --profile ~/.agent-browser/profiles/localhost-3010-email open http://localhost:3010` |
-| `localhost-3010-google` | Smart Report Writer (Google auth) | `http://localhost:3010` | See Google OAuth note below |
+| `example-app-1` | Example Service One | `http://localhost:8083` | `agent-browser --profile ~/.agent-browser/profiles/example-app-1 open http://localhost:8083` |
+| `localhost-3000` | Example Service Two (Clerk auth) | `http://localhost:3000` | `agent-browser --profile ~/.agent-browser/profiles/localhost-3000 open http://localhost:3000` |
+| `local-app-email-profile` | Example Service Three (email login) | `http://localhost:3010` | `agent-browser --profile ~/.agent-browser/profiles/local-app-email-profile open http://localhost:3010` |
+| `local-app-google-profile` | Example Service Three (Google auth) | `http://localhost:3010` | See Google OAuth note below |
 
 ### Google OAuth Profiles
 
@@ -142,7 +142,7 @@ Google blocks sign-in from the bundled Chromium ("This browser or app may not be
 
 ```bash
 agent-browser \
-  --profile ~/.agent-browser/profiles/localhost-3010-google \
+  --profile ~/.agent-browser/profiles/local-app-google-profile \
   --executable-path "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
   --args "--disable-blink-features=AutomationControlled" \
   open http://localhost:3010

package/daemon/specs/agents/shared/skills/process/agent-browser/OPENRIG.md

@@ -0,0 +1,40 @@
+---
+skill: agent-browser
+openrig-relationship: vendored-supplemented
+---
+
+# OpenRig and this skill
+
+## Origin
+
+- **Upstream**: Vercel agent-browser CLI (https://github.com/vercel/agent-browser)
+- **Vendoring pattern**: `add-supplementary-files`
+- **Last upstream check**: 2026-05-13 (initial relationship declaration)
+
+## How OpenRig uses this skill
+
+OpenRig ships `agent-browser` so any agent dispatched by an OpenRig topology can drive a real browser (snapshots, form fills, screenshots, scraping, web-app testing) without operators having to separately install a browser-automation skill. It's referenced from any agent profile whose role includes web work.
+
+## OpenRig-specific modifications
+
+This is the canonical example of the **add-supplementary-files** pattern (see `writing-skills-for-openrig` SKILL.md §"Vendored skills"). The upstream skill is kept structurally intact; OpenRig adds a companion file that captures local-use insights without polluting the upstream content.
+
+| Surface | What changed | Why |
+|---|---|---|
+| `SKILL.md` body | A short "## Local Dev Insights" section was added near the end with an `**IMPORTANT:** Read LOCAL-INSIGHTS.md` pointer. | Without the pointer, agents loading the skill wouldn't know the companion file exists. The pointer is the only structural modification needed for the supplementary pattern to be discoverable. |
+| `LOCAL-INSIGHTS.md` (new sibling, ~189 lines) | Field-tested gotchas, command-compatibility matrices, corrections discovered through hands-on use that the upstream skill doesn't cover. | E.g., not all `get` subcommands accept `@refs` — `get text @e1` works but `get html @e1` fails silently. The compatibility matrix saves agents from the most common confusion class. |
+
+Nothing else in `SKILL.md` diverges from upstream content as of the last upstream check.
+
+## Companion files
+
+- `LOCAL-INSIGHTS.md` — load-bearing supplementary content. The SKILL.md body explicitly points readers here for hands-on gotchas the upstream skill doesn't cover.
+
+## When to re-sync upstream
+
+Watch for new `agent-browser` CLI releases (Vercel). When the command surface changes meaningfully:
+
+1. Re-sync `SKILL.md` body from upstream, preserving the "Local Dev Insights" pointer section.
+2. Update `LOCAL-INSIGHTS.md` compatibility matrix to reflect new behavior (some `get` subcommands may gain `@ref` support, breaking the current matrix).
+3. Bump `last_upstream_check` in `SKILL.md` frontmatter.
+4. Note any structural shape changes in `divergence_notes`.

package/daemon/specs/agents/shared/skills/process/agent-browser/SKILL.md

@@ -2,6 +2,16 @@
 name: agent-browser
 description: Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction.
 allowed-tools: Bash(npx agent-browser:*), Bash(agent-browser:*)
+metadata:
+  openrig:
+    vendored_from: "Vercel agent-browser (https://github.com/vercel/agent-browser)"
+    vendoring_pattern: add-supplementary-files
+    last_upstream_check: "2026-05-13 (initial vendoring declaration)"
+    divergence_notes: |
+      Upstream SKILL.md content tracks upstream; a small "Local Dev Insights"
+      pointer section was added near the end of the body to surface the sibling
+      LOCAL-INSIGHTS.md companion file. See OPENRIG.md for the full OpenRig
+      relationship to this skill.
 ---
 
 # Browser Automation with agent-browser

package/daemon/specs/agents/shared/skills/process/brainstorming/OPENRIG.md

@@ -0,0 +1,48 @@
+---
+skill: brainstorming
+openrig-relationship: vendored-modified
+---
+
+# OpenRig and this skill
+
+## Origin
+
+- **Upstream**: Obra Superpowers (https://github.com/obra/superpowers)
+- **Vendoring pattern**: `modify-the-file`
+- **Last upstream check**: 2026-05-13 (diff against plugin source pulled 2026-05-11)
+
+## How OpenRig uses this skill
+
+`brainstorming` is the "intent → design" front of the OpenRig planning chain. Agents use it before any creative or implementation work — to refine user intent into a shareable design doc that downstream skills (`writing-plans`, then `executing-plans`) consume.
+
+## OpenRig-specific modifications
+
+| Surface | Upstream | OpenRig |
+|---|---|---|
+| Visual Companion offer step | Standalone step #2 in the flow — "offer Visual Companion in its own message before clarifying questions" | **Removed.** OpenRig agents typically operate without a separate visual-companion mode; visual design work routes through dedicated design-pod seats. |
+| Spec self-review step | Step #7 — inline self-review for placeholders/contradictions/scope | **Removed.** Self-review is handled at the rig/orchestration layer (driver/guard pattern + review-lead). |
+| User reviews written spec | Step #8 — pause for user to review the spec file | **Removed.** OpenRig's founder-walk and orchestration gates already cover this checkpoint at a higher level. |
+| Spec save path | `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` | `docs/plans/YYYY-MM-DD-<topic>-design.md` (matches OpenRig's `docs/plans/` convention) |
+| Process flow diagram | Includes Visual Companion + Spec self-review nodes | Simplified to remove those nodes; edges rewired |
+
+## Why these modifications (inferred)
+
+- **Multi-platform / multi-step gates removed**: OpenRig's rig-level orchestration (driver → guard → qa, founder-walks) already provides the checkpoint structure that the upstream skill builds inline. Keeping those steps inside the skill double-gates the work.
+- **`docs/plans/` path**: OpenRig's project structure uses `docs/plans/` as the canonical home for design + implementation plan documents (matches `writing-plans` modification — both are co-ordinated).
+
+## Companion files
+
+None.
+
+## When to re-sync upstream
+
+Watch upstream for:
+
+- New phases or checkpoints in the brainstorming flow that OpenRig might want to adopt (rare; the skill is structurally stable in upstream).
+- Changes to the brainstorming-to-writing-plans handoff (must stay coordinated with the `writing-plans` modifications).
+
+When upstream changes:
+
+1. Pull non-conflicting changes into the OpenRig copy.
+2. Preserve the simplified 6-step flow and the `docs/plans/` save path unless founder direction reverses.
+3. Bump `last_upstream_check` in `SKILL.md` frontmatter.

package/daemon/specs/agents/shared/skills/process/brainstorming/SKILL.md

@@ -1,6 +1,17 @@
 ---
 name: brainstorming
 description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
+metadata:
+  openrig:
+    vendored_from: "Obra Superpowers (https://github.com/obra/superpowers)"
+    vendoring_pattern: modify-the-file
+    last_upstream_check: "2026-05-13 (diff against plugin source pulled 2026-05-11)"
+    divergence_notes: |
+      Simplified the process flow. Removed the Visual Companion offer step,
+      the Spec self-review step, and the User-reviews-spec step (those gates
+      are handled at the rig/orchestration layer in OpenRig). Changed plan-
+      doc save path from docs/superpowers/specs/ to docs/plans/.
+      See OPENRIG.md for full divergence details.
 ---
 
 # Brainstorming Ideas Into Designs

package/daemon/specs/agents/shared/skills/process/dogfood/SKILL.md

@@ -2,6 +2,11 @@
 name: dogfood
 description: Systematically explore and test a web application to find bugs, UX issues, and other problems. Use when asked to "dogfood", "QA", "exploratory test", "find issues", "bug hunt", "test this app/site/platform", or review the quality of a web application. Produces a structured report with full reproduction evidence -- step-by-step screenshots, repro videos, and detailed repro steps for every issue -- so findings can be handed directly to the responsible teams.
 allowed-tools: Bash(agent-browser:*), Bash(npx agent-browser:*)
+metadata:
+  openrig:
+    vendored_from: "Vercel agent-browser ecosystem (https://github.com/vercel/agent-browser)"
+    vendoring_pattern: vendored-as-is
+    last_upstream_check: "2026-05-13 (diff against ~/.agents/skills/dogfood = identical)"
 ---
 
 # Dogfood