@openrig/cli 0.5.4 → 0.5.6

package/daemon/assets/plugins/openrig-core/skills/openrig-operating-model/templates/LEARNED.md

@@ -0,0 +1,40 @@
+---
+seat: <pod>-<member>@<rig>            # or rig/pod/fleet coords at higher altitudes
+template: <path-or-name of PLAYBOOK.md this diffs against> @ <version/sha>
+owners: self (sole direct writer) · <orchestrator/PM> (by proposal) · hierarchy (boundaries only, marked)
+updated: <YYYY-MM-DD from the clock command — never mental math>
+status: UNSEEDED  # the first real occupant replaces this line with: seeded-by-self <date>
+---
+# LEARNED — <instance coords>
+<!-- HARD CAP ~150 lines. At the cap: distill LESSONS into HOW I WORK, or expire them. -->
+
+## MY JOB HERE (≤10 lines)
+<!-- This instance's actual function, in operational terms. If you cannot write
+     this section yourself, say so to your orchestrator — that discovery is the
+     audit working, not a failure. -->
+
+## STANDING DUTIES
+<!-- One per line: DUTY — cadence — surface. These survive handovers ONLY if
+     enumerated here. -->
+- 
+
+## HOW I WORK
+<!-- Learned SOP bullets. EVERY bullet carries its reason — a rule without its
+     why is scripture and will be misapplied. -->
+- 
+
+## GATES & AUTHORITIES
+<!-- What I hold (granted in writing, cite the grant). What I must never infer. -->
+- 
+
+## KEY RELATIONSHIPS
+<!-- who I hand to · who gates me · whose funnel I feed -->
+- 
+
+## TRIGGER POINTERS
+<!-- situation → read this. Attach pointers to MOMENTS, not to boot. -->
+- 
+
+## LESSONS (append-only, dated, capped)
+<!-- newest first. At cap: distill upward or expire. -->
+- 

package/daemon/assets/plugins/openrig-core/skills/openrig-operating-model/templates/NOTES.md

@@ -0,0 +1,9 @@
+---
+node: <mission | slice>
+updated: <YYYY-MM-DD>
+---
+# NOTES — <node>
+<!-- The working record: what actually happened doing this work. Append-only,
+     dated entries, newest first. Corrections annotated, never swapped.
+     Seat-specific learnings do NOT belong here — they go to that seat's
+     LEARNED.md (this file is the WORK's memory, not the worker's). -->

package/daemon/assets/plugins/openrig-core/skills/openrig-operating-model/templates/PLAYBOOK.md

@@ -0,0 +1,5 @@
+# MOVED — this file is now SOP.md
+
+Renamed PLAYBOOK.md -> SOP.md per owner naming ruling 2026-08-11 (names are
+prompts; SOP is the stronger consult-and-follow trigger and the factory-native
+term). Read ./SOP.md. One-transition-period pointer; do not edit here.

package/daemon/assets/plugins/openrig-core/skills/openrig-operating-model/templates/SOP.md

@@ -0,0 +1,24 @@
+---
+kind: <seat-type | pod-type | rig-type | fleet>
+owner: <spec author>                   # instances NEVER edit this file
+updated: <YYYY-MM-DD>
+status: UNSEEDED
+---
+# SOP — <kind>
+<!-- The TEMPLATE half: how this KIND of thing does its job, anywhere it is
+     instantiated. Absorbs the static role file at seat altitude. Instance-local
+     knowledge belongs in LEARNED.md beside this, never here. -->
+
+## PURPOSE
+<!-- what this kind exists to do -->
+
+## CORE LOOP
+<!-- the job's shape: inputs → work → outputs/handoffs -->
+
+## DEFAULT PRACTICES
+<!-- each with its reason attached -->
+- 
+
+## BOUNDARIES
+<!-- what this kind never does; where its authority ends -->
+- 

package/daemon/assets/plugins/openrig-core/skills/openrig-operating-model/templates/SPEC.md

