@openrig/cli 0.5.8 → 0.5.9

package/daemon/docs/reference/project-workspace.md

@@ -4,6 +4,9 @@ OpenRig's Project TUI is a file-backed view over a workspace root. The folder
 shape is intentionally simple so humans and agents can create or repair it
 without daemon-internal knowledge.
 
+This subtree is part of the wider [OpenRig Instance Layout](instance-layout.md).
+The instance initializer delegates these exact workspace bytes to this owner.
+
 ## Default Shape
 
 `rig config init-workspace` creates the default workspace at
@@ -11,48 +14,70 @@ without daemon-internal knowledge.
 
 ```text
 workspace/
-  README.md
-  STEERING.md
+  SPEC.md
+  project.yaml
+  workspace.yaml
+  .gitignore
   missions/
-    README.md
-    idea-ledger/
-      SPEC.md
-      NOTES.md
-      PROGRESS.md
-      slices/
-        capture-product-ideas/
-          SPEC.md
-          PROGRESS.md
-          PROOF.md
-          proof/
-        triage-product-ideas/
-          SPEC.md
-          PROGRESS.md
-          PROOF.md
-          proof/
-    handoff-loop/
-      SPEC.md
-      NOTES.md
-      PROGRESS.md
-      slices/
-        route-work-packets/
-          SPEC.md
-          PROGRESS.md
-          PROOF.md
-          proof/
-        verify-loop-evidence/
-          SPEC.md
-          PROGRESS.md
-          PROOF.md
-          proof/
-  progress/
-  field-notes/
-  specs/
+  exhaust/
+```
+
+The scaffold is additive: it creates missing canonical entries and never
+overwrites existing files, including with the deprecated `--force` flag.
+`exhaust/` and local `.openrig/` runtime projections are ignored; authored
+project context and mission/slice files remain versionable. `workspace.yaml`
+is the project-location catalog. The project manifest exposes empty
+`install.context` and `install.skills` selectors for ordered Markdown
+addresses and stable managed-catalog skill IDs, but neither skill source nor a
+System World belongs in this tree.
+
+## Project-world install
+
+`project.yaml` may select project context and managed skills together:
+
+```yaml
+schema: openrig.project/v0alpha1
+kind: project
+install:
+  intent: SPEC.md
+  context:
+    - conventions.md
+  skills:
+    - repository-maintenance
 ```
 
+`install.context` contains project-relative Markdown addresses. `install.skills`
+contains stable skill identities only. Skill source bytes live in the single
+configured managed catalog (`skills.root`, default `$OPENRIG_HOME/skills`),
+never under the project or workspace. `rig context work-install --runtime
+<claude-code|codex>` resolves both parts; add `--apply-skills` to reconcile the
+selected exact bytes into `.claude/skills/` or `.agents/skills/` under the
+caller's current working directory. Use `--cwd` when the receiving agent works
+somewhere else; the project-world metadata root is never assumed to be its code
+working directory.
+
+The generated harness directories and `.openrig/skill-loadouts/` ownership
+receipts are projections, not source. Product repositories should ignore them.
+Reconciliation removes a deselected entry only when its current bytes still
+match OpenRig's last owned projection; unrelated and locally modified entries
+are preserved or reported as conflicts.
+
+Seats of the same runtime commonly share one working directory. Their topology
+selectors are retained per canonical seat identity and projected as a union, so
+starting one role cannot remove another role's skill. A changed projection is
+visible only to a fresh harness process; reconciliation reports that boundary
+instead of claiming a running seat hot-reloaded it.
+
+An installed project selection is also retained in that working directory's
+ownership receipt. A later seat start with no project-world input preserves it;
+an explicit install whose `install.skills` is empty clears it. This keeps
+"project not supplied" distinct from "project deliberately selects no skills."
+
 ## UI Mapping
 
 - `workspace.root` maps to the Project workspace.
+- `workspace.catalog_path` maps to the `workspace.yaml` project catalog.
+- `workspace.projects_root` is the default home for catalogued project worlds.
 - `workspace.root/missions/<mission-id>` maps to a Project mission.
 - `workspace.root/missions/<mission-id>/slices/<slice-id>` maps to a Project slice.
 - Mission `PROGRESS.md` frontmatter supplies the mission status badge when the
@@ -98,12 +123,13 @@ default setup contract.
 If Project shows a mission discovery warning:
 
 1. Run `rig config get workspace.root --show-source`.
-2. Run `rig config get workspace.slices_root --show-source`.
-3. Confirm `workspace.slices_root` points at a folder containing mission
+2. Run `rig config get workspace.catalog_path --show-source`.
+3. Run `rig config get workspace.slices_root --show-source`.
+4. Confirm `workspace.slices_root` points at a folder containing mission
    directories with `slices/` children.
-4. Confirm `files.allowlist` includes `workspace:<workspace.root>` so the TUI
+5. Confirm `files.allowlist` includes `workspace:<workspace.root>` so the TUI
    can read mission `PROGRESS.md`.
-5. If the workspace is missing, run `rig config init-workspace` after operator
+6. If the workspace is missing, run `rig config init-workspace` after operator
    approval.
 
 No daemon restart is required for most config reads. Restart when changing

package/daemon/specs/agents/shared/skills/core/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/specs/agents/shared/skills/core/openrig-upgrade/SKILL.md

@@ -113,6 +113,87 @@ The helper never deletes a live file and never overwrites a local modification.
 Local deletions, live-only files, target removals, and ambiguous types are
 reported for the agent to resolve. Re-run the plan after any manual resolution.
 
+### Migrate a pre-0.5.9 instance layout
+
+Version 0.5.9 puts context-usage telemetry in
+`$OPENRIG_HOME/state/context-usage`, provider telemetry in
+`state/provider-usage`, the addressable library under `context/`, and the
+default System World at `context/system/system-world.yaml`. Existing 0.5.8
+homes cross that boundary through an **Agent-Operated Migration**: the target
+runtime reads canonical-first with legacy-fallback while all new writes use the
+canonical state roots. An explicitly configured custom context-library root
+stays stable throughout activation.
+
+The helper supplies bounded, inspectable operations. The agent owns their
+sequence and the target-runtime activation between them. With an exact
+protected preimage path, first inspect and then prepare canonical directories,
+the default System World, and a config pin to the existing library. Preparation
+does not copy telemetry, rewrite live collector settings, or run lifecycle
+actions:
+
+`--help` prints the phase grammar without inventorying the instance. With no
+phase flag the helper intentionally runs the read-only plan; unknown options
+fail nonzero before plan or mutation.
+
+```bash
+node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" --help
+
+node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
+  --home "$OPENRIG_HOME"
+
+node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
+  --home "$OPENRIG_HOME" \
+  --apply-state \
+  --preimage "$OPENRIG_HOME/backups/layout-0.5.9-before"
+```
+
+Activate the exact target runtime using the ordinary upgrade workflow. Then
+wait until every bounded post-apply legacy tail is followed by newer paired
+new-root samples for that same seat. This proves temporal convergence
+without blanket process replacement; a later legacy write remains a hard stop.
+Capture the verification JSON; copied old sidecars are not evidence:
+
+```bash
+node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
+  --home "$OPENRIG_HOME" \
+  --verify \
+  --preimage "$OPENRIG_HOME/backups/layout-0.5.9-before" \
+  > /safe/path/layout-0.5.9-verify.json
+```
+
+Only a successful receipt authorizes the separately invoked non-destructive
+finalizer. It copies an unconfigured legacy library into the canonical root
+without overwriting anything; a custom context-library root remains stable:
+
+```bash
+node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
+  --home "$OPENRIG_HOME" \
+  --apply-library \
+  --preimage "$OPENRIG_HOME/backups/layout-0.5.9-before" \
+  --verification /safe/path/layout-0.5.9-verify.json
+```
+
+Stop on every reported issue: malformed or foreign telemetry, a reserved-path
+conflict, a library collision, config drift, resumed legacy writes, byte drift,
+or a missing fresh dual sample all require the named repair before continuing.
+Verification binds the exact accepted tail bytes to their paired-newer samples;
+the finalizer revalidates them immediately before switching config. The helper
+never removes the legacy telemetry or library. Their later retirement is a
+separate agent decision after stable runtime, writer, reader, and recovery proof.
+It does not stop/start the daemon, launch a seat, touch the database, or decide
+whether the upgrade proceeds.
+
+To recover, restore the prior runtime as the agent-led workflow requires, then
+reverse only helper-owned config, System World, empty-directory, and copied
+library effects. Real state samples and both legacy recovery sources remain for
+inspection:
+
+```bash
+node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
+  --home "$OPENRIG_HOME" \
+  --rollback "$OPENRIG_HOME/backups/layout-0.5.9-before"
+```
+
 ## Agent-led continuity upgrade
 
 This is a decision guide, not a command recipe. Adapt paths and checks to the