@openrig/cli 0.5.10 → 0.5.12

package/daemon/context-packs/skills/orienting-to-an-inherited-seat/CHANGELOG.md

@@ -1,64 +1,20 @@
 # Changelog — orienting-to-an-inherited-seat
 
-**`SKILL.md` carries the practice; this file carries how it got there.** Rationale, superseded
-wording, and the incidents that produced a rule live here so the instruction surface stays
-instructional.
+The skill carries the current practice. This changelog retains portable change
+rationale, not local session outcomes or current runtime acceptance evidence.
 
----
+## 2026-08-13 — clarify predecessor reach-back
 
-## 2026-08-13 — "the channel does not expire" (Rule 3)
+The guidance distinguishes a retired tenure's advisory role from the availability
+of its retained session history. Retirement alone does not impose a consultation
+expiry. When a decision cannot be reconciled from artifacts, use the lineage's
+exact resume handle and check the current runtime's ability to resume it.
 
-### The incident
+The public lookup is `rig ask --help`: ordinary search returns recorded evidence;
+`--wake` intentionally runs a bounded consultation. A missing history record,
+unavailable runtime, timeout, or exhausted context can prevent an answer. Diagnose
+that specific failure before inferring that all predecessor access is closed.
 
-A successor seat concluded mid-conversation that its reach-back
-window had closed at cutover, and reasoned from that for several turns before being challenged.
-
-It was wrong. `rig ask --wake` ships in CLI 0.5.1, the predecessor's session record was intact and
-resumable, and the seat's own lineage carried a wake rule explicitly marked active from the
-retirement row onward. **One `rig ask --help` would have settled it.**
-
-### What produced the error
-
-Two artifacts asserted a bound that does not exist, and the successor inherited one side of a
-contradiction without checking:
-
-- the handover packet: *"I am a transcript after retirement, not a conversation. Ask while the
-  window is open."*
-- the operating-model README: *"Until this seat is retired, ask it directly... After that it is a
-  transcript: greppable, not conversational."*
-
-Both were written by an author who knew better — the same tenure authored the correct wake rule in
-the lineage. The charitable reading of "greppable, not conversational" is a **posture** claim (treat
-a woken tenure as testimony), which is right. It is phrased as a **capability** claim, and it was
-read as one.
-
-### Why the fix is worded positively
-
-The generalisable form: **prose that talks a capable reader out of a capability it has.** This is
-worse than a missing trigger. `PREMISE-capable-and-underinformed.md` already records that
-affordances without triggers go unused (*"you may consult your predecessor"* → zero consultations
-across a lineage). This is one turn worse — a **counter-trigger**. The successor did not fail to
-reach for the channel; it concluded the channel was absent.
-
-So Rule 3 now states the true bound positively rather than warning about the bad wording. Rule 2
-(*the packet is testimony, checked not believed*) already covers refusing a stale packet claim, and
-naming the specific bad sentence in `SKILL.md` would install the doubt it is trying to prevent.
-
-### Also added
-
-- **The real bound**, which had never been written down anywhere: the predecessor's own context
-  wall, hit *while answering* — yielding a truncated answer, an unclear error, or nothing. That is
-  one exhausted tenure, not a closed channel.
-- **Ask repeatedly, across the first working day.** Observed in the same handover: the successor's
-  only high-value question arrived after hours of work with the artifacts, when a reconciliation
-  failed. Questions formed at orientation are shallow.
-- **The live-resume tier**, which existed and was undocumented: resume a tenure into a named tmux
-  pane and message it with `rig send` for multi-turn work.
-- **`rig ask --wake` reliability caveat.** The verb is a thin wrapper over the harness resume and is
-  not yet well-exercised (mission owner, 2026-08-13). A failing wrapper must not be read as a closed
-  channel — fall back to `claude -p --resume`.
-
-### Standing
-
-Not yet re-tested. The next handover is the test: if a successor uses the channel more than once and
-without prompting, the fix worked. **Zero unprompted consultations remains the baseline to beat.**
+Treat the answer as testimony and disclose that the consulted tenure is retired.
+Ask further questions when real work exposes a missing rationale. These are
+instruction changes, not evidence that a successor read them or used the channel.