@@ -0,0 +1,54 @@
+---
+node: <project | mission | slice>
+intent: >-
+  <ONE sentence: what this node is FOR. This composes UP the chain, so write it to be
+   read from below by someone standing on a slice. Say the purpose, never the location —
+   "deferred features land here" is a routing rule and orients nobody.>
+id: <OPR.x.y[.n] — minted by the PM; omit if unminted>
+stage: wip
+# stage: wip | provisional | established | canonical | superseded | retired
+status: UNSEEDED
+---
+
+<!-- ONE authored file per work node. README.md and IMPLEMENTATION-PRD.md fold into this.
+     PROOF.md stays separate and is good. PROGRESS.md is the authored acceptance checklist:
+     checkbox items are stored marks; every roll-up above them is derived, never hand-authored.
+     Legacy README.md nodes stay valid indefinitely; nothing is forced to migrate.
+
+     PROJECT and MISSION nodes: the frontmatter `intent:` IS the whole job. A mission
+     ORGANISES slices and carries the context they need; it specifies nothing. Keep the
+     body short or delete it — everything below this line is for SLICES.
+
+     WHATEVER BODY YOU DO WRITE, two tests per sentence:
+       PORTABILITY — if it would read correctly on a stranger's machine it is knowledge
+         about a KIND; it belongs in the operating-model skill, not on the tree.
+       VOLATILITY — a SHA, a count, a status, a roster: write the COMMAND that derives it,
+         never the answer. A value here is stale by the next fold.
+     And check the tree: traps and how-we-work live in LEARNED.md on the topology tree,
+     not here. This file is what is being BUILT.
+
+     SLICE nodes are the ONLY altitude that specifies. Keep the sections you need and
+     delete the rest; this is a starting shape, not a contract. Under the FACTORY operating
+     model this node also carries mini-requirements and a proof contract — see that mode's
+     plugin. Under the LAB it does not. -->
+
+# <name>
+
+## What must be built
+
+<!-- The change itself, at the altitude a builder can act on. -->
+
+## Why this is the shape
+
+<!-- The reasoning a reader would otherwise have to reconstruct — especially any option
+     considered and rejected. This is the part that survives you. -->
+
+## How we will know it works
+
+<!-- Verified by EFFECT: run it, look at the result. Name the command and what it should
+     print, not the feeling of being done. -->
+
+## Scope fences
+
+<!-- What this deliberately does NOT include, so it neither swallows the release nor grows
+     during the build. Fences written after the fact are excuses; written now they hold. -->

package/daemon/assets/plugins/openrig-core/skills/openrig-skills/SKILL.md

