@openrig/cli 0.5.7 → 0.5.9

package/daemon/assets/claude-statusline-context.cjs

@@ -42,6 +42,7 @@ process.stdin.on("end", () => {
       },
       session_id: raw.session_id ?? null,
       session_name: raw.session_name ?? null,
+      occupant_generation: process.env.OPENRIG_OCCUPANT_GENERATION || process.env.RIGGED_OCCUPANT_GENERATION || null,
       transcript_path: raw.transcript_path ?? null,
       sampled_at: new Date().toISOString(),
     };

package/daemon/assets/plugins/openrig-core/README.md

@@ -4,7 +4,7 @@ Canonical OpenRig skills and hooks for cross-runtime agent topology coordination
 
 ## What this plugin ships
 
-**Skills (17):** canonical OpenRig operating knowledge, including the public `refocusing` skill and
+**Skills (19):** canonical OpenRig operating knowledge, including the public `refocusing` skill and
 its path-only topology/work trace.
 
 **Hooks:** activity tracking, compaction continuity, and the default-on refocus channel. Refocus is

package/daemon/assets/plugins/openrig-core/hooks/scripts/refocus.cjs

@@ -91,6 +91,28 @@ function readConfiguredContent(home) {
   };
 }
 
+// A live seat carries no OPENRIG_REFOCUS_WORK_NODE, so the trace used to report an
+// unresolved work node while the daemon could already name the seat's typed baton. Ask it.
+// The explicit variable always wins and short-circuits the call; any failure here returns
+// null and leaves the pre-existing gap line intact, because refusing to answer is correct
+// and guessing a work node would silently re-point the whole trace.
+function deriveWorkStart() {
+  if (process.env.OPENRIG_REFOCUS_WORK_NODE) return process.env.OPENRIG_REFOCUS_WORK_NODE;
+  const result = spawnSync("rig", ["queue", "whoami", "--json"], {
+    encoding: "utf8",
+    env: process.env,
+    timeout: 2_000,
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  if (result.error || result.status !== 0 || !result.stdout || !result.stdout.trim()) return null;
+  try {
+    const workNodePath = JSON.parse(result.stdout)?.currentWork?.workNodePath;
+    return typeof workNodePath === "string" && workNodePath ? workNodePath : null;
+  } catch {
+    return null;
+  }
+}
+
 function renderTrace() {
   const script = path.resolve(__dirname, "../../skills/refocusing/scripts/trace-to-root.py");
   const args = [
@@ -101,8 +123,9 @@ function renderTrace() {
   if (process.env.OPENRIG_REFOCUS_TOPOLOGY_NODE) {
     args.push("--topology-start", process.env.OPENRIG_REFOCUS_TOPOLOGY_NODE);
   }
-  if (process.env.OPENRIG_REFOCUS_WORK_NODE) {
-    args.push("--work-start", process.env.OPENRIG_REFOCUS_WORK_NODE);
+  const workStart = deriveWorkStart();
+  if (workStart) {
+    args.push("--work-start", workStart);
   }
   const result = spawnSync(process.env.PYTHON || "python3", args, {
     encoding: "utf8",

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

@@ -0,0 +1,92 @@
+---
+name: agent-operated-software
+description: >-
+  Use when designing, building, operating, or diagnosing an ongoing application whose live backend
+  or control loop includes OpenRig agents, including applications with a Markdown, YAML, or JSON
+  agent control plane or a thin surface over specialist agent roles.
+metadata:
+  openrig:
+    stage: provisional
+    audience: any agent building or operating an agent-backed application
+    sibling_skills:
+      - agent-operated-workflows
+      - forming-an-openrig-mental-model
+      - mission-slice-sop
+      - openrig-user
+---
+
+# Agent-Operated Software
+
+**Agent-Operated Software** is an ongoing application whose functioning runtime includes an OpenRig
+agent or rig in its live backend or control loop. The application surface can be thin: structured
+state and specialist roles do the work, while the UI makes that work legible and steerable.
+
+## Start with the shared taxonomy
+
+- **AI-enabled software:** application code owns the control loop and calls a model as one capability.
+- **Agent-Operated Workflow:** an agent owns one bounded procedure with a start and stop condition;
+  see `agent-operated-workflows`.
+- **Agent-Operated Software:** agents participate in an ongoing application's functioning runtime.
+
+An application may compose many Agent-Operated Workflows. A bounded workflow does not by itself make
+its surrounding product Agent-Operated Software, and a model call is neither category unless an agent
+owns part of the control loop.
+
+## Agents are part of the backend
+
+In this architecture, behavior is not located only in functions. It is distributed across agents,
+skills, instructions, bootstrap files, schemas, Markdown, YAML, JSON, folders, and deterministic
+tools. A surprising result may therefore be a code defect or a coherence gap in this control plane.
+Trace the path that actually produced the behavior before choosing which layer to repair.
+
+This is not permission to tolerate defects in OpenRig core or another rock-solid substrate. There,
+reproduce the bug, fix the code, and hold the full gate. The faster coherence-first posture belongs
+to recoverable agent-operated application layers whose state and behavior can be inspected and
+repaired cheaply.
+
+## Markdown is the control plane
+
+Markdown is maximally useful to an agent while remaining legible enough for a human to steer. Put
+intent, work state, evidence, and decisions into stable addressed artifacts rather than private chat
+or an opaque custom database. Keep schemas and conventions aligned with the running behavior: the
+agent population acts on those files as executable context.
+
+Use **progressive disclosure**. A skill's name and description are the hot trigger; its body is cold
+procedure. Descriptions say when to load, not how to work. The body should route the reader to exact
+sources instead of copying them into another doctrine fork.
+
+Scripts can act as prompts. A good script returns the context or exact effect an agent needs; when it
+cannot, its failure teaches what it observed, why it stopped, and safe next actions. Keep deterministic
+mechanics in tools and judgment in agents.
+
+## Make artifacts self-certifying
+
+When a tool produces an artifact, do not make every consumer invent a completeness test:
+
+1. Write to a partial path, never the final path.
+2. Verify the property that can actually be wrong, such as duration, streams, resolution, or schema.
+3. Flush and atomically rename the partial artifact to its final path.
+4. Write the manifest, then a `.done` sentinel last.
+
+Consumers fail closed on the shared proof. A filename or exit code is not content verification.
+
+## Build with an agent SDLC
+
+Map work onto **intent -> plan -> spec -> build -> verify -> review -> QA -> done**. The human supplies
+steering, judgment, taste, and the call on irreversible ambiguity; agents perform and coordinate the
+technical work. Locks freeze the agreed spec and accepted delivery so multiple seats can work without
+guessing whether the target moved.
+
+For studio applications, the running product is usually the best iteration surface. A separate mockup
+earns its cost only when it resolves a real design uncertainty that the running app cannot expose as
+cheaply. This removes a redundant artifact, not the visual review or proof contract.
+
+## Repair the narrowest authoritative layer
+
+Find the generator or source that every affected agent actually consumes. Fix a code defect in code;
+fix a missing trigger in the skill; fix a malformed contract in its schema. Then verify through the
+consumer. Editing a rendered or installed copy creates a temporary fork, not a repair.
+
+The payoff compounds: a correction to the shared application control plane changes the next agent's
+starting point. That is how an ongoing agent-operated system improves without making one human its
+permanent router.

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

@@ -0,0 +1,79 @@
+---
+name: agent-operated-workflows
+description: >-
+  Use when a bounded real-world procedure has a deterministic happy path but brownfield, variable,
+  or partially knowable state; when an operation must resume from verified evidence; or when deciding
+  whether agent judgment or ordinary code should own a procedure's control loop.
+metadata:
+  openrig:
+    stage: provisional
+    audience: any agent operating or designing a bounded procedure
+    sibling_skills:
+      - agent-operated-software
+      - openrig-user
+      - systematic-debugging
+---
+
+# Agent-Operated Workflows
+
+An **Agent-Operated Workflow** is a bounded procedure whose control loop belongs to an agent. The
+agent observes, interprets, sequences bounded actions, verifies their effects, adapts, and escalates
+genuine ambiguity. Deterministic code remains the exact substrate; it does not pretend to understand
+every state of a brownfield world.
+
+## Name the architecture before using it
+
+- **AI-enabled software:** application code owns the control loop and calls a model as one capability.
+- **Agent-Operated Workflow:** an agent owns one bounded procedure with a start and stop condition.
+- **Agent-Operated Software:** an OpenRig agent or rig participates in an ongoing application's live
+  backend or control loop. It may run many workflows; see `agent-operated-software`.
+
+Calling a model is not enough. A deterministic program that consults a model still owns its loop.
+
+## Decide whether the agent earns the loop
+
+Use an agent when the happy path is deterministic but the environment is brownfield, variable,
+partially knowable, or disproportionately expensive to model exhaustively. The judgment is in
+discovering what is true and choosing the next safe act.
+
+Prefer ordinary code when the state space is closed and code is simpler and more reliable than
+judgment. A parser, fixed data transformation, or fully enumerated state machine does not become
+better because an agent drives it.
+
+## Keep ownership explicit
+
+| Owner | Responsibility |
+|---|---|
+| Runbook | owns policy, the mental model, checkpoints, stop conditions, and escalation rules |
+| Deterministic tools | own context gathering and bounded exact actions |
+| Agent | owns interpretation, sequencing, adaptation, and effect verification |
+| Human | owns destructive ambiguity and product policy |
+
+The runbook guides judgment; tools enforce the invariants that must not be arguable.
+
+## Operate
+
+1. Establish identity, durable state, the runbook, and the promised outcome.
+2. Inspect with side-effect-free reads or an explicit plan mode.
+3. Choose one bounded action from observed state; do not mechanically replay the happy path.
+4. Verify the effect at the consumer or state surface that could prove it wrong.
+5. Record an observable checkpoint before moving on, so another agent can resume.
+6. Continue, stop at the declared condition, or escalate with evidence and the decision needed.
+
+An interrupted or timed-out mutation is **indeterminate**, never failed by assumption and never safe
+to retry blind. Where a compatibility period is safer, separate reversible preparation from the
+destructive finalizer. Idempotence is a claim to prove per action, not a label for the whole run.
+
+## Build
+
+Expose composable verbs, not an optimistic end-to-end controller. Help is inert. Read and plan modes
+are explicit. Mutations are narrow and independently readable. A failure should say what was
+observed, why the tool stopped, what remains unchanged, the safe next choices, and where its evidence
+lives. Keep checkpoints durable, effects observable, and recovery possible without private developer
+knowledge.
+
+A capability composition is a reusable recipe; this is the execution architecture that operates
+capabilities toward an outcome. Promote a proven workflow to the composition shelf only after use.
+
+**Reference implementation:** Release 0.5.9 Slice 05 is the first **Agent-Operated Migration**. Its
+runbook and helpers remain there; this skill carries the reusable contract, not a duplicate procedure.

package/daemon/assets/plugins/openrig-core/skills/claude-compaction-restore/scripts/precompact-hook.mjs

@@ -6,7 +6,12 @@ import { spawnSync } from "node:child_process";
 
 const skillRoot = path.resolve(new URL("..", import.meta.url).pathname);
 const restoreScript = path.join(skillRoot, "scripts", "restore-from-jsonl.mjs");
-const outRoot = "/tmp/claude-compaction-restore";
+// P6(C) injectable output-root: the packet base defaults to the shared
+// /tmp/claude-compaction-restore (production), but becomes per-run isolated when the
+// hermetic env-var OPENRIG_COMPACTION_OUT_ROOT is set — so concurrent writers with the
+// same injected clock + sessionId no longer collide on the same `${sessionId}-${stamp}`
+// dir. Mirrors the injectable-clock seam (OPENRIG_TEST_CLOCK_NOW). Empty/absent = /tmp.
+const outRoot = process.env.OPENRIG_COMPACTION_OUT_ROOT || "/tmp/claude-compaction-restore";
 const defaultRestoreInstruction =
   "Read the claude-compaction-restore skill and follow its \"If You Just Compacted\" protocol.";
 
@@ -24,6 +29,14 @@ function getOpenRigHome() {
   return process.env.OPENRIG_HOME || process.env.RIGGED_HOME || path.join(os.homedir(), ".openrig");
 }
 
+// A3-R3 injectable clock (slice 51-01): marker.createdAt defaults to real wall-clock,
+// but becomes deterministic when the shared hermetic env-var OPENRIG_TEST_CLOCK_NOW is
+// set (an ISO instant). Empty/absent = production real-time.
+function nowIso() {
+  const injected = process.env.OPENRIG_TEST_CLOCK_NOW;
+  return typeof injected === "string" && injected.trim().length > 0 ? injected : new Date().toISOString();
+}
+
 function expandInstructionPath(filePath) {
   if (filePath.startsWith("~/")) return path.join(os.homedir(), filePath.slice(2));
   if (filePath.startsWith("${OPENRIG_HOME}/")) {
@@ -41,6 +54,50 @@ function readInstructionFile(filePath) {
   return fs.readFileSync(expanded, "utf8");
 }
 
+// OPR.0.4.1.09 / R5 marker-lifecycle (foreign-content-in-marker face): the hook
+// path must apply the SAME seat-check the daemon enforcer's resolvePostCompactExtra
+// applies (rev1-r2 dcd95bd9), or a FOREIGN seat's global messageFilePath leaks into
+// THIS seat's marker. Parse a WELL-FORMED leading `---` frontmatter for a declared
+// seat (target_seat / seat / session); body text is never scanned; a broken/absent
+// fence is GENERIC (valid for any seat). Byte-mirrors the enforcer regexes.
+function declaredSeatOf(content) {
+  const fm = /^\s*---\s*\n([\s\S]*?)\n---/.exec(content);
+  if (!fm) return null;
+  const m = /^[ \t]*(?:target[_-]?seat|seat|session(?:[_-]?name)?)[ \t]*:[ \t]*["']?([^"'\n#]+?)["']?[ \t]*$/im.exec(fm[1]);
+  return m ? m[1].trim() : null;
+}
+
+function sanitizeSeat(value) {
+  return value.replace(/[^a-zA-Z0-9_.@-]/g, "_");
+}
+
+// Resolve the post-compaction extra FOR THIS SEAT (mirror of the enforcer): (1) prefer
+// a per-seat compaction/post-compact-extra/<seat>.md — no cross-seat contamination
+// possible; (2) fall back to the global ONLY when it does not declare a DIFFERENT seat
+// (a wrong-seat global is REFUSED). Generic/undeclared/configured-but-absent stay
+// allowed. Returns the path to read, or null when nothing valid for this seat.
+function resolveSeatSafeExtraPath(globalFilePathRaw) {
+  const rawSeat = process.env.OPENRIG_SESSION_NAME || process.env.RIGGED_SESSION_NAME || "";
+  const seatKey = rawSeat ? sanitizeSeat(rawSeat) : "";
+  if (seatKey) {
+    const perSeatPath = path.join(getOpenRigHome(), "compaction", "post-compact-extra", `${seatKey}.md`);
+    if (fs.existsSync(perSeatPath)) {
+      const declared = declaredSeatOf(fs.readFileSync(perSeatPath, "utf8"));
+      if (declared && sanitizeSeat(declared) !== seatKey) return null; // wrong-seat per-seat file
+      return perSeatPath;
+    }
+  }
+  const trimmed = (globalFilePathRaw || "").trim();
+  if (!trimmed) return null;
+  const expanded = expandInstructionPath(trimmed);
+  // configured-but-absent: keep the path (an absent file cannot be a wrong-seat leak;
+  // readInstructionFile returns "" so nothing is appended).
+  if (!fs.existsSync(expanded)) return trimmed;
+  const declared = declaredSeatOf(fs.readFileSync(expanded, "utf8"));
+  if (declared && sanitizeSeat(declared) !== seatKey) return null; // foreign-seat global REFUSED
+  return trimmed;
+}
+
 function sessionKey(input) {
   const raw = [
     process.env.OPENRIG_SESSION_NAME,
@@ -58,12 +115,28 @@ function pendingMarkerPath(input) {
   return path.join(getOpenRigHome(), "compaction", "restore-pending", `${sessionKey(input)}.json`);
 }
 
+// R5 absent-when-needed: drop a lightweight EXPECTED sentinel FIRST (before the packet is
+// generated + the marker is written), carrying the SAME identity binding the marker gets.
+// Its presence-without-a-marker is what lets the bridge be LOUD about a missing packet
+// (hook died partway / write failed); policy off = no hook = no sentinel = silent.
+function writeExpectedSentinel(input) {
+  const p = path.join(getOpenRigHome(), "compaction", "restore-pending", `${sessionKey(input)}.expected.json`);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, `${JSON.stringify({
+    version: 1,
+    sessionName: process.env.OPENRIG_SESSION_NAME || process.env.RIGGED_SESSION_NAME || null,
+    sessionId: input.session_id || input.sessionId || null,
+    transcriptPath: input.transcript_path || null,
+    createdAt: nowIso(),
+  }, null, 2)}\n`, "utf8");
+}
+
 function writePendingRestoreMarker(input, parsed, restoreInstruction, customMessage) {
   const markerPath = pendingMarkerPath(input);
   fs.mkdirSync(path.dirname(markerPath), { recursive: true });
   const payload = {
     version: 1,
-    createdAt: new Date().toISOString(),
+    createdAt: nowIso(),
     sessionName: process.env.OPENRIG_SESSION_NAME || process.env.RIGGED_SESSION_NAME || null,
     sessionId: input.session_id || input.sessionId || null,
     transcriptPath: input.transcript_path || null,
@@ -118,13 +191,18 @@ function readClaudeCompactionMessage() {
     parts.push(`Inline restore instruction:\n${inline}`);
   }
   if (filePath && filePath.length > 0) {
-    try {
-      const fileText = readInstructionFile(filePath);
-      if (fileText) {
-        parts.push(`Additional restore instruction file (${filePath}):\n${fileText}`);
+    // R5 seat-check: resolve to the per-seat extra or a seat-safe global; a
+    // foreign-seat global resolves to null and is never injected into this marker.
+    const resolved = resolveSeatSafeExtraPath(filePath);
+    if (resolved) {
+      try {
+        const fileText = readInstructionFile(resolved);
+        if (fileText) {
+          parts.push(`Additional restore instruction file (${resolved}):\n${fileText}`);
+        }
+      } catch {
+        // Keep any inline instruction; unreadable extra files degrade quietly.
       }
-    } catch {
-      // Keep any inline instruction; unreadable extra files degrade quietly.
     }
   }
   if (parts.length > 0) return parts.join("\n\n");
@@ -140,7 +218,16 @@ function buildSystemMessage(restoreInstruction, customMessage) {
 }
 
 try {
+  // Slice 51-01 RIDER (leak-visibility, review-r1 escalation): OPENRIG_TEST_CLOCK_NOW is
+  // read by nowIso() to make createdAt deterministic in tests — but a LEAKED var in a
+  // real seat would silently FREEZE production createdAt. Announce loudly on stderr when
+  // active so any leak is visible in seat logs; absence stays silent (production path).
+  // MUST stay byte-identical to STUB_CLOCK_ANNOUNCEMENT in stub-runner.ts.
+  if (typeof process.env.OPENRIG_TEST_CLOCK_NOW === "string" && process.env.OPENRIG_TEST_CLOCK_NOW.trim().length > 0) {
+    process.stderr.write("OPENRIG_TEST_CLOCK_NOW active — timestamps are injected\n");
+  }
   const input = readHookInput();
+  writeExpectedSentinel(input); // R5: sentinel FIRST, before the packet + marker (catches hook-died-partway)
   const args = [restoreScript, "--out", outRoot, "--json"];
   if (input.cwd) args.push("--cwd", input.cwd);
   if (input.transcript_path && input.transcript_path.endsWith(".jsonl") && fs.existsSync(input.transcript_path)) {

package/daemon/assets/plugins/openrig-core/skills/claude-compaction-restore/scripts/restore-from-jsonl.mjs

@@ -423,8 +423,16 @@ function restoreInstructions(summary, outputPaths) {
   return lines.join("\n");
 }
 
+// A3-R3 injectable clock (slice 51-01): the packet output-dir timestamped path
+// defaults to real wall-clock, but becomes deterministic when the shared hermetic
+// env-var OPENRIG_TEST_CLOCK_NOW is set (an ISO instant). Empty/absent = production.
+function nowIso() {
+  const injected = process.env.OPENRIG_TEST_CLOCK_NOW;
+  return typeof injected === "string" && injected.trim().length > 0 ? injected : new Date().toISOString();
+}
+
 function writeOutputs(summary, outRoot) {
-  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const stamp = nowIso().replace(/[:.]/g, "-");
   const base = path.join(outRoot, `${summary.sessionId ?? "unknown-session"}-${stamp}`);
   fs.mkdirSync(base, { recursive: true });
 

package/daemon/assets/plugins/openrig-core/skills/forming-an-openrig-mental-model/SKILL.md

@@ -24,8 +24,8 @@ metadata:
       - openrig-builder
       - openrig-architect
       - openrig-upgrade
-      - ai-dev-workflows
-      - software-for-agents
+      - agent-operated-workflows
+      - agent-operated-software
 ---
 
 # Forming an OpenRig Mental Model

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

@@ -13,7 +13,7 @@ You're running inside OpenRig. OpenRig ships a set of **skills** — small docum
 
 ## How OpenRig context works (30 seconds)
 
-Skills are **progressive disclosure**: a skill's *name + description* sit in your context ambiently (the "hot tier"); its *body* loads only when you open it. So you don't pre-read everything — you pattern-match a skill's "when" to your moment, then open just that one. This file is the index over the whole shipped set. (For the full model of building/operating agent software, open `software-for-agents`.)
+Skills are **progressive disclosure**: a skill's *name + description* sit in your context ambiently (the "hot tier"); its *body* loads only when you open it. So you don't pre-read everything — you pattern-match a skill's "when" to your moment, then open just that one. This file is the index over the whole shipped set. (For bounded procedures, open `agent-operated-workflows`; for ongoing agent-backed applications, open `agent-operated-software`.)
 
 Every row below names **how to reach the skill** — already-hot, or an exact load path. No row is a dead end.
 
@@ -63,7 +63,9 @@ These are auto-delivered to every rig; their name+description are already in you
 - **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.
 - **messaging-the-human** — composing a message to the human. Plain language, no insider jargon.
-- **software-for-agents** — you want the full first-load model of how agent software is built and operated here.
+- **agent-operated-workflows** — a bounded real-world procedure needs an agent to interpret state and operate exact tools, or you are deciding whether ordinary code should own the loop.
+- **agent-operated-software** — you are designing or operating an ongoing application whose live backend includes OpenRig agents.
+- **software-for-agents** — compatibility redirect for the former `agent-operated-software` name; remove in 0.6.0.
 - **openrig-skills** — this index (you're reading it). Always loaded; the entry point to everything below.
 
 ### Load when your role or task calls for it (repo-shipped, profile-selected)

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

@@ -175,7 +175,7 @@ section.
 
 ### Instantiate the canonical workspace scaffold
 
-Agent-actionable. Idempotent on existing dirs without `--force`.
+Agent-actionable. The operation is additive and preserves existing files.
 
 ```bash
 rig config init-workspace
@@ -187,19 +187,15 @@ rig config init-workspace --dry-run --json
 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.
+- `exhaust/` — project-local coordination exhaust
+- `SPEC.md` — project intent
+- `project.yaml` — project catalog selections and mission root
+- `workspace.yaml` — project registration
+- `.gitignore` — local OpenRig state and exhaust exclusions
+
+`--root <path>` targets a non-default root for this call; `--dry-run` reports
+what would be created without writing. `--force` is deprecated compatibility
+and still preserves existing files.
 
 ### Redirect the workspace root
 
@@ -235,8 +231,8 @@ Agent-actionable. Same surface as the canonical scaffold above; the
 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
+The command additively creates any missing canonical entries and preserves
+every existing one; only a complete six-entry scaffold is a no-op. Run
 `rig workspace validate /path/to/new/workspace --json` after to confirm the
 contract holds.