package/daemon/context-packs/skills/orienting-to-an-inherited-seat/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: "orienting-to-an-inherited-seat"
-version: "0.5.10"
+version: "0.5.12"
 taxonomy: "skills"
 purpose: "Use when you have just been primed into an EXISTING seat through a planned handover — a different agent retired and handed you the seat plus its earned context — and you need a world model of what just happened to you. Covers how a handover differs from compaction and from a fresh launch, the inherit-the-seat-not-the-identity rule, treating the handover packet as testimony you verify (and refusing stale ghost prompts, and verifying your OWN identity surfaces), why a seat is a COMPOUNDING LINEAGE"
 files:

package/daemon/context-packs/skills/pm/backlog-capture/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: "backlog-capture"
-version: "0.5.10"
+version: "0.5.12"
 taxonomy: "skills"
 purpose: "Quickly capture product ideas, feature requests, or insights from meetings and conversations. Rapid documentation with smart categorization and deduplication."
 files:

package/daemon/context-packs/skills/pm/context-builder/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: "context-builder"
-version: "0.5.10"
+version: "0.5.12"
 taxonomy: "skills"
 purpose: "Gather and distill context from meetings, competitors, regulatory sources, and internal discussions. Produces background.md for a feature and updates shared context docs when new knowledge is discovered."
 files:

package/daemon/context-packs/skills/pm/exec-summary/SKILL.md

@@ -13,7 +13,7 @@ A single `executive-summary.md` file in the feature folder. 600-800 words exclud
 
 Before writing, silently gather all context from the feature folder:
 
-1. **requirements.md** — acceptance criteria, business rules, scope, user stories
+1. **SPEC.md** — acceptance criteria, business rules, scope, user stories
 2. **background.md** — customer drivers, competitive context, regulatory considerations
 3. **validation.md** — demand evidence, status quo, desperate user, narrowest wedge
 4. **supporting/mockup-ascii.md** — visual mockups (pull 2-3 key screens)

package/daemon/context-packs/skills/pm/exec-summary/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: "exec-summary"
-version: "0.5.10"
+version: "0.5.12"
 taxonomy: "skills"
 purpose: "Generate a 1-2 page executive summary for a feature — orients sales, leadership, and engineering from a single document."
 files:

package/daemon/context-packs/skills/pm/office-hours/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: "office-hours"
-version: "0.5.10"
+version: "0.5.12"
 taxonomy: "skills"
 purpose: "YC-style product validation using six forcing questions. Pressure-tests a feature idea before it becomes a requirement — ensuring real demand, a clear wedge, and evidence behind assumptions."
 files:

package/daemon/context-packs/skills/pm/plan-review/SKILL.md

@@ -39,7 +39,7 @@ Rate these dimensions (0-10):
 Read all available docs in the feature folder:
 - **validation.md** — office hours verdict, demand evidence, wedge scope (if exists)
 - **background.md** — customer drivers, competitive context (if exists)