@@ -34,22 +34,30 @@ Don't guess a file path or a name. Go **ask → ref → load** in three steps:
 rig context get skills/core/rig-lifecycle
 ```
 
+The router itself is available through both forms it teaches:
+`rig context get openrig-skills` and `rig context get skills/core/openrig-skills`.
+
 The content is served **from the installed CLI**, so what you load always matches your running version —
 no path-guessing, no frozen-fork drift. (The daemon assembles the same bundle `rig context preview`
 shows an operator — `get` is the agent-facing pull.)
 
 ## The index
 
+> Membership rule (`layout.skills[*].edges.length > 0`): every public skill with at least one product edge in the generated edge layout appears exactly once in this index; no other skill appears.
+
 ### Always loaded — the universal spine (open its body when its moment hits)
 These are auto-delivered to every rig; their name+description are already in your context. Open the body when the "when" matches.
 
 - **forming-an-openrig-mental-model** — first boot, or you're unsure how the pieces fit. The runtime mental model.
+- **openrig-operating-model** — you do not know where context or work belongs, or you are about to duplicate knowledge. The two-tree placement and trace-to-root model.
 - **openrig-user** — you need a `rig` CLI command (send / queue / ps / whoami / scope / broadcast). The daily CLI surface.
+- **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.
 - **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.
 - **seat-continuity-and-handover** — handing your seat's work across a restart or to another owner.
-<!-- Territory amended 2026-08-26 by desk ruling qitem-20260826080800-r054-s9a-scope-ruling. -->
 - **orienting-to-an-inherited-seat** — you just inherited an existing seat through a planned handover and need to verify its identity, state, and testimony.
 - **retiring-and-inheriting-a-seat** — you're planning a seat transition and need to retire the current occupant into a fresh successor without losing continuity.
 - **mission-slice-sop** — you're working a mission/slice (the SDLC: intent → mini-requirements + proof contract → build → QA → proof). The operating manual.
@@ -66,22 +74,21 @@ These ship in the OpenRig repo and reach a seat when its profile selects them. T
 - **agent-startup-and-context-ingestion** — a seat is booting and ingesting its startup context.
 - **topology-mutation-and-seat-management** — adding, removing, renaming seats or otherwise mutating rig topology.
 - **rig-lifecycle** — rig up / down / pause / resume lifecycle operations.
-- **applying-a-permission-policy** — a rig/seat has a permission policy attached, or you're setting one up (Locked / Standard / Open): translate it into the live harness config (Claude `settings.json` / Codex `config.toml`), agent-driven + interactive. Reached at onboarding and at rig setup/preflight. (YOLO / bypass is a launch-flag OpenRig sets, not this skill.)
 - **rig-bundles-and-shareable-artifacts** — packaging or installing a rig bundle / shareable artifact.
 - **cross-host-rig-commands** — reaching seats or queues on another host (`--host`).
 - **openrig-upgrade** — upgrading OpenRig or the daemon.
 - **agent-starters** — composing an agent's starter context / priming packs.
 - **specification-system** — authoring or reading AgentSpecs and rig specs.
-- **attention-queue** — managing the attention / needs-attention surface.
 - **human-in-the-loop** — deciding when to involve the human vs. proceed on your own authority.
-- **delegating-work** — deciding WHO does a task: yourself, a spawned subagent, or another agent that already holds the context (the when/whether decision, not the fan-out mechanics).
 - **watchdog** — monitoring or recovering a seat (health, restore, stuck state).
 - **session-source-fork** — forking a session's source/context.
+- **context-engineering** — designing context systems. Provisional and non-normative: current OpenRig skills, explicit rulings, and measured practice outrank it on any conflict.
 
 Pod handbooks (load when you're in that pod):
 - **orchestration-team** — you're orchestrating a rig: dispatching, monitoring, keeping the loop moving.
 - **development-team** — you're on the dev pod: building and shipping product changes.
 - **review-team** — you're reviewing: fresh scrutiny, anti-slop, empirical verification.
+- **oversight-team** — you're in an oversight pod: monitor boundaries and route findings without taking over the work.
 
 Product-management craft (load when shaping/reviewing work):
 - **requirements-writer** — turning intent into clear requirements.
@@ -109,5 +116,3 @@ General engineering skills OpenRig ships as vendored copies. Open when the task
 ## Need more than what ships here?
 
 This index covers the **shipped** surface. A dev host carries far more (factory, architecture, PM-craft, studio skills) reached through the host's own routers/codemaps — if you're on a builder host and need something not listed above, that deeper routing is the next hop, not a wall. (Host-scale routing is the subject of the context-routing architecture doc; at product scale, this one file is the whole map.)
-
-> Membership note: this index lists exactly the skills that ship with OpenRig. When a skill graduates into the shipped set it joins this index — the index and the shipped set stay one scope.

package/daemon/assets/plugins/openrig-core/skills/openrig-user/SKILL.md

@@ -11,9 +11,7 @@ description: >-
 This is an as-built guide to the shipped `rig` CLI.
 Use current code and `rig ... --help` as ground truth if anything here ever conflicts with older planning docs.
 
-This is not the config-layer or builder guide. Use the substrate control-plane guidance for `rigx`
-and experimental overlays. Use the OpenRig builder guidance when changing OpenRig behavior,
-doctrine, or release posture.
+Use the OpenRig builder guidance when changing OpenRig behavior, doctrine, or release posture.
 
 
 ## Coordination trust boundary
@@ -114,10 +112,6 @@ process does not require.
   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`
   → use `--body-file /tmp/<descriptive-name>.txt` (or `-` for stdin), the
   corruption-safe surface. The body parser does not tolerate raw backticks or
@@ -147,11 +141,6 @@ Default posture:
   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. For queue specifically, `rigx queue` is recovery-only fallback;
-  qitems written via `rigx queue` are invisible to daemon-backed reads and break fleet-wide
-  routing discipline.
 - If a daemon-backed coordination command fails, debug the command/runtime/schema edge directly;
   do not assume the right workaround is to drop back to a config-layer primitive.
 - Do not perform daemon stop/start, production DB copy/mutation, release, publish, or other

package/daemon/assets/plugins/openrig-core/skills/orienting-to-an-inherited-seat/CHANGELOG.md

@@ -10,7 +10,7 @@ instructional.
 
 ### The incident
 
-A successor (orch-advisor tenure 4, v-openrig-build) concluded mid-conversation that its reach-back
+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

package/daemon/assets/plugins/openrig-core/skills/orienting-to-an-inherited-seat/SKILL.md

@@ -46,6 +46,21 @@ Rule 2 below teaches you to refuse. Read this before you act on anything the pac
 The mechanic that produced your handover lives in `retiring-and-inheriting-a-seat`; the
 compaction backstop this planned path replaces lives in `claude-compaction-restore`.
 
+## Apprentice arc — successor
+
+If you arrived in a staged apprentice seat, you are **authority-free until** the named owner words
+the gate and the cutover mechanic records its effect. That is a safety property, not a judgment on
+your capability: stable authority must move at one observable moment. Use the apprenticeship as a
+conversation—observe real work, ask why, attempt bounded errands, and let the incumbent correct your
+model. Evidence helps that judgment; it does not replace it.
+
+Derive your own layer-5 delta after world, mission, and position context land, and have another
+reader check it, **because reading a deposit does not install it**. Confirm every enumerated standing
+duty and keep the predecessor's verbatim reach-back handle plus pre-formed questions. Never self-cut
+over, rename the live seat, or treat a passed probe as owner word. When the stakes earn more evidence,
+the optional toolkit linked from `seat-continuity-and-handover` provides it without turning the
+default experience into ceremony.
+
 ## Why this seat is a lineage — inherit, acquire, improve
 
 There are two kinds of thing a predecessor could pass you, and they are **not** passed the

package/daemon/assets/plugins/openrig-core/skills/queue-handoff/SKILL.md

@@ -16,7 +16,6 @@ metadata:
       - looping-workflows
       - intake-routing
       - human-in-the-loop
-      - attention-queue
       - dispatching-parallel-agents
       - subagent-driven-development
       - structured-ack-dispatch
@@ -114,7 +113,6 @@ the seat level and needs no new machinery — the last act *after a handoff* is
 | `rig queue create` | yes | New qitem created from scratch |
 | `rig queue handoff` | yes | Transactional close-as-handed-off + create-new |
 | `rig queue handoff-and-complete` | yes | Atomic close + create-new; default nudge wakes the new owner |
-| `rigx queue handoff` (filesystem v0 prototype; **recovery-only fallback since 2026-05-11**) | yes | Legacy artifact; qitems invisible to daemon-backed reads; deprecation warning + removal queued at `missions/bug-fix/slices/rigx-queue-deprecation-message/`. Use `rig queue handoff` (daemon-backed) for all new substantive work. |
 
 **Footgun**: `--no-nudge` accidentally added to a live-loop handoff.
 The shipped 0.3.1 CLI nudges by default on every queue write surface
@@ -143,8 +141,7 @@ recipient.
   at the file for the detail. A pasted dump makes `rig queue show <id>
   --json` huge — a second-order token bloat: bloated DATA living in the
   queue, distinct from the command-default output bombs the token-burn
-  emergency pack covers. (Sensor: guard token-burn-flag 8ea201e4,
-  2026-06; operator-directed cure.)
+  emergency pack covers.
 - **Substantive bodies go through `--body-file`, not inline `--body`.**
   For anything beyond a short line, write the body to a file and pass
   `--body-file <path>` (or `-` for stdin). Inline `--body` with shell
@@ -183,19 +180,10 @@ Every qitem carries:
 
 **(0.5.0) `--body-context <ref>` — context riding the handoff.** `rig queue create … --body-context <ref>` attaches a composed context pack to the qitem. The snapshot rule: the qitem stores the **resolved content** in its body **plus the ref for provenance** — the handoff carries what was actually sent, and a later edit to the library never silently rewrites a past handoff's history. (The `rig context` noun composes the ref; the queue delivers it — the noun has no send.) See `openrig-user` → "Context packs and paced delivery."
 
-The fields are auditable across both `rigx queue` (config-layer) and
-`rig queue` (daemon-shipped) surfaces. Watchdog policies and workflow
-runtime project new owners off these fields.
+The fields are auditable on the daemon-backed `rig queue` surface. Watchdog
+policies and workflow runtime project new owners off these fields.
 
-## Two surfaces (same shape)
-
-| Surface | Status | When to use |
-|---|---|---|
-| `rig queue ...` (daemon-shipped, v0.2.0) | Active host coordination surface | Daemon-backed PL-004 work; SQLite-canonical |
-| `rigx queue ...` (config-layer dogfood) | Coexists with daemon | Workflows still operating on the temporary substrate coordination layer; legacy artifacts |
-
-Default posture: prefer daemon `rig queue` for new work. If a
-daemon-backed coordination command fails, debug the command/runtime/schema
+If a daemon-backed coordination command fails, debug the command/runtime/schema
 edge directly — don't fall back to stale pre-upgrade assumptions.
 
 ## See also

package/daemon/assets/plugins/openrig-core/skills/refocusing/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: refocusing
+description: >-
+  Use when a long-running agent may have lost the product outcome, when context was compacted,
+  when work has crossed a major boundary, or when a fresh path-based trace is needed before the
+  next consequential action. Not for fresh-session orientation, waking an idle seat, or checkpoints.
+metadata:
+  openrig:
+    stage: product
+---
+
+# Refocusing
+
+Refocus preserves a long session's earned expertise while re-grounding it in current intent and
+lived context. It is not a restart, wake, or phase checkpoint.
+
+Run the bundled trace from this skill directory instead of reconstructing the hierarchy from memory:
+
+```bash
+python3 scripts/trace-to-root.py --trees both --depth light
+```
+
+Use `--trees topology|work|both` to select context domains and `--depth light|full` to control how
+much each node contributes. Light work traces compose `intent:` and name notes; full traces include
+the complete node and notes bodies. The script resolves `topology.root` and `workspace.root` with
+`rig config get`. When a current node cannot be derived, set `OPENRIG_REFOCUS_TOPOLOGY_NODE` or
+`OPENRIG_REFOCUS_WORK_NODE`, or pass the matching `--*-start` option.
+
+Read [references/refocus.md](references/refocus.md) when changing the automatic hook or its content
+ladder. A missing chain file is evidence: report the gap and continue; never follow pointers to invent
+a second parent.

package/daemon/assets/plugins/openrig-core/skills/refocusing/references/refocus.md

@@ -0,0 +1,22 @@
+# Refocus
+
+1. What is the person actually trying to get? Not your current task — the outcome.
+2. Does what you are doing RIGHT NOW move that? If you cannot say what a user gets, stop and say so.
+3. What have you concluded without opening the file or running the thing?
+
+Discomfort on any of these is the signal: drift feels like work.
+
+The `refocusing` skill carries the source-appropriate path-only trace. Its
+`scripts/trace-to-root.py` walks both current trees by default: topology `LEARNED.md`, then work
+`SPEC.md` intent plus `NOTES.md`. Change breadth with `OPENRIG_REFOCUS_TREES=topology|work|both`
+and read depth with `OPENRIG_REFOCUS_DEPTH=light|full`.
+
+Replace this default without editing the plugin. The content ladder, highest precedence first, is:
+
+1. `OPENRIG_REFOCUS_CONTENT_REF`, resolved by `rig context get`.
+2. `OPENRIG_REFOCUS_CONTENT_FILE`, an operator-authored file.
+3. `$OPENRIG_HOME/refocus/REFOCUS.md`, instance content.
+4. This shipped default.
+
+Fresh seats receive the separate onboarding assets `openrig-onboarding-01.md` and
+`openrig-onboarding-02.md`. This file only cites those assets; it does not copy their world install.

package/daemon/assets/plugins/openrig-core/skills/refocusing/scripts/trace-to-root.py

