# Configuration

Documented against OpenRig 0.5.14. Help text uses "node" where these pages say **seat**, for a seat's position in the running rig.

## What it is for

Most of what looks fixed about OpenRig is a typed setting: where the work tree lives, how often snapshots are taken, when a seat counts as stalled, the context-pressure thresholds that raise a health finding. `rig config` with no arguments prints every key, its current value and where that value came from. Resolution is CLI flag, then environment variable, then config file, then default, and `--with-source` names the winner per key. A source of `default` means derived on this machine, not a universal constant; paths in particular differ per installation.

Permission posture is a different thing. OpenRig records a posture into the rig spec and never enforces allow, ask or deny at runtime; the harness's own permission settings are the control surface. `rig policy` teaches and records that posture. `rig mode` inspects and sets the scoped operating posture, human-led or delegated, and grants no authority by itself.

## The three commands you will use first

**See everything, with provenance.**

```
rig config
rig config --with-source
rig config --json
```

**Read or change one key.** Use the key instead of hardcoding a path.

```
rig config get daemon.port
rig config get workspace.root --show-source
rig config set snapshots.periodic.interval_seconds 600
rig config reset snapshots.periodic.interval_seconds
```

**Scaffold a workspace.** `rig config init-workspace` lays down the canonical project scaffold additively on a machine that has none.

```
rig config init-workspace
```

## Every configuration key

The full key table is generated from the running binary and lives in the generated reference: **see generated/config-keys.md** (67 keys, with type, reported default and the source layer that won on the generation host). Defaults that are host-derived paths or names are redacted there on purpose; document them as derived, never as constants.

## The config family

[//]: # (table:start)
| Command | What it does (from help) | Help source |
|---|---|---|
| `rig config` | Inspect and change OpenRig configuration | config.txt |
| `rig config get` | Read a single config value | config.get.txt |
| `rig config init-workspace` | Scaffold a repo-ready project workspace | config.init-workspace.txt |
| `rig config reset` | Clear a config override (or delete the entire file when no key given) | config.reset.txt |
| `rig config set` | Set a config value | config.set.txt |
| `rig mode` | Inspect and explicitly set scoped operating posture (human-led/delegated) and operator-context modes. | mode.txt |
| `rig mode cite` | Emit a citation line for the effective mode at a read context. Per convention §Citation Rules. | mode.cite.txt |
| `rig mode defaults` | Print the recommended per-mode 8×7 + default-scope + stale rule. | mode.defaults.txt |
| `rig mode effective` | Inspect effective operating posture, scope, phase and source. Resolved unset scopes default to human-led; unreadable or ambiguous identity stays unknown. | mode.effective.txt |
| `rig mode set` | Propose a mode binding. Without --confirm, restates the proposed binding and exits 2 (no daemon write). With --confirm, sets it. | mode.set.txt |
| `rig mode show` | List all operator-context-mode bindings. | mode.show.txt |
| `rig mode unset` | Delete one binding (operator-only). Scope: global_host  /  rig  /  project  /  mission  /  workstream  /  qitem. | mode.unset.txt |
| `rig policy` | Teach and record the rig-level permission policy. OpenRig bakes NO allow/ask/deny permission policy , the harness-native permissions are the control surface. OpenRig records posture into RigSpec; harness-native permissions enforce , never runtime enforcement. (The context-mode verb formerly at this name is now: rig mode.) | policy.txt |
| `rig policy apply` | Record a policy choice into an EXISTING rig spec (the same recording flow as `rig setup --policy`, which stays as the setup-step composition). OpenRig bakes NO allow/ask/deny permission policy , the harness-native permissions are the control surface. OpenRig records posture into RigSpec; harness-native permissions enforce , never runtime enforcement. | policy.apply.txt |
| `rig policy current` | Show the EFFECTIVE permission policy for a rig spec and what would apply, per site (rig + member overrides), through the authoritative validator/resolver. | policy.current.txt |
| `rig policy list` | List the built-in permission-policy templates, plus the custom policies visible in a spec context. OpenRig bakes NO allow/ask/deny permission policy , the harness-native permissions are the control surface. OpenRig records posture into RigSpec; harness-native permissions enforce , never runtime enforcement. | policy.list.txt |
| `rig policy show` | Show one built-in policy choice, or validate + open a CUSTOM policy spec by ref (relative to --spec's directory, else cwd). | policy.show.txt |

[//]: # (table:end)

## What it does not do

- It does not grant or deny permissions. `rig policy` records posture; the harness enforces.
- `rig mode set` without `--confirm` only restates the proposed binding and exits 2; nothing is written.
- Changing startup-time roots (the files allowlist, progress scan roots) needs a daemon restart; most other keys do not.
- A reported default is what this installation derived. Do not copy it into another machine's docs as a constant.

## Where it goes next

- [Troubleshooting](/docs/troubleshooting): what to check when the daemon and the CLI disagree about where the work tree is.
- [The terminal UI](/docs/tui): the `system` and `config` views browse the same keys.