-- **requirements.md** — the main document to review
+- **SPEC.md** — the main document to review
 - **supporting/** — mockups, data files, visual references
 
 ### Step 2: Run All Three Reviews
@@ -50,7 +50,7 @@ Read all available docs in the feature folder:
 ## Plan Review: [Feature Name]
 
 **Date**: [date]
-**Reviewed**: [requirements.md path]
+**Reviewed**: [SPEC.md path]
 
 ### Strategy Assessment
 **Score: [1-10]**

package/daemon/context-packs/skills/pm/plan-review/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: "plan-review"
-version: "0.5.10"
+version: "0.5.12"
 taxonomy: "skills"
 purpose: "Multi-perspective review of a feature plan or requirements doc before development begins. Evaluates from strategy, design/UX, and engineering angles to catch gaps early."
 files:

package/daemon/context-packs/skills/pm/requirements-writer/SKILL.md

@@ -23,7 +23,7 @@ Before starting the conversation, silently gather context:
 
 1. **Check for validation.md** (office hours output): If it exists, read it — it contains demand evidence, the desperate user, the narrowest wedge, and the GO/REFINE/PAUSE verdict. Use it to skip questions the PM already answered.
 2. **Check for background.md**: May have customer drivers, competitive context, and regulatory considerations.
-3. **Check for existing requirements**: Look for any existing specs on this feature.
+3. **Check for existing requirements**: Use the selected slice's `SPEC.md`. If only legacy `requirements.md` exists, preserve it as input/history and reconcile it into `SPEC.md` before downstream mockup/review/summary work. Maintain one requirements authority.
 4. **Check for shipped features**: Look for related as-built specs.
 
 If validation.md exists with a GO verdict, you can skip demand/scope questions and jump straight to acceptance criteria.

package/daemon/context-packs/skills/pm/requirements-writer/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: "requirements-writer"
-version: "0.5.10"
+version: "0.5.12"
 taxonomy: "skills"
 purpose: "Use when converting PM intake into a slice SPEC.md with observable acceptance outcomes, explicit scope, and advisory sibling build dependencies."
 files:

package/daemon/context-packs/skills/pm/ui-mockup/SKILL.md

@@ -27,7 +27,7 @@ Self-contained HTML files that look like the real app. Portable, no dependencies
 Rules:
 - Match the application's existing styling exactly
 - Use real data from the codebase
-- Only show what's in requirements.md
+- Only show what's in SPEC.md
 - Self-contained single HTML file
 - Screen switcher nav to toggle between screens via JavaScript
 - Keep under 1,000 lines
@@ -46,7 +46,7 @@ Rules:
 ### Step 1: Understand What to Mockup
 
 Read feature folder docs first:
-- **requirements.md** — acceptance criteria define what screens are needed
+- **SPEC.md** — acceptance criteria define what screens are needed
 - **validation.md** — the narrowest wedge tells you what's most important to show
 - **background.md** — customer drivers and competitive context inform what to emphasize
 
@@ -70,7 +70,7 @@ Then ask the PM about fidelity level and specific screens.
 ## Guidelines
 
 - **Use real data.** Real names, real ranges, real hierarchies.
-- **Only show what's in requirements.md.** Don't add features beyond the requirement.
+- **Only show what's in SPEC.md.** Don't add features beyond the requirement.
 - **Less is more.** 3-5 screens beats 10.
 - **Match the app exactly.** Read existing code and match styling patterns.
 - **Tell the PM what's real vs mocked.**

package/daemon/context-packs/skills/pm/ui-mockup/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: "ui-mockup"
-version: "0.5.10"
+version: "0.5.12"
 taxonomy: "skills"
 purpose: "Create UI mockups at three fidelity levels — ASCII wireframes for quick iteration, standalone HTML mockups for delivery with requirements, and live prototypes for interaction testing."
 files:

package/daemon/context-packs/skills/pods/development-team/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: "development-team"
-version: "0.5.10"
+version: "0.5.12"
 taxonomy: "skills"
 purpose: "Use when a development pod begins or hands off implementation, QA, or design work."
 files:

package/daemon/context-packs/skills/pods/orchestration-team/SKILL.md

@@ -41,9 +41,9 @@ The orchestration pod is responsible for:
 - **Status lives in the queue, not panes** (`status-not-chat-orchestrator`): `rig ps --nodes --json` + `rig queue` are your status source; do NOT reconstruct fleet-state by capturing panes (pane `rig capture` is high-bandwidth *within your own pod* — that's fine; it is not how you track cross-pod/fleet state). *(`rig ps --nodes` is YOUR rig's seats only — bare `rig ps` lists ALL rigs on the host; don't mistake a narrow node read for the whole world.)*
 - **The watchdog is your clock** (`watchdog`): configure `rig watchdog` to wake you (~3 min); between wakes, idle (zero tokens) — no self-run sleep-loop re-reading panes at steady-state. Prefer one workflow-watchdog + targeted exception handling over many per-seat nag loops.
 - **On each wake — cheap sweep:** `rig queue` + a *filtered* `rig ps` (see "Read cheap" below) first; ONLY for a seat that looks idle/suspicious, `rig capture <session>` last few lines (never a full pane, never huge chunks); **active owner → no-op.**
-- **Read cheap — every status command has a token cost; project to the question.** The queue-first rule is about *where* status lives; this is about *how much you pay to read it*. The token bomb is the broad unfiltered dump, not the pane capture: an unfiltered fleet-wide `rig ps --nodes --json` emits ~77k tokens — for a one-rig or one-qitem question that is almost all waste, and at watchdog cadence it burns the shared account fast.
+- **Read cheap — every status command has a token cost; project to the question.** The queue-first rule is about *where* status lives; this is about *how much you pay to read it*. The token bomb is the broad unfiltered dump, not the pane capture: a broad fleet response can overwhelm a one-rig or one-qitem question. Select the scope and fields before returning output to the agent.
   - **Scope the read to the question.** Specific item → `rig queue show <qitem> --json`. One rig's frontier → filter + project only the fields you need, e.g. `rig ps --nodes --json | jq '.[] | select(.rigName=="<rig>") | {session:.canonicalSessionName, state:.agentActivity.state, hasAssignedWork, pendingWorkCount}'` (prefer a native rig/session filter if one exists). Never pull whole-fleet JSON to answer a narrow rig/qitem question.
-  - **Pane capture / transcript = last resort for one named stale owner,** not a status-polling loop — **re-capturing an unchanged pane returns no new information and is the measured token-burn failure** (the unit of monitoring is an event — a wake, a queue transition, an activity signal — never elapsed time or a repeat count).
+  - **Pane capture / transcript = last resort for one named stale owner,** not a status-polling loop — **re-capturing an unchanged pane returns no new information** (the unit of monitoring is an event — a wake, a queue transition, an activity signal — never elapsed time or a repeat count).
   - **Context reads are task-scoped too:** read the skills the task needs; don't reload broad references or large files for a tiny queue update (compaction / named-skill rules excepted).
   - **Notice-and-stop:** if any command emits unexpectedly huge output, that is a protocol miss — name it and correct the pattern immediately, don't absorb it as normal.
   - **Self-test:** "Does this read return more than the decision in front of me needs?" If yes, narrow it before running.
@@ -115,36 +115,28 @@ When an agent looks stuck:
 
 Do not call a blocked agent "in progress" forever.
 
-## Capacity — a seat is never the bottleneck (fork to unblock)
-
-Seat capacity is **elastic**, so a blocked or overloaded lane is a **policy** problem, not a capacity
-fact — *"the seat is busy"* is never a real constraint. You have **standing authority to fork any
-agent** to unblock a lane; no escalation.
-
-- **`rig fork <source-session>`** clones a live seat *with its context window* into a new seat (`--rig`
-  / `--pod` to place it; it composes the shipped agent-image fork path). **Claude is supported today;
-  Codex fork is pending a research spike — don't rely on it until that lands.**
-- **The pattern:** fork → the fork does the task → **salvage its result as markdown** → **retire the
-  fork** → return the rig to its spec's steady state. Short-lived forks are safe because seats carry
-  **distinguished names** (a fork is never mistaken for the seat it came from — see
-  `seat-continuity-and-handover`).
-- **The ladder, and whose call each rung is:** fork an agent *(yours, standing)* → onboard a new seat
-  → clone / stand up a whole rig → stand up a host on a VPS. **Rig- and host-level spin-up belong to
-  the oversight / owner altitude, not the orchestrator's** — fork is your rung.
-- **What's actually scarce:** with seats elastic, the real constraints reduce to **humans** (the
-  owner's attention, the operator slot), **money** (provider limits — account switching is the relief
-  valve), and **compute** (host limits). Protect *those*; never let a lane sit blocked on a "busy seat."
-
-See `session-source-fork` for the fork primitive's mechanics and `delegating-work` for choosing fork
-vs. subagent vs. route-to-a-context-holder.
+## Capacity and assignment
+
+A busy seat may be the current constraint. First check available owners, retained
+context and the work's independent-review requirements. Reassign, defer, or add
+capacity only within the declared scope and current provider/host limits.
+
+`rig fork` can compose a new occupant from retained context when the installed
+runtime and source support it. Check current help and actual source availability;
+this skill grants no standing permission to fork, change accounts, or launch rigs
+or hosts. A selected temporary fork needs a bounded outcome, durable return,
+continuity disposition and an authorized retirement path. Distinct names alone
+do not prove safe or correct lifecycle behavior.
+
+See `session-source-fork` for continuity semantics. Choose a context holder or an
+ephemeral subagent according to whether the acquired knowledge needs to persist.
 
 ## Topology settlement
 
 **Your rig's roster is a fact you READ, never one this skill asserts.** Get the actual team
 from `rig ps --nodes --json` at settlement time — a skill that hardcodes a specific topology
 goes stale exactly like a stale boot overlay, and a cleared or fresh seat has no context to
-doubt it (field case: a seven-node demo roster taught as "the expected team" sent a
-fourteen-seat rig's seats waiting for nodes that did not exist).
+doubt it. A starter roster is an example, not a live inventory.
 
 - Settle **what the current atom needs**, not the whole declared roster: dispatch when the
   seats THIS work requires are up. **Never park the rig waiting for absent nodes** — a
@@ -173,10 +165,10 @@ An availability report is enough. Do not create obligations to improve utilizati
 
 ## Communication modes
 
-Use direct `rig send` when:
-- you are assigning one agent or one pod
-- you need a specific answer from one seat
-- you are sending a scoped task packet
+Use a durable queue handoff for assigned work with an owner and closure condition.
+Use direct `rig send` for information or a scoped nudge that creates no new
+obligation. Confirm durable custody and delivery separately; neither proves the
+recipient understood or completed the work.
 
 Use the chatroom when:
 - the whole rig should see the status
@@ -213,37 +205,27 @@ The orchestrator does NOT relay messages between them. They communicate directly
 
 On gated atoms, never send impl a "Go" without explicitly stating the FIRST action is to send a pre-edit to QA — impl will race through an entire task list if given a general "Go." On ungated atoms, a general "Go" is correct; do not smuggle the gate back in through dispatch phrasing.
 
-## Dogfood fix loop
-
-When QA is dogfooding (testing existing features), QA works solo with full autonomy:
-- QA finds issues AND fixes them in a loop
-- QA tests the fix, then moves to the next issue
-- QA only escalates architecture-level concerns
-- Do not dispatch QA to "test and report" — dispatch to "dogfood, fix what you find, re-test"
-- The orchestrator does NOT fix things — QA and impl fix things
-
-## Permission prompt handling
-
-Permission prompts are the #1 mechanical blocker — surface them on your watchdog wake (a scoped `rig ps` / queue check), never a steady-state poll loop.
+## Dogfood and review ownership
 
-For Codex (3-option prompts): select option 2 ("Yes, and don't ask again") to permanently approve the pattern.
-For Claude (2-option): approve with Enter.
-For destructive operations (git push, rm, daemon stop, npm publish): DO NOT auto-approve. Check with the human.
+A dogfood assignment may authorize the outcome owner to diagnose, fix and retest
+bounded issues. Say that scope explicitly. A read-only evaluation remains
+read-only; a QA title does not authorize source edits or broader architecture.
+Preserve any independently selected final check when the evaluator authors a fix.
+Route findings outside the assignment to their owner with evidence.
 
-## Agent behavioral models
+## Permission and runtime handling
 
-### Claude Code agents (impl, reviewers, lead)
-- Will blast through an entire task list if given a "Go" without explicit gates
-- After being told to slow down, over-corrects to "wait for permission for everything"
-- Compaction is catastrophic — full context loss, needs preparation
-- After compaction: restore the active assignment and its selected context; skill names alone are not restored content. Follow the declared continuity policy without adding a universal quiz gate.
+Use the actual prompt and declared authority to decide an intervention. Never
+select a numbered option from a timeless harness recipe: prompt shape and the
+consequence of persistent approval vary. An authorized unblock must preserve the
+operation's scope; it does not grant publication, destructive or lifecycle powers.
 
-### Codex agents (QA, peer, R2)
-- Self-manages its own context window — do NOT intervene based on context percentage
-- Compacts automatically and continues working — this is normal, not an emergency
-- Never tell Codex to "wrap up" or "save state" based on context percentage
-- Over-engineers when given spec-writing authority — never let Codex write implementation specs
-- Excellent at: implementation, code review, dogfood testing, finding edge cases
+Choose models and roles from the environment's current execution policy and
+observed capabilities. Neither a vendor label nor a seat title determines who
+may author plans, implement, review or accept work. Verify required runtime/model
+identity before relying on the result. Follow the declared continuity policy;
+context telemetry is evidence to interpret, not automatic authority to compact
+or replace another seat.
 
 ## Intervention discipline
 
@@ -283,5 +265,5 @@ installed skill or a quiz as a universal admission gate.
 - relay messages between agents (they communicate directly)
 - auto-approve destructive operations
 - rush agents with deadline pressure
-- write implementation specs (that's a Claude task, not Codex)
-- intervene based on Codex context percentage
+- assign specification or acceptance authority from a runtime label alone
+- change continuity from a context percentage without the selected policy and authority

package/daemon/context-packs/skills/pods/orchestration-team/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: "orchestration-team"
-version: "0.5.10"
+version: "0.5.12"
 taxonomy: "skills"
 purpose: "Use when coordinating assignments, selected review boundaries, or blocked work across a rig."
 files:

package/daemon/context-packs/skills/pods/oversight-team/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: "oversight-team"
-version: "0.5.10"
+version: "0.5.12"
 taxonomy: "skills"
 purpose: "Use when you are a seat on the oversight pod (a standing monitor-mode rig that keeps OTHER rigs healthy), configuring or running the drift detectors, or choosing whether to intervene vs escalate. Covers the pull-not-poll posture, the v0 detectors (premature-park, process-drift, off-task, token-burn), the intervention ladder (orchestrator-ping -> refocus -> human escalation), and the cheap+deep model economics. NOT for orchestrating your OWN rig (orchestration-team) and NOT the intervention primi"
 files:

package/daemon/context-packs/skills/pods/review-team/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: "review-team"
-version: "0.5.10"
+version: "0.5.12"
 taxonomy: "skills"
 purpose: "Use when assigned a review or when an authored review boundary is reached."
 files:

package/daemon/context-packs/skills/process/agent-browser/LOCAL-INSIGHTS.md

@@ -1,8 +1,8 @@
 # agent-browser: Local Dev Insights
 
-> Companion to the official SKILL.md. These are gotchas, corrections, and best practices
-> discovered through hands-on testing that the upstream skill doesn't cover.
-> Last updated: 2026-02-20 | Tested against: v0.13.0
+> Companion notes for browser tasks. Command details below reflect v0.13.0-era
+> usage and may differ in the installed release. Check current help and verify
+> the target operation; this file is not a current browser or login test receipt.
 
 ---
 
@@ -60,7 +60,7 @@ Refs are invalidated by **any page state change**. This includes:
 | `-s "#sel"` | Scoped to selector | Laser focus on one component |
 | `--json` | JSON format | Programmatic parsing |
 
-**Token efficiency example:** GitHub repo page with 4,574 DOM elements → `snapshot -i` returns ~25 lines.
+Use an interactive or scoped snapshot when a full DOM listing would obscure the elements needed for the task.
 
 ## Annotated Screenshots
 
@@ -121,55 +121,26 @@ EVALEOF
 - **Persistent headed config:** Add `{"headed": true}` to `~/.agent-browser/config.json`
 - **Named sessions for parallel work:** `agent-browser --session name open <url>`
 
-## 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: 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.
-
-### Saved Profiles
-
-| Profile | Service | URL | Command |
-|---------|---------|-----|---------|
-| `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
-
-Google blocks sign-in from the bundled Chromium ("This browser or app may not be secure"). The workaround is to use the **real Chrome binary** with automation detection disabled:
-
-```bash
-agent-browser \
-  --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
-```
-
-**This applies to ANY profile that needs Google OAuth.** Always use `--executable-path` + `--args` for Google sign-in flows.
-
-### Auth Setup Pattern
-
-```bash
-# First time: login in headed mode (user enters password)
-agent-browser --profile ~/.agent-browser/profiles/<name> --headed true open <login-url>
-# ... user logs in manually ...
-agent-browser close
-
-# Every future run: headless, already authenticated
-agent-browser --profile ~/.agent-browser/profiles/<name> open <app-url>
-```
-
-### Encryption
-
-Session state files in `~/.agent-browser/sessions/` are encrypted with AES-256-GCM.
-Key stored at `~/.agent-browser/.encryption-key` (chmod 600).
-Loaded via `AGENT_BROWSER_ENCRYPTION_KEY` env var in `~/.zshrc`.
-
-Note: `--profile` directories are NOT encrypted (they're standard Chromium profile dirs).
-Keep `~/.agent-browser/profiles/` permissions locked down.
+## Authentication and retained browser state
+
+Choose the installed tool's supported state or profile mechanism for the target
+application. A saved state file or persistent profile does not prove a later
+session is authenticated: check the intended account and a meaningful authorized
+page or operation after reopening. Server expiry and application policy can
+invalidate retained state.
+
+Use an explicitly owned profile for the task. Obtain any required login through
+the user's authorized flow; do not assume a profile, account, application URL or
+provider workaround from this guide. Browser/provider compatibility must be
+checked for the actual version and flow. No tested login or saved profile is
+shipped with these notes.
+
+Treat profile directories and saved state as credential-bearing data. Keep them
+in the authorized private location, restrict access, and omit cookies, tokens,
+passwords and encryption keys from source, ordinary logs and shared evidence.
+If encryption is configured, verify the actual tool configuration and key custody;
+do not infer encryption from a filename or assume a shell already exports a key.
+Retain or remove only state the task owns and whose disposition is authorized.
 
 ## Updating the Official Skill
 

package/daemon/context-packs/skills/process/agent-browser/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-browser"
-version: "0.5.10"
+version: "0.5.12"
 taxonomy: "skills"
 purpose: "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."
 files:

package/daemon/context-packs/skills/process/context-engineering/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: "context-engineering"
-version: "0.5.10"
+version: "0.5.12"
 taxonomy: "skills"
 purpose: "Use when designing, reviewing, or debugging how an agent's context window gets filled, pruned, or shared — choosing what loads at boot versus on demand, sizing an install or an always-loaded file, fixing an agent that drifts, repeats itself, or forgets constraints mid-task, planning compaction or summarization, deciding single-agent versus subagents, engineering handoffs between agents, or picking a tool loadout. NOT for rewording a prompt's tone, choosing which model to pin, or debugging busine"
 files:

package/daemon/context-packs/skills/process/dogfood/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: "dogfood"
-version: "0.5.10"
+version: "0.5.12"
 taxonomy: "skills"
 purpose: "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."
 files:

package/daemon/context-packs/skills/process/frontend-design/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: "frontend-design"
-version: "0.5.10"
+version: "0.5.12"
 taxonomy: "skills"
 purpose: "Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics."
 files: