@openrig/cli 0.5.17 → 0.6.1

package/daemon/context-packs/reference/instance-layout.md

@@ -0,0 +1,106 @@
+# OpenRig Instance Layout
+
+An OpenRig instance keeps its managed state under one configured
+`$OPENRIG_HOME`. `rig daemon start` and direct daemon first start reconcile the
+same additive layout before the database is opened or the listener binds.
+
+```text
+$OPENRIG_HOME/
+  config.json             # typed instance settings; created as an empty object
+  state/                  # runtime-owned durable state
+  context/                # addressable context library (`context.root`)
+    system/
+      system-world.yaml   # selected baseline context + skill identities
+  skills/                 # managed skill catalog (`skills.root`)
+  workspace/              # project work tree (`workspace.root`)
+    SPEC.md                # project intent
+    project.yaml           # project context and skill selection
+    workspace.yaml         # project-location catalog
+    .gitignore
+    missions/
+    exhaust/
+  specs/                  # canonical instance spec library
+  topology/               # instance, rig, pod, and seat continuity tree
+  plugins/                # installed OpenRig plugins
+  run/                    # process coordination files
+  logs/                   # daemon and operation logs
+  transcripts/            # durable per-seat terminal transcripts
+  backups/                # operator-created recovery artifacts
+  secrets/                # local connector and host secrets
+```
+
+The initializer creates only missing managed entries. It never overwrites an
+existing file, and it checks every managed path before the first write. A path
+with the wrong type is reported by its exact location; unrelated user-owned
+content is preserved. A second run against an already-converged instance writes
+nothing.
+
+The workspace subtree is owned by the [Project Workspace
+Contract](project-workspace.md). The instance initializer calls that owner
+rather than carrying another copy of its file bytes. `skills/` and `topology/`
+are created as empty roots; their respective catalog and topology workflows own
+their contents.
+
+## Context library setting
+
+The addressable context library has one typed setting and one environment
+override:
+
+| Surface | Value |
+| --- | --- |
+| Config key | `context.root` |
+| Environment | `OPENRIG_CONTEXT_ROOT` |
+| Default | `$OPENRIG_HOME/context` |
+| Resolved property | `contextRoot` |
+
+The removed `context.packs_root`, `context.packsRoot`, and
+`OPENRIG_CONTEXT_PACKS_ROOT` spellings are refused with guidance to use
+`context.root`; they are not compatibility aliases. Bundle installation and
+`rig context add` both resolve the same configured landing root.
+
+## System World
+
+The System World is the instance-wide baseline selected before topology/role
+and Project World material. Its versioned manifest contains ordered context-pack
+references plus managed skill identities; it never contains authoritative skill
+bytes. The default manifest is installed additively at
+`$OPENRIG_HOME/context/system/system-world.yaml`.
+
+| Surface | Value |
+| --- | --- |
+| Config key | `context.system_world` |
+| Environment | `OPENRIG_CONTEXT_SYSTEM_WORLD` |
+| Default | `default` |
+| Resolved property | `systemWorld` |
+
+`default` selects the installed manifest, a safe relative or absolute path
+selects an explicit replacement, and `disabled` is an explicit off state.
+Missing or malformed selections fail; absence is never inferred as disablement.
+`rig context work-install --json` reports the effective state, source, manifest,
+context selectors, and skills. With `--runtime`, its managed skill loadout then
+combines System World, topology, and Project World selectors with provenance.
+
+For a pre-0.5.9 home, use the `openrig-upgrade` skill's
+`migrate-telemetry-state-0.5.9.mjs` helper as an Agent-Operated Migration. Its
+order is plan → `--apply-state` → separately activate the target runtime →
+paired new-root samples newer than any bounded legacy tail → `--verify` → the
+non-destructive finalizer `--apply-library`. During activation, runtime readers
+are canonical-first with legacy-fallback and a custom context-library root
+remains stable. Verification binds exact accepted tail bytes; finalization
+revalidates them, copies without overwrite, and switches config last. It never
+removes the legacy telemetry or library. `--rollback` reverses only helper-owned
+config, System World, empty-directory, and copied-library effects. The helper
+must stop rather than claim success if writer/reader convergence, resumed legacy
+writes, byte drift, collision, or any migration-owned path cannot be proved.
+`--help` prints the phase grammar without inventorying; no phase flag is the
+intentional read-only plan, and unknown options fail nonzero before plan or
+mutation.
+
+## Existing spec libraries
+
+Creating `$OPENRIG_HOME/specs` does not migrate existing launch-era specs.
+Upgraded installations may still have a separate legacy specs library that the
+runtime reads for compatibility. Treat the two-home state as an explicit
+limitation: use the live spec-library commands to determine where a spec is
+served from, and do not infer convergence merely because the canonical
+directory exists.

package/daemon/context-packs/reference/manifest.yaml

@@ -0,0 +1,16 @@
+# Reference guides the help pack links to, loaded one file or section at a time by address
+# (rig context get reference/<file>#<section>). Each file is a symlink to docs/reference/.
+name: reference
+version: "0.6.1"
+taxonomy: world
+purpose: "Version-matched reference guides the help guide links to. Load a single file or section by address; don't load the whole pack."
+files:
+  - path: getting-started.md
+    role: reference
+    summary: "Getting started: setup, first team, recovery after a reboot, and permissions."
+  - path: instance-layout.md
+    role: reference
+    summary: "Where an OpenRig instance keeps its files and configuration."
+  - path: rig-spec.md
+    role: reference
+    summary: "The rig specification format."