@@ -0,0 +1,264 @@
+#!/usr/bin/env python3
+"""Render topology and work context by ascending directory paths only."""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+from pathlib import Path
+
+SHELVES = {"rigs", "pods", "seats", "missions", "slices"}
+
+
+def rig_output(*args):
+    try:
+        result = subprocess.run(
+            ["rig", *args], capture_output=True, text=True, timeout=10, check=False
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    value = (result.stdout or "").strip()
+    return value if result.returncode == 0 and value else None
+
+
+def configured_root(key, env_key):
+    value = os.environ.get(env_key) or rig_output("config", "get", key)
+    return Path(value).expanduser().resolve() if value else None
+
+
+def under_root(path, root):
+    try:
+        path.relative_to(root)
+        return True
+    except ValueError:
+        return False
+
+
+def ascent(start, root):
+    start = start.expanduser().resolve()
+    if not under_root(start, root):
+        return None, f"start is outside configured root: {start}"
+    nodes = []
+    current = start
+    while True:
+        if current.name not in SHELVES:
+            nodes.append(current)
+        if current == root:
+            break
+        parent = current.parent
+        if parent == current:
+            return None, f"could not reach configured root: {root}"
+        current = parent
+    return list(reversed(nodes)), None
+
+
+def read(path):
+    try:
+        return path.read_text(encoding="utf8", errors="replace")
+    except OSError:
+        return None
+
+
+def resolve_notes(node):
+    try:
+        result = subprocess.run(
+            ["rig", "scope", "resolve-notes", str(node), "--json"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+        )
+    except subprocess.TimeoutExpired:
+        return None, "resolver command timed out"
+    except OSError as error:
+        return None, f"resolver command could not start: {error}"
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout or "").strip().splitlines()
+        suffix = f": {detail[0]}" if detail else ""
+        return None, f"resolver command exited {result.returncode}{suffix}"
+    try:
+        payload = json.loads(result.stdout)
+    except (json.JSONDecodeError, TypeError):
+        return None, "resolver command returned malformed JSON"
+    if not isinstance(payload, dict) or payload.get("ok") is not True or "resolution" not in payload:
+        return None, "resolver command returned an invalid success shape"
+    resolution = payload["resolution"]
+    if resolution is None:
+        return None, None
+    if not isinstance(resolution, dict):
+        return None, "resolver command returned an invalid resolution shape"
+    resolved_path = resolution.get("path")
+    resolved_name = resolution.get("name")
+    if not isinstance(resolved_path, str) or not isinstance(resolved_name, str):
+        return None, "resolver command returned an invalid resolution shape"
+    return (Path(resolved_path), resolved_name), None
+
+
+def intent(text):
+    if not text or not text.startswith("---"):
+        return None
+    match = re.match(r"^---\s*\n(.*?)\n---(?:\s*\n|$)", text, re.S)
+    if not match:
+        return None
+    lines = match.group(1).splitlines()
+    for index, line in enumerate(lines):
+        found = re.match(r"^intent:\s*(.*)$", line)
+        if not found:
+            continue
+        value = found.group(1).strip()
+        if value in {"|", ">", "|-", ">-", "|+", ">+"}:
+            block = []
+            for later in lines[index + 1:]:
+                if later and not later[0].isspace():
+                    break
+                block.append(later.strip())
+            return " ".join(part for part in block if part)
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in {"'", '"'}:
+            if value[0] == '"':
+                try:
+                    return json.loads(value)
+                except json.JSONDecodeError:
+                    pass
+            return value[1:-1]
+        return value or None
+    return None
+
+
+def light_learned(text):
+    if not text:
+        return ""
+    body = re.sub(r"^---\s*\n.*?\n---\s*\n", "", text, count=1, flags=re.S).strip()
+    if len(body) <= 800:
+        return body
+    boundary = body.rfind("\n", 0, 800)
+    return body[:boundary if boundary > 0 else 800].rstrip() + "\n[… use --depth full for the rest]"
+
+
+def render_topology(start, root, depth):
+    output = ["## TOPOLOGY TRACE", f"root: {root}", f"start: {start}"]
+    nodes, error = ascent(start, root)
+    if error:
+        return "\n".join(output + [f"TRACE GAP — {error}"])
+    for node in nodes:
+        chain_file = node / "LEARNED.md"
+        text = read(chain_file)
+        label = node.relative_to(root) or Path(".")
+        if text is None:
+            output.append(f"\n### {label}\nMISSING LINK — {chain_file}")
+            continue
+        body = text.strip() if depth == "full" else light_learned(text)
+        output.append(f"\n### {label} · LEARNED.md\n{body}")
+    return "\n".join(output)
+
+
+def render_work(start, root, depth):
+    output = ["## WORK TRACE", f"root: {root}", f"start: {start}"]
+    nodes, error = ascent(start, root)
+    if error:
+        return "\n".join(output + [f"TRACE GAP — {error}"])
+    for node in nodes:
+        label = node.relative_to(root) or Path(".")
+        spec = next((candidate for candidate in (node / "SPEC.md", node / "README.md") if candidate.is_file()), None)
+        if spec is None:
+            output.append(f"\n### {label}\nMISSING LINK — no SPEC.md or README.md at {node}")
+        else:
+            text = read(spec) or ""
+            if depth == "full":
+                body = text.strip()
+            else:
+                value = intent(text)
+                body = f"intent: {value}" if value else "MISSING INTENT — no readable intent: field"
+            output.append(f"\n### {label} · {spec.name}\n{body}")
+
+        notes, resolution_error = resolve_notes(node)
+        if resolution_error:
+            output.append(f"NOTES RESOLUTION GAP — {resolution_error} at {node}")
+        elif notes:
+            notes_path, notes_name = notes
+            if depth == "full":
+                notes_text = read(notes_path)
+                if notes_text is None:
+                    output.append(f"NOTES RESOLUTION GAP — resolved {notes_name} became unreadable at {notes_path}")
+                else:
+                    output.append(f"\nNOTES · {notes_name}\n{notes_text.strip()}")
+            else:
+                try:
+                    size = notes_path.stat().st_size
+                except OSError:
+                    output.append(f"NOTES RESOLUTION GAP — resolved {notes_name} became unreadable at {notes_path}")
+                else:
+                    output.append(f"NOTES · {notes_name} · {size} bytes · {notes_path}")
+        else:
+            output.append(f"NOTES GAP — no readable mission notes at {node}")
+    return "\n".join(output)
+
+
+def derive_topology_start(root):
+    explicit = os.environ.get("OPENRIG_REFOCUS_TOPOLOGY_NODE")
+    if explicit:
+        return Path(explicit)
+    raw = rig_output("whoami", "--json")
+    if not raw:
+        return None
+    try:
+        identity = json.loads(raw).get("identity", {})
+    except json.JSONDecodeError:
+        return None
+    rig = identity.get("rigName")
+    session = identity.get("sessionName")
+    if not rig or not session:
+        return None
+    seat = str(session).split("@", 1)[0]
+    return root / "rigs" / str(rig) / "seats" / seat
+
+
+def derive_work_start(root):
+    explicit = os.environ.get("OPENRIG_REFOCUS_WORK_NODE")
+    if explicit:
+        return Path(explicit)
+    current = Path.cwd().resolve()
+    if not under_root(current, root):
+        return None
+    while under_root(current, root):
+        if (current / "SPEC.md").is_file() or (current / "README.md").is_file():
+            return current
+        if current == root:
+            break
+        current = current.parent
+    return None
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--trees", choices=("topology", "work", "both"), default=os.environ.get("OPENRIG_REFOCUS_TREES", "both"))
+    parser.add_argument("--depth", choices=("light", "full"), default=os.environ.get("OPENRIG_REFOCUS_DEPTH", "light"))
+    parser.add_argument("--topology-start")
+    parser.add_argument("--work-start")
+    args = parser.parse_args()
+
+    sections = []
+    if args.trees in {"topology", "both"}:
+        root = configured_root("topology.root", "OPENRIG_TOPOLOGY_ROOT")
+        if root is None:
+            sections.append("## TOPOLOGY TRACE\nTRACE GAP — topology.root is unresolved")
+        else:
+            start = Path(args.topology_start) if args.topology_start else derive_topology_start(root)
+            sections.append(render_topology(start, root, args.depth) if start else
+                            "## TOPOLOGY TRACE\nTRACE GAP — current topology node is unresolved; set OPENRIG_REFOCUS_TOPOLOGY_NODE")
+
+    if args.trees in {"work", "both"}:
+        root = configured_root("workspace.root", "OPENRIG_WORKSPACE_ROOT")
+        if root is None:
+            sections.append("## WORK TRACE\nTRACE GAP — workspace.root is unresolved")
+        else:
+            start = Path(args.work_start) if args.work_start else derive_work_start(root)
+            sections.append(render_work(start, root, args.depth) if start else
+                            "## WORK TRACE\nTRACE GAP — current work node is unresolved; set OPENRIG_REFOCUS_WORK_NODE")
+
+    print("\n\n".join(sections))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())