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.

$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. 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:

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.

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.

Config updates publish a complete replacement file atomically where directory permissions and the filesystem allow it. On POSIX systems, replacement preserves the existing owner, group, and read/write/execute permission bits. If creating or preparing the replacement, or renaming it, fails with EACCES, EPERM, or EBUSY, the stores write the writable target in place, preserving compatibility with unwritable directories and single-file bind mounts. This fallback is not atomic and retains the previous partial-write risk. Read-only config files are refused. Other errors, including ENOSPC, leave the original file intact on the atomic path. Atomic replacement does not carry extended ACLs or other inode metadata; a hard-linked second name continues to refer to the previous file.