cli-reference.md

# Nimbus CLI Reference

Complete reference for all `nimbus` commands. For installation see [`README.md`](./README.md). For architecture context see [`architecture.md`](./architecture.md).

**Three ways to use Nimbus interactively:**

- [`nimbus tui`](#nimbus-tui) — rich Ink terminal UI (5 panes, streaming result, inline mid-stream HITL, live connector + watcher + sub-task panes). Auto-falls back to the REPL on unsuitable terminals.
- [`nimbus repl`](#nimbus-repl) — line-based readline loop for scripts, SSH, CI, and other headless environments. `nimbus` with no arguments on an interactive shell is an alias.
- `nimbus <command>` — one-shot commands documented below (`ask`, `search`, `query`, `run`, `status`, `doctor`, `diag`, …).

---

## Global Flags

These flags are accepted by most commands, which silently ignore any dash-argument they do not define. Five surfaces are the exception and hard-reject an unrecognised flag: `nimbus search` (throws on any argument starting with `-`), `nimbus glossary`, `nimbus update` (which rejects anything other than `--check` / `--yes` / `-y`), `nimbus deploy annotate`, and `nimbus tribal capture`.

| Flag | Description |
|---|---|
| `--help`, `-h` | Print command help and exit |
| `--version`, `-v` | Print Nimbus version and exit |
| `NO_COLOR` (env var, not a flag) | Disable ANSI colour output. There is no `--no-color` flag. |
| `--json` | Machine-readable JSON output — **per-command**, not global. Only the commands whose Options table or examples list it change their output; anywhere else it is silently ignored (top level, `--json` only suppresses the interactive banner). |
| `--demo` | Run this command against the isolated **demo root** (`<data dir>/demo`) instead of your real install: its own config, data and logs, plus a separate IPC endpoint and an in-memory (never-persisted) vault in place of the OS credential store. Global — stripped before the command runs, so `nimbus --demo status` runs `status`. Equivalent to `NIMBUS_DEMO=1`. The demo root starts empty. See invariant I41. |

### The `--json` contract

Every command that documents `--json` obeys the same four rules, so a script can rely on them without
reading the command's implementation:

1. **stdout is the document, and nothing else.** With `--json`, stdout carries exactly one JSON value
   (pretty-printed, 2-space indent) — no banner, no table, no empty-state hint, no progress line. `nimbus <cmd> --json | jq` always works.
2. **Diagnostics go to stderr.** Warnings, hints, and degradation notes are written to stderr, never
   mixed into the document.
3. **Exit codes are unchanged by `--json`.** A command that exits `1` on a finding (e.g. `nimbus db verify`) still does so. A command that *fails* prints its error to stderr, exits non-zero, and emits **no JSON at all** — check the exit code, not the presence of output. This covers failures raised before the command can build a document at all, including the one most likely to bite a monitoring script: `nimbus status --json` against a **stale state file** whose socket has no listener. Connecting to the socket throws (`connect ENOENT` / `ECONNREFUSED`) before any JSON exists, so stdout stays empty and the process exits `1` — exactly as `nimbus status` without `--json` does. Do not expect a `running: false` document there.
4. **The shape is the gateway's own payload, unwrapped.** There is no `{ ok, data }` envelope: list commands emit a JSON array, single-result commands a JSON object, with the gateway's own field names. Pre-rendered human strings (the `formatted` blob some gateway methods return) are dropped rather than embedded.

---

## Getting Started

### `nimbus init`

Index the git repository in the current directory. Needs no credentials, no API key, and no LLM.

```bash
cd ~/code/your-project
nimbus init
nimbus init --no-sync           # Write the config only; do not start or sync
nimbus init --no-detect         # Skip the offer to reuse existing gh/aws/kubectl/gcloud logins
nimbus init --help              # Usage and the exit-code table
```

What it does:

1. Verifies the current directory is a git repository (exits 1 if not, writing nothing).
2. **Appends** a `[[filesystem.roots]]` block for it to `nimbus.toml` with `git_aware = true` and `code_index = true`. Appending — never rewriting — is deliberate: it cannot reorder keys, strip comments, or reformat anything you wrote. An existing file is copied to `nimbus.toml.bak` first.
3. Starts the Gateway if it is not already running, then syncs the `filesystem` connector.
4. On a successful index, offers to reuse any local `gh`/`aws`/`kubectl`/`gcloud` login it finds — the same
   walk as [`nimbus connector detect`](#nimbus-connector-detect): interactively in a terminal, or a
   one-line count of what it found on a non-TTY shell (nothing is adopted there). Skip it with
   `--no-detect`; it also never runs under `--no-sync` (no gateway was started), in demo mode, or
   with `CI=true` set.
5. Prints a real `file:line` from your own repository to try with [`nimbus why`](#nimbus-why).
6. On a TTY (both stdin and stdout), after step 4, asks `Run the tour now?` (default yes) and runs
   [`nimbus wow`](#nimbus-wow) in-process, sharing the same terminal and streams. The offer is made
   only when step 5 actually found a `file:line` target — a repository the index has nothing to
   show for gets the `nimbus wow` next-step line only, since `nimbus wow`'s own tour reads the
   same substrate step 5 just read and would otherwise open by telling you to run `nimbus init`
   again. It is also skipped with `CI=true` set, the same guard step 4 uses, since a CI runner that
   allocates a TTY would otherwise hang on the prompt. Any failure of the tour — a "no" is not
   one — prints a one-line hint, ``Run `nimbus wow` any time for a guided tour of what was just
   indexed.``, and never changes `init`'s own exit code. On a non-TTY shell, after a "no" answer,
   or when the offer is skipped, nothing extra is printed here: the closing `Try it:` / `Next:`
   block (step 5) already ends with `nimbus wow` on its own last line. `--no-sync` never offers
   it — no gateway was started, so there is nothing to tour. Output order on a TTY run that says
   yes: the `Try it:` block (step 5, with its `file:line`) prints before the offer, so that line
   sits above the tour's own output rather than scrolling past it.

Re-running is safe and idempotent — a root that is already configured reports `Already configured` and is not duplicated.

Exit codes:

| Code | Meaning |
| --- | --- |
| `0` | The repository was indexed. A concrete `nimbus why` target may or may not have been found — if the index had nothing to suggest yet, `init` says so and prints the generic next step. |
| `1` | The current directory is not a git repository. Nothing was written. |
| `2` | The Gateway never became ready, so **nothing was indexed**. The failure names what happened, inlines the tail of the gateway log, and tells you what to run next. |
| `3` | The Gateway is reachable but this repository was still not indexed — the `filesystem` sync failed, or a Gateway that is already running has to be restarted before it can see the new root. |

A failed guided tour cannot turn a successful `init`'s exit `0` into anything else — the tour offer runs entirely after the exit code for indexing has already been decided.

Two behaviours worth knowing:

- **If a Gateway is already running**, it cannot see a root that was just added: filesystem roots are read once at startup. `nimbus init` says so and asks you to `nimbus stop && nimbus start` rather than syncing nothing or restarting your daemon for you (exit `3`).
- **The config edit is the durable half of the work** and survives every failure above — a second `nimbus init` after fixing the Gateway will not duplicate it. What does *not* survive is the pretence that the command succeeded: a run that indexed nothing exits non-zero and never prints a next step it cannot back up.

`NIMBUS_CONFIG_DIR` overrides the config directory this command writes to (the Gateway honours the same variable). It moves the config directory only — never the data directory.

`NIMBUS_GATEWAY_SOCKET` overrides the IPC socket/pipe path and is honoured by **both** the CLI and the Gateway. It is deliberately a separate variable from `NIMBUS_CONFIG_DIR`: one variable moving both would let a test-isolation mistake silently reroute live IPC. Note it does **not** move the data directory either, so a Gateway started with it still reads and writes the real index.

---

### `nimbus wow`

A guided tour of **whatever index the gateway it talks to holds** — `nimbus wow` has no seed path of its own. On your real install that is your own indexed data; under the global `--demo` flag (`nimbus --demo wow`) it is the synthetic Acme org `nimbus demo` seeds, and the tour's own `command` strings render as `nimbus --demo …` in that case. Up to six deterministic, per-kind selectors (`oncall` / `why` / `owners` / `standup` / `decisions` / `glossary`) each ask "is there something in this index worth showing, and with what arguments?" against whichever substrate is live, run the winning ones through the same agent CLI commands you would type yourself, then close on a locality panel: which listeners are open right now, what the index holds, and how much left the machine while the tour ran.

```bash
nimbus wow
nimbus wow --steps 5
nimbus wow --no-proof
nimbus wow --json
```

**Options:**

| Flag | Description |
|---|---|
| `--steps <n>` | How many of the offerable steps to run, `1`–`6`. **Refused, never clamped**, outside that range (exit `2`) — both here and in the gateway's own `tour.plan` handler, so a client-side bypass would only be caught a round-trip later. Default `3`. |
| `--no-proof` | Skip the closing locality panel (and the `egress.proveWindow` call it would have made). The tour's step headers still count correctly without it — `[1/3]` rather than `[1/4]`, since the panel no longer occupies a slot. |
| `--json` | Emit `{ plan, locality }` — the raw `tour.plan` and `locality.report` results — instead of running anything. **No tour step runs and no proof call is made** in this mode; it is a plan-and-panel-data dump, not a dry run of the human output. |

Any other flag is refused (exit `2`), same as an out-of-range `--steps`.

**What "worth showing" means, per step:** `oncall` needs an indexed incident; `why` needs an indexed symbol under a configured `[[filesystem.roots]]` path; `owners` needs at least one indexed directory with at least one indexed file beneath it — it PREFERS a non-root directory over the configured root itself, falling back to the root only when no non-root candidate has any files under it; `standup` needs activity attributed to you (via `resolveSelfPerson`, below) in the last 24 hours; `decisions` needs an extracted decision in the last 90 days; `glossary` needs a consolidated term. A kind with nothing to show is skipped, never padded with an empty brief — the tour prints `Not shown: <kind> (<reason>)` for each, and any offerable step beyond `--steps` is listed under `Also try:` with its exact command.

**An empty plan is not an error.** If none of the six kinds has anything to offer — the most common reason being a fresh gateway with nothing indexed yet — `nimbus wow` prints a pointer to [`nimbus init`](#nimbus-init) and exits `0`. No locality panel, no proof call: there is nothing yet to be honest about.

**Exit codes:** `0` when every step that ran succeeded (or the plan was empty, `--help`/`-h` was given, or `--json` was used). `1` when any step failed, **or** when the closing `egress.proveWindow` call itself fails — either way, the locality panel (unless `--no-proof`) and the skip/more lists still print first, since a failed step or a failed proof call must never hide the tour's own disclosures. A failed proof call does not discard the locality report already in hand: the panel still prints in full, with `proof unavailable — the egress.proveWindow call failed: <message>` under the outbound-activity heading — a distinct fact from the chain-unverifiable "indeterminate" line `formatProveResult` renders when the call itself succeeds, never routed through it and never carrying a count. `2` on a bad argument (`--steps` outside `1`–`6`, a missing `--steps` value, or an unrecognised flag) — refused before any gateway call.

The panel itself opens with its own rule-line header (the same shape a step's own header renders, minus the `$ command` line beneath it), so on the default 3-step tour the panel reads `── [4/4] Where your data is`.

**`nimbus wow` diverges from `nimbus prove` / `nimbus egress` on a degraded ledger.** When the
`egress.proveWindow` call itself succeeds but reports the chain unverifiable or the count
indeterminate, `formatProveResult` renders the same `indeterminate — cannot prove zero egress: …`
line under the panel's outbound-activity heading either way — but `nimbus wow` does **not** look at
`verify.ok` / `completeness.indeterminate` when deciding its own exit code, so it still exits `0` in
that state as long as every tour step ran. `nimbus prove` and `nimbus egress` both exit `1` in the
identical state (`window.verify.ok === false || window.completeness.indeterminate`). A script that
must gate on ledger health should use `nimbus egress verify`, not `nimbus wow`'s exit code.

**The proof line is a time window, not attribution.** The window is exactly `{since: plan.t0, until: locality.t1}` — `t0` is the gateway's own clock when `tour.plan` ran, `t1` is its clock when `locality.report` ran, and both are gateway-side values, never `Date.now()` computed in the CLI. It answers "how much left this machine, gateway-wide, while the tour was running" — **not** "how much this tour's own three commands sent." A concurrent sync, a background fleet run, or another client's `nimbus ask` during the same window would show up on the same line, and the panel does not (and cannot) separate them out. `nimbus prove --sign`, `nimbus egress` and `nimbus egress verify` — named at the foot of the panel — are how to inspect the same window (or a different one) in full.

**IPC:** `tour.plan(params: { steps?: 1..6 })` and `locality.report(params: {})`. Both are **CLI-only**: the `tour` and `locality` namespaces are `FORBIDDEN_OVER_LAN` (I5) and neither method is in the Tauri `ALLOWED_METHODS` (I7 — still 105). Read-only, no HITL, no new egress class — the panel's own proof line is produced by the existing `egress.proveWindow` method, not a new one.

**Three residuals of the locality panel, stated rather than hidden:**

- **A socket opened by a gateway-SPAWNED CHILD PROCESS is not in the registry.** Today that is
  Chromium's DevTools debugging port (`--remote-debugging-port=0`) during a live `nimbus computer`
  browser session — a default-off capability, open only while that session is live, bound to
  loopback. The panel lists the gateway process's own listeners only, which is why its heading
  reads "Listeners the gateway has open right now:" rather than an unqualified "Listeners".
- **`oauth_callback` is transient.** It is registered only for the lifetime of an in-flight OAuth authorization (`auth/pkce.ts`) and unregistered the moment that flow ends, so it will essentially never appear on a `nimbus wow` panel — its absence means no OAuth flow was in progress at that instant, not that the mechanism is broken.
- **Only the Windows named-pipe `ipc` probe reads the server's real state** (`netServer.listening`, live on every call), so an unrequested fault there is reflected immediately. Every other probe — the POSIX `ipc` socket included — reflects registration bookkeeping rather than a liveness check: `http`, `metrics` and `oauth_callback` each return a fixed object for as long as they stay registered; `lan` and `mdns` read only their own `this.instance` / `this.bonjour` field, which nothing but that listener's own deliberate `stop()` clears. In every one of these cases, a listener reports open until its stop path unregisters it — a fault that closes the underlying socket without going through `stop()` is invisible to the panel on all of them.

**Identity for the `standup` step is resolved exactly as [`nimbus standup`](#nimbus-standup) resolves it** — `[user] mePersonId`, then `git config user.email`; **never** the OS username tier `resolveSelfPerson` also supports, since `nimbus standup` itself never reaches it in production. `nimbus wow` and `nimbus standup` cannot disagree about who "me" is.

---

## Demo Sandbox

### `nimbus demo`

```bash
nimbus demo                # recreate the demo root, seed it, tour three briefs and the locality panel
nimbus demo --no-tour      # recreate and seed only — skip the tour
nimbus demo stop
nimbus demo reset
```

Seeds a synthetic "Acme" org — people, issues, commits, pull requests, reviews, CI runs,
deployments, incidents, and chat messages, all with timestamps offset from "now" so the data always
looks current — into the isolated demo root (`--demo` / `NIMBUS_DEMO=1`; see the `--demo` global
flag above and invariant **I41**), then tours three built-in agent briefs against it and closes on
the locality panel. It never touches your real config, data, or vault, and the demo gateway makes
no outbound call of any kind, at boot or afterward (see below).

What plain `nimbus demo` does, in order:

1. Stops any running demo gateway and **recreates the demo root from scratch**. The seeder never
   truncates an already-seeded index — `demo.seed` refuses with `ERR_DEMO_ALREADY_SEEDED` on a
   non-empty one — so re-seeding means removing and rebuilding the whole root, every time, even if
   it already held data.
2. Starts the demo gateway and seeds it once over the CLI-only, LAN-forbidden `demo.seed` IPC
   method, writing the corpus through the same production write APIs a real connector sync would
   use (`upsertIndexedItem`, `insertPerson`, `upsertBlameLines`, `annotateDeployment`, plus the
   ownership/glossary/decisions extraction passes) — never hand-crafted rows.
3. Restarts the demo gateway, so every config-time read (`me`, filesystem roots, the DORA service
   bindings) sees the `nimbus.toml` the seeder just wrote — a live gateway does not re-read those at
   runtime.
4. Unless `--no-tour` is given, tours three agent briefs in order — through the same shared
   `runTour` [`nimbus wow`](#nimbus-wow) uses — each preceded by a `── [n/4] <title>` header naming
   the exact command, printed verbatim before it runs: `nimbus --demo oncall --incident
   pagerduty:PDEMO412`, `nimbus --demo why src/retry/backoff.ts:42`,
   `nimbus --demo owners src/retry`. A backticked command named inside a brief — a `## Gaps`
   remediation such as `nimbus owners --refresh` — is printed as `nimbus --demo owners --refresh`,
   so pasting it reaches the demo gateway, never your real install; one the demo refuses (e.g.
   `nimbus --demo connector sync …`) is refused there with `ERR_DEMO_FORBIDDEN`. The same rewrite
   applies to every agent brief a `--demo` command prints, and only to the printed Markdown:
   `--json` findings are the gateway's bytes, unchanged, and a command written without backticks is
   not recognised.
5. Unless `--no-tour` is given, closes on the `── [4/4] Where your data is` locality panel — the
   **same panel** [`nimbus wow`](#nimbus-wow) prints: which listeners are open right now, what the
   index holds, and a proof line over the exact window `{since: t0, until: t1}`, both gateway-clock
   values — `t0` stamped the moment seeding finished, `t1` stamped when the panel itself ran — so the
   window spans the post-seed restart in step 3. Every egress class reads zero on a demo gateway
   because it is inert (I41, above): nothing here is a claim about a normal install.
6. Prints a closing list of four more commands that work without an LLM: `nimbus --demo standup`,
   `nimbus --demo expert payments`, `nimbus --demo decisions`,
   `nimbus --demo stats deployment-frequency --service payment-service`.

A step that fails, or a failed `egress.proveWindow` call behind the panel, exits `1` — but only
**after** the panel (step 5) and the closing list (step 6) have both printed, the same rule
[`nimbus wow`](#nimbus-wow) follows: a failure must never hide the honesty panel or the closing
suggestions behind it.

`nimbus demo stop` stops the demo gateway without touching the seeded data — for walking away
without losing anything (plain `nimbus demo` re-seeds from scratch on its next run regardless).
`nimbus demo reset` stops it and deletes the whole demo root; nothing else on disk is touched.
All three signal the recorded demo gateway only after its IPC socket answers. A pid that is alive
but whose socket does not is never signalled, and what happens next depends on when its state file
was written. If it predates the machine's last boot (the state file outlived a reboot, so the pid
may now be some other program), the stale file is removed and the command proceeds as if no demo
gateway were running. If it was written since the last boot, the demo gateway is most likely hung:
the command stops before deleting or starting anything and exits `1` with `A demo gateway (pid N)
is running but not answering; end that process, then rerun nimbus demo.` Each takes exactly its
own arguments — `nimbus demo`, `nimbus demo --no-tour`, `nimbus demo stop`, `nimbus demo reset` —
and anything else (e.g. `nimbus demo --no-tour stop`) is refused with the usage line before
anything is stopped or deleted. If seeding fails, `nimbus demo` stops the demo gateway it just
started before reporting the seed error.

**Banner.** Every `--demo` command prints one line to stderr, never stdout, so piped output stays
clean:

| State | Line |
|---|---|
| Seeded, fresh | `DEMO — synthetic "Acme" org, not your data · seeded <age> · nimbus demo reset to remove` |
| Seeded, stale (older than 24h) | `DEMO — synthetic "Acme" org · seeded <age> (stale — briefs may be empty) · run nimbus demo to re-seed` |
| Not seeded yet | `DEMO — not seeded yet · run nimbus demo` |

**Refused in the demo.** A demo-rooted gateway serves only three `connector.*` reads
(`connector.listStatus`, `connector.status`, `connector.healthHistory`) and refuses every other
`connector.*` method, plus `vault.set`, `vault.delete`, `data.import`, and `extension.install`, with
`ERR_DEMO_FORBIDDEN` (JSON-RPC code `-32000`) — none of these may be allowed to bring real
credentials or real data into a root that is supposed to hold only the synthetic org.
`nimbus --demo init` refuses outright, before touching the gateway or `nimbus.toml`, for the same
reason: its onboarding would otherwise call a refused command and overwrite the seeder's config.
`nimbus --demo doctor --fix-keyring` (with or without `--dry-run`) refuses too: the fixer acts on the
host OS keyring, which the demo never uses — its vault is in memory — so run it without `--demo` to
repair the real keyring. Rationale: invariant **I41** (`SECURITY-INVARIANTS.md`).

**No outbound call.** A demo gateway's sync scheduler is constructed but never started and registers
no syncable — `forceSync` refuses with `ERR_SYNC_DISABLED`, and `tick`/`pump` (like `start` and
`register`) return without doing anything, all keyed on a `syncDisabled` constructor option, not on
whether `start()` was ever called, so a caller that bypassed the IPC refusal above still could not
run a sync. The updater startup check, telemetry flush, embedding-runtime model download,
and extension auto-update daemon are all skipped at boot. `nimbus demo` makes no real network
request.

**`nimbus --demo ask`.** The demo's seeded `nimbus.toml` configures no `[llm]` section, so on the
**seeded** demo `ask` exits `1` and prints, to stderr, the demo gateway's own no-LLM refusal — the
same text the REPL, the TUI and `nimbus --demo prove "<question>"` receive, since the gateway picks
it, not the client:

```text
Nimbus needs an LLM for this command. The demo does not configure one.

Everything in the tour works without one — try:
  nimbus --demo standup
  nimbus --demo expert payments
  nimbus --demo decisions

`ask` works on your real install once an LLM is configured (see nimbus doctor).
```

With no demo gateway running at all — before the first `nimbus demo`, after `nimbus demo stop`, or
right after `nimbus demo reset` — `ask` instead fails with the demo root's not-running message
(`Start with: nimbus --demo start`). Only a demo gateway started with `nimbus --demo start` on an
**unseeded** root reaches the gateway's empty-index check: `ask` then exits `0` and prints the
demo's own empty-index hint to stdout, which points at `nimbus demo` rather than the real install's
`nimbus connector auth …`:

```text
No data indexed yet.

This is the demo root. Seed the synthetic "Acme" org with:
  nimbus demo
```

Every other command in the tour and the closing list renders its brief deterministically, with no
LLM at all — `ask` is the one command in the demo that genuinely needs a model, because it is the
one command everywhere, demo or real install, that genuinely needs one.

---

## Gateway Lifecycle

### `nimbus start`

Start the Gateway as a background process and register it for autostart on login.

```bash
nimbus start
nimbus start --no-wizard        # Skip first-run onboarding hints
```

The Gateway starts in the background and listens on the platform-native IPC socket. On first start it prints next-step hints (connect a service, run `nimbus doctor`) unless `--no-wizard` is passed or the index already contains items.

The Gateway also writes **structured JSON logs** (Pino) to a daily file under your data directory’s **`logs/`** folder, named `gateway-YYYY-MM-DD.log` (same path the CLI uses when it redirects the child process). This applies whether you start via `nimbus start` or run the gateway binary directly, so logs are available even when nothing is attached to a console.

---

### `nimbus stop`

Stop the running Gateway process.

```bash
nimbus stop
```

---

### `nimbus status`

Show Gateway status and connector health.

```bash
nimbus status
nimbus status --verbose         # Per-connector item counts, p95 query latency, health lines
nimbus status --drift           # Include IaC drift hints alongside status
nimbus status --json            # One JSON object; `--verbose` / `--drift` add keys to it
nimbus status --json | jq -r '.version'
```

`nimbus status` reads exactly three flags — `--verbose`, `--drift`, and `--json`. Any other dash-argument is silently ignored.

**Output includes:** Gateway PID, uptime, active profile, total indexed items, agent limits (`depth=N  tool-calls/session=N`), connector list with health state (`healthy` / `degraded` / `error` / `rate_limited` / `unauthenticated` / `paused`).

**`--json` shape.** One object; **every key is always present**, using `null` for absent data, so `jq` never has to guard for existence:

| Key | Type | Notes |
|---|---|---|
| `running` | boolean | `true` only when the state file exists **and** `gateway.ping` answered |
| `pid` / `socketPath` / `logPath` | number / string / string, or `null` | Read from the gateway state file |
| `version` | string \| null | Gateway version |
| `uptimeMs` | number \| null | Milliseconds, not the rounded seconds the human view prints |
| `agentLimits` | object \| null | `{ maxAgentDepth, maxToolCallsPerSession }` |
| `embeddingBackfill` | object \| null | `{ done, total }` |
| `drift` | object \| null | `{ lines: string[] }` — populated only with `--drift` |
| `index` / `connectorHealth` | object / array, or `null` | The `diag.snapshot` payload — populated only with `--verbose` |
| `error` | string \| null | Set when the socket **connected** but `gateway.ping` then failed — the JSON form of the human "state exists but IPC failed" line; `running` is `false`. A socket that cannot be connected to at all does not reach this field (see below) |

Two "not running" cases, and they do **not** behave alike:

- **No state file.** `running: false`, `error: null`, every other key `null`, exit `0`. Not an error.
- **A stale state file whose socket has no listener.** The connect throws before the document can be
  built, so **no JSON is emitted at all**: the connect error (`connect ENOENT` on a Windows named pipe,
  `ECONNREFUSED` on a Unix socket) goes to stderr and the process exits `1`. This is `--json` obeying
  rule 3 of the contract above, and it matches what plain `nimbus status` does with the same stale
  file. `error` is populated only in the narrower case where the connection succeeded and the
  subsequent `gateway.ping` failed — a gateway that is listening but wedged, or one that dies
  mid-call. A script that must distinguish "gone" from "never started" should check the exit code
  first and only parse stdout on `0`.

---

## Querying and Asking

### `nimbus ask`

Ask the agent a natural-language question or give it a task. The agent answers from the local index; it only calls live APIs when freshness is required. Any destructive or outgoing action requires HITL consent before it executes.

If `[llm].prefer_local = true` and a local provider is available, `nimbus ask` routes open-ended conversational answers through the local model. With Ollama, set `[llm].local_model` to any pulled model name; if no remote classifier API key is configured, Nimbus falls back to local indexed-context answering instead of failing before the local model can run.

```bash
nimbus ask "Find all PDFs I received last month that I haven't opened"
nimbus ask "Which of my open PRs mention payment-service and have failing CI?"
nimbus ask "What caused the payment-service alert — what deployed recently?"
nimbus ask "Summarise everything that happened across my projects this week"
```

**Devil's-advocate mode (`--devil`):** argues *against* the plan or assumption in your question
instead of helping to carry it out — the risks it runs, the edge cases it ignores, the alternative
reading of the evidence. A confirmation-bias antidote for a decision you have already half made.

```bash
nimbus ask --devil "ship the checkout migration tonight"
nimbus ask --devil --agent devops "roll the canary to 100%"
```

Two things worth knowing. It **always answers in prose**: the flag skips intent classification and
takes the conversational path, so a phrasing that would normally execute a plan gets argued with
instead. And objections are grounded in the index where the evidence exists — where it does not,
the answer says the objection is unsupported rather than inventing support for it, so a confident
counter-argument still has to be checkable. The mode needs an LLM like any other `nimbus ask`
answer; with none configured it reports the same missing-LLM guidance.

**Session mode:** Run `nimbus` with no arguments to open an interactive REPL. Context accumulates across turns.

```bash
nimbus                          # Opens interactive session
```

For a richer interactive experience — live connector health, sub-task progress bars, inline mid-stream HITL consent — use [`nimbus tui`](#nimbus-tui) instead.

---

### `nimbus search`

Fast structured search over the local index. Answers always come from the SQLite metadata index — no cloud call is ever made. The query is positional; results are printed as JSON.

```bash
nimbus search "quarterly review documents"
nimbus search "payment-service incident" --service slack --limit 50
nimbus search "design doc" --service google_drive --type pdf
nimbus search "flaky test" --keyword-only            # BM25 only, no vector ranking
```

**Options:**

| Flag | Description |
|---|---|
| `--service <name>`, `-s` | Filter by connector (e.g. `github`, `google_drive`, `slack`) |
| `--type <type>`, `-t` | Item type (`pr`, `issue`, `file`, `email`, `message`, `ci_run`, `web_clip`, …). `pipeline_run` is a `graph_entity` type, not an item type — it matches nothing here. |
| `--semantic` | *(default)* Vector/semantic ranking — already on, so passing this changes nothing |
| `--no-semantic`, `--keyword-only` | Turn semantic ranking off; keyword (BM25) results only |
| `--limit <n>`, `-n` | Maximum results (1–500, default: 20) |

> **No other flags are accepted.** `nimbus search` throws `Unknown flag: <arg>` on any argument starting with `-` that is not in the table above — including `--help`, `--json`, `--since` and `--state`. (It is not alone: `nimbus glossary`, `nimbus update`, `nimbus deploy annotate` and `nimbus tribal capture` reject unknown flags too. Most other commands ignore them.) Time, state and assignee filtering are not available here; use [`nimbus query`](#nimbus-query) for `--since`, or raw SQL via `nimbus query --sql`.
>
> If the embedding model is still warming up, a semantic search falls back to keyword-only for that call and prints a note on stderr.
>
> **stdout is always the plain JSON array of results**, so `nimbus search … | jq '.[0]'` keeps working. Anything the results do not say about themselves goes to **stderr** as `note:` lines:
>
> - **Keyword-only results:** why semantic ranking did not run — the query embedding timed out (default budget 5 s, override with `NIMBUS_EMBEDDING_QUERY_TIMEOUT_MS`, capped at 25 s so it still fires inside the 30 s IPC bound), the model is still loading, embeddings are disabled or did not start, or the vector index could not be loaded.
> - **Partial ranking:** a hybrid result ranked on one dimension only, because the other half timed out.
> - **Incomplete results:** a background embedding pass is still running, reported as `8,400 of 51,600 items processed this pass`. That is progress of the current pass, not index coverage; `nimbus index health` reports per-connector coverage.
>
> A gateway older than the CLI prints no notes.

---

### `nimbus query`

Structured index query with explicit filters or raw SQL. Intended for scripting and CI pipelines.

```bash
nimbus query --service github --type pr --since 7d
nimbus query --service linear --type issue --since 14d --json
nimbus query --sql "SELECT title, url FROM item WHERE pinned = 1" --pretty
nimbus query --service pagerduty --type alert --since 1d --json | jq '.[] | .title'
```

**Options:**

| Flag | Description |
|---|---|
| `--service <name>` | Filter by connector |
| `--type <type>` | Item type |
| `--since <duration>` | Lower time bound (`7d`, `24h`, `30m`, `2w`, …) |
| `--sql <query>` | Raw read-only SQL (SELECT only; DML is blocked) |
| `--pretty` | Pretty-print table output |
| `--json` | JSON array output |
| `--limit <n>` | Max rows (default: 50, capped at 1000) |
| `--not-touching <glob>` | **Negation.** PRs with no indexed changed-file path matching the glob. Requires `--type pr`. |
| `--no-downstream-incident` | **Negation.** Deployments with no correlated downstream incident. Requires `--type deployment`. |
| `--explain` | Print the SQL that ran, its bound parameters, and the substrate probe |

`--service` is required unless `--sql` is used.

#### Negation predicates

```bash
nimbus query --service github --type pr         --not-touching 'tests/**'
nimbus query --service github --type deployment --no-downstream-incident
```

**A negation is not a filter with a NOT in it, and these flags are built around that.** For a positive query a missing row costs you a result. For a negation a missing row *produces* one — a PR whose file list was never fetched satisfies "no row matching `tests/**`" exactly as well as a PR that genuinely never touched tests, and the two are identical at the SQL level. An unpopulated index does not make a negation incomplete; it makes it **wrong**, and wrong in the direction that reads as a finding. Four consequences, all enforced rather than advisory:

- **An empty substrate refuses.** Each predicate probes its substrate first (any `pr_files_state` row; any `correlates_with` edge). If nothing is there the command exits `1` and emits a refusal instead of rows — the message and remediation to **stderr**, or, under `--json`, a `{ "status": "refused", "reason": "missing_substrate", "message": …, "remediation": … }` document to **stdout** so a pipeline can parse it. *Refused* and *none matched* are opposite answers, and a non-zero exit alone does not distinguish a refusal from a crash.
- **Unverifiable rows are excluded AND counted, on every call.** A `Gaps:` line prints whether or not you passed `--explain`, because the accounting is part of the answer: a short result set with no explanation is the false finding these flags exist to prevent. `--not-touching` reports its two exclusion reasons separately — PRs whose file coverage was never indexed, versus PRs whose coverage was truncated — because they mean different things to a reader deciding whether to trust the result. `--no-downstream-incident` reports deployments with no graph entity of the required type.
- **Type scoping is mandatory.** `--not-touching` without `--type pr` (or `--no-downstream-incident` without `--type deployment`) is an error, checked before any Gateway call. Unscoped, `--not-touching 'tests/**'` would return every issue, message and commit in the index — none of which can touch a path at all.
- **The correlation window is fixed at two hours and there is no flag to widen it.** `--no-downstream-incident` reads `correlates_with` edges that are written under a fixed window at *write* time, and the edge row's timestamp is when it was written, not when the deploy happened — so a query-time window cannot be reconstructed even in principle. The output names the window rather than offering a control that does not exist.

The `meta.total` a negation query reports is the size of the returned batch, bounded by `--limit` — the human output says so explicitly rather than printing it as a match total.

Exposing these predicates to `nimbus ask` is a separate, not-yet-built sub-project (W6-B.2); today they are `nimbus query` / `nimbus people list` flags only.

#### `--explain`

```bash
nimbus query --service github --type deployment --no-downstream-incident --explain
nimbus query --service github --type pr --since 7d --explain          # works on any query, not just negations
```

Prints the **composed** SQL that actually shaped the result (never the bare predicate subquery, which omits the limit and any other filter and would answer a wider question if pasted into `sqlite3`), its bound parameters, and — on a negation query — the substrate probe with its row count. The probe line is the only way to see *why* a query refused, or to confirm that a non-empty answer rested on real data; a plain query has no probe to report, so that line is absent.

Under `--json`, `--explain` changes the shape of the document: instead of a bare array of rows you get `{ "items": [...], "meta": {...}, "explain": {...} }` (plus `"gaps"` on a negation query). The block is always a field in the document, never loose text printed alongside it — that would make the output unparseable.

> **Unknown flags are ignored, not rejected.** `nimbus query` scans for the flags above and ignores anything else it finds, so a typo or an invented filter fails silently rather than erroring. (`nimbus search` behaves the opposite way — it throws on any flag it does not define.)
>
> **Security note:** `--sql` is guarded — only `SELECT` statements are allowed. Any `INSERT`, `UPDATE`, `DELETE`, or DDL is rejected before execution.

---

### `nimbus run`

Execute a YAML script file as a single agent session. All steps use the same engine as `nimbus ask`. A plain `nimbus run` executes straight away — there is no preview step and no "proceed?" confirmation; HITL gates fire inline as each step reaches them. A preview is opt-in via `--dry-run` or `--no-ttv`.

```bash
nimbus run ./weekly-cleanup.yml
nimbus run ./deploy.yml --dry-run         # Preview only — no step executes
nimbus run ./deploy.yml --no-ttv          # Preview first, abort if any step is flagged HITL; otherwise run
```

`--no-ttv` is the unattended-safety flag, not a dry run: the CLI asks for a dry-run preview, and if any step's `hitlActions` is non-empty it throws `Workflow steps may require human approval (HITL). …` and nothing executes. If nothing is flagged, the workflow runs for real. `--agent nimbus|devops|research` selects the agent profile.

**Script format:**

```yaml
name: weekly-cleanup
steps:
  - Find all PDF files in Google Drive not opened in 90 days
  - Summarize them by project folder
  - Move the ones from the Zurich project to /Archive/2025
  - Send me an email with the summary
```

Optional per-step metadata:

```yaml
steps:
  - prompt: Move files older than 90 days to archive
    label: archive-old-files
    continue-on-error: false
```

Scripts with only read-only steps run without a TTY (safe for CI). Scripts with HITL-required steps require an interactive terminal.

---

## Team Intelligence

Built-in agents that answer team-level questions from the local relationship graph and indexed metadata. Each agent is read-only, never triggers HITL, and streams a Markdown brief to stdout.

**Brief synthesis.** Every built-in agent's Markdown brief can be rewritten by a local LLM (Ollama or llama.cpp) into more natural prose before it reaches you, instead of the deterministic template render. With Ollama running, this happens **by default** — set `synthesis = "off"` below to keep the deterministic-only behaviour. Two honesty guards protect a rewrite from saying less than the deterministic render promised (invariant **I31**). Disclosure-only sections — `## Gaps` for all fourteen brief kinds, plus `nimbus negotiate`'s `## Sources` and `## Evidence not available from the index` — are never shown to the model at all: the renderer builds them and re-attaches them verbatim afterwards, so a rewrite cannot drop one by construction. Disclosures woven into prose the model *is* meant to rewrite are covered instead by a `requiredPhrases` anchor check, which spans the whole interleaved set — `negotiate`'s seven null-lane disclaimers, its window, ownership-accountability, list-truncation and `unattributable` clauses, and `glossary`'s two definition-provenance lines. A rewrite that drops any of them is discarded and the deterministic render is served instead. Each sentence and its anchor have a single definition in `agents/_lib/brief-disclosures.ts`, read by both the renderer and the guard, so the two cannot drift apart. A rendered brief always carries a plain-language footer stating its own provenance: deterministic by design (`synthesis = "off"`, or no LLM registry wired), deterministic because no eligible provider was resolved, deterministic after an attempt was made and then discarded (with the reason), or synthesized (with the model name and whether it was local or remote) — and the same fact rides the `briefReady` notification and `GET /v1/agents/runs/{id}` as a machine-readable `synthesis` field.

**Configuration — `[agents]`, read from the profile-resolved TOML:**

`[agents]` follows the same **whole-file** profile semantics as `[llm]` and `[session]`: when a profile is active and its `nimbus.<profile>.toml` exists, that file is the ONLY one read, and the base `nimbus.toml` is not consulted for these keys. This cuts **both ways**, and both directions are real behaviour changes as of 2026-08-18. A key set in a profile TOML is now honoured, where it used to be silently ignored; and a key set ONLY in the base `nimbus.toml` no longer applies while a profile whose file lacks an `[agents]` section is active — so a user with `synthesis = "off"` in `nimbus.toml` and an `[agents]`-less `nimbus.work.toml` gets the `"local"` default under the `work` profile until they repeat the key there.

| Key | Default | Meaning |
|---|---|---|
| `synthesis` | `"local"` | `"off"` never attempts a rewrite — every brief is the deterministic render, regardless of `[llm]` settings. `"local"` attempts a rewrite only when the resolved provider is local (Ollama or llama.cpp); a resolved remote provider is refused outright, so nothing egresses by construction. `"allow-remote"` additionally permits a non-local provider, appending a `model`-class `egress_ledger` row (I29) before that call. An unrecognised value falls back to `"local"`, never widening to `"allow-remote"` on a typo. |
| `synthesis_timeout_ms` | `20000` | How long a synthesis attempt is raced against before it is abandoned as `timeout` and the deterministic render is used instead. Deliberately generous: briefs are fire-and-forget, so this does not gate a caller — it exists so a hung provider still yields a brief. The underlying provider call is not cancelled at timeout (no `AbortSignal` support), only abandoned. |

**Configuration — `[persona]`, read from the profile-resolved TOML (see below):**

| Key | Default | Meaning |
|---|---|---|
| `tone` | `"neutral"` | `"neutral"` — a strict no-op, contributes nothing to the prompt. `"terse"` — short sentences, no preamble; says everything it would otherwise say, in fewer words. `"formal"` — complete sentences, precise wording, no contractions. `"casual"` — contractions fine, plain words over jargon. `"verbose"` — spells out reasoning and the connections between findings. An unrecognised value keeps `"neutral"` and logs a one-time warning naming the key, the rejected value, and the fallback. |
| `voice` | `"neutral"` | `"neutral"` — a strict no-op. `"opinionated"` — states a recommendation where the evidence supports one, rather than laying out options neutrally. `"collective"` — first-person plural ("we should…") rather than an outside observer's voice. Same unrecognised-value fallback as `tone`. |

`[persona]` is read from the **profile-resolved** TOML and resolved fresh on every query — editing it changes the very next response, no restart required. Profile resolution means: the active profile's `nimbus.<profile>.toml` when a profile is active **and that file exists**, otherwise the base `nimbus.toml`. Switching *which* profile is active (`nimbus profile switch`) still requires a Gateway restart, same as every other profile-scoped setting, because the active profile is fixed for the life of the Gateway process.

Applies to **three** surfaces: `nimbus ask`, every built-in agent brief, and — because a `@nimbus <question>` mention runs through the same `runAsk` pipeline — **ChatOps replies in Slack/Teams**. That third one is worth stating plainly: an `opinionated` or `collective` voice configured for your own machine will be visible to everyone in the channel the bot answers in. It carries no new content and no new egress — only tone — and it is the owner's own configured voice on the owner's own ChatOps integration, which is why it is not scoped out: doing so would make ChatOps replies the one surface that ignores your persona. It composes with `--devil` (persona directive outermost, `--devil`'s directive innermost, closest to the question). Every `tone` and `voice` value governs register and stance, never what gets said — no persona directive may tell the model to omit content. A `terse` persona can still raise the rate at which a brief falls back to its deterministic rendering, because the honesty contract that protects every brief discards a rewrite that drops a required disclosure rather than risk losing it — that is the contract working, not a bug, and the resolved persona rides the `briefReady` notification's `synthesis` field alongside the discard reason, so a `contract_violation` under `tone = "terse"` is self-explanatory.

**Not supported:** `tool_caution` (HITL escalation levels) and `confidence_threshold` (how often the agent admits uncertainty) are not configuration keys. Both were rejected, not deferred — a knob that loosens what triggers the HITL consent gate, or one that lets the agent suppress an uncertainty admission, is prohibited on the same grounds as the consent gate itself.

### `nimbus expert`

Answer "who on my team has the most context on this?" — returns a ranked list of people drawn from indexed PR authorship, review participation, Slack thread activity, and Linear/Jira ticket assignments. Each ranking comes with a confidence score and the underlying evidence.

```bash
nimbus expert src/billing/retry.ts
nimbus expert "payment retry logic"
nimbus expert --json src/billing/retry.ts
```

**Options:**

| Flag | Description |
|---|---|
| `--limit <n>` | Maximum number of ranked people to return (default: 5) |
| `--json` | Machine-readable JSON output (otherwise Markdown) |

**Output (Markdown):** ranked list of contributors, each with their evidence (e.g. *"authored 4 of the last 6 PRs touching this file, resolved 2 incidents tagged `payment-retry`"*) and any **gap notes** if the local index lacks the connectors or relations needed for a confident answer (e.g. "no GitHub connector authenticated", "no review history for this file").

**Read-only:** never triggers HITL, never makes a live API call — answered entirely from the local index.

---

### `nimbus impact`

Answer "if I change this, what breaks?" — reverse-dependency blast radius across five categories: services that import the affected module (via indexed code symbols and `depends_on` graph edges), pipelines that would rebuild (via `pipeline_run` items linked to the repo), dashboards pulling from affected data models (via `upstream_refs` graph edges), API endpoints exposed by the affected service (via the OpenAPI indexer's `api_endpoint → service` edges), and on-call rotations that own the affected services (via PagerDuty schedules). Five parallel sub-agents over the relationship graph.

```bash
nimbus impact src/billing/retry.ts
nimbus impact https://github.com/acme/payment-service/pull/312
nimbus impact --json --service payment-service src/billing/retry.ts
```

**Options:**

| Flag | Description |
|---|---|
| `--service <id>` | Restrict the report to a single service id |
| `--json` | Machine-readable JSON output (otherwise Markdown) |

**Output (Markdown):** structured blast-radius report grouped by category (services / pipelines / dashboards / endpoints / on-call), with gap notes when the local index lacks a connector or relation needed for a confident answer.

**Read-only:** never triggers HITL, never makes a live API call. Built entirely on the Phase 3 relationship graph substrate — no new connectors required.

---

### `nimbus why`

Answer "why is this line/file the way it is?" — six parallel lanes over the local relationship graph: authorship (who last touched the line and when), pull request (the PR that merged it), ticket (the issue it resolves), discussion (Slack/Teams messages mentioning the commit, PR, or ticket), driver/what-drove-it (a temporally correlated incident within a 48h window — never a causal claim), and downstream (reverse `depends_on` edges from the file's indexed symbols). `<ref>` is a `path[:line]` (e.g. `src/billing/retry.ts:42`), a bare symbol name resolved against indexed code symbols, **or a pull-request URL** — resolved against the index alone (`agents.why`'s `{ prUrl }` arm), so it needs no local checkout and works for a repo you have never cloned. `--line` overrides a line number embedded in a path `<ref>`; it has no meaning for a URL. A lane with nothing to show degrades to a gap note naming the missing connector or graph relation rather than going silent — except on the PR-URL arm, where the authorship and downstream lanes are file/line lanes by nature and stay silent with no gap note (a `prUrl` question never had a file/line subject for them to report as missing). The rendered subject line says so in one sentence: *"Asked about a change: authorship needs a line (`nimbus why <file>:<line>`), and downstream impact is `nimbus impact <url>`."*

```bash
nimbus why src/billing/retry.ts:42
nimbus why retryPayment --peek
nimbus why src/billing/retry.ts --line 42 --json
nimbus why https://github.com/acme/web/pull/482
```

**Options:**

| Flag | Description |
|---|---|
| `--line <n>` | Line number, overriding any `:line` suffix on `<ref>` |
| `--peek` | Sub-300ms one-liner via `agents.whyPeek` instead of the full six-lane brief: author · short SHA · date · commit subject · PR # · ticket key. **Path/symbol `<ref>` only** — `agents.whyPeek` has no PR-URL arm, and the CLI hard-fails (`--peek takes a path or symbol, not a pull request URL`) before dispatching rather than sending a URL it cannot answer |
| `--json` | Machine-readable JSON output (otherwise Markdown / a one-line string for `--peek`) |

**Output (Markdown):** one section per lane with its findings, plus gap notes for any lane that couldn't answer confidently (e.g. "no blame available for this line", "PRs emit `merged_as` when github-sync records a merge commit SHA — sync the connector for this repo"). The downstream lane currently degrades to a gap note on most real indexes — the graph populator emits `depends_on` at workspace→package granularity today; symbol-level edges are a populator follow-up. On the PR-URL arm, a URL that does not resolve to an indexed pull request renders as a one-line miss rather than a full brief. `--peek --json` returns the full `agents.whyPeek` payload (subject, author, commit, PR, ticket) rather than the one-line summary string, including `hasMore: true` whenever the full six-lane agent would surface findings beyond what author/PR/ticket already cover (a mentioning message, a `depends_on` edge, or a `correlates_with` deployment).

**Read-only:** never triggers HITL, never makes a live connector API call — answered from the local index and relationship graph, with one exception: an unblamed line triggers a single, cached, root-fenced local `git blame` subprocess (via `ensureBlameLine`), scoped to a configured `[[filesystem.roots]]` repo, bounded by a 20s timeout, and cached forever after in `git_blame_line`. This is a local git read, not a connector dispatch.

---

### `nimbus glossary`

Turn terminology the team already uses — but has never written down — into a queryable glossary, extracted entirely from the local index. `nimbus glossary` with no argument prints terms sorted by frequency; `nimbus glossary <term>` prints the team's consolidated definition, resolved against an exact term match, then a known synonym, then (on a miss) a "did you mean" list of near-misses. Candidates are mined deterministically from indexed titles/bodies (5 surface-form families — acronyms, backticked tokens, PascalCase identifiers, hyphenated compounds, capitalized phrases) and require evidence across at least `min_doc_freq` (default 3) source items before a term is considered; a local LLM then consolidates or vetoes each candidate.

Extraction normally runs as a background pass, debounced after a successful connector sync (`[glossary]` in `nimbus.toml`, default on); `nimbus glossary` with no mutating flag only reads the already-materialized `glossary_term` table. `--refresh` and `--rebuild` drive an on-demand pass instead of waiting for the next sync.

```bash
nimbus glossary
nimbus glossary CDR
nimbus glossary --limit 50 --json
nimbus glossary --refresh
nimbus glossary --rebuild
nimbus glossary --rebuild --yes
```

**Options:**

| Flag | Description |
|---|---|
| `--limit <n>` | Cap the number of terms/entries returned |
| `--json` | Machine-readable JSON output (otherwise Markdown) |
| `--refresh` | Run an on-demand incremental pass now, then print the (possibly updated) brief. Fails with `ERR_GLOSSARY_PASS_RUNNING` if a pass is already in flight. |
| `--rebuild` | Truncate every consolidated/pending glossary term and re-derive. Without `--yes`, prints a count of what would be deleted plus a sample of the highest-scoring terms and exits without touching anything. **One `--rebuild` runs exactly one bounded pass** (`SCAN_BATCH_LIMIT` items scanned, `max_new_terms_per_pass` terms consolidated — 25 by default) — it does not re-derive the whole glossary in one shot; the rest comes back incrementally over subsequent connector syncs or further `--refresh`/`--rebuild` runs. |
| `--yes` | Required alongside `--rebuild` to actually run the destructive rebuild. |

`--refresh` and `--rebuild` are mutually exclusive. A pass can take several minutes (up to `max_new_terms_per_pass * consolidate_timeout_ms`, ~12.5 minutes at defaults); on a TTY, progress prints in place as `consolidating <done>/<total>` and is suppressed for piped/redirected output. On completion, up to three summary lines are written to **stderr** (never stdout, so `--json`'s stdout stays JSON-only): a base line reporting new/upgraded term counts, a warning if a local LLM was configured but never answered and terms were deferred to retry (Ollama not running), and a line naming (up to 10, with a count of any remainder) any previously snippet-defined term vetoed during an upgrade.

**Output (Markdown):** with no argument, a frequency-sorted term list with coverage stats (how many terms are consolidated vs. still pending). With `<term>`, the consolidated definition, first-seen / last-seen dates, up to 5 top sources, and known synonyms/near-misses; gap notes explain an empty or partially-built glossary (no pass has run yet, every candidate fell below the frequency floor, consolidation is still in progress) rather than looking broken.

**Definition provenance.** A definition's `definitionSource` is `"llm"` (the local model consolidated it from source snippets), `"snippet"` (no LLM was available at consolidation time, so the verbatim sentence containing the term was used instead — honest and attributable, but not synthesized), or `"manual"` (a human authored it directly in `nimbus.toml` — see **Authoring and correcting terms manually** below). The background pass consolidates through a local model whenever `[glossary].use_llm` is true (the default) and one is available (Ollama or llama.cpp); with neither running, or `use_llm = false`, it produces snippet-sourced definitions instead. A snippet-sourced definition is not permanent: a later pass automatically re-consolidates it once a local LLM becomes available, using a reserved share of that pass's budget so a large backlog of new terms cannot starve upgrades indefinitely. A manual definition never auto-consolidates — it changes only when you edit `nimbus.toml`.

**Enabling the LLM can remove terms you've already seen.** Snippet mode has no veto path, so a glossary built without a model can accumulate terms nothing has ever judged. The upgrade path above puts those same terms in front of a real model for the first time, and a term the model vetoes is removed from the glossary (it survives internally as `vetoed`, and returns only if a later `--rebuild` re-derives it). `--refresh` names up to 10 terms vetoed this way in its stderr summary — plus a count of any remainder beyond that (`VETOED_TERMS_REPORTED`), so the total is never silently dropped — but a user who only reads the terminal output between runs, or consumes the glossary via search/`nimbus ask`, will not see that line unless they run `--refresh` themselves.

**Authoring and correcting terms manually.** A term does not have to come from mining. Add entries under two flat blocks in `nimbus.toml`:

```toml
[glossary.terms]
CDR = "Change Data Record — the durable event our pipeline emits on every row mutation."
"node.js" = "Our shorthand for the Node runtime services, as opposed to the Python worker fleet."

[glossary.synonyms]
"Change Data Record" = "CDR"
```

**Entries must sit under exactly these two headers — `[glossary.terms]` and `[glossary.synonyms]`.** This is a deliberately dependency-free line-based TOML parser, not a general-purpose one: a dotted key written directly under `[glossary]` (`[glossary]` with `terms.CDR = "…"` on its own line) is valid TOML, but this parser does not read it. That entry is now reported by name as a skipped/rejected entry in `--refresh`'s stderr summary (`packages/gateway/src/config/nimbus-toml-glossary-terms.ts`) rather than silently dropped — but the fix is to move it under `[glossary.terms]`, not to rely on the warning appearing. **A definition must be a single line — `"""` triple-quoted block strings are not supported** and are also reported as a skipped entry rather than silently dropped; write the definition as one quoted line, however long.

An authored entry is upserted straight to a consolidated, `definitionSource: "manual"` term the moment the config is next read — no LLM call, no pending queue, no `min_doc_freq` evidence requirement. On a key collision with a mined term, the authored definition **wins** unconditionally, and it sorts ahead of every mined term in `nimbus glossary`'s list output and near-miss suggestions regardless of score. `[glossary.synonyms]` aliases resolve only to an authored term — pointing one at a mined term is rejected and reported the same way as a misplaced entry.

**The edit-then-`--refresh` loop:** config is re-read at the start of every pass (not cached from gateway startup), so editing `nimbus.toml` and running `nimbus glossary --refresh` applies the change immediately — no gateway restart needed. To remove an override, delete its line from `[glossary.terms]` and run `--refresh` again: the row is **demoted, not deleted**, back to `status='pending'`. A term with real mined evidence (`doc_freq >= min_doc_freq`) then re-enters the ordinary consolidation queue and comes back with a mined definition over subsequent passes (subject to the same per-pass cap as any other pending term, not necessarily the very next one), while a pure invention with no mined evidence sinks below the floor and disappears from the glossary for good.

A manual row is exempt from being demoted or vetoed by the reconciliation sweep — a human assertion outranks a doc-frequency floor — but **not** exempt from having its statistics (`doc_freq`, `top_sources`) refreshed by that same sweep, so an authored term's cited sources still self-heal as the underlying threads are edited or deleted.

**Term-key normalization is not exact-string round-tripping.** The key you write (`CDR`, `node.js`) is normalized the same way a mined surface form is — casefolded, de-pluralized, backticks stripped — before it becomes the term's lookup key, and `depluralize()` still strips a trailing plural `s` outside of dotted identifiers: `"https"` normalizes to `"http"` and `"kubernetes"` to `"kubernete"`. That is a pre-existing, deliberate limitation of the shared normalizer (an acronym allowlist would be needed to fix it, and a general "consonant + s" rule was measured to break the normalizer's own headline case, `"SLOs"` → `"slo"`) — only dotted identifiers like `node.js` are exempted from it, not every acronym. What a user actually **sees**, though, is unaffected: `display_term` always preserves the exact key you wrote in `nimbus.toml`, so `nimbus glossary` prints `"node.js"` and `"CDR"` verbatim regardless of what the internal term key normalizes to.

**Read-only:** never triggers HITL, never makes a live API call — the extraction pass calls only the local LLM (when configured), and the `nimbus glossary` read path is pure SQLite. Zero `egress_ledger` rows.

**Exit codes:** `1` = gateway not running; `2` = agent error (timeout or a malformed `agents.glossary` response). An unknown term is not an error — it returns a "did you mean" brief of near-misses.

---

### `nimbus decisions`

The third member of the implicit-knowledge triad (after `nimbus why` and `nimbus glossary`): recovers decisions buried in Slack/Discord/Teams messages, Notion/Confluence/Obsidian pages, and Linear/Jira/GitHub/GitLab issues — statements of the form "we decided X because Y, alternatives were Z" — and corroborates each one against downstream PRs, commits and ADRs already in the local relationship graph. `nimbus decisions` prints a chronological, confidence-scored list read straight from the already-materialized `decision_record` table; it never calls a model on the read path.

Extraction normally runs as a background pass, debounced after a successful connector sync (`[decisions]` in `nimbus.toml`, default on). `--refresh` and `--rebuild` drive an on-demand pass instead of waiting for the next sync.

```bash
nimbus decisions
nimbus decisions --since 30d --service billing
nimbus decisions --explain --min-confidence 0.5
nimbus decisions --refresh
nimbus decisions --rebuild --yes
nimbus decisions --json
```

**Options:**

| Flag | Description |
|---|---|
| `--since <duration>` | Only decisions decided on/after `now - <duration>` (`ms\|s\|m\|h\|d\|w`, e.g. `90d`, `2w`). Defaults to `90d`. |
| `--service <name>` | Filter to decisions matched by either of two routes: the repository a corroborating PR/commit touches, or the source ticket's project key (Jira/Linear). Matching is on normalized tokens, not substrings — `--service bill` does not match `billing`. `--explain` labels which route fired; the brief reports how many decisions matched neither. |
| `--min-confidence <0..1>` | Drop any decision scoring below this. When omitted, the floor is `[decisions].min_confidence` (default `0.3`); an explicit value always wins, including `--min-confidence 0` for no floor at all. |
| `--explain` | Print the four confidence terms (`cue_strength`, `corroboration`, `source_authority`, `completeness`) and the matched cue text for every decision. |
| `--json` | Machine-readable JSON output (otherwise Markdown) |
| `--refresh` | Run an on-demand pass now, then print the (possibly updated) brief. Fails with `ERR_DECISIONS_PASS_RUNNING` if a pass is already in flight. |
| `--rebuild` | Clear the decision store — **including every `vetoed` row** — reset the watermark, and re-mine from scratch. Without `--yes`, prints a warning and exits without touching anything: a veto is a judgement already spent, and a rebuild re-asks the model about every previously rejected candidate. |
| `--yes` | Required alongside `--rebuild` to actually run the destructive rebuild. |

`--refresh` and `--rebuild` cannot be combined. A pass can take several minutes (bounded by `max_llm_calls_per_pass` sequential local-model calls); on completion, a one-line summary is written to **stderr** (never stdout, so `--json`'s stdout stays JSON-only): counts of extracted/upgraded/no-model rows. If discovery stopped on its internal batch bound with source items still unscanned, that same line says so explicitly and re-running resumes from where it stopped — a pass never silently reports success over a partial scan. Unlike `nimbus glossary`, a decisions pass reports no mid-pass progress — there is no `decisions.passProgress` notification.

**If `--refresh` or `--rebuild` keeps failing with `ERR_DECISIONS_PASS_RUNNING`, restart the gateway (`nimbus stop && nimbus start`).** A pass has no timeout and no cancellation: it awaits the local model one candidate at a time, and neither shutdown nor a later request can interrupt a call already in flight. A model that hangs therefore leaves the pass marked as running for the life of the gateway process, and every subsequent on-demand pass is refused. A restart clears it, and no work is lost — extraction resumes from the persisted watermark. Bounding the model call properly requires an abort signal the LLM layer does not yet carry (the same limit `nimbus glossary` has); it is deferred rather than papered over, and the code says so at `packages/gateway/src/decisions/decision-llm-adapter.ts`.

**Output (Markdown):** a chronological list, each entry showing the confidence score, decided-at date, statement, rationale, alternatives, evidence (source item plus any corroborating PR/commit/ADR), and a `⚠ no ADR found` marker when `has_adr` is false. Gap notes explain an empty or partially-built list (no pass has run yet, candidates are still awaiting extraction, decisions matched neither service route) rather than looking broken.

**Two honest limits, stated in every brief — not optional polish:**

- **Body cap.** This pass reads `item.body` directly (`decision-extract.ts` `scanDelta`), so prose-heavy item types (e.g. `confluence:page`, `notion:page`) are visible up to their 16 KiB cap, not the old flat 512 characters — a decision stated deep in a long Confluence/Notion page is no longer structurally invisible the way it once was. Everything else is still capped at 512, since only prose-heavy types get the wider `item.body` cap. (The embedding pipeline is a separate surface: it deliberately still reads the 512-character `body_preview`, unchanged and intentional, so semantic search recall over long documents is unaffected by this.) Recall is capped, not complete.
- **Confidence ceiling is 0.86, not 1.0.** The corroboration term of the confidence formula reserves its top score (1.0) for `migration`/`iac` evidence — properties of a corroborating change's file paths — but no connector today indexes changed-file paths, so that tier is specified in the schema and never actually reached. The real ceiling with only PR/commit corroboration available is `0.6`, which caps total confidence at `0.86`. The brief does not present a full-marks scale you cannot reach.

**Definition provenance.** A decision's `extractionSource` is `"llm"` (a local model structured it into statement/rationale/alternatives) or `"snippet"` (no local model was available at extraction time, so the matched sentence itself became the statement, with no rationale or alternatives). A snippet-sourced row is not permanent: a later pass automatically upgrades it once a local LLM is available, using a reserved share of that pass's budget so a large backlog of new candidates cannot starve upgrades indefinitely.

**Configuration — `[decisions]` in `nimbus.toml`:**

| Key | Default | Meaning |
|---|---|---|
| `enabled` | `true` | Run the background extraction pass at all. Extraction opens no network surface — it reads the local index and writes local rows — so, like `[glossary]` and unlike `[briefs]`, it defaults on. |
| `use_llm` | `true` | Extract via a local model (Ollama or llama.cpp). `false` keeps the cheap deterministic cue-mining pass but forces every candidate into snippet mode, sparing a laptop the sequential local-model calls. |
| `min_confidence` | `0.3` | The `nimbus decisions` read-path floor when `--min-confidence` is omitted: decisions scoring below it are not listed. An explicit `--min-confidence` overrides it (pass `0` to see everything). Re-read per command, so an edit applies without restarting the gateway. Extraction itself is unfiltered — every candidate is stored with its score, so raising or lowering this changes what you see without re-running a pass. |
| `max_llm_calls_per_pass` | `25` | LLM calls per pass (sequential), split between new pending candidates and snippet-row upgrades. |
| `debounce_ms` | `30000` | How long a burst of connector syncs coalesces before triggering one pass. |
| `retry_cooldown_ms` | `60000` | Cooldown before a failed (unparseable) extraction is retried, preventing a permanently-unparseable high-priority candidate from starving lower-priority ones. |

**Read-only:** never triggers HITL, never makes a live connector API call, never calls `connectors.dispatch` — the extraction pass calls only the local LLM (when configured and available), and the `nimbus decisions` read path is pure SQLite. Zero `egress_ledger` rows.

**Exit codes:** `1` = gateway not running; `2` = agent error (timeout or a malformed `agents.decisions` response).

---

### `nimbus owners`

The read surface over the git-blame-derived ownership graph (schema **V51**): ranks who wrote a file or directory's lines, recency-weighted, and rolls a repository root up to the `[ci.service.<id>]` it is bound to. With no argument it prints a coverage summary (last-pass timestamp, roots/files covered, services bound).

**This is authorship-derived ownership, not accountability.** It answers "who wrote this," from `git blame`, not "who is responsible for approving a change to it." There is no CODEOWNERS file, no code-review data, and no on-call rotation anywhere in the local index, so the ranking is a starting point for who to ask — never an approval list. Every brief says so explicitly via an unconditional gap note.

```text
Usage: nimbus owners [<path>] [--service <name>] [--json] [--refresh]
  <path>       a file or directory inside a configured git-aware root
  --service    a [ci.service.<id>] service id
  (no args)    ownership coverage summary
```

```bash
nimbus owners
nimbus owners src/billing/retry.ts
nimbus owners src/billing
nimbus owners --service billing
nimbus owners --refresh
nimbus owners --json
```

**Options:**

| Flag | Description |
|---|---|
| `<path>` | A file or directory inside a configured git-aware root (either a `[[filesystem.roots]]` block or a `nimbus index add` registration). Resolves to the nearest graph entity; a path with no owners still routes to its parent directory so a one-committer file isn't a dead end. Mutually exclusive with `--service`. |
| `--service <name>` | Look up the owners of a bound `[ci.service.<id>]` service directly, instead of a path. Mutually exclusive with `<path>`. |
| `--json` | Machine-readable JSON output (otherwise Markdown). |
| `--refresh` | Run an on-demand derivation pass now (`ownership.refresh`), then print the (possibly updated) brief. Fails if a pass is already running. |

Like `nimbus glossary`, `nimbus owners` **hard-rejects** an unrecognised flag rather than ignoring it — a typo'd `--srevice` would otherwise silently fall through to a whole-repo coverage summary that looks like a successful answer to a different question. `<path>` and `--service` together are also rejected, not silently resolved by picking one.

**Output (Markdown):** the requested target's ranked owners (each with a recency-weighted share and a resolved-person-or-git-email label), the parent directory's owners as a fallback lane, the service the containing root rolls up to (if any), and the coverage summary. Gap notes explain a `0`-coverage result (no git-aware roots configured, the pass hasn't run yet, the path is outside every configured root, `[ownership].ignore_globs` excluded it) rather than looking broken, plus the standing authorship-vs-accountability disclaimer described above.

**Configuration — `[ownership]` in `nimbus.toml`:**

| Key | Default | Meaning |
|---|---|---|
| `enabled` | `true` | Run the background derivation pass at all. Like `[glossary]` and `[decisions]`, this opens no network surface — it reads the local `git_blame_line` index and writes local graph edges — so it defaults on. |
| `half_life_days` | `365` | Recency half-life for blame-line weighting: a line blamed today counts more than one blamed a half-life ago. |
| `min_share` | `0.05` | An owner below this recency-weighted share of a path is dropped from the emitted set (but still counted toward the true total). |
| `max_owners_per_path` | `10` | Cap on owners emitted per path; the true count above the floor is kept on the entity's metadata and reported as a truncation fact. |
| `ignore_globs` | a default list of lock files, `vendor/`, `node_modules/`, `dist/`, `build/`, minified/generated/snapshot files | Root-relative globs excluded from aggregation. `git log --name-only` consults no exclude list on its own, so an unfiltered lock file would otherwise hand a directory to whoever last ran the installer. An explicit `[]` disables filtering entirely. |
| `debounce_ms` | `30000` | How long a burst of connector syncs coalesces before triggering one pass. |

**Read-only (normal lookup):** never triggers HITL, never makes a live connector API call, never calls `connectors.dispatch` — a plain `nimbus owners` reads only the already-indexed `git_blame_line` table and calls no model. Zero `egress_ledger` rows. `--refresh` is different: it invokes `ownership.refresh`, which clears and re-derives every ownership edge — local write-class maintenance, not a live connector call, but not read-only either.

**Exit codes:** `1` = gateway not running; `2` = agent error (timeout or a malformed `agents.ownership` response).

---

### `nimbus pre-mortem`

The thirteenth built-in agent: a risk brief for a Jira epic, built from comparable past epics already in the local index. Four sequential lanes — resolve the epic to its affected services, build an IDF-weighted service-overlap cohort of closed epics touching those services, compute five structural risks over that cohort (cycle-time overrun, size overrun, review drag, incident coupling, abandonment), and read recurring blocker themes mined by the background pass (schema **V53**). It then proposes — but never arms — one paused `incident_opened` watcher per affected service that resolves to a configured deployment-service id.

**Jira-only, and narrower still within Jira:** `--service` overrides aside, affected-service derivation walks `parent_key`-linked children, which `jira-sync.ts` only populates for **team-managed** projects — a company-managed epic resolves to zero derived services. No Linear epic is ever recognized: no `linear:project` items are indexed at all, so a `linear:...` reference is reported as an unsupported-tracker gap, not silently ignored.

```text
Usage: nimbus pre-mortem <epic-ref> [--service <name>]... [--json] [--refresh] [--repropose]
  <epic-ref>   a Jira epic key, e.g. PROJ-120 or jira:PROJ-120
  --service    repeatable; overrides the derived affected-service set
  --refresh    run the pre-mortem theme pass before building the brief
  --repropose  re-create a previously-deleted watcher proposal for this epic
```

```bash
nimbus pre-mortem PROJ-120
nimbus pre-mortem PROJ-120 --service billing-api --service payments-api
nimbus pre-mortem PROJ-120 --refresh
nimbus pre-mortem PROJ-120 --repropose
nimbus pre-mortem PROJ-120 --json
```

**Options:**

| Flag | Description |
|---|---|
| `<epic-ref>` | Required. A Jira epic key (`PROJ-120`) or explicitly-prefixed reference (`jira:PROJ-120`). Any other tracker prefix (e.g. `linear:ABC-1`) is reported as an unsupported-tracker gap rather than looked up. |
| `--service <name>` | Repeatable. Overrides the derived affected-service set entirely — useful for a brand-new epic with no PR-derivable services yet. |
| `--refresh` | Run `premortem.refresh` (the on-demand theme-extraction pass) before building the brief. Unlike `glossary`/`decisions`/`ownership`'s `.refresh`, this is a bare awaited RPC call, not a `{ jobId }` long-running job — a disabled pass (`[premortem].enabled = false`) or a concurrent pass surfaces as a normal error, exit code 2. |
| `--repropose` | Deletes this epic's `premortem_watcher_proposal` tombstones before proposing, so a watcher the user had previously deleted is re-created (paused) instead of staying suppressed. Scoped to this one epic only. |
| `--json` | Machine-readable JSON output (otherwise Markdown). |

Like `nimbus owners`/`nimbus glossary`, `nimbus pre-mortem` **hard-rejects** an unrecognised flag rather than ignoring it.

**Watcher proposals — what they are and are not:** every affected service **that resolves to a configured deployment-service id** gets one `watcher` row inserted with `enabled = 0` (paused) plus a `premortem_watcher_proposal` tombstone, wrapped in one transaction so the two can never land separately. A paused row cannot fire — `automation/watcher-store.ts`'s `listEnabledWatchers` filters strictly on `enabled = 1` — until a human arms it through the existing watcher-arming path; `nimbus pre-mortem` never arms anything itself. Proposals depend on the target epic's affected services only, not on its cohort, so an epic with no comparable history still gets them. This is the one narrowly-bounded exception to the built-in-agent read-only shape invariant — see the `nimbus-agent-patterns` skill for its exact bounds and why it is not an I2/HITL matter.

**A proposal is scoped by affected service, not by connector.** The watcher condition carries `filter.affectedService` — the `[metrics.dora.<id>]` / `[ci.service.<id>]` id the repo resolves to — which the watcher engine matches against the incident's `graph_entity.metadata.affectedService`. The older `filter.service` axis matches the `item.service` **column**, which for an incident is always the connector id (`pagerduty`), so it can only ever scope a watcher to a whole connector. **A repo with no configured service mapping gets no watcher at all**, and the brief says so by name: falling back to the repo path would write a watcher that silently matches nothing once armed. Add a `[ci.service.<id>]` block whose `repos` names the repository, then re-run.

**No deploy-failure watcher is proposed.** Deploy failure is a watcher condition kind, not one of the five risks — the fifth risk is abandonment, and no deploy-failure risk is computed. The engine can now scope such a watcher the same way, so the earlier reason (`item.service` being the annotate provider slug) no longer holds; what does is that `deployment/annotate.ts` — the only writer of the `metadata.conclusion` a `deploy_failed` watcher matches — inserts its `item` row directly and creates no `deployment` graph entity, so such a watcher would match nothing until `nimbus index regraph` runs.

**Review drag cannot currently be measured for any repo:** no connector indexes a pull request's *opened* timestamp (only `merged_at`), so the review-drag risk reports a named gap rather than a fabricated `0`. The measured path exists and activates the moment a connector starts recording that field; until then every brief reports the gap.

**Read-only in the request sense, not the write sense:** a plain `nimbus pre-mortem` never triggers HITL and never calls `connectors.dispatch` — the watcher-proposal writes above are plain local SQLite inserts, not egress. `agents.premortem` is deliberately excluded from the HTTP agent-invocation surface (`POST /v1/agents/{agent}`) and the MCP tool surface, matching `agents.preflight`, because those writes have no HITL gate and an external caller must not be able to trigger them unprompted; it remains reachable from the CLI (this command) and the Tauri renderer.

**Exit codes:** `1` = gateway not running; `2` = agent error (unknown or non-Epic epic key, unsupported tracker, or a `--refresh` pass failure).

---

### `nimbus negotiate`

The fourteenth built-in agent: a cited contribution brief for one person over a time window, assembled entirely from evidence already in the local index — no connector is opened and nothing is fetched live. Seven lanes: PRs authored (with size stats where the enrichment pass has reached them), PRs reviewed (approve / changes-requested / other), tickets opened and tickets closed by an authored PR, code and services owned, decisions authored, documents/notes/messages written, and incident/error-issue attribution — PagerDuty incidents resolved or assigned, and Sentry error issues assigned, reported as two separate counts (an error group that never paged anyone is not an incident). Either connector's absence, or its presence with no attributable edges yet, is reported as a named gap note rather than a false zero.

```text
Usage: nimbus negotiate [--since <duration>] [--person <id>] [--json]
  --since    window to summarise, e.g. 90d (default 90d, max 365d)
  --person   brief a different person by id (defaults to you)
```

```bash
nimbus negotiate
nimbus negotiate --since 180d
nimbus negotiate --person person:jane
nimbus negotiate --json
```

**Options:**

| Flag | Description |
|---|---|
| `--since <duration>` | Window to summarise (`ms\|s\|m\|h\|d\|w`, e.g. `90d`). Defaults to `90d`. The gateway rejects anything above `365d` outright (exit code 2, naming the 365-day bound) rather than silently clamping it — sized for a full annual review cycle, wider than every sibling agent's shared 90-day cap. |
| `--person <id>` | Brief a different, already-indexed person instead of yourself. Takes a **`person.id`** (`person:…`) — run `nimbus people search <name>` to find one. A `git:<email>` blame alias is **not** a person id: it is the identity the ownership pass emits for a git email with no `person` row, so **ownership is the only one of the seven lanes that can measure it** — the three lanes keyed on `item.author_id` (always a `person.id`) can never match it, and the `authored`/`opened` graph edges are built from `item.author_id` too, so PRs authored and tickets cannot either. An id that resolves to no person is not silently briefed as zero — the brief carries a gap note saying the counts are structurally zero rather than measured. Resolved **entirely from locally indexed data** — this opens no connector and fetches nothing live, the same as a self brief. |
| `--json` | Machine-readable JSON output (otherwise Markdown). |

Like `nimbus owners`/`nimbus pre-mortem`, `nimbus negotiate` **hard-rejects** an unrecognised flag rather than ignoring it — a typo'd `--persn` would otherwise silently fall through to the local user's own brief in response to a question about someone else, a wrong answer that looks like a right one.

**Every item-backed lane cites its evidence.** Under each count, the brief lists up to **5** of the actual items behind it — newest first, linked where the connector recorded a URL and plain text where it did not (never an empty or invented link). When a lane counted more than it lists, it says so: `…and N more not listed`. Two lanes differ on purpose: **ownership** carries no citations because it already names the services and directories it counted, and **tickets** cites only the issues you opened — the "closed by an authored PR" figure would otherwise cite issues someone else filed. The citation list obeys the same `personal_sources` gate as the counts, so a personal note never appears as a citation under a brief that says personal docs are off.

**Personal sources are off unless configured.** Confluence pages and chat messages are always in scope. Obsidian notes and Notion pages are mined only when their service is named in `[negotiate] personal_sources` in `nimbus.toml` — configuration IS the consent, following the `[glossary.terms]` precedent. The brief's `sources` block reports whether the opt-in is active and names the config key it reads. Entries are case-folded (`"Obsidian"` works), and an entry that names no recognised personal-document service is reported back in the brief as ignored rather than dropped in silence — "configured" means an entry actually widened the query, never merely that the key is present.

**The ownership section is authorship-derived, exactly as `nimbus owners` says.** The lane reads the same precomputed `owns` edges, derived from recency-weighted `git blame`. Every brief states plainly that this is who wrote the lines, not who is formally accountable: there is no CODEOWNERS and no on-call rotation in the local index, and reviewer data (the `reviewed` edges the "PRs reviewed" section above is built from) is **not** factored into the ownership ranking.

**Six limits every brief states plainly — not decoration, the point of the command:**

- **The window is "active in", not "created in".** `item` carries no creation timestamp, only `modified_at` — which for GitHub is `updated_at`, the last touch. Every item-backed lane therefore filters on last-modified, so `--since 90d` means "authored by the subject at any time and touched within the last 90 days", not "authored within the last 90 days"; a ticket closed two years ago still counts if a bot commented on its PR last week. That would overstate the headline numbers silently, so the window line in every brief says so outright. (Two lanes sit outside the window: decisions windows on `decision_record.decided_at`, a real decision date, and ownership is not windowed at all — it is an all-time snapshot.)
- **Ownership can understate.** The ownership lane counts only `git_blame_line` rows whose git email maps to a known `person` row. Work committed under an unmapped alias — a second machine, an old address, a GitHub `noreply` address — is attributed to a separate, unmapped identity in the index and is **not** counted toward the subject. For a self brief the agent can usually detect this (it knows which git email self-resolution attempted) and adds a gap note naming it; for an explicit `--person` subject it cannot, since someone else's alias set is unknowable from here, and heuristically guessing by name/email was deliberately rejected as worse than an acknowledged gap.
- **Ownership can also be stale, or never computed.** The ownership lane is a read over the precomputed `owns` graph, not a live derivation, so every brief also states when that background pass last ran — or, if it has never run, says so and names `nimbus owners --refresh` as the fix — rather than presenting a possibly-outdated or empty list as current.
- **PR size stats carry their own coverage.** `additions`/`deletions`/`changed_files` live in a PR's metadata only where the enrichment pass has already run. `authoredPrs.stats` is an aggregate over whatever subset was enriched, and `authoredPrs.statsCoverage` (`covered` of `total`) is reported alongside it so the aggregate is never read as if it covered every authored PR.
- **Unattributable decisions are a fact about the index, not about the subject.** `decisions.unattributable` counts decisions mined from a source (Obsidian, Teams) that records no author at all — it is an index-wide count, never the subject's own. Reading "N authored, M unattributable" as "N + M decisions are mine, M just aren't linked to me" turns an undercount into an overstatement, so the brief spells out that those M decisions are not counted above and are not necessarily the subject's.
- **On-call shifts and deploys triggered are not available at all.** The local index carries no attribution for either. The brief names both, unconditionally, on every run — never only when they would otherwise read as an empty or zero section, so a genuine zero is never confused with "cannot be computed." Incidents resolved is **not** on this list: the `person --resolves--> incident` graph edge is emitted and the incidents lane measures it directly, the same way Sentry error-issue assignments are measured via the `person --assigned--> error_issue` edge. Either measurement's absence — no PagerDuty/Sentry connector, or a connector with no attributable edges yet — is reported as its own named gap note instead of a silent zero.

The brief is also recomputed fresh on every invocation rather than cached, so two runs a window apart can legitimately disagree as the underlying index changes.

**Not reachable over the local HTTP API, nor as an MCP tool.** `agents.negotiate` is served on the CLI/Tauri socket only — it is excluded from the HTTP agent surface (`POST /v1/agents/{agent}`) and it defines no MCP tool, so a model driving `nimbus mcp-server` cannot invoke it either. Unlike `agents.preflight`/`agents.premortem` (excluded for their side effects) it writes nothing, but combined with `--person` an exposed version would let any holder of the `agents` bearer token — or any model driving the tool server — assemble a contribution dossier on any indexed person without the local owner initiating it. The CLI and Tauri renderer are same-machine, owner-initiated surfaces; the local HTTP API and the MCP tool server are not.

**Configuration — `[negotiate]` in `nimbus.toml`:**

| Key | Default | Meaning |
|---|---|---|
| `personal_sources` | `[]` | Personal-document services to mine in the docs/notes lanes — currently `obsidian` and/or `notion`. Empty means work artifacts only (Confluence, chat messages, and any other always-in-scope service). |

**Output (Markdown):** the resolved subject, the query window, each lane's counts (or a gap note where a lane could not be computed), the unconditional unavailable-evidence list, and the personal-sources status.

**Read-only:** never triggers HITL, never makes a live connector API call, never calls `connectors.dispatch` — every lane reads only the already-indexed graph and item tables. Zero `egress_ledger` rows.

**Exit codes:** `1` = gateway not running, or an unrecognised flag / unexpected argument (rejected by `parseNegotiateArgs` before the gateway is ever called); `2` = agent error (an out-of-range `--since`, or a malformed `agents.negotiate` response).

---

### `nimbus catchup`

Personalized retrospective digest of everything that happened across connected services while you were away, weighted by your historical involvement. Unlike a uniform, service-scoped digest, `catchup` prioritizes activity by the user's recent work: services they own, repos they contribute to, incidents they've responded to, people they collaborate with frequently. Five parallel sub-agents (`s_owned_services`, `s_active_repos`, `s_responded_incidents`, `s_collaborators`, `s_window_items`); three-tier self-person resolver (override → git email → OS username).

```bash
nimbus catchup
nimbus catchup --since 7d
nimbus catchup --since 24h --service payment-service --json
```

**Options:**

| Flag | Description |
|---|---|
| `--since <duration>` | Window to summarise (default: `3d`); accepts `<n>d` / `<n>h` |
| `--service <id>` | Restrict the digest to a single service |
| `--json` | Machine-readable JSON output (otherwise Markdown) |

**Output (Markdown):** sections per service, prioritized by a per-section relevance score; each section lists recent items (PRs, incidents, threads, tickets) with one-line context.

**Read-only:** never triggers HITL, never makes a live API call.

---

### `nimbus changelog`

The fifteenth built-in agent: a Markdown changelog assembled entirely from the local index over a time window, for a single configured service or across all of them. Four categories: merged pull requests and incidents opened window on real event fields (`metadata.merged_at`, `metadata.opened_at_ms`) rather than `item.modified_at` ("last touched", not "when it happened"); deployments (a successful CI run whose title matches the deploy pattern, unioned with annotated deploys from `POST /v1/deployments`) and incidents resolved use `item.modified_at` deliberately, on the same basis `nimbus metrics dora` already uses for resolution time. Dependency updates and configuration changes have no indexed item type and are disclosed unconditionally in `## Gaps` rather than silently omitted.

```bash
nimbus changelog
nimbus changelog --since 14d
nimbus changelog --service payments --format slack
nimbus changelog --json
```

**Options:**

| Flag | Description |
|---|---|
| `--since <duration>` | Lookback window (default: `7d`); accepts `<n>d` / `<n>h`, etc. Capped at **90 days** by `agents.changelog` — a longer window parses locally and is then refused by the gateway. |
| `--service <id>` | Restrict to one `[ci.service.<id>]` service (repos + PagerDuty ids + deploy pattern). Naming a service `nimbus.toml` does not define is not an error — every scoped query correctly matches nothing, and the brief says so in `## Gaps` rather than reading as a quiet week. Omitted: every service, using the shipped default deploy pattern `^[Dd]eploy`. |
| `--format <markdown\|slack\|plain>` | A text transform over the brief's own Markdown (default `markdown`) — never a re-render from the typed findings, so a synthesized rewrite's prose survives the transform. |
| `--json` | Print the typed findings instead of the brief. |

**Output (Markdown):** `# Changelog`, a preamble stating the window and the scoped service (or "all services"), then `## Merged Pull Requests`, `## Deployments`, `## Incidents Opened`, `## Incidents Resolved` — each rendered even when empty (`_None in this window._`), because a missing heading and an empty one say different things — followed by the reserved `## Gaps` section, which is never empty: it always carries the unconditional dependency-updates/config-changes disclosure, and additionally names any merged pull request on a non-GitHub forge (`metadata.merged_at` is written by the GitHub connector alone, so GitLab/Bitbucket merges are invisible — the same substrate gap `nimbus stats` reports as `github_only_merge_data`), and any `--service` bound to no repos and no PagerDuty ids.

**Entry lists are capped at 50 per category**, so a 500-PR window is not handed wholesale to the synthesis model. `counts` (visible via `--json`) always carries the true pre-cap total per category, so the truncation is recoverable — a window with 53 merged PRs and a 50-entry list means 3 were dropped, not lost.

**Read-only:** never triggers HITL, never makes a live connector API call. Not reachable over the local HTTP API, nor as an MCP tool, nor from ChatOps, nor from the desktop renderer — `agents.changelog` is served on the local IPC socket and is **not** on the Tauri `ALLOWED_METHODS` allowlist (I7), so the CLI is the only surface a *user* can reach it from today; a sequencing decision (letting the shape settle against one consumer before it is committed across every external surface) rather than a side-effect or dossier concern like the other excluded agents. The gateway's own `nimbus fleet` scheduler is the one other caller, and it is not an exception to that reasoning: a fleet job is owner-configured in advance and runs in-process, never an arbitrary network caller. It **is** therefore eligible for `nimbus fleet` — an unattended weekly changelog produced on idle hardware is close to the feature's own stated purpose, and it is a pure read with no side effects.

---

### `nimbus standup`

The sixteenth built-in agent: your own activity over a window, assembled entirely from the local index and formatted as copy-pasteable Markdown. Six lanes — pull requests active and merged, reviews given, tickets opened, incidents responded to, and Slack activity — each windowed on its own timestamp and each labelled with where that timestamp came from. Scoped to **you**: the person the people graph resolves for this machine, via `git config user.email` matched against indexed canonical emails, then your OS username matched against indexed GitHub logins, or `[user] mePersonId` in `nimbus.toml` to pin it. There is no flag to run it for someone else.

```bash
nimbus standup
nimbus standup --since 3d
nimbus standup --format slack
nimbus standup --json
```

**Options:**

| Flag | Description |
|---|---|
| `--since <duration>` | Lookback window (default: `24h`); accepts `<n>h` / `<n>d`, etc. Capped at **90 days** by `agents.standup` — a longer window parses locally and is then refused by the gateway. |
| `--format <markdown\|slack\|plain>` | A text transform over the brief's own Markdown (default `markdown`) — never a re-render from the typed findings, so a synthesized rewrite's prose survives the transform. |
| `--json` | Print the typed findings instead of the brief. |

**Output (Markdown):** `# Standup`, a preamble stating the window, who the brief is about and how that identity was decided, then `## Pull requests active`, `## Pull requests merged`, `## Reviews given`, `## Tickets opened`, `## Incidents responded to` and `## Slack activity` — each rendered even when empty (`_None in this window._`), because a missing heading and an empty one say different things — followed by the reserved `## Gaps` section. Entry timestamps carry the **time**, not just the date: over a 24-hour window a date-only stamp would render every entry identically.

**An unresolvable identity REFUSES rather than printing an empty standup.** Every lane keys on the resolved person, so with no identity the brief would be six empty sections — indistinguishable from a quiet day, and a false claim about your work in output meant to be pasted into a channel. `nimbus standup` exits non-zero with `ERR_STANDUP_IDENTITY_UNRESOLVED` and names the fix (`nimbus people list` to find your id, then `[user] mePersonId`).

**Three things it cannot tell you, and says so unconditionally in `## Gaps`:**

- **Deployments you triggered.** No connector records who started one — every `ci_run` row is indexed with no author, an annotated deploy from `POST /v1/deployments` carries none either, and the relationship graph holds no person-to-deployment edge. `nimbus changelog` lists deployments without attributing them.
- **Tickets you moved or commented on.** Ticket comments are not indexed as items, and Jira/Linear are indexed with only a ticket's current status rather than its transitions. Only tickets you **opened** appear.
- **Work recorded under a different account.** Attribution runs through one resolved person id, so where one human appears in the index as two people (a work email on commits, a different address on tickets) this brief covers whichever half was resolved.

**Where each lane's timestamp comes from** — the brief discloses this in its preamble, and the distinction is sharper here than on `nimbus changelog` because the default window is a single day:

| Lane | Timestamp | Can it sit in the wrong window? |
|---|---|---|
| Pull requests merged | `metadata.merged_at` | No — a real event field |
| Tickets opened | `metadata.created_at_ms` | No — a real event field, written by both ticket connectors |
| Reviews given | `item.modified_at`, which for a `review` row **is** its `submitted_at` (one immutable row per review) | No, except where the source payload carried no timestamp |
| Slack activity | `item.modified_at`, which for a `message` row **is** its Slack `ts` (one immutable row per message) | No, same exception |
| Pull requests active | `item.modified_at` — GitHub's `updated_at` | **Yes** |
| Incidents responded to | `item.modified_at`, the same basis `nimbus metrics dora` uses | **Yes** — under-reports by sync lag |

`## Pull requests active` is deliberately not called "opened": a `pr` row carries no creation timestamp at all, so "pull requests I opened in the last 24 hours" is not a question this index can answer. What it can answer is which of your pull requests moved, which for a standup is the more useful one. Merged pull requests are excluded from that section, since they are reported under their own heading.

**Slack activity is summarised by THREAD as well as by message** (`N messages across M threads`), because eleven replies in one thread is one conversation rather than eleven items of work.

**Entry lists are capped at 50 per lane**, so a chatty day is not handed wholesale to the synthesis model. `counts` (visible via `--json`) always carries the true pre-cap total per lane, so the truncation is recoverable.

**Read-only:** never triggers HITL, never makes a live connector API call. Not reachable over the local HTTP API, nor as an MCP tool, nor from ChatOps, nor from the desktop renderer — `agents.standup` is served on the local IPC socket and is **not** on the Tauri `ALLOWED_METHODS` allowlist (I7). Unlike `nimbus changelog`'s exclusion, that is not a sequencing decision: this brief is owner-scoped by construction, so an external caller cannot ask about *itself* and would instead receive the gateway owner's day. An external surface for it needs a way to establish who is asking first. It **is** eligible for `nimbus fleet`, which is a different principal — owner-configured in advance, running in-process, and about its own owner.

---

### `nimbus oncall`

The seventeenth built-in agent: **one incident, and everything the local index can honestly say about the change around it.** With no flags it briefs the newest active incident assigned to you; `--incident <item-id>` names one outright and `--service <name>` picks the newest active one on a configured service.

```bash
nimbus oncall
nimbus oncall --service checkout
nimbus oncall --incident "pagerduty:PXXXXX"
nimbus oncall --since 3d --format slack
```

**Options:**

| Flag | Description |
|---|---|
| `--incident <item-id>` | Brief this incident by its **index item id** (not its PagerDuty number — find one with `nimbus query --type incident`). Accepts a resolved incident, which is the postmortem case. Mutually exclusive with `--service`. |
| `--service <name>` | Pick the newest active incident on this configured service. Mutually exclusive with `--incident`. |
| `--since <duration>` | **Chat lookback only** (default: `24h`, capped at 90 days — rejected locally, so a typo fails on the command line rather than after a round trip). The deployment, change and prior-incident lanes anchor on when the incident *opened* and are not affected by this flag. |
| `--format <markdown\|slack\|plain>` | A text transform over the brief's own Markdown (default `markdown`) — never a re-render from the typed findings, so a synthesized rewrite's prose survives. |
| `--json` | Print the typed findings instead of the brief. |

**Output (Markdown):** `# On-call`, a preamble naming the incident and the chat window, then `## Incident`, `## Last deployment before the alert`, `## Change in that deployment`, `## CI`, `## Chat` and `## Prior incidents on this service` — each rendered even when empty (`_None found._`), because a missing heading and an empty one say different things — followed by the reserved `## Gaps` section.

**Nothing with no incident is a REFUSAL, not an empty brief.** Every section anchors on a selected incident, so with none the brief would be six headings over nothing — which during an incident reads as *you are clear*, the one wrong answer that looks like a good one. `nimbus oncall` exits non-zero with `ERR_ONCALL_NO_ACTIVE_INCIDENT`, and names the two other shapes plus `nimbus index health`. Two sibling refusals exist and are deliberately distinct: `ERR_ONCALL_IDENTITY_UNRESOLVED` (Nimbus cannot tell who you are — a different fix entirely from "nobody is paging you", and collapsing the two would tell an on-call engineer they are clear when nothing was ever checked) and `ERR_ONCALL_INCIDENT_NOT_FOUND`.

**Runner-up incidents are labelled by how they were selected.** With no flags they are *other active incidents assigned to you*; with `--service` they are *other active incidents on this service* — that query filters on service and status alone and applies no assignee predicate, so calling them yours would be false.

**The prior-incident count is a floor once it saturates.** That lane over-fetches one past its display cap, so a service with forty earlier incidents reads *at least 11* rather than a precise-looking `11`. Recurrence is the signal the lane exists for, so understating it silently would defeat the point.

**The deployment is the one before the alert — that is timing, not cause.** Nothing in the index links a deployment to an incident. The heading says what the claim is and the preamble says what it is not; neither calls it a root cause.

**Incident status is only as fresh as the last PagerDuty sync, and the preamble always says how stale that is.** This is the one disclosure that qualifies the *selection* rather than a count: a resolved incident whose row has not been re-synced still reads `triggered`, so a stale sync can put you in front of an incident that closed an hour ago. It is printed even when the sync is seconds old — a line you only ever see when something is wrong gives you no way to calibrate what it means.

**Three things it cannot tell you, and says so unconditionally in `## Gaps`:**

- **How any earlier incident was resolved.** An incident is indexed with its status as its entire body, so no resolution note, remediation step or postmortem link exists anywhere in the index. Prior incidents can say *who* closed one and *when*, never what they did — which is why that lane is framed around recurrence, the signal it can actually carry.
- **What the change did.** No connector indexes a patch, a changed-file list or a commit message body, so a pull request is described by its title and its added/removed line counts and nothing more.
- **Anything paged through OpsGenie.** There is no OpsGenie connector, so this brief has nothing to select from there and its silence is not evidence that nobody is paged.

**A fourth gap is conditional and worth fixing when you see it:** an incident whose PagerDuty service maps to no configured Nimbus service leaves the deployment, change, CI and chat sections structurally empty. The brief names the unmapped PagerDuty id and points at the `[metrics.dora.<service>]` / `[ci.service.<service>]` binding — the same one `nimbus metrics dora` already uses.

**Read-only:** never triggers HITL, never makes a live connector API call. Reachable over the local HTTP API, as an MCP tool and from ChatOps — but **only on its explicit shapes**. The zero-parameter owner-scoped form is refused for an external caller, because it resolves the *gateway owner's* identity: a bearer token cannot ask about itself and would receive the owner's active incident, assignees included. That is the concern that keeps `agents.standup` off every external surface entirely; the difference here is that `oncall` has an answerable external shape, so the bound sits on the **shape** rather than the method — the same split invariant `I36` applies to `agents.ghost` / `agents.conflicts`. Eligible for `nimbus fleet`, where a job names its service and the prior-incident lane is the half a nightly digest watches move.

---

### `nimbus tail`

Follow the gateway's operational event stream live: connector health transitions, watcher fires, sync completions, extension mutations and HITL prompts/resolutions — the five categories a running gateway can tell a connected client about outside of a direct IPC call.

```bash
nimbus tail
nimbus tail --filter sync
nimbus tail --filter connector,hitl --json
```

**Options:**

| Flag | Description |
|---|---|
| `--filter <categories>` | Comma-separated, repeatable: `connector`, `watcher`, `sync`, `extension`, `hitl`. Default (flag omitted): all five. An event of a kind this build does not recognise is never filtered out, even under a narrow `--filter` — a stream that silently drops what it does not recognise is worse than one unfamiliar line. |
| `--json` | Emit the raw JSON-RPC notification (`{method, params}`) as one JSON object per line, instead of the human-readable rendering. |

**`nimbus tail` is follow-only** — the same contract as `tail -f -n 0`. It shows only what happens *from the moment it connects*; there is no backfill of events that occurred before it started, and nothing it prints is persisted anywhere. Reaching for it after the fact (e.g. "what happened to that sync ten minutes ago?") will not work — that history exists only if some other subsystem records it (the egress ledger, `nimbus audit`), not here.

**Deliberately excluded: per-item sync progress.** Every event on this stream is a `broadcastNotification` fan-out to *every* connected client, so a connector mid-sync emitting one event per item would flood every open `nimbus tail`, every desktop window and every other IPC client at once. The five categories above are the coarse-grained, operationally relevant subset; item-level detail stays out of the broadcast surface entirely.

**Extension events can carry an empty `extensionId`.** On an `extension.stateChanged` event whose `action` is `"update"`, an `extensionId` of `""` does not name an extension — it means the originating `extension.update` request named no target at all. The gateway emits the event anyway rather than throwing on malformed input, so a blank id on an `update` action is a request-shape signal, not an id to look up.

**Exit codes:** `0` on a clean Ctrl+C (SIGINT/SIGTERM); `1` if the gateway is not running when the command starts, or if the gateway connection is lost while streaming.

**Read-only, local-socket only:** connects over the same IPC socket as every other CLI command; not reachable over the local HTTP API, MCP, ChatOps, or the Tauri renderer allowlist.

---

### `nimbus explain last [--json]`

X-ray of the most recent `nimbus ask` (or `agent.invoke`, or the ChatOps read path — every caller of the shared `runAsk` pipeline): what data reached the model's context, how each candidate was ranked, what was cut and why, which tools were actually called, and which route the turn took. Every `runAsk` call writes exactly one record to an in-memory ring of the last 10 asks, win or throw; this command reads the newest one.

```bash
nimbus explain last
nimbus explain last --json
```

**Options:**

| Flag | Description |
|---|---|
| `--json` | Emit the validated wire shape as JSON instead of the human-readable rendering — the record reparsed by `parseExplainLastResult`, not the raw IPC response; an unrecognised gateway field is dropped rather than passed through. |

**In memory only, and deliberately so.** The ring lives in the gateway process; it holds nothing across a restart, and nothing is written to the index. "No ask recorded since the gateway started" is a different, honest statement from "no ask has ever happened" — the CLI never conflates the two.

**What a record shows, by route** (`runAsk` takes exactly one per turn):

- **`empty_index`** — the index has nothing in it; the turn never reached a model or a search.
- **`local_context`** — the turn answered from the local SQLite index directly (no live connector call). Shows the search terms used, every candidate the ranking pass considered — grouped by which retrieval pass surfaced it (primary hybrid search, a quoted-phrase match, a repo-slug lookup, a fallback-term retry), never mixed across passes, since their scores are not comparable — and, for each, whether it was `shown` to the model or cut, and **why it was cut**: `cut: probe slice` (ranked outside the top of the primary probe, so it never entered the candidate pool at all), `cut: over cap` (in the pool, dropped by the final size cap), or `cut: service fairness` (in the pool and under the cap by arrival order, displaced by per-service round-robin so one noisy connector cannot crowd out the rest). A `discardedTail` summary counts what never made the pool at all, by service and type.
- **`agent_tools`** — the turn went to the conversational agent, which made zero or more live tool calls (each shown with its service, status, duration and — for a `searchLocalIndex` call specifically — its own internal ranking). If a local-context probe was *also* built for this turn (the local-router-fallback path only) and actually reached the model's prompt, it is shown using the same `local_context` rendering, under its own heading.
- **`plan_dispatch`** — the turn was classified as an action and dispatched a plan; the record shows the plan, not a live trace of its execution.
- **`failed`** — the turn threw. Shows the stage it reached (`classification` / `retrieval` / `model` / `dispatch`) and the error; a `dispatch`-stage failure (a connector or executor error, not a model failure) also shows the plan that was being dispatched.

**Three things the roadmap row that introduced this command promised and the index cannot back up — stated here rather than dropped quietly:**

- **There is no "connector rate-limited" discard reason.** The `local_context` route queries the local SQLite index only — it never calls a connector at all, so a connector's rate limit cannot be why a candidate was cut. The three real cut reasons are the probe slice, the size cap, and per-service fairness, above; none of them is about a live API call.
- **There is no relevance threshold.** Nothing here scores a candidate against a minimum and drops it for scoring too low. Every cut is a *slice/cap/fairness* decision over an already-ranked list, not a relevance judgment — which is also why a candidate that would have scored well can still be marked `cut: service fairness` if enough same-service items arrived ahead of it.
- **"Which connectors were queried vs. answered from cache" is not the axis that exists.** The local index *is* the cache — there is no separate query-vs-cache distinction inside it. The real axis this record shows is **local index vs. live tool call**: a `local_context` turn (or an `agent_tools` turn's own `searchLocalIndex` calls) reads the already-synced local index; any other `agent_tools` tool call reaches out live. The record shows which of those happened, not a cache-hit/miss split that the local index has no concept of.

**Deferred, not shipped:** a durable `ask_explain` table — persisting this would write every question the user asks, with its full retrieval trace, to an index that is not encrypted at rest, and now will not be (SQLite encryption via SQLCipher was **rejected 2026-09-15** — `bun:sqlite` cannot link it on Windows or Linux; see roadmap § Rejected Directions). The deferral therefore stands on a permanent property of the index rather than on waiting for a row that is no longer coming; `nimbus explain list` / `nimbus explain <n>` to browse beyond the newest record (the ring holds up to 10, but only the newest is reachable today); and capture of the three negation predicates (`--not-touching`/`--no-downstream-incident`/exclusion counts) and of `indexCountFor` guidance inside an explain record.

**Read-only, no HITL, CLI-only, LAN-forbidden.** `ask.explainLast` is not reachable over the local HTTP API, MCP, ChatOps, or a paired peer over the LAN — the record carries the owner's question verbatim plus titles of items retrieved from the owner's private index, so admitting it over the wire would hand a peer the owner's own ask. It is not on the Tauri renderer allowlist either.

---

### `nimbus ghost`

Surface ambient teammate context for a file by querying paired peers' expertise across the federation mesh. Returns a ranked list of teammates with recent PRs, issues, and commits touching the file — helping you identify who to consult before starting work. No message is ever sent automatically; this is a read-only suggestion surface.

```bash
nimbus ghost src/auth/session.ts
nimbus ghost src/auth/session.ts --json
nimbus ghost src/auth/session.ts --namespace project:zurich
```

**Options:**

| Flag | Description |
|---|---|
| `--namespace <n>` | Restrict the peer sweep to a single published namespace (default: ambient sweep across all paired peers) |
| `--json` | Machine-readable JSON output (otherwise Markdown) |

**Output (Markdown):** ranked list of teammates with their file-relevant evidence (recent PR titles, commit messages, issue assignments), confidence scores, and any gap notes (e.g. "peer offline", "no matching namespace").

**Read-only:** never triggers HITL, never sends a message, never makes a live API call. Fan-out goes only to consented, paired peers via the existing federated query gate (I17).

---

### `nimbus conflicts`

Warn of work-in-progress collisions before editing a file — surfaces teammates who have an open PR, assigned ticket, recent commit, or open branch touching the same file across the federation mesh.

```bash
nimbus conflicts src/auth/session.ts
nimbus conflicts src/auth/session.ts --json
nimbus conflicts src/auth/session.ts --namespace project:zurich
```

**Options:**

| Flag | Description |
|---|---|
| `--namespace <n>` | Restrict the peer sweep to a single published namespace (default: ambient sweep across all paired peers) |
| `--json` | Machine-readable JSON output (otherwise Markdown) |

**Output (Markdown):** list of detected WIP collisions per teammate (open PR url / ticket / branch / recent commit), ordered by recency; gap notes if a peer is unreachable.

**Read-only:** never triggers HITL, never makes a live API call.

---

### `nimbus huddle`

Team-scoped morning briefing aggregating each teammate's recent PRs, tickets, and incidents from across paired peers — a status summary without manual reporting.

```bash
nimbus huddle
nimbus huddle --since 86400000
nimbus huddle --json
nimbus huddle --namespace project:zurich --json
```

**Options:**

| Flag | Description |
|---|---|
| `--since <ms>` | Lookback window in milliseconds (default: 86400000 = 24 h) |
| `--namespace <n>` | Restrict the peer sweep to a single published namespace (default: ambient sweep across all paired peers) |
| `--json` | Machine-readable JSON output (otherwise Markdown) |

**Output (Markdown):** one section per teammate, each listing recent merged PRs, closed tickets, and resolved incidents with one-line context; gap notes if a peer is unreachable.

**Read-only:** never triggers HITL, never makes a live API call.

---

### `nimbus janitor`

Answer "is this cloud resource still in use, and what breaks if I delete it?" — cross-references a resource against indexed deployments, dashboards, alerts, and on-call rotations, and reports how long it has been idle.

```bash
nimbus janitor arn:aws:s3:::legacy-reports
nimbus janitor legacy-reports --idle-days 30
nimbus janitor legacy-reports --cleanup aws.s3.bucket_delete
nimbus janitor legacy-reports --allow-gaps --json
```

**Options:**

| Flag | Description |
|---|---|
| `--idle-days <n>` | Idle threshold in days (default: 14); must be a positive integer |
| `--cleanup <action.type>` | Propose a cleanup action of this type. The action still passes the local owner's HITL gate before it executes — the brief itself never deletes anything |
| `--allow-gaps` | Report a verdict even when some evidence lanes are missing (default: an incomplete sweep is called out rather than concluded from) |
| `--json` | Machine-readable JSON output (otherwise Markdown) |

**Output (Markdown):** the idle verdict with its evidence, the referencing surfaces found, and — when `--cleanup` is given — the proposed action awaiting consent.

**Read-only until approved:** the brief itself makes no writes; any `--cleanup` action is gated by HITL (invariant `I24`).

---

### `nimbus preflight`

Blast-radius preflight before a change lands: asks each paired downstream owner in a namespace to run their own verification against your candidate ref, then merges the answers. Each downstream owner approves the request behind their own HITL gate (invariant `I24` / static `D18`), so the call blocks on human responses for up to 10 minutes.

```bash
nimbus preflight src/billing/retry.ts --namespace project:zurich
nimbus preflight src/billing/retry.ts --namespace project:zurich --strict
nimbus preflight src/billing/retry.ts --namespace project:zurich --json
nimbus preflight approve req_8f3c21
```

**Options:**

| Flag | Description |
|---|---|
| `--namespace <ns>` | **Required.** The published namespace whose downstream owners are asked |
| `--strict` | Also exit non-zero when coverage is incomplete (a downstream declined, is not configured, or is unreachable) |
| `--json` | Machine-readable JSON output (otherwise Markdown) |

**Sub-command:** `nimbus preflight approve <request-id>` — respond to an inbound federated preflight request as the local owner.

**Exit code:** non-zero if any downstream's verification failed; with `--strict`, also non-zero on incomplete coverage. Useful as a CI gate.

**`nimbus deploy preflight` is a different command** — that one runs the local pre-deploy checks for a service; see [`nimbus deploy preflight`](#nimbus-deploy-preflight).

---

## CI/CD

DORA metrics, pre-deploy checks, and post-deploy annotation — answered from the local index without an external API call. All three commands target a stable `<service-id>` you choose (e.g. `payment-service`); the underlying repo URNs (`<provider>:<owner>/<repo>`) and PagerDuty service ids are configured per-service in `[metrics.dora.<service-id>]` / `[ci.service.<service-id>]` blocks in `nimbus.toml`.

### `nimbus metrics dora`

Compute the four DORA metrics — deployment frequency, lead time for changes, change failure rate, MTTR — for a service over a chosen window. Answered entirely from indexed deployments, PRs, and incidents.

```bash
nimbus metrics dora --service payment-service
nimbus metrics dora --service payment-service --since 30d --json
```

**Options:**

| Flag | Description |
|---|---|
| `--service <id>` | Service id (the table key in `[metrics.dora.<id>]`) (required) |
| `--since <duration>` | Window — `<n>d` or `<n>h`, e.g. `30d`, `24h` (default: `30d`) |
| `--json` | Machine-readable JSON output |

Read-only; no HITL.

---

### `nimbus stats`

Bucketed time series over the local index — the counterpart to `nimbus metrics dora`, which
returns a single scalar over one window. `nimbus stats` returns one value per bucket instead.

```bash
nimbus stats mttr --service payment-service
nimbus stats pr-merges --service payment-service --window 90d --bucket 1w --json
```

**Metrics:**

| Metric id | What it counts | Notes |
|---|---|---|
| `deployment-frequency` | deploys per bucket | wraps `nimbus metrics dora`'s calculator, unchanged — windows on `item.modified_at`, which for `ci_run`/`deployment` rows is effectively event time |
| `lead-time` | median lead time for changes | wraps the DORA calculator, unchanged — windows on `item.modified_at`, **last touch** for the `pr` rows it reads |
| `change-failure-rate` | share of deploys that caused an incident | wraps the DORA calculator, unchanged — windows on `item.modified_at`, **last touch** for the `incident` rows it reads |
| `mttr` | median incident-resolution time | wraps the DORA calculator, unchanged — same `modified_at` windowing, plus DORA's `synced_at` fallback for an incident with no `opened_at_ms`; sparse buckets are common — see below |
| `pr-merges` | PRs merged, by `metadata.merged_at` | **GitHub-only** — see below |
| `incidents-opened` | incidents opened, by `metadata.opened_at_ms` | excludes incidents with no `opened_at_ms`, reported via an `incidents_missing_opened_at` gap |

**Options:**

| Flag | Description |
|---|---|
| `--service <id>` | Service id (the table key in `[metrics.dora.<id>]` / `[ci.service.<id>]`) (required) |
| `--window <duration>` | Total lookback — `<n>w`/`d`/`h`/`m`/`s`/`ms`, e.g. `90d` (default: `90d`) |
| `--bucket <duration>` | Bucket width, same units as `--window` (default: `1w`). A bucket under a day labels rows with the time as well as the date |
| `--json` | Machine-readable JSON output (human-readable table otherwise) |

Five things worth knowing before reading the output:

- **Only the two new counters bucket on a real event timestamp.** `pr-merges` uses
  `metadata.merged_at` and `incidents-opened` uses `metadata.opened_at_ms`. The four wrapped
  DORA metrics call the existing calculators unchanged, which also inherits their
  `item.modified_at` windowing — last touch, not event time, for the `pr` and `incident` rows
  three of them read, so a PR merged three weeks ago and commented on yesterday counts toward
  yesterday's bucket. This is the accepted cost of not maintaining a second copy of DORA's
  arithmetic; fixing it means changing `dora.ts` itself, which moves `nimbus metrics dora`
  too, and is a named follow-up.

- **Buckets are disjoint, except at a shared boundary for the four wrapped metrics.**
  `pr-merges` and `incidents-opened` window half-open (`>= start` and `< end`), so a boundary
  timestamp lands in exactly one bucket — genuinely disjoint. `deployment-frequency`,
  `lead-time`, `change-failure-rate`, and `mttr` call the DORA calculators unchanged, which
  window both bounds inclusively (`>= lower` and `<= upper`); an event landing exactly on a
  bucket boundary is therefore counted in *both* adjacent buckets for those four. Fixing it
  means changing `dora.ts` itself, the same accepted cost as the event-timestamp point above.

- **Buckets walk backward from now and are not calendar-aligned.** `--window 90d --bucket 1w`
  produces 13 buckets ending exactly at the moment you ran the command, so the newest point is
  always complete rather than truncated at the last calendar boundary. The accepted cost: the
  same command run on different days covers a different absolute span each time, so two runs
  are not directly comparable point-for-point.
- **`pr-merges` is GitHub-only.** Only `github-sync.ts` writes the `merged_at` timestamp this
  metric buckets on — `gitlab-sync.ts` and `bitbucket-sync.ts` write nothing. A service bound
  to a non-GitHub repo gets a `github_only_merge_data` gap alongside its count; a service with
  no GitHub repos at all gets `no_repos` rather than a misleading zero.
- **A sparse bucket prints `—`, not `0`, and a caveated one prints both its number and its
  gap.** An empty bucket means "could not be computed," not "zero occurred" — the two are
  different facts, and the gap column names why. But a gap does not always mean an empty
  bucket: `mttr` is a median, so a one-week bucket holding two incidents returns a REAL median
  carrying `low_sample`. Every non-null gap is printed on its own row, and the summary line
  underneath counts caveated buckets separately from empty ones — e.g. `4 of 13 buckets had
  data (3 caveated: 3 low_sample) · 9 empty (9 low_sample)` — so a caveated number is never
  mistaken for a solid one, nor counted as missing data.

No new `nimbus.toml` section — every metric scopes through the same `[metrics.dora.<id>]` /
`[ci.service.<id>]` config `nimbus metrics dora` already reads. Read-only; no HITL.

---

### `nimbus deploy preflight`

Pre-deploy index check: counts active P1 incidents, failing CI on the target ref, and open PR conflicts. Useful as a deploy-gate step in CI.

```bash
nimbus deploy preflight --service payment-service --target-ref main
nimbus deploy preflight --service payment-service --target-ref release/v2.14 --mode block --json
```

**Options:**

| Flag | Description |
|---|---|
| `--service <id>` | Service id (required) |
| `--target-ref <ref>` | Git ref being deployed (required) |
| `--mode <warn\|block\|off>` | `warn` (default) — print findings, exit 0. `block` — exit 1 when any finding triggers the gate. `off` — skip checks |
| `--json` | Machine-readable JSON output |

**Exit codes:** `0` = ok (or `warn` mode with findings); `1` = `block` mode triggered or usage error; `2` = infrastructure failure (gateway not running, IPC error, malformed envelope).

**An unknown service does not pass the gate.** If `--service <id>` matches neither
`[metrics.dora.<id>]` nor `[ci.service.<id>]` in `nimbus.toml`, none of the three checks can run,
so the verdict is **`warn`** with `unknown_service` on every check — `--mode block` exits 1. It is
deliberately not `ok`: a typo'd or renamed service id is the most likely misconfiguration of a
deploy gate, and the counts being zero means "nothing was checked", not "nothing was found". The
same envelope is served over `GET /v1/preflight/deploy`, so the GitHub Action blocks too.

A first-party GitHub Action wraps `GET /v1/preflight/deploy` for use directly in workflows — see [`packages/github-actions/preflight-query/`](../packages/github-actions/preflight-query/).

Read-only; no HITL.

---

### `nimbus deploy annotate`

Record a deployment event in the local index after a deploy completes. The Gateway upserts a `deployment` item and writes one audit entry. Used by CI to feed DORA metrics.

```bash
nimbus deploy annotate \
  --service payment-service \
  --sha 4a3f9c2 \
  --target-ref main \
  --env production \
  --status success \
  --started-at 1715812800000 \
  --finished-at 1715813100000 \
  --provider github-actions \
  --run-id 12345
```

**Options:**

| Flag | Description |
|---|---|
| `--service <id>` | Service id — 1..64 chars matching `[a-z0-9][a-z0-9._-]*` (required) |
| `--sha <sha>` | Deployed commit SHA — 7..64 lowercase hex chars (required) |
| `--target-ref <ref>` | Git ref deployed (required) |
| `--env <env>` | Environment (`production`, `staging`, …) — 1..32 chars matching `[a-z0-9][a-z0-9._-]*` (required) |
| `--status <s>` | One of `success`, `failure`, `cancelled`, `in_progress` (required) |
| `--started-at <ms>` | Deploy start time, unix milliseconds (required) |
| `--finished-at <ms>` | Deploy end time, unix milliseconds (optional) |
| `--provider <name>` | One of `github-actions`, `gitlab`, `jenkins`, `circleci`, `bitbucket`, `other` (default: `other`) |
| `--workflow-url <url>` | Optional pointer to the CI run URL |
| `--run-id <id>` | CI run identifier |
| `--job-id <id>` | CI job identifier within the run |
| `--json` | Machine-readable JSON output |

**HTTP write surface:** internally this routes through `POST /v1/deployments` on the local HTTP API — one of the fourteen routes on the compile-time `WRITE_ROUTE_ALLOWLIST` (invariant `I13`: allowlist + bearer auth + per-token rate limit + audit-on-rejection). Any write to a non-allowlisted route is rejected. For this route an 8 KiB body cap applies, and every rejection is recorded as a `deployment.annotation_rejected` audit row.

**Required vault key:**

| Key | Purpose |
|---|---|
| `http_api.deployment_token` | Bearer token sent with every `POST /v1/deployments`. Set with `nimbus vault set http_api.deployment_token <token>`. Without it the HTTP write surface returns 503 (`write_surface_disabled`). |

A first-party GitHub Action wraps the endpoint for use directly in workflows — see [`packages/github-actions/annotate-action/`](../packages/github-actions/annotate-action/).

---

## Editor Integration

### `nimbus mcp-server`

Expose the Nimbus local index to MCP-compatible editor AIs (Cursor, Claude Code, Copilot) as a read-only MCP stdio server.

```bash
nimbus mcp-server            # print the MCP config block to paste into your editor (mcp.json)
nimbus mcp-server --stdio    # run the server over stdio (your editor launches this)
```

The Gateway must be running (`nimbus start`). Seventeen tools are registered; run
`nimbus mcp-server --help` for the live list, which is derived from the registry rather
than restated.

**Index and metrics (6, synchronous):** `searchIndex`, `getConnectorStatus`,
`getRecentIncidents`, `getRecentPullRequests`, `getRecentDeployments`, `getDoraMetrics`.

**Why-lens probe (1, synchronous):** `peekWhy` — a sub-300 ms one-liner for a
`path[:line]` or symbol.

**Agent briefs (10, asynchronous):** `explainWhy`, `getCatchup`, `findExpert`,
`assessImpact`, `findConflicts`, `findDecisions`, `getGlossary`, `checkResourceUsage`,
`getPeerContext`, `getTeamHuddle`. Each starts an `agents.*` run and returns the markdown
brief plus its typed findings once the matching `briefReady` notification arrives; the
wait is bounded at 60 s, overridable with `NIMBUS_MCP_TIMEOUT_MS`. `getPeerContext` and
`getTeamHuddle` reach paired peers across the federation mesh, not just this machine.

`agents.preflight` is deliberately **not** exposed: it is the `I24` federated action path,
and triggers sandboxed execution on peers behind the owner's HITL gate. No write or HITL
surface is exposed.

Briefs served over MCP are recorded in the egress ledger (`I29`) — the adapter declares
`kind: "mcp"` on connect, so `nimbus prove` accounts for them.

---

## Security

### `nimbus security scan`

Local credential-hygiene scan over already-indexed content.

```bash
nimbus security scan                       # pretty table
nimbus security scan --json                # frozen JSON envelope (machine-readable)
nimbus security scan --service filesystem  # scope to one connector
nimbus security scan --fail-on-finding     # exit 1 if any non-muted finding remains (CI)
nimbus security scan --extended            # also run the low-confidence pattern tier
```

**Flags.** `--service <name>` scopes the scan to one connector. `--fail-on-finding`
makes the command exit `1` when any non-muted finding remains (for CI gates).
`--extended` additionally runs the low-confidence pattern tier
(`[security].extended_patterns`) — combine it with `--fail-on-finding` only with a
well-maintained `[[security.allowlist]]`, or CI will flag false positives.

**Muting false positives.** Each finding prints a `fingerprint`; add it under
`[[security.allowlist]]` in `nimbus.toml` to mute it on future scans.

**Blame attribution.** For findings in git-tracked source files, the scan reports
the commit, author, and date that introduced the line — read from the local index
(no `git` call at scan time). If a finding shows no attribution, run
`nimbus connector sync filesystem` to populate the blame data, then re-scan.

**What it does.** Iterates every `item` row from connectors at `summary` or
`full` depth, applies a curated set of high-precision regex patterns
against `body_preview`, and reports likely secrets along with their
connector, item id, and modification time. **Read-only** — the scan never
fetches new content, never invokes a connector, never writes anything
beyond a single summary audit row. Connectors at `metadata_only` depth
are skipped and listed in the response.

**Output safety.** The full secret value never appears in stdout, JSON,
logs, or any audit row. Findings show:

- `match_redacted` — first-4 + `****` + last-4 (e.g. `AKIA****MPLE`).
- `context_snippet` — ±40 chars around the match, secret middle replaced
  with the literal string `[REDACTED]`.

**Posture.** CLI-only — not exposed to the Tauri renderer (not in
`ALLOWED_METHODS`), not callable over LAN (in `FORBIDDEN_OVER_LAN` as
exfiltration-class), not on the HTTP API.

**Exit codes.** `0` on completion (with or without findings); `1` on
usage error or gateway-not-running; `2` on IPC failure / malformed
response.

---

## Sandboxed Code Execution

### `nimbus exec`

Run code inside the platform sandbox, behind an approval prompt showing the
exact body that will execute. Invariant **I33**.

**Off by default.** Add to `nimbus.toml`:

```toml
[code_execution]
enabled           = true       # DEFAULT false
max_wall_clock_ms = 30000
max_output_bytes  = 1048576
allowed_runtimes  = ["bun"]
```

With `enabled = false` the gate refuses *before* prompting, so a fresh install
has no arbitrary-code-execution path and the capability cannot be discovered by
triggering a prompt.

```bash
nimbus exec --code 'console.log(1 + 1)'
nimbus exec --file ./script.ts --allow-fs-write ./out --timeout 5000
```

| Flag | Meaning |
| --- | --- |
| `--code <src>` | Inline source. Mutually exclusive with `--file`; one is required. |
| `--file <path>` | Script to run. Read **once**, before the prompt — the approved bytes are the executed bytes. |
| `--runtime <id>` | Registry id. Only `bun` ships today; `--file` otherwise maps by extension (`.ts`/`.js`/`.mjs`) and **rejects** an unrecognised one rather than guessing. |
| `--allow-fs-read <path>` | Repeatable. Resolved to absolute against **your** cwd before it is sent. |
| `--allow-fs-write <path>` | Repeatable. Same resolution. |
| `--timeout <ms>` | Wall-clock budget, capped by `max_wall_clock_ms`. |

**There is no `--allow-net`, and no network is grantable.** That includes
loopback — a script cannot reach the Gateway's own IPC socket or HTTP API. A
request that asks for network is rejected, not silently downgraded.

**Exit codes.** A script's own exit code passes through unchanged. Control
outcomes use the 124–127 band the shell already reserves for "the command did
not run":

| Code | Meaning |
| --- | --- |
| *n* | The script exited with *n*. |
| `124` | Killed: wall-clock exceeded. |
| `125` | Killed: output cap exceeded. |
| `126` | You denied the approval, cancelled the prompt, or let it time out. |
| `127` | Refused before consent — disabled by config or org policy, unknown runtime, relative grant path, missing file, body over the size cap. |

**The distinction is not absolute, and this document will not pretend it is.** A
script is free to `exit 126` itself, and nothing in the exit code can separate
that from a denial. The band is chosen to make the collision unlikely rather
than impossible — 124 is GNU `timeout`'s, 125 is `git bisect`'s, 126 and 127
are the shell's found-but-not-executed and not-found. **stderr carries the
unambiguous reason** in every control case, and is what a script should read
when it needs certainty.

There is no separate timeout code. The consent broker treats an unanswered
prompt as a denial, so a timeout reports as one; a distinct code would be
documented and unreachable.

**The LLM cannot invoke this.** `nimbus exec` is owner-only in this release, so
no indexed content can cause code to run. That bound is what makes a single
human approval a sufficient boundary.

**Org lockoff.** A signed `nimbus.policy.toml` can disable it fleet-wide:

```toml
[policy.capabilities.ai_v2]
code_execution = false
```

Only `false` carries meaning — `= true` is a no-op, because policy may tighten
the local posture and never loosen it.

---

## Computer-Use Sessions (browser and terminal lanes)

### `nimbus computer`

Open a HITL-gated computer-use session — a sandboxed **browser** or a sandboxed
**terminal** — and watch its action log, answering the two consent-prompt kinds
inline. Invariant **I35**, static rule **D26**, schema **V57**.

**Off by default, and empty even when on.** Add to `nimbus.toml`:

```toml
[computer_use]
enabled                 = true       # DEFAULT false
allowed_lanes           = ["browser", "terminal"] # DEFAULT [] — a second, deliberate lock
max_actions             = 50
max_wall_clock_ms       = 300000
snapshot_max_bytes      = 262144
snapshot_retention_days = 7
```

`enabled = true` alone grants no lane — `allowed_lanes` must name one too, so
turning the capability on does not silently turn every lane on with it. With
either left at its default the gate refuses *before* prompting.

```bash
nimbus computer browser --origin https://github.com --script-origin https://api.github.com
nimbus computer terminal --cwd ./my-project
nimbus computer sessions
nimbus computer close <session-id>
```

| Subcommand | Meaning |
| --- | --- |
| `browser --origin <o>...` | Open a browser-lane session. Repeatable `--origin` builds the navigate allowlist (at least one required); repeatable `--script-origin` builds the SEPARATE allowlist for script-initiated `fetch`/XHR/`WebSocket` requests (default empty). `--max-actions <n>` / `--timeout <seconds>` clamp the session's action and wall-clock budgets. Every origin is canonicalised client-side and REFUSED — never widened — if it carries a path, query, fragment, userinfo, or a trailing-dot hostname. |
| `terminal --cwd <dir>` | Open a terminal-lane session: a sandboxed shell in `<dir>`, which is resolved client-side and is the shell's ONLY filesystem grant. `--shell <id>` names a registry shell (`sh` on POSIX, `cmd` on Windows) — an id, never an argv; omit it for the platform default. `--max-actions <n>` / `--timeout <seconds>` clamp the budgets. |
| `sessions` | List known sessions: id, lane, open/closed, actions used, close reason. |
| `close <session-id>` | End a session early. |

**`nimbus computer browser` is a passive listener, not a driver.** It opens the
session, answers `computer.envelopeRequest` (the up-front session approval —
lane, the **full** origin lists, the action budget, the wall-clock budget,
never elided or summarised) and `computer.actionRequest` (one per
`actuating` action — a clearly labelled **gateway-observed fact** alongside
the model's own **untrusted claim** about its intent), and then watches the
session's action count until it closes. It does not drive any action itself,
and that is by design rather than a gap: `computer.act` is driven from inside
the gateway by the model-callable browser tools, which exist only while a
session is live.

**What the terminal lane does and does not do.** Every command is shown to you
in full and approved individually before a single byte reaches the shell —
bytes the model composes accumulate gateway-side until it submits a complete
line. Control characters, escape sequences and invisible/bidirectional
formatting characters are refused outright rather than buffered, so the line
you approve renders as the bytes that will run.

Two consequences worth knowing before you enable it:

- **The shell has NO network access, including `localhost`.** `curl`, `git
  fetch`, `npm install` and anything else that needs the network will fail.
  That is the design, not a limitation to work around, and it is what lets the
  lane add no egress class at all.
- **It is line-oriented only.** `vi`, `less`, `top`, `fzf` and interactive
  confirmation prompts do not work — the shell has no tty, so most of them
  refuse to start on their own. This is the deliberate cost of approving whole
  commands rather than keystrokes.

And one bound stated plainly: approving a line proves you **saw** it, not that
you understood it. A single approved command can still do arbitrary damage
inside its working directory.

If a terminal session refuses with `ERR_CU_SANDBOX_DEGRADED`, the sandbox could
not confine it: on Linux install `bubblewrap` (`bwrap`); on Windows ensure
`nimbus-sandbox-helper.exe` sits beside the `nimbus` binary. The lane spawns a
real shell and will not do so unsandboxed.

**Ctrl-C closes the session on the GATEWAY, and exits `130`.** The session
belongs to the gateway, not to this process, so an interrupt asks the gateway
to close it rather than merely exiting — otherwise a live headless browser
would sit inside an approved envelope, unwatched, until its wall-clock ceiling
expired. A second Ctrl-C stops waiting and prints the recovery command
(`nimbus computer close <id>`) rather than blocking your terminal on a close
that is not landing.

**Refusals you can actually hit, in the order you hit them.** With the shipped
defaults (`enabled = false`, `allowed_lanes = []`) a session refuses with
`ERR_CU_DISABLED` first, then `ERR_CU_LANE_NOT_ALLOWED`. Past those,
`ERR_CU_UNSAFE_LAUNCH` means the launch policy for this session would have been
under-confined (for example a `browser_profile_dir` that is empty or relative —
Chromium with no `--user-data-dir` would run against your real browser profile),
and `ERR_CU_NO_BROWSER` means no Chrome, Chromium or Edge was found: install one,
or point `NIMBUS_CHROMIUM_PATH` at an absolute path to a non-standard install.
Unlike before 2026-08-31, `ERR_CU_NO_BROWSER` now has a local fix — the raw-CDP
driver shipped, so a machine with a Chromium-family browser can open a real
session.

**Exit codes.**

| Code | Meaning |
| --- | --- |
| `0` | The session closed cleanly — no close reason, or an owner-initiated `close`. |
| `110` | The owner denied the session envelope. |
| `112` | Terminated: action budget exhausted. |
| `113` | Terminated: wall-clock budget exhausted. |
| `127` | Refused — bad arguments, disabled by config/org policy, an under-confined launch policy, or no Chromium-family browser found. Shared with `nimbus exec`'s `refused` code: same meaning, different command, deliberately. |
| `130` | Interrupted (Ctrl-C). `128 + SIGINT`, the POSIX convention — the session was asked to close cleanly on the gateway. |

**No pixels ever reach disk.** A screenshot capture is BLAKE3-digested and
discarded in the same expression; only the digest is recorded. No image
file is written on any lane, at any point.

**Org lockoff.** A signed `nimbus.policy.toml` can disable it fleet-wide:

```toml
[policy.capabilities.ai_v2]
computer_use = false
```

Only `false` carries meaning, matching `nimbus exec`'s lockoff.

---

## Media Understanding

### `nimbus media understand`

Transcribe audio/video already in the index — local files and, as of PR 3 (2026-09-04),
cloud-backed artifacts from Google Photos, Google Drive and OneDrive — caption still images,
and — as of PR 2 (2026-09-03) — caption a small number of uniformly sampled frames from each
video alongside its transcript. Output is stored as searchable derived items
(`nimbus:video_understanding`, `nimbus:image_understanding`).

**Local models by default, with one narrow exception.** As of PR 4 (2026-09-05), a STILL IMAGE —
never audio or video — may instead be described by a remote vision model, but only for an
artifact the owner has explicitly granted with `nimbus media allow-remote` (below). Absent a
grant, images are captioned locally exactly as before PR 4. **Audio and video are never sent to a
remote model in this release, full stop** — transcription and frame sampling stay entirely local,
and the pass refuses rather than reaching for the cloud when no local whisper/vision model is
available, unchanged from PR 1. A cloud candidate's BYTES leaving the machine (bounded, ledgered —
see below, PR 3) is a separate question from whether its UNDERSTANDING does — granting one grants
neither the other. Schema **V58** (`media_pass_cursor`); the per-artifact remote-consent grant
below is schema **V59** (`media_grant`).

**Off by default, twice.** Both switches must be set:

```toml
[multimodal]
enabled = true            # DEFAULT false

[[filesystem.roots]]
path        = "~/recordings"
media_index = true        # DEFAULT false — per root
```

`media_index` is per-root and separate on purpose: enabling the capability should not
silently start walking every configured root for large binaries.

**The whole `[multimodal]` section — seven keys, all optional:**

| Key | Default | Meaning |
| --- | --- | --- |
| `enabled` | `false` | The capability kill switch, above. |
| `vlm_base_url` | `http://127.0.0.1:11434` | The Ollama base URL the LOCAL vision model is served from. **Must be a loopback address** (`127.0.0.0/8`, `localhost`, or `[::1]` — the same `isLoopbackBaseUrl` check I34 uses) **or the gateway refuses to load `[multimodal]` at all**, throwing an error that names the offending value and the reason, rather than silently substituting the loopback default. This key has nothing to do with sending an image to a remote vendor — that is `remote_vlm`, below, a wholly separate provider selected per artifact by an explicit grant, never by pointing this URL off-loopback. A non-loopback value here is still refused after PR 4: `av-understander.ts` computes `isLocal` as `stt.isLocal && vlm.isLocal`, so a non-local value on this key would silently disable the audio transcription that works today — the failure mode `remote_vlm`'s separate, grant-gated opt-in exists to avoid. Leave this at its default, or point it at another loopback port. |
| `vlm_model` | `qwen2.5vl:7b` | The Ollama model tag to caption with. **You must pull this yourself** (`ollama pull qwen2.5vl:7b` or your own tag) — nothing in this pass downloads a model. A daemon that is up but has not pulled a vision-capable model reports unavailable, and the pass refuses images/frames with `no_local_model` rather than guessing. |
| `max_frames` | `8` | The maximum keyframes sampled per video, clamped to 1–64. Actual sampling is also density-capped at one frame per 2 seconds of video, so a short clip samples fewer than the maximum. |
| `fetch_budget_bytes` | `2147483648` (2 GiB) | The byte budget for a single `nimbus media understand` run's cloud-backed fetches (Google Photos / Google Drive / OneDrive). A **negative** value is malformed for this key and fails the WHOLE `[multimodal]` section off (same fail-off direction as a malformed `enabled`), rather than substituting the default. `0` is accepted and means "no cloud bytes may be fetched this run" — a local-only pass still runs. Overridden per run by `--budget`, below. |
| `prefer_renditions` | `false` | Ask Google Photos for a downsized rendition instead of the original artifact. Drive and OneDrive have no rendition concept and always serve the original regardless of this setting. Overridden per run by `--renditions`/`--originals`, below. |
| `remote_vlm` | unset | **As of PR 4 (2026-09-05).** Names the ONE vendor allowed to receive a per-artifact remote-vision grant: `anthropic`, `openai` or `gemini` — a deliberately narrower set than `[llm.remote.*]`'s four text vendors (no `xai`; it ships no vision adapter here). **Images only** — this key has no effect on audio or video, which stay local-only regardless of its value. Unset (the default) means no remote vendor is configured, and `nimbus media allow-remote` refuses every grant request outright rather than silently picking one. An unsupported or misspelled name **refuses to load `[multimodal]` at all**, naming the offending value — the same loud-refusal posture as a non-loopback `vlm_base_url`, and for the same reason: a silently-disabled section would be indistinguishable from the feature not existing. The vendor's API key is **reused**, never re-entered: it is the existing `[llm.remote.<vendor>]` Vault entry (`nimbus vault set <vendor>.api_key` — see the "Cloud vendors" subsection below). Reusing the credential is deliberate and its limit is stated plainly: having given that vendor a key for `nimbus ask` does **not** grant it permission to see this machine's photos — that permission is `nimbus media allow-remote`'s alone, artifact by artifact. |

**Requires three external binaries on PATH:** `ffmpeg` (transcode + frame extraction) and
`whisper-cli` (transcription) are required for audio/video; `ffprobe` (video duration,
needed to place sampled frames) is required for frame captions specifically — a video
still transcribes without it, just with no frame captions and the absence stated in the
row's body. Override with `NIMBUS_FFMPEG_PATH` / `NIMBUS_WHISPER_PATH` /
`NIMBUS_FFPROBE_PATH`.

```bash
nimbus media understand                        # up to 50 candidates
nimbus media understand --limit 10             # bound the run
nimbus media understand --service filesystem   # one service
nimbus media understand --modality image       # still images only
nimbus media understand --modality av          # audio/video only
nimbus media understand --since 30             # modified within 30 days
nimbus media understand --budget 500MB         # cap this run's cloud byte-fetches
nimbus media understand --renditions           # prefer smaller downsized copies (Photos only)
nimbus media understand --originals            # always fetch the original (mutually exclusive with --renditions)
nimbus media understand --json                 # machine-readable summary
```

**Cloud-backed as of PR 3 (2026-09-04).** Alongside local files under `[[filesystem.roots]]`,
the pass now discovers and fetches candidate bytes from Google Photos, Google Drive and
OneDrive — the same three OAuth-backed services already indexed elsewhere. `--budget <size>`
bounds one run's cloud byte-fetches (a raw byte count, or a number with a unit suffix —
decimal `KB`/`MB`/`GB`, 10^3n, vs. binary `KiB`/`MiB`/`GiB`, 2^10n; the two are **not**
interchangeable, e.g. `4GB` = 4,000,000,000 bytes but `4GiB` = 4,294,967,296), overriding
`[multimodal] fetch_budget_bytes` for that run. `--renditions` asks Google Photos for a
downsized copy rather than the original (Drive and OneDrive always serve the original
regardless); `--originals` is the explicit opposite; the two are mutually exclusive. The
whole candidate batch is priced before any fetch: if the known cost already exceeds the
budget, the run refuses up front rather than fetching part of it and stopping mid-way.

**Resumable, with two different behaviors depending on WHY a run stopped.** Progress is a
cursor in `media_pass_cursor`. A per-artifact SKIP always advances the cursor — including a
**permanent** refusal, where a cloud candidate's size alone exceeds the ENTIRE run budget
(reported as `over_byte_cap`, below) — so a re-run does not retry an unprocessable artifact
forever. But a **transient** budget stop — a candidate that simply didn't fit what THIS run
had left, having already spent part of its budget on earlier candidates — leaves the cursor
on the last *completed* item instead, so the stopping artifact IS retried, not skipped, once
a later run has a fresh budget to offer it. The understanding-format version bumped to 2
with PR 2, so a video already transcribed under PR 1 is re-offered once and gains frame
captions on its next pass.

**The summary reports skips by reason, not just a total:**

```text
Understood 42 of 108.
Skipped:
  over_byte_cap: 51
  no_local_model: 15
```

`over_byte_cap` covers **two different bounds**, not one: the per-artifact cap AND, for a
cloud candidate whose declared size alone exceeds the entire per-run `fetch_budget_bytes`,
the permanent run-budget case described above. Only ONE of those two is tunable. The
per-artifact cap is a hardcoded 250 MiB (`DEFAULT_MAX_MEDIA_BYTES` in
`packages/gateway/src/multimodal/build-media-pass-deps.ts`), one value for images and audio/video alike — there is
no config key and no flag for it, so raising it means changing the code. `fetch_budget_bytes`
IS a `[multimodal]` config key. So a nonzero `over_byte_cap` is worth reading before acting:
check whether the skipped candidates are cloud-backed, because only that half of the count has
a knob at all.

A bare count would not tell you whether the other 66 were absent, too large, or refused.
The same discipline applies inside a `video_understanding` row's body: a caption count
("6 of 8 sampled frames captioned") and any reason frame captions are entirely absent
("no vision model was available", "the video duration could not be determined") are
stated in the text itself, not only in metadata — the text is what an agent's context
actually sees.

**What it does NOT do:** no dedicated OCR engine (a VLM's text extraction on a dense
screenshot is worse than a purpose-built OCR pass); no remote model for audio or video, at
any tier — transcription and frame sampling stay entirely local even for a cloud-fetched
artifact's bytes, refusing rather than reaching for the cloud when no local model is
available, unchanged since PR 1; and speaker diarization (`whisper-cli` cannot do it). A
sampled video is not a watched video: anything happening only between sampled frames goes
undescribed, and a caption is a model's guess, not an observation — nothing here stores a
confidence number. Transcripts and captions are embedded **locally** even when a remote
embedder is configured, so text and image descriptions extracted from a private recording
or a remotely-described image are never sent to a remote embedding service. **Still images
are the one exception to "no remote model"** — see `nimbus media allow-remote` immediately
below.

**Not reachable over LAN.** The whole `media` namespace is denied to paired peers,
alongside `exec` and `computer` — the command reads local files and spawns subprocesses.

**Org policy gates this capability.** `[policy.capabilities.ai_v2]`'s `multimodal_input`
flag is read live on every call (invariant I22); setting it disables `media.understand`
even when `[multimodal] enabled = true` locally, and the command also refuses fail-closed
if the policy accessor itself is unavailable rather than silently proceeding.

### `nimbus media allow-remote` — grant remote vision consent, per artifact

**As of PR 4 (2026-09-05). This grants a REMOTE MODEL permission to see an image, and
ONLY an image** — there is no way to grant audio or video: the grant store itself refuses
to write one for either modality, and the pass never even asks a granted-but-non-image
candidate whether it has one. Reading an image's bytes over the network (PR 3, `--budget`
above) and letting a remote model DESCRIBE those bytes (this command) are two independent
permissions; granting one never implies the other.

```bash
nimbus media allow-remote <itemId>... --vendor <name>
nimbus media allow-remote --service <name> --limit N --vendor <name> [--since <days>]
```

Two mutually exclusive forms — explicit item ids, or a selector — and mixing them is
refused rather than resolved by precedence:

- **Explicit form:** name one or more indexed item ids directly.
- **Selector form:** `--service`/`--since` narrow a scan of indexed media; **`--limit` is
  MANDATORY here and has no default** — an unbounded "grant everything matching" must never
  be expressible. **`--limit` is capped at 500** (`MAX_GRANT_LIMIT`); a value above that is
  refused outright, not clamped down to it. If you hit that refusal, it is the documented
  ceiling working as intended, not a bug — split the grant across more than one invocation,
  or narrow the selector with `--service`/`--since` first.

`--vendor <name>` is required on every invocation and must match the configured
`[multimodal] remote_vlm` **exactly** — a mismatch is refused rather than silently granted
to whichever vendor actually is configured, since the caller named a specific third party.
Every invocation prints an enumerated preview — every matching artifact by **title**, never
just a count, naming BOTH ends of the transfer (`source <service>|local` and `destination
<vendor>`) and whether it is new or already granted — then asks for `[y/N]` confirmation
before writing anything. Refuses outright in non-interactive (non-TTY) mode rather than
defaulting to "no": a consent surface must never assume an answer. An explicit item id the
scan cannot resolve to a known source service is refused rather than shown with a
guessed or blank source, since a consent preview must never assert a source it cannot
substantiate.

A grant is durable and per `(artifact, modality, vendor)` until revoked — see
`nimbus media grants list`/`revoke` below — and, once written, the artifact is re-offered by
`nimbus media understand` even if it was already understood locally, so the next run
re-describes it through the granted remote vendor.

### `nimbus media grants list` / `nimbus media grants revoke`

```bash
nimbus media grants list
nimbus media grants revoke <itemId> [--vendor <name>]
```

`grants list` prints every currently ACTIVE grant — title (or a placeholder if the item is
no longer indexed), vendor, and the timestamp it was granted — with no filtering flags.
`grants revoke` **always requires an item id**; there is no "revoke everything" form, by
design (a blanket revoke is a `for` loop over `grants list`'s output, not a command this
surface offers). `--vendor` narrows a revoke to one vendor's grant on that item; omitted, it
revokes every vendor's active grant on that item.

---

## Overnight Agent Fleets

Standing, owner-configured agent jobs that run on idle local hardware and leave a brief waiting.
**Shipped as PR 1 of 2 (2026-09-07); off by default.** Enable with `[fleet] enabled = true` plus at
least one `[[fleet.job]]` block — both are required, and a config with `enabled = true` and no jobs
is *enabled and not running*, which `nimbus fleet status` reports as two separate fields.

Everything here is local: a fleet brief is written to SQLite and read back by you. Invariant
**I38** pins an unattended run's synthesis to a LOCAL model unless `[fleet] allow_remote = true`
AND the run's remaining call budget covers the call — a frontier key configured under
`[llm.remote.<vendor>]` for interactive `nimbus ask` grants the fleet nothing on its own.

**Subject enumeration (PR 2b) shipped 2026-09-17.** A `[[fleet.job]]` can name a `sweep` kind
instead of one subject, in which case the fleet rotates through a bounded window of subjects each
run — see `sweep`/`max_subjects`/`path_prefix` below, `--subject` on `fleet briefs`, and the
`sweep` field on `fleet list`. `negotiate` remains classified `deferred` rather than eligible, so
it cannot be named as a job's `agent`: no sweep enumerator returns person-shaped subjects, and
turning "the owner built one dossier" into a nightly, unattended dossier on every indexed person
has no consent surface today.

### `nimbus fleet status`

```bash
nimbus fleet status [--json]
```

Prints the `[fleet]` config and a **live** host-activity probe. Touches neither the scheduler nor
the store, so it answers truthfully when the fleet was never constructed at all:

```text
fleet: enabled (running)
  jobs configured:    2
  requires AC power:  true
  min idle seconds:   900
  allow remote:       false (budget 0)
  retention days:     14
  host power:         ac
  host idle ms:       unknown
```

`host idle ms: unknown` is a real answer, not a failure. **Linux never measures user idle** — the
backend reads `/sys/class/power_supply` for power and reports `idleMs: null` with
`source: "power_only"` — because X11, Wayland and headless each answer differently and a server has
no session to be idle from. Admission on Linux is therefore power-only, and every run row records
`host_source` so a brief can never imply an idle check that was not performed.

### `nimbus fleet list`

```bash
nimbus fleet list [--json]
```

Lists every **configured** job (from `[[fleet.job]]`), not only ones that have run, with its
last-success timestamp and consecutive-failure count:

```text
morning-catchup  agent=catchup  interval=86400s  last success=2026-09-07T03:12:44.001Z  consecutive failures=0
```

A job with a `sweep` gains a trailing summary of its enumeration and rotation state, read from
`fleet_job_state` (`fleet.list` already reads that store; sweep progress lives HERE, not on
`fleet.status`, which never touches it):

```text
bus-factor  agent=ownership  interval=86400s  last success=2026-09-17T03:12:44.001Z  consecutive failures=0  sweep=paths max=200 total=843
```

`total` is `null` (rendered `?`) before the job has ever enumerated. An empty enumeration prints
its `emptyReason` alongside the counts rather than a silent `total=0`. When the estimated full
rotation (`ceil(total / max_subjects)` runs, at the job's `interval_seconds`) exceeds
`retention_days`, the line ends with `WARNING: a full rotation outlasts retention; this sweep
cannot report movement` — a subject's predecessor brief would already have expired by the time the
rotation revisits it, so the digest (below) can never show what changed for that subject. In
`--json`, each entry's `sweep` is `null` for a config-named job, or
`{ kind, maxSubjects, pathPrefix, subjectsTotal, cursor, emptyReason, rotationExceedsRetention }`
for a sweep job.

### `nimbus fleet briefs`

```bash
nimbus fleet briefs [--limit N] [--job <name>] [--subject <key>] [--json]
```

Lists synthesised briefs, most recent first — id, job, agent method, creation time. `--limit`
defaults to 20 and is capped at 500 **at the IPC boundary**, not in the CLI (a `brief_markdown`
body can be tens of KB, so an unbounded limit is an unbounded response). `--subject <key>` filters
to one subject's briefs; used **without** `--job`, it is a legitimate cross-job question — two
jobs can sweep the same subject — and is not a table scan (`idx_fleet_brief_subject`). Every row
carries `subjectKey` in `--json`; the human listing shows it in brackets only when it differs from
the job id (a config-named job's subject IS the job, so its output line is unchanged from before
this PR).

Expiry is enforced **on the read path** — `expires_at > now` — as well as by the prune, so an
expired brief is never returned even between prunes; a read surface that still returned one would
make retention a lie. The physical delete runs at **gateway boot** and again at the **end of every
fleet run**, never on a timer of its own — the boot pass runs **unconditionally**, with the fleet
disabled and even when `[fleet]` failed to parse, and is therefore the only one a machine with the
fleet turned off ever gets. Rows written
while it was enabled exist either way, and retention must not hinge on today's typo. Org policy can
raise `retention_days` but never lower it (`retentionMinDays`), and the floor is applied *before*
the scheduler stamps each brief's `expires_at`, not only to the prune.

### `nimbus fleet show <id>`

```bash
nimbus fleet show <briefId> [--json]
```

Prints one brief's full markdown body. A brief that never existed and one that has expired are
**deliberately indistinguishable** (both exit `3`): a distinguishable "it expired" answer would
itself be a retention disclosure.

### `nimbus fleet run <job> [--force]`

```bash
nimbus fleet run morning-catchup
nimbus fleet run morning-catchup --force
```

Runs one configured job right now, bypassing its schedule — both its `interval_seconds` and any
failure backoff it is currently sitting in. NAMING the job is what does that: backoff exists to stop
an unattended loop hammering a failing job, not to refuse an owner's explicit single request, and
the run still records its outcome so backoff re-arms for the scheduled path. `--force` additionally
bypasses the host-admission check (battery / user-active), and nothing else. Neither bypasses
`[fleet] enabled`, org policy, agent eligibility, or the remote call budget — those refuse
identically with or without them.

```text
completed: attempted 1, completed 1, skipped(not due) 0, unattempted 0
```

Two different refusals both report `deferred` and are told apart by the message: *"a fleet run is
already in flight"* (the scheduler's re-entrancy guard fired; no `fleet_run` row was opened) versus
*"the host is on battery or in use"* (a row was opened and admission then said no).

### `nimbus fleet digest`

```bash
nimbus fleet digest [--since <duration>] [--json]
```

Prints what moved since the window began — every job in the **union** of currently configured
`[[fleet.job]]` blocks and any job that produced a brief inside the window, each compared against
its most recent predecessor before the window, with the comparison and non-comparison entirely
local (SQLite in, markdown out; no model call). A job that produced briefs but has since been
removed from config is still reported — never silently dropped — marked `[unconfigured]` so a
reader cannot infer it will run again tonight. `--since` accepts the same duration syntax as
elsewhere (`5m`, `1h`, `90d`) and defaults to `24h`; an unparseable or non-positive value is a usage
error, exit `1`, same as any other malformed flag on this command.

An **empty digest is not an error** — a quiet night (nothing changed, or nothing has run twice yet)
and a broken fleet must not look the same to a script that checks the exit status, so `digest`
always exits `0` when it successfully reaches the store. A job with only one brief in the window
(no predecessor to compare against), a configured job that produced no brief inside the window at
all, a brief whose findings JSON does not match its agent's shape, and a job that changed which
agent it runs between the two compared briefs are each reported under `## Not compared`, not
treated as failures.

**A sweep job (above) renders as ONE section, not one per subject.** It prints a coverage line
(`<agent> · swept <n> of <total> subjects this window · full rotation ≈ <k> runs ≈ <d> days ·
retention <r> days`), every moved subject in full, and unchanged / first-observation (the first 10
keys, `… and N more` in Markdown — `--json` carries every key) / not-summarizable / agent-changed
as counts; `## Not compared` for a sweep is computed at JOB level only, since an individual
subject having "no brief in window" is the expected shape of rotation, not a comparison failure.
When the rotation estimate exceeds `retention_days`, the section says so rather than silently
omitting movement it cannot compute. `--json`'s top-level result gains one additive key, `sweeps`
(empty when no job sweeps); a config-named job's own `jobs[]` entry is unaffected.

**Exit codes** (`nimbus fleet` only): `0` ok — including a `yielded` run, which is a host-activity
boundary stopping a run early rather than a failure, and including an empty digest; `1` usage; `2`
fleet disabled or its store unavailable; `3` no such job or no such brief; `4` run deferred; `5` run
failed.

### `[fleet]` configuration

```toml
[fleet]
enabled            = false   # DEFAULT OFF
allow_remote       = false   # DEFAULT OFF; requires remote_call_budget > 0 or the config is REFUSED
remote_call_budget = 0       # non-local synthesis calls PER RUN, reset at each run boundary
min_idle_seconds   = 900     # ignored on a host that cannot measure idle (see above)
require_ac_power   = true    # blocks on `battery`; `unknown` (desktop/VM/server) still admits
retention_days     = 14      # org policy may RAISE this floor, never lower it

[[fleet.job]]
name             = "morning-catchup"
agent            = "catchup"    # must be a fleet-ELIGIBLE agent; `negotiate` is deferred
interval_seconds = 86400
digest_min_delta = 1          # DEFAULT 1; a metric must move by at least this much to be reported
                               # as "changed" rather than "unchanged within threshold" — values
                               # below 1 are REFUSED (a 0 would report every no-op fluctuation)
# any other key becomes a param passed to the agent, camel-cased on the way, e.g.:
since_ms         = 86400000   # -> sinceMs, which `agents.catchup` reads
```

Refusals are loud rather than silent, on purpose. `allow_remote = true` with no budget is
**refused** — an unbounded overnight remote grant must not be expressible. A `[[fleet.job]]` block
missing `name`, `agent` or a positive `interval_seconds`, or repeating a `name`, is **refused**
rather than dropped (dropping it silently would leave the owner believing a job runs) and rather
than defaulted (a daily schedule they never chose). A malformed `[fleet]` config does not crash
boot: the gateway logs loudly, constructs no scheduler, and comes up with the fleet off.

#### Sweep jobs (`sweep`, `max_subjects`, `path_prefix`)

A `[[fleet.job]]` can set `sweep` instead of naming one subject in its own parameters, so the
scheduler rotates through every subject the index can list for that kind, a bounded window per
run:

```toml
[[fleet.job]]
name             = "bus-factor"
agent            = "ownership"
interval_seconds = 86400
sweep            = "paths"       # "paths" | "services" | "symbols" | "terms"
max_subjects     = 200           # REQUIRED when `sweep` is set; integer 1..500
path_prefix      = "packages/"   # optional; "paths"/"symbols" only
```

`sweep`, `max_subjects` and `path_prefix` join the reserved keys, so they never reach the agent as
a parameter. **Refused, never clamped or silently dropped, naming the job and the reason:**

- `sweep` names a kind the agent does not accept — including every not-enumerable agent (`why`,
  `expert`, `impact`, `catchup`, `decisions`, `standup`, `huddle`, `janitor`; see the enumerator
  table below).
- `sweep` is set and the job ALSO sets the parameter that kind supplies (`path`, `service`,
  `file`, `term`) — two sources for one subject.
- `sweep` is set and `max_subjects` is absent, non-integer, `< 1`, or `> 500`.
- `max_subjects` or `path_prefix` is set without `sweep`.
- `path_prefix` is set on `services`/`terms` (neither accepts it), or is the empty string (every
  path starts with `""`, so an empty prefix would silently mean "no narrowing"; whitespace is
  kept verbatim — a path may legally contain spaces, so it is never trimmed).
- `sweep` is combined with `namespace`/`namespaces` on `ghost`/`conflicts` — those fan out to
  paired peers, and a sweep would multiply federated calls under the owner's identity; a sweep
  stays local.

**The four kinds and what they enumerate:**

| `sweep` | Source | Eligible agents | `path_prefix` |
|---|---|---|---|
| `paths` | the ownership pass's own indexed files/directories (git-aware roots only) | `ownership` | yes |
| `services` | configured `[ci.service.<id>]` / `[metrics.dora.<id>]` ids | `oncall`, `changelog`, `ownership` | no |
| `symbols` | distinct code-symbol labels from the filesystem symbol graph | `ghost`, `conflicts` | yes |
| `terms` | consolidated glossary terms | `glossary` | no |

`ownership` accepts both `paths` and `services`; a job picks one. `ghost`/`conflicts` sweep
`symbols` rather than file paths, since their match parameter takes an exact symbol-label lookup
before a fuzzy basename match, and a path sweep would hand every same-named file the identical
fuzzy token; a same-named function/type in one file, or the same file indexed under two roots,
share one label and enumerate as ONE subject (a stated bound — see
[`architecture.md` § Spine S2 Subsystems](./architecture.md#spine-s2-subsystems)). `janitor`
cannot be swept: its subject is free text probed for mentions, and the index holds no resource
inventory to enumerate one from.

**Eligible agents** (14 of the 18 served `agents.*` methods): `catchup`, `standup`, `oncall`,
`changelog`, `huddle`, `glossary`, `decisions`, `ownership`, `why`, `ghost`, `conflicts`, `impact`,
`expert`, `janitor`. Excluded: `preflight` and `premortem` (side effects — a HITL prompt nobody is
awake to answer, and durable watcher/tombstone writes), `whyPeek` (synchronous shape, never fires
the completion notification the invoker awaits), and `negotiate` (**deferred**, settled rather
than pending: no sweep enumerator returns person-shaped subjects, and a nightly, unattended
dossier over every indexed person has no consent surface today). The map is TOTAL over the served
methods, so a new agent does not compile until someone classifies it.

**Org lockoff:** `[policy.capabilities.ai_v2] agent_fleet = false` in a signed `nimbus.policy.toml`
halts the scheduler before any hardware probe (invariant I22, tighten-only).

---

## Runtime Tool Generation

### `nimbus tool`

Register, list and revoke owner-approved, session-ephemeral generated tools — model-authored code
that runs sandboxed and can reach only the hosts and credentials the owner explicitly approved.
Invariant **I39**.

**Drafting shipped as PR 2 of 3 of the runtime-tool-generation slice.** `nimbus tool create` now
drafts a real tool body instead of refusing: it grounds a prompt on API endpoints already indexed
from OpenAPI specifications under `[[filesystem.roots]]`, asks a model for the tool's JavaScript
body AND its input schema in one structured reply, runs a four-rung validation ladder — the reply
is JSON; the schema fits the restricted input-schema subset; the body parses as valid JavaScript;
the body contains no construct the sandbox would refuse — with exactly ONE bounded redraft on
failure, and only then prompts the owner to approve the verbatim body, the drafted parameters, and
the grounding provenance. `ERR_TOOLGEN_DRAFT_NOT_IMPLEMENTED` is gone. Design:
[`architecture.md` § Runtime tool generation](./architecture.md#runtime-tool-generation-toolgen-nimbus-tool).

**Persistence shipped as PR 3 of 3 (invariant I40, schema V61).** `nimbus tool save <tool-id>`
promotes a live, session-only generated tool to a DURABLE one: the artifact is signed with a
Vault-held Ed25519 key, written to `<configDir>/toolgen/saved/<tool-id>/`, rowed in
`generated_tool`, verified again at every boot and — where an invoke path exists — again at spawn.
It is the first STANDING approval in this codebase, so it prompts separately from `create` and over
a separate broker: approving a save consents to "run this in every future session, unattended",
which the create-time approval never covered. `nimbus tool revoke` is its withdrawal path and drops
the row, the `saved/` directory, the registry entry, the ephemeral script and the Vault credential
together. Design:
[`architecture.md` § Runtime tool generation](./architecture.md#runtime-tool-generation-toolgen-nimbus-tool).

**Invocation shipped in a follow-up.** `nimbus tool run <tool-id> [--input <json>] [--json]` calls
a SAVED tool through the new `toolgen.invoke` IPC method — CLI-only and LAN-forbidden like every
other `toolgen.*` method, and absent from the Tauri allowlist. It runs the saved artifact's real,
signature-verified body in a fresh confined spawn and returns the result. See below for its full
contract. **What has not moved:** the engine's `deps.toolgen` is still deliberately left unwired in
`gateway-main.ts`, so the model itself still cannot call a generated tool — `nimbus tool run` is
CLI/owner-only, the same scope bound `nimbus exec` holds under I33. An ephemeral (created-but-not-
saved) tool is still not invocable at all.

**Not shipped:** agent-initiated tool proposal (`allow_agent_initiated` + `allowed_hosts`).

**`[tool_generation] drafting` controls which model may author a tool body — DEFAULT `"local"`:**

```toml
[tool_generation]
enabled                = true    # DEFAULT false
drafting                = "local" # "off" | "local" | "allow-remote" — DEFAULT "local"
max_tools_per_session   = 3
max_requests_per_tool   = 50
request_timeout_ms      = 10000
```

- **`"off"`** — drafting always refuses (`ERR_TOOLGEN_NO_DRAFT_MODEL`); the rest of the substrate
  (gate, sandbox, broker) is unaffected.
- **`"local"`** (the default) — only a provider whose `isLocal` is `true` (I34, derived from its
  resolved base URL, never a vendor id) may draft. **Configuring a `[llm.remote.<vendor>]` key for
  `nimbus ask` grants drafting nothing on its own** — a frontier key already working for
  interactive use does not widen what `nimbus tool create` may do; the owner must opt in
  per-capability by setting `drafting` itself. Mirrors `[agents] synthesis` (I31) and `[fleet]
  allow_remote` (I38): a grant WIDENS what may happen and never redirects a call that would
  otherwise stay local.
- **`"allow-remote"`** — permits a remote draft but does not force one: it asks the router for the
  `"reasoning"` task with no `preferLocal` override, so it DEFERS to the owner's own `[llm]
  prefer_local` preference exactly as any other unoverridden call would — a local model already
  registered still drafts locally under `"allow-remote"` unless `prefer_local = false` (or no local
  route exists at all).

**What a remote draft actually sends, when `"allow-remote"` picks a remote provider:** the owner's
tool description, the normalised host list, the names (never values) of hosts that will carry a
credential, and the grounding block — the indexed endpoints' method, path, `operationId` and
summary drawn from this machine's own private index. It never sends a credential value: the
drafting function is never even handed one (spec § 9.1). The call rides the existing `model` I29
egress class (`egressMethod: "toolgen.draft"`) like any other remote generate, so a non-zero
`nimbus prove` window discloses it.

**Grounding.** The prompt is grounded on `api_endpoint` items already indexed from OpenAPI
specifications under `[[filesystem.roots]]`, via the local index's ranked search — hybrid
(BM25 + vector) where semantic search is available, lexical-only otherwise. **The index read itself
is local, but the query embedding is not automatically:** the description is embedded through
whatever `[embedding]` is configured with, so on a remote-embedder install the grounding search
sends the tool description to that embedding vendor. That request is ledgered `model`-class like
any other remote embed, so a `nimbus prove` window discloses it. With a local embedder — the
default — nothing leaves the machine. `drafting = "off"`, and a machine with no eligible drafting
route, refuse BEFORE the grounding search runs, so neither reaches the embedder at all. When
nothing matches, the model
drafts from the description and standard REST conventions alone, and the approval prompt says so
rather than leaving the owner to assume the draft was grounded:

```text
Register the generated tool "generated_<id>"?

  description: fetch the weather

async function __invoke(args) { ... }

  parameters:       city: string (required), units: string?
  grounding:        3 indexed endpoint(s) from open-meteo

  hosts:            api.example.com
  credential hosts: none

  note: an approved host may receive anything this tool can compute. The host list bounds
        WHERE it may send, never WHAT.
```

When nothing was indexed, the `grounding:` line instead reads `no indexed API specification
matched — drafted from the description alone`.

**The pre-consent confinement probe.** The gate proves the sandbox can confine a candidate tool
(`toolgen-confinement.ts`'s `assertToolConfinement`) BEFORE the owner is ever prompted — even after
a draft succeeds. It writes a sentinel file outside every path the tool's manifest grants, verifies
it can read that file itself, then spawns a nine-line inline `-e` script under the tool's real
policy and requires it to FAIL to read the same path. Parent can, child cannot: therefore the
sandbox confined it. Any read failure counts, because the three platforms deny by three different
mechanisms — `ENOENT` on Linux (bwrap's `--tmpfs /tmp` masks the file out of existence), `EPERM` on
macOS under `(deny default)`, an ACL denial on Windows, where the AppContainer holds no ACE for that
path.

Both halves of that were different, and wrong, until 2026-09-10, and the command did not work on
ANY platform:

- It spawned a diagnostic script from `@nimbus-dev/sdk/testing` as a bare file entry point
  (`bun <probe> --probe=fs-denied`), which cannot start under a restrictive manifest inside the
  Windows AppContainer (`CouldntReadCurrentDirectory` — the measured dead end `toolgen-client.ts`
  already works around for the tool's own post-approval launch, via an `-e` stub). Moving the probe
  inline removes the file entry point AND the `node_modules/` path no manifest grants read to.
- It read a "known-protected system path" (`/etc/passwd`, `C:\Windows\System32\config\SAM`), which
  is not a measurement of THIS sandbox on POSIX: `bwrap` `--ro-bind`s `/etc` unconditionally and the
  macOS profile grants `(subpath "/private/etc")`, so a perfectly confined child read
  `/etc/passwd` happily and the probe reported "unconfined". Every `nimbus tool create` on Linux and
  macOS refused with `ERR_TOOLGEN_CONFINEMENT_FAILED` before the owner was prompted.

This was invisible because nothing ever ran the default probe — the unit tests inject `spawnProbe`,
and the integration suite injected its own inline copy. Both now drive the real one. Verified: the
toolgen integration suite passes on Windows against a real `nimbus-sandbox-helper.exe`, and on Linux
against real `bwrap` 0.11.1, where the same two cases failed before the change. macOS is
unverified on hardware here; the sentinel shape is the one
`test/integration/platform/sandbox/sandbox-wrapper-spawn.test.ts`'s "refuses a path the policy does
not grant" case already uses and passes with on that platform's CI leg.

**What `max_tools_per_session` actually bounds from the CLI.** Every `nimbus tool` invocation
shares one fixed session id (`cli`), so `nimbus tool list` run from a fresh process can find a tool
a previous `nimbus tool create` invocation just registered — a random id per invocation would make
that impossible, since each command is its own short-lived process. The tradeoff: for
CLI-originated tools, `max_tools_per_session` is not a per-command limit at all — it is a single
budget of `max_tools_per_session` LIVE generated tools shared by every `nimbus tool create` call
this gateway process serves, for as long as that process runs (the registry is in-memory only and
resets on a gateway restart). A real agent conversation does not share this bound: it mints a fresh
session id per conversation via `agentRequestContext`, so its budget really is per-conversation.

```bash
nimbus tool create --description "fetch the weather" --host api.example.com
nimbus tool create --description "post to my tracker" --host api.example.com \
  --host files.example.com --credential api.example.com=sk_live_...
nimbus tool list
nimbus tool list --json
nimbus tool save 3fa85f64-5717-4562-b3fc-2c963f66afa6
nimbus tool run 3fa85f64-5717-4562-b3fc-2c963f66afa6 --input '{"city":"Berlin"}'
nimbus tool run 3fa85f64-5717-4562-b3fc-2c963f66afa6 --input '{"city":"Berlin"}' --json
nimbus tool revoke 3fa85f64-5717-4562-b3fc-2c963f66afa6
nimbus tool credential set 3fa85f64-5717-4562-b3fc-2c963f66afa6 api.example.com --bearer sk_live_...
```

A tool id is a raw `randomUUID()` value (`ToolgenGateDeps.newId`) — there is no `tg_`-style prefix.

| Subcommand | Meaning |
| --- | --- |
| `create --description <text> --host <h>...` | Register a tool. `--host` is repeatable and at least one is required. `--credential <host>=<token>` is repeatable and bearer-only from the CLI; naming a host not also passed to `--host` is refused before anything is sent to the gateway. |
| `list [--json]` | Live tools from this CLI's own session, UNION every SAVED tool regardless of session — including a saved tool that failed verification, which is listed with its `disabledReason` rather than silently omitted. Never a credential value, only the host names a credential is bound for. |
| `save <tool-id>` | Promotes a live tool to a DURABLE one (I40): signs the artifact with a Vault-held Ed25519 key, writes `saved/<tool-id>/`, rows it in `generated_tool`. Prompts SEPARATELY from `create`, over its own broker — approving a save is a STANDING approval ("runs in every future session, unattended"), not the create-time one reused. Refuses a tool that is not live in this session. Saving the exact bytes twice is a no-op (`already_saved`); re-saving bytes whose row is disabled but whose digest still matches is a `repaired`, with no fresh prompt. |
| `run <tool-id> [--input <json>] [--json]` | Invokes a SAVED tool — `create` alone is not enough; the tool has to have gone through `save` first. `--input` is a JSON object of the tool's arguments, validated CLIENT-SIDE before anything is sent to the gateway: it must parse as JSON and be an object, or the CLI refuses before opening a connection. Omitted `--input` defaults to `{}`. No approval prompt: the STANDING approval already obtained at `save` time covers every future invocation, unattended, which is the whole point of persisting a tool — see `save`'s own row. Headless-capable, unlike `create`/`save`: nothing here needs a TTY. |
| `revoke <tool-id>` | The WITHDRAWAL PATH, and the one the save prompt names. Ends the tool's child process, evicts it from the registry's saved set, deletes its `generated_tool` row and its `saved/<tool-id>` directory, deletes its approved ephemeral script, and deletes every Vault credential bound to it — one call, all of it, so a revoked tool does not come back at the next boot. Idempotent, and works whether the tool is saved-only, ephemeral-only, or both. The reserved id `signing` is refused (`ERR_TOOLGEN_TOOL_ID_RESERVED`): its Vault prefix is the artifact-signing keypair's. |
| `credential set <tool-id> <host> (--bearer <token> \| --header <name> <value> \| --basic <user> <pass>)` | Binds a credential to a host the tool was ALREADY approved to reach. This is the recovery path for a SAVED tool after a restart: a saved tool's approval persists, its per-host secret never does (the boot/shutdown sweep is total), so a saved tool needing a credential re-acquires it here. `credentialHosts` is part of the signed artifact and is never widened — a host outside it is refused with `ERR_TOOLGEN_CREDENTIAL_HOST_UNKNOWN`. All three schemes work. |

**`--credential <host>=<token>` is now transmitted and binds a BEARER credential per host, at
create time.** `create`'s `--credential <host>=<token>` is parsed and checked client-side (host
membership, non-empty value), sent to the gateway on `toolgen.create`'s `credentials` field, and
bound into a per-host Vault entry (`toolgen.<toolId>.<hostSlug>`) before the owner is prompted — the
approval prompt's `credential hosts:` line names every host that actually got a binding, so a
dropped or malformed entry is visible there rather than silently absent. The broker attaches it as
an `Authorization: Bearer <token>` header on every brokered request to that host, and a credential
value never reaches the drafting prompt or the approval prompt (spec § 9.1) — only the host name
does.

**All three credential schemes are now reachable, via `nimbus tool credential set`.** `nimbus tool
create --credential <host>=<token>` still only ever constructs a `bearer` binding — there is no
create-time flag for the other two — but `credential set` parses `--bearer`, `--header <name>
<value>` and `--basic <user> <pass>`, sends the narrowed binding on `toolgen.credentialSet`, and the
gateway writes it to the per-host Vault entry. (Through PR 2 this subcommand always refused, and
`header`/`basic` were reachable from no user-facing path at all; both statements are now out of
date.)

**A credential can be supplied AFTER create — but only for a host that was already approved.** The
earlier "credentials are supplied at create time, never after" framing described PR 2 and no longer
holds: a SAVED tool's approval survives a restart while its per-host secret deliberately does not
(the boot/shutdown Vault sweep is total), so a saved tool that needs a credential has to be able to
get one again, and `credential set` is that path. What has NOT changed is the part that carries the
security weight: `credentialHosts` sits inside the signed, owner-approved artifact, and
`credential set` never widens it — a host outside that signed list is refused
(`ERR_TOOLGEN_CREDENTIAL_HOST_UNKNOWN`), so a standing approval can never quietly come to cover a
recipient the owner did not consent to. Binding a secret for an already-approved host is not the
same act as approving a new host, and only the second one is what the gate exists to prevent.

**The approval prompt shows the tool's VERBATIM body, its drafted parameters, its grounding
provenance, its host list and its credential host list — never a digest and never a credential
value.** The human approving it is the entire security boundary for this capability, the same
posture `nimbus exec`'s prompt takes for a script body.

**Refuse in a non-TTY, always.** `nimbus tool create` needs an interactive terminal to show that
prompt; run it from a script or a pipe and it refuses immediately, before opening a gateway
connection, rather than treating a piped `y` as approval of code it never showed anyone:

```text
$ echo y | nimbus tool create --description d --host api.example.com
error: nimbus tool create needs an interactive TTY for owner approval.
There is no headless path: toolgen.create is LAN-forbidden and local-only.
```

`toolgen.*` is LAN-forbidden in its entirety (`create` is RCE-class by definition, and
`approvalRespond` is the local owner answering a prompt no peer may answer for them) and absent
from the Tauri allowlist (I7).

**Exit codes for `create`.**

| Code | Meaning |
| --- | --- |
| `0` | The tool was registered. |
| `126` | The owner denied the approval prompt or let it time out. |
| `127` | Refused before consent — disabled by config or org policy, a bad argument, non-TTY stdin, the session's tool budget spent, drafting failed the validation ladder twice (`ERR_TOOLGEN_DRAFT_INVALID`) or found no eligible model (`ERR_TOOLGEN_NO_DRAFT_MODEL`), or sandbox confinement failed (`ERR_TOOLGEN_CONFINEMENT_FAILED`). |

On `ERR_TOOLGEN_DRAFT_INVALID`, and only when the route that produced the failing draft was LOCAL,
the CLI adds a hint: configure a larger local model (`[llm] min_reasoning_params`) or set
`[tool_generation] drafting = "allow-remote"`. It is withheld when the failing route was remote —
suggesting a bigger local model to someone already on a frontier model is noise, not help.

**`nimbus tool run` — invoking a saved tool.** `--input`'s object is checked for the right SHAPE,
never full JSON Schema conformance: every key the tool's drafted `inputSchema` marks `required` must
be present, and that is the entire check — a `required: number` field holding a string is not
caught here, nor is anything about `properties` the drafted schema does not mark required. The tool
body itself is what actually consumes the value, so a type mismatch surfaces as a normal tool
failure (`status: "failed"`), not a refusal.

`toolgen.invoke` (`{ toolId, input? }`) returns one of three shapes, exactly:

```text
{ status: "executed", toolId, result, durationMs }
{ status: "failed",   toolId, error,  durationMs }
{ status: "refused",  toolId, code,   reason? }
```

Without `--json`, stdout carries only the result (a string bare, anything else pretty-printed, and
`(no output)` for none) and the duration goes to **stderr** — `nimbus: completed in <n> ms`, or
`nimbus: failed after <n> ms` beneath a failure's error — so piping stdout still yields exactly the
tool's output. With `--json`, a successful run prints the JSON result and nothing else, duration
included.

**Nothing about the call is recorded except that it happened.** At most one `audit_log` row is
written per invocation — never two, and if that single append fails the invocation fails with it
rather than returning an outcome, which can leave zero rows for a tool that ran —
(`action_type: "tool.invoke"`, `hitl_status: "not_required"` — the STANDING
approval obtained at `save` time, not a fresh one per call), and its payload carries the outcome,
the tool id, the duration, and — on a refusal or failure — the code/error text. It carries neither
the `--input` object nor the tool's `result`: the projection type the row is built from has no
member for either, so adding one is a compile error, not a discipline someone has to remember.
**One honest bound, stated rather than left implicit:** a tool's `error` text is free text the TOOL
itself composes, capped at 512 Unicode code points before it is written to the row — a tool that
echoes its own input back into its error message can put that fragment in the row. The cap bounds
the exposure; it does not eliminate it. The full, uncapped error still reaches the caller on the
returned outcome, which is where an operator actually reads it — the cap applies only to the copy
written to disk.

**Exit codes for `run`.**

| Code | Meaning |
| --- | --- |
| `0` | `status: "executed"` — the tool ran and returned its result. |
| `1` | `status: "failed"` — the tool ran and threw. This code means the tool EXECUTED; nothing that refuses before a spawn lands here. |
| `127` | `status: "refused"` — refused before any spawn: the capability is off (config or org policy), the tool id does not name a SAVED tool (`ERR_TOOLGEN_NOT_SAVED` — includes a tool that was only ever `create`d, never `save`d; when a saved row exists but was skipped at load, the refusal's reason names its `disabledReason`), the input failed the gateway's own required-key check, the platform sandbox cannot confine the tool on this machine (`ERR_TOOLGEN_SANDBOX_DEGRADED` — e.g. the Windows helper is missing; the same code `tool create` refuses with, and asked before spawning so it is never recorded as a run that failed), or the saved artifact's signature no longer verifies (`ERR_TOOLGEN_SIGNATURE_INVALID` — tampered or corrupted since `save`). A `--input` that fails the CLIENT-SIDE JSON/object check exits `127` too: it is a usage error refused before the gateway is dialed at all, so it shares the code every other usage error gets rather than `1`, which would claim the tool ran. |

**Org lockoff.** A signed `nimbus.policy.toml` can disable it fleet-wide:

```toml
[policy.capabilities.ai_v2]
tool_generation = false
```

Only `false` carries meaning, matching `nimbus exec`'s and `nimbus fleet`'s lockoffs.

---

## Interactive Sessions

### `nimbus tui`

Launch the rich Ink terminal UI for interactive sessions.

```bash
nimbus tui
```

**Panes** (Option-1 "classic split" layout):

- **Query input** (top bar) — type a query; `Enter` submits.
- **Result stream** (main area) — tokens render live; scrollback preserved via Ink `<Static>` so prior output never re-renders.
- **Connector health** (right column) — polls `connector.listStatus` every 30 s; renders `●` / `◐` / `○` glyphs for `ok` / `degraded` / `down`.
- **Watchers** (right column) — polls `watcher.list` every 30 s; shows N active, M firing, plus up to 5 firing watcher names (truncates beyond with `…N more`).
- **Sub-tasks** (right column) — event-driven via `agent.subTaskProgress`; renders a progress bar + status glyph per sub-task, truncated beyond 8 rows with `…N more (M total)`. Clears when a new query is submitted.

**Interaction:**

- `Up` / `Down` cycles history from `tui-query-history.json` (last 100 queries, dedup-on-repeat-of-last).
- `Ctrl+C` once during a stream → cancels locally with `(canceled by user — LLM may continue in the background)` line; `^C Press again within 2s to exit` hint renders for 1.5 s. Double `Ctrl+C` within 2 s → exits cleanly.
- **Mid-stream HITL:** `──[ consent required ]──` banner appears inline; prompt switches to `nimbus[hitl]>` with single-keystroke capture:
  - `a` — approve current action
  - `r` — reject current action
  - `d` — show details (no-op; full payload is already shown)
  - `q` — reject all remaining actions and exit

**Automatic fallback** (invokes `nimbus repl` instead, no Ink render) when any of these hold:

- `TERM=dumb`
- `NO_COLOR` set (any value)
- stdout is not a TTY (pipe, file, non-interactive shell)
- `CI=true`
- Terminal height is below 20 rows

Fallback path prints exactly one reason (first match wins) to stderr before handing off to the REPL.

**Responsive layout:**

- Below 100 columns: collapses to a single-column layout with a compact status bar replacing the right column.
- Below 20 rows at any time: Ink unmounts cleanly with a one-line notice; relaunch after resizing.

**Gateway-offline behavior:**

- Top banner: `⚠ Gateway disconnected — reconnecting…`
- Poll panes show last-known data with a `(stale)` marker.
- Input dimmed and disabled; `Ctrl+C` still exits.
- Exponential reconnect: 2 s → 4 s → 8 s → 16 s → 30 s (repeats). Input re-enables on reconnect; `✓ Reconnected` fade confirms recovery.

**Cancel note:** the Gateway has an `engine.cancelStream` handler (`ipc/engine-cancel-stream.ts`) that stops token streaming immediately on `Ctrl+C`. The underlying LLM generation may still complete in the background — the `AbortSignal` is not yet plumbed into the agent invocation context (see `architecture.md` § *AbortController scope in `engine.cancelStream`*), so full-fidelity cancellation remains a follow-up.

---

### `nimbus repl`

Line-based readline loop over `agent.invoke`. Always works (no Ink dependency), including SSH sessions, dumb terminals, CI, and non-TTY pipelines.

```bash
nimbus repl                      # Interactive line-based session
nimbus repl --session <id>       # Resume a saved session
```

Use this for scripts and headless environments; `nimbus tui` is the richer alternative for interactive developer sessions. `nimbus tui`'s fallback path invokes `runRepl` internally on unsuitable terminals, so you never need to choose manually — just run `nimbus tui` and let it degrade.

---

## Connectors

### `nimbus connector auth <service>`

Authenticate a service and store credentials in the OS keystore. Never stores credentials to disk or logs.

The canonical per-connector credential keys live in `CONNECTOR_VAULT_SECRET_KEYS` (`packages/gateway/src/connectors/connector-secrets-manifest.ts`); the list below is grouped by domain.

```bash
# Cloud storage / mail / calendar (OAuth PKCE — opens browser)
nimbus connector auth google_drive
nimbus connector auth gmail
nimbus connector auth google_photos
nimbus connector auth onedrive
nimbus connector auth outlook
nimbus connector auth teams

# Source control / project tracking / knowledge
nimbus connector auth github         # PAT prompt — stored in OS keystore
nimbus connector auth gitlab         # PAT (+ optional self-hosted api_base)
nimbus connector auth bitbucket      # username + app password
nimbus connector auth linear         # API key
nimbus connector auth jira           # API token + email + base URL
nimbus connector auth confluence     # API token + email + base URL
nimbus connector auth notion         # OAuth
nimbus connector auth slack          # OAuth
nimbus connector auth discord        # bot token (opt-in)

# CI/CD
nimbus connector auth jenkins        # base URL + username + API token
nimbus connector auth circleci       # API token
# github_actions reuses the github credential above (there is no gitlab_ci service: GitLab CI data
# comes from the gitlab connector, authenticated above)

# Cloud platforms / infrastructure
nimbus connector auth aws
nimbus connector auth azure
nimbus connector auth gcp
nimbus connector auth kubernetes
nimbus connector auth iac            # IaC CLIs (enable flag)

# Observability / incident
nimbus connector auth pagerduty
nimbus connector auth grafana        # URL + API token
nimbus connector auth sentry         # auth token + org slug + URL
nimbus connector auth newrelic       # API key + account id
nimbus connector auth datadog        # API key + app key + site

# Recruiting / CRM (OAuth where noted — opens browser)
nimbus connector auth hubspot        # OAuth 3-legged
nimbus connector auth salesforce     # OAuth 3-legged + PKCE — per-tenant instance_url

# Design / whiteboard (OAuth 3-legged — opens browser)
nimbus connector auth miro           # OAuth
nimbus connector auth canva          # OAuth + PKCE (Basic-header secret)
nimbus connector auth figma          # OAuth (+ non-secret team id)

# Meetings
nimbus connector auth zoom           # OAuth 3-legged PKCE — opens browser
```

**Credential reuse — no separate `connector auth` needed.** `github_actions` reuses the `github` credential (there is no `gitlab_ci` service — GitLab CI data comes from the `gitlab` connector, which you authenticate directly); `google_meet` rides the `google` OAuth; and the metadata-only **BigQuery / Athena / CloudWatch / SageMaker / Cloud Logging / Vertex AI** connectors reuse your `aws` / `gcp` credentials. Authenticate the underlying provider and these light up automatically.

**Connectors set up with `nimbus vault set`, not `connector auth`.** The services below have no `connector auth` flow. Running `nimbus connector auth <service>` for one of them refuses and prints the exact `nimbus vault set` commands for that service. Store each setting with `nimbus vault set <key> <value>`; every write asks for your approval. Set the keys your setup uses: optional ones, such as a self-hosted base URL or a team id, can be left out. The table comes from `CONNECTOR_VAULT_SECRET_KEYS`; if it ever disagrees with what the refusal prints, the refusal is current.

| Service | Vault keys |
| --- | --- |
| `snyk` | `snyk.token` |
| `bitrise` | `bitrise.token` |
| `codemagic` | `codemagic.token` |
| `testflight` | `testflight.issuer_id`, `testflight.key_id`, `testflight.private_key` |
| `firebase` | `firebase.service_account_json`, `firebase.app_ids` |
| `sonarqube` | `sonarqube.token`, `sonarqube.url`, `sonarqube.organization` |
| `semgrep` | `semgrep.token`, `semgrep.deployment_slug` |
| `wiz` | `wiz.client_id`, `wiz.client_secret`, `wiz.api_url`, `wiz.auth_url` |
| `launchdarkly` | `launchdarkly.token`, `launchdarkly.base_url`, `launchdarkly.project_key` |
| `flagsmith` | `flagsmith.token`, `flagsmith.api_base` |
| `argocd` | `argocd.url`, `argocd.token` |
| `flux` | `flux.api_url`, `flux.token` |
| `dbt` | `dbt.token`, `dbt.api_base`, `dbt.account_id` |
| `metabase` | `metabase.url`, `metabase.api_key` |
| `superset` | `superset.url`, `superset.username`, `superset.password` |
| `databricks` | `databricks.host`, `databricks.token` |
| `mlflow` | `mlflow.host`, `mlflow.token` |
| `vercel` | `vercel.token`, `vercel.team_id` |
| `netlify` | `netlify.token` |
| `stripe` | `stripe.api_key` |
| `mercury` | `mercury.token` |
| `readwise` | `readwise.token` |
| `raindrop` | `raindrop.token` |
| `intercom` | `intercom.token` |
| `zendesk` | `zendesk.url`, `zendesk.email`, `zendesk.api_token` |
| `lever` | `lever.api_key` |
| `greenhouse` | `greenhouse.api_key` |
| `pipedrive` | `pipedrive.token` |
| `stackoverflow` | `stackoverflow.token`, `stackoverflow.team` |
| `zotero` | `zotero.api_key`, `zotero.library` |
| `dependencytrack` | `dependencytrack.base_url`, `dependencytrack.api_key` |
| `airflow` | `airflow.base_url`, `airflow.username`, `airflow.password` |
| `prefect` | `prefect.api_url`, `prefect.api_key` |
| `dagster` | `dagster.base_url`, `dagster.api_token` |
| `ramp` | `ramp.client_id`, `ramp.client_secret` |
| `elasticsearch` | `elasticsearch.url`, `elasticsearch.api_key` |
| `great_expectations` | `great_expectations.results_dir` |
| `imap` | `imap.host`, `imap.port`, `imap.username`, `imap.password`, `imap.mailbox`, `imap.smtp_host`, `imap.smtp_port`, `imap.smtp_username`, `imap.smtp_password` |
| `fastmail` | `fastmail.api_token`, `fastmail.base_url` |
| `protonmail` | `protonmail.username`, `protonmail.password`, `protonmail.imap_host`, `protonmail.imap_port`, `protonmail.mailbox`, `protonmail.smtp_host`, `protonmail.smtp_port`, `protonmail.smtp_username`, `protonmail.smtp_password` |
| `localdb` | `localdb.scripts_dir` |
| `storybook` | `storybook.dir` |
| `dataprofile` | `dataprofile.dir` |
| `snowflake` | `snowflake.account`, `snowflake.oauth_token`, `snowflake.key_pair_jwt` |
| `tableau` | `tableau.url`, `tableau.pat_name`, `tableau.pat_secret` |
| `looker` | `looker.base_url`, `looker.client_id`, `looker.client_secret` |
| `powerbi` | `powerbi.tenant_id`, `powerbi.client_id`, `powerbi.client_secret` |
| `montecarlo` | `montecarlo.api_id`, `montecarlo.api_token` |
| `bigeye` | `bigeye.base_url`, `bigeye.api_key` |
| `apple` | `apple.icloud_email`, `apple.icloud_app_password`, `apple.mailbox`, `apple.cal_window_past_days`, `apple.cal_window_future_days`, `apple.cal_max_instances`, `apple.cal_include_calendars`, `apple.cal_exclude_calendars` |

**Output — the command reports only what it actually checked.** For a handful of PAT-based connectors (`github`, `gitlab`, `bitbucket`, `jira`, `jenkins`) the gateway makes one cheap identity-endpoint call before returning; every OAuth connector is confirmed by construction — a completed PKCE browser consent + token exchange IS the provider confirming the credential. So the outcome is one of:

- `Verified: <service>` — the provider confirmed the credential: a 2xx from the identity check (PAT connectors), or a completed OAuth token exchange (OAuth connectors).
- `Stored: <service> (NOT verified — the provider did not confirm it)`, plus a follow-up line suggesting a retry — the credential was stored but the check got a non-401 failure (403, 429, 5xx, 404, or a transport failure); those causes are not distinguished. It may still be valid.
- `Stored: <service> (not verified)` — no probe is registered for that service (the remaining PAT connectors); the credential was stored as given and nothing was checked.

A credential the provider actively **rejects** (HTTP 401) is never stored: `nimbus connector auth` throws and exits with status `1` (a user-actionable precondition — fix the token and retry). Any other failure to store — including the gateway being unreachable — also exits with status `1`; `connector auth` has only one error path (an unhandled `Error` reaching the CLI's top-level catch-all), so there is no separate "operational failure" exit code here. All three outcomes above — verified, unverified, and unprobed — exit `0`: the credential was stored, which is what the command was asked to do.

#### Zoom OAuth setup

Zoom uses 3-legged OAuth (PKCE + Basic-header client-secret). Before running `nimbus connector auth zoom`, create a Zoom app and export the client credentials:

1. Go to [marketplace.zoom.us](https://marketplace.zoom.us) → **Develop** → **Build App** → **General app** (User-managed, PKCE).
2. Add scopes: `user:read:user`, `meeting:read:list_meetings`, `cloud_recording:read:list_user_recordings`.
3. Copy the **Client ID** and **Client Secret** and export them:

```bash
export NIMBUS_OAUTH_ZOOM_CLIENT_ID=<client_id>
export NIMBUS_OAUTH_ZOOM_CLIENT_SECRET=<client_secret>
nimbus connector auth zoom
```

The access token and rotating refresh token are stored in the OS keystore under `zoom.oauth`. Token rotation is handled automatically by the Gateway's single-flight refresh lock (Zoom invalidates the entire token chain on refresh-token reuse, so only one refresh runs at a time).

The connector indexes both scheduled meetings (`zoom:meeting`) and cloud-recording AI transcripts (`zoom:transcript`, prose-heavy). The `cloud_recording:read:list_user_recordings` scope above covers transcripts — no re-consent is needed beyond the initial `nimbus connector auth zoom`. New transcripts are picked up on the next sync cycle; `nimbus connector reindex zoom` forces an immediate pass.

---

### `nimbus connector detect`

Reuse a login you already have in `gh`, `aws`, `kubectl` or `gcloud` instead of creating a token.

```bash
nimbus connector detect
nimbus connector detect --source gh
nimbus connector detect --source gcloud --project acme-prod
nimbus connector detect --replace
nimbus connector detect --json
```

Lists what it finds, then — in a terminal — offers each one. With several gh accounts, AWS
profiles or kube contexts it asks which (Enter takes the active one); gcloud has no numbered pick —
its login is whatever `gcloud config list` currently reports active. Every adoption asks for your
approval (`connector.adoptLocalAuth`, a HITL action); without a terminal nothing is adopted.

| Source | What Nimbus stores | Stays in sync with the CLI? |
| --- | --- | --- |
| `gh` | a COPY of the token `gh auth token` prints, as `github.pat`, checked against GitHub first | No — `gh auth logout` does not disconnect Nimbus; run `detect --replace` after a re-login |
| `aws` | the profile name (+ its region); no key is copied | Yes — the aws CLI resolves the profile at every sync |
| `kubectl` | the kubeconfig path + context; nothing is copied | Yes — kubectl resolves it at every sync |
| `gcloud` | the account's login, and a project id; nothing is copied | Yes — gcloud resolves it at every sync |

`--project <id>` names the GCP project id to adopt. It is required when gcloud has no default
project of its own (`gcloud config list` reports `needs_project` — still offerable, unlike every
other non-`available` status) and optional otherwise, where it overrides gcloud's own default
project for this adoption only. A project number, or anything that does not match a GCP project id
shape, is refused rather than stored.

Detection is local: it reads gh's `hosts.yml`, runs `aws configure list-profiles` and
`kubectl config …`, and runs `gcloud config list --format json`; none of these makes a network
request. Adopting gh sends ONE request — the token check to `api.github.com/user` — recorded in
the egress ledger (`nimbus prove`); adopting gcloud makes none (`connector.auth gcp`'s gcloud arm
only writes Vault keys, so there is nothing to probe and no egress row for it). GitHub Enterprise
hosts are listed but not offered (the GitHub connector has no `api_base` yet). Refused under
`--demo`.

**`--json` is unstable** in this release: it prints the gateway's findings array as-is and may
change shape.

---

### `nimbus connector list`

List all connectors and their current health state.

```bash
nimbus connector list
nimbus connector list --json
nimbus connector list --json | jq -r '.[] | select(.healthState != "healthy") | .serviceId'
```

**Health states:** `healthy` · `degraded` · `error` · `rate_limited` · `unauthenticated` · `paused`

**`--json` shape.** A JSON array of the raw `connector.listStatus` rows — `serviceId`, `status`, `lastSyncAt`, `nextSyncAt`, `intervalMs`, `itemCount`, `lastError`, `consecutiveFailures`, `healthState`, `healthRetryAfterMs` (timestamps are epoch ms or `null`, not the relative "5m ago" strings the table renders). With no connectors registered the output is `[]`, not the human "No connectors registered yet" hint.

---

### `nimbus connector status <name>`

Show detailed status for a single connector.

```bash
nimbus connector status github
nimbus connector status github --stats   # Attach the 15 most recent sync-telemetry rows
```

Output is always JSON; `--stats` is the only flag read.

---

### `nimbus connector sync <name>`

Trigger an immediate sync for a connector.

```bash
nimbus connector sync github
nimbus connector sync google_drive
```

---

### `nimbus connector pause <name>` / `resume <name>`

Pause or resume sync scheduling for a connector without removing its credentials.

```bash
nimbus connector pause github
nimbus connector resume github
```

---

### `nimbus connector set-interval <name> <duration>`

Override the sync interval for a connector. The duration is unit-suffixed (`ms`, `s`, `m`, `h`) — a bare number is rejected with `Invalid duration "300" (use e.g. 5m, 1h, 30s)`.

```bash
nimbus connector set-interval github 5m
nimbus connector set-interval google_drive 1h
```

---

### `nimbus connector history <name>`

Show the health transition history for a connector — useful for diagnosing flapping or persistent errors.

```bash
nimbus connector history github
nimbus connector history github --limit 50
```

Output is always JSON.

---

### `nimbus connector remove <name>`

Remove a connector: deletes all associated Vault entries and index rows atomically.

```bash
nimbus connector remove github          # Prompts: y/n
nimbus connector remove github --yes    # Skip confirmation (-y also works)
```

> **Irreversible.** On success the command prints the number of index rows deleted plus the Vault keys it cleared, and nothing restores them. Take a snapshot first (`nimbus db snapshot`) if you may want the index rows back.

The CLI asks for confirmation before it sends `connector.remove`. Declining the prompt (or cancelling it with Ctrl-C) prints `Cancelled.` and sends nothing. Outside an interactive shell — piped, or run from a script — there is no prompt to answer, so the command refuses with a non-zero exit rather than waiting for input; pass `--yes` or `-y` to proceed non-interactively.

`connector.remove` is also a HITL action on the Gateway side, but you are only asked once: the CLI confirmation *is* the consent decision, and the CLI answers the Gateway's consent request with it. A declined prompt never reaches the Gateway at all, and `--yes` covers both — the auto-approval is still noted on stderr (`[--yes] auto-approving HITL request: …`) so it shows up in a script's log. If the Gateway rejects the removal anyway (for example an org policy that forbids it), the command exits non-zero with the rejection reason and removes nothing.

---

### `nimbus connector reindex <name>`

Re-ingest a connector's data at a chosen depth. Useful after changing data-minimization policy, recovering from a corrupted partial sync, or applying a new schema version. The Gateway preserves Vault credentials; only index rows are rewritten.

```bash
nimbus connector reindex github
nimbus connector reindex slack --depth metadata_only
nimbus connector reindex notion --depth summary
nimbus connector reindex confluence --depth full
```

**Depth values:**

| Depth | Effect |
|---|---|
| `metadata_only` *(default for this command)* | IDs, timestamps, titles, URLs, owners — no body content. Suppresses both `body` and `body_preview`; a connector's fetched text is discarded before it reaches the index. |
| `summary` | Metadata + a 512-character prefix of each item's body, stored in `body_preview`. There is no summarizer — it is a plain truncation, and it never claims completeness (`body_complete` stays 0). |
| `full` | Metadata + full body content up to the connector's cap (16 KiB for prose-heavy item types, 512 characters otherwise) — the largest index footprint. |

`metadata_only` is the default **only for `nimbus connector reindex` when `--depth` is omitted** (the CLI passes `metadata_only` explicitly in that case, and the reindex persists it). It is not the depth a connector starts at: a connector that has never had its depth explicitly set — a fresh install's first sync — resolves to `full`, since `sync_state` rows are always written with `depth = 'full'` (`connectors/health.ts` `upsertHealthRow`) and a missing `sync_state.depth` row also resolves to `full`. Running `reindex` without `--depth` therefore *lowers* a connector's depth from its `full` starting point — pass `--depth full` explicitly to reindex without changing it.

Output reports the resolved mode and the number of items affected. The depth is persisted as the connector's default and is enforced on **every** subsequent sync, not only at `reindex` time — every connector's item-writing code path is routed through a shared depth chokepoint (`upsertIndexedItemForSync`) that coerces the row to the configured depth before it is written, so a `metadata_only` or `summary` connector never accumulates full bodies between explicit reindexes.

**Deepening is not retroactive.** Lowering the depth rewrites existing rows immediately (bodies are stripped or clamped in place), but **raising** it does not bring back text that was never stored: `--depth full` on a connector that has been running at `summary` or `metadata_only` reports `0` items affected and switches the setting for future syncs only. The Gateway has no copy of the discarded bodies to restore from — they have to be fetched again. To recover them, either force a fresh sync (`nimbus connector sync <name> --full`, which re-fetches from scratch rather than resuming the stored cursor) or run `nimbus index rebody --service <name>` for the connectors that support it. This asymmetry has always been in the code; it becomes visible for the first time now that depth is actually enforced between reindexes.

---

## Configuration

### `nimbus config get <key>`

Read a single configuration value.

```bash
nimbus config get telemetry.enabled
nimbus config get llm.local_model
```

There is no TOML key for sync cadence — per-connector intervals are set with `nimbus connector set-interval <service> <duration>`, which writes to the index, not to `nimbus.toml`.

---

### `nimbus config set <key> <value>`

Set a configuration value. Changes take effect on the next Gateway restart for Gateway-owned keys; CLI-only keys take effect immediately.

```bash
nimbus config set telemetry.enabled false
nimbus config set llm.local_model       llama3.2
nimbus config set llm.prefer_local      true
```

Cloud vendors are **not** configured this way — they need a whole `[llm.remote.<vendor>]` table plus a Vault key, so use `nimbus config edit` and `nimbus vault set`. See [Configuration File](#configuration-file) below.

---

### `nimbus config list`

Print the config file path, then a per-key line for whichever of the three env-overridable keys (`telemetry.enabled`, `telemetry.endpoint`, `telemetry.flush_interval_seconds`) currently has a value, followed by the raw `nimbus.toml` body. A key is listed as `env` when its environment variable is set to a non-empty value, otherwise as `file` when it is present in `nimbus.toml` — and is **omitted entirely** when it is neither. There is no `default` source and no line for an unset key. Every other key appears only in the raw dump; there is no per-key documentation column.

```bash
nimbus config list
nimbus config list --json
nimbus config list --json | jq -r '.keys[] | select(.source == "env") | .envVar'
```

**`--json` shape.** One object:

| Key | Type | Notes |
|---|---|---|
| `path` | string | Resolved `nimbus.toml` path |
| `exists` | boolean | Whether that file is present |
| `keys` | array | `{ key, value, source: "file" \| "env", envVar: string \| null }` — `envVar` is the overriding variable, `null` for file-sourced keys |
| `raw` | string \| null | The file body verbatim; `null` when the file is missing |

The prose "other `NIMBUS_*` overrides" legend the human view prints is static documentation, not data, and has no JSON counterpart.

---

### `nimbus config validate`

Validate the current `nimbus.toml` configuration file against the schema. Exits `0` on success, `1` on error.

```bash
nimbus config validate
```

---

### `nimbus config edit`

Open `nimbus.toml` in `$EDITOR`.

```bash
nimbus config edit
```

---

### Configuration File

`nimbus.toml` lives in the platform config directory:

| Platform | Path |
|---|---|
| Windows | `%APPDATA%\Nimbus\nimbus.toml` |
| macOS | `~/Library/Application Support/Nimbus/nimbus.toml` |
| Linux | `~/.config/nimbus/nimbus.toml` |

Key sections:

```toml
[llm]
# Local-LLM routing.
prefer_local       = true
local_model        = "llama3.2" # Any pulled Ollama model name
# llama.cpp HTTP base URL; not the filesystem path to the llama-server binary.
# llamacpp_server_path = "http://127.0.0.1:8080"
# enforce_air_gap   = false
# max_agent_depth   = 3              # 1–10
# max_tool_calls_per_session = 20    # 1–200

[embedding]
enabled = true
provider = "local"              # local | openai
# model = "all-MiniLM-L6-v2"
# pause_on_battery = true       # default TRUE — see the note below

[telemetry]
enabled = false
endpoint = "https://telemetry.nimbus-agent.dev/v1/collect"

[filesystem]
# roots = ["/home/user/projects", "/home/user/documents"]

[updater]
# enabled = true
# url = "https://releases.nimbus-agent.dev/latest.json"

[lan]
# enabled = false
# port = 7475

[automation]
# graph_conditions = true
```

#### `[embedding] pause_on_battery` — what it does to a laptop

**Default `true`, and as of 2026-09-07 it changes behaviour.** When the host reports `power =
"battery"`, embedding **backfill** pauses — not aborts — and re-probes every 30 s, resuming the
moment the machine is back on mains. Set it to `false` to backfill regardless of power.

Three things worth knowing before you go looking for a bug:

- **Only `battery` pauses.** `unknown` — a desktop, a VM, a host whose backend cannot answer —
  proceeds. The promise the key makes is "do not drain my battery", not "do not embed unless you
  can prove I am plugged in"; treating an unmeasurable host as discharging would switch semantic
  search off on every machine that has no battery at all.
- **It pauses, it does not abandon.** A paused backfill is still waiting, so it picks up where it
  left off. Nothing re-triggers backfill after boot, which is why an early return would have meant
  "stopped until the next gateway restart".
- **This is backfill only.** Newly synced items still embed; what waits is the catch-up pass over
  the existing index. If semantic search on a laptop suddenly stops improving, this key — plus
  `nimbus fleet status`' `host power` line, which reads the same probe — is the first place to
  look.

Historical note, because it affects how you read older configs: the key parsed and defaulted to
`true` from the day it was added and **nothing read it** until the overnight-fleet work gave it a
consumer. On a build before that, setting it had no effect whatsoever.

#### Cloud vendors — `[llm.remote.<vendor>]`

Four vendors are supported: `anthropic`, `openai`, `gemini`, `xai`. Each is its own table, and each is **off by default**.

```toml
[llm.remote.anthropic]
enabled = true                    # REQUIRED. Never inferred from the presence of a key.
model   = "claude-sonnet-4-6"     # REQUIRED. An empty model drops the route (warn-logged by name).
# base_url = "https://api.anthropic.com"   # optional; for a proxy
```

The API key is **never** read from the environment or from this file. Store it in the Vault:

| Vendor | Vault key |
|---|---|
| `anthropic` | `anthropic.api_key` |
| `openai` | `openai.api_key` — deliberately the SAME key the embedding runtime uses |
| `gemini` | `gemini.api_key` |
| `xai` | `xai.api_key` |

```bash
nimbus vault set gemini.api_key      # prompts for the value; never on the command line
```

Both halves are required and they are independent: a key with no `enabled = true` registers no route, and `enabled = true` with no key registers a route that reports `no (no api key)` in `nimbus llm status`. Each enabled vendor becomes one route named `<vendor>/<model>`, which is the name `[llm].route_priority` and `nimbus llm status` use.

**Model ids are the vendor's, and vendors retire them.** Check the vendor's current list rather than copying an id from a document — a retired id fails with a 404 that names the replacement. As of 2026-08-28, for example, `gemini-2.5-pro` and `gemini-2.5-flash` still appear in Google's `GET /v1beta/models` listing but return `404 NOT_FOUND … no longer available to new users` on `generateContent` for a key issued after their retirement; `gemini-flash-lite-latest` and `gemini-3.5-flash` answer normally.

**Environment variable overrides:** Most TOML keys have a corresponding `NIMBUS_`-prefixed env var that wins over the file — `NIMBUS_TELEMETRY_ENABLED`, `NIMBUS_ASK_MAX_STEPS`, and so on. **No vendor credential or vendor selection is env-overridable**, by design: a capability must not turn itself on because a credential happens to exist in the environment. See the [Environment Variables](#environment-variables) table at the end of this document for the full list.

---

## Profiles

Named configuration profiles let you maintain separate settings (e.g. `work` vs `personal`). Each profile has its own Vault key prefix — credentials from one profile are not accessible to another.

### `nimbus profile create <name>`

```bash
nimbus profile create work
nimbus profile create personal
```

---

### `nimbus profile list`

```bash
nimbus profile list
```

---

### `nimbus profile switch <name>`

Switch the active profile. Takes effect on the next Gateway restart.

```bash
nimbus profile switch work
nimbus profile switch personal
```

---

### `nimbus profile delete <name> --yes`

Delete a profile and its associated configuration. Does not delete Vault entries (use `nimbus connector remove` first). Requires the `--yes` flag for confirmation (same pattern as other destructive operations).

```bash
nimbus profile delete personal --yes
```

---

## Team Federation

Peer-to-peer federation between Nimbus Gateways over the encrypted LAN channel (Phase 6 Slice 1). Disabled by default; enable via the `[federation]` section in `nimbus.toml`. Every inbound query is answered only through the consent-scoped, leak-proof **query gate** (invariant `I17`): grant + role + consent + declared-namespace filter, returning rank/metadata-free results only. Pairing uses an out-of-band code (same trust model as `nimbus lan pair`).

### `nimbus team discover`

Discover reachable peer Gateways via mDNS (with a manual fallback). Read-only. This is the default subcommand (`nimbus team` with no argument runs `discover`).

```bash
nimbus team discover
```

### `nimbus team pair <host> <code>`

Pair with a peer Gateway using a one-time, out-of-band pairing code. Transmit the code over a channel other than the one being paired (read it aloud, SMS, etc.) — a mid-pairing network attacker who sees the code can substitute their own key.

```bash
nimbus team pair gw.lan:7700 a1b2c3d4e5f6g7h8i9j0
```

### `nimbus team namespace publish <name> --type <T> --service <S>`

Publish a shared scoped namespace. Requires at least one `--type` / `--service` / `--tag` filter; the filters define exactly what a granted peer may query.

```bash
nimbus team namespace publish incidents --type incident --service pagerduty
```

### `nimbus team namespace grant <ns> <peerId> <role> [--standing]`

Grant a paired peer role-based access to a published namespace. `--standing` persists the grant across sessions (otherwise it is session-scoped).

```bash
nimbus team namespace grant incidents peer:aabbcc reader --standing
```

### `nimbus team namespace revoke <ns> <peerId>`

Revoke a peer's access to a namespace. Further answers stop within one sync cycle.

```bash
nimbus team namespace revoke incidents peer:aabbcc
```

### `nimbus team query <ns> <peerId> "<purpose>"`

Send a consent-scoped federated query to a paired peer within a namespace. The answering peer's query gate enforces grant + role + consent (`I17`); results never include raw item bodies.

```bash
nimbus team query incidents peer:aabbcc "open P1 incidents this week"
```

### `nimbus team who-knows <peerId> "<query>"`

Expertise routing — ask a peer "who knows X?" Returns a ranked contributor list with **no** indexed item content transmitted (ranks only).

```bash
nimbus team who-knows peer:aabbcc "src/billing/retry.ts"
```

### `nimbus team consent <requestId> approve|deny` · `nimbus team listen`

`consent` replies to an inbound federated-query consent request — the host owner remains the consent authority. `listen` runs the foreground listener that surfaces inbound consent requests as they arrive.

```bash
nimbus team consent req:1234 approve
nimbus team listen
```

### Team Vault (Phase 6 Slice 2)

Store team-shared secrets in a leak-proof team vault and grant paired peers tool-scoped use of them. Secrets are never returned over the wire (invariant `I19`); a granted peer can only *invoke* a tool that consumes the secret.

### `nimbus team vault put <entry> <service> --secret key=value`

Store one or more secrets for a team-vault entry bound to a connector service. Repeat `--secret key=value` for each field; at least one is required.

```bash
nimbus team vault put prod-stripe stripe --secret api_key=sk_live_xxxx
```

### `nimbus team vault grant <entry> <peerId> <toolId>`

Grant a paired peer permission to invoke one tool against a team-vault entry.

```bash
nimbus team vault grant prod-stripe peer:aabbcc stripe.refund.create
```

### `nimbus team vault revoke <entry> <peerId> <toolId>`

Revoke a peer's permission to invoke a tool against a team-vault entry.

```bash
nimbus team vault revoke prod-stripe peer:aabbcc stripe.refund.create
```

### `nimbus team vault list`

List the team-vault entries and their grants (JSON).

```bash
nimbus team vault list
```

### `nimbus team invoke <peerId> <entry> <toolId> --purpose "<why>" [--args <json>]`

Ask a peer to invoke a granted tool against one of their team-vault entries on your behalf. The peer's gateway runs the tool with team-scoped credentials and returns a leak-proof result (invariant `I19`). `--args` accepts a JSON object of tool arguments.

```bash
nimbus team invoke peer:aabbcc prod-stripe stripe.refund.create --purpose "refund order 1234" --args '{"charge":"ch_xyz"}'
```

### Delegation & Quorum Approval (Phase 6 Slice 2)

### `nimbus team delegate <peerId> --scope kind:value --expires <seconds>`

Delegate your HITL approval authority for a scope to a paired peer for a bounded window. A delegated approval is honored only from a live, in-scope, identity-valid delegate; otherwise it falls back to the local owner (invariant `I20`).

```bash
nimbus team delegate peer:aabbcc --scope service:stripe --expires 3600
```

### `nimbus team delegations`

List the active HITL delegations (JSON).

```bash
nimbus team delegations
```

### `nimbus team approve <requestId> [--as <peerId>]` / `nimbus team deny <requestId> [--as <peerId>]`

Approve or deny a pending federated approval — a delegated approval or a quorum vote. `--as <peerId>` casts the decision as a specific peer identity (defaults to `self`). Quorum counts only distinct authenticated peers and is deny-fail-closed (invariant `I21`).

```bash
nimbus team approve req:1234
nimbus team deny req:1234 --as peer:aabbcc
```

### Audit & GDPR (Phase 6 Slice 4)

### `nimbus team audit <namespace> [--purpose "<why>"] [--since <unixMs>]`

Render the merged team-audit timeline for a namespace as a fixed-width table (timestamp, peer, action, HITL status, hash). `--since` filters by unix-millisecond timestamp.

```bash
nimbus team audit incidents --purpose "quarterly review" --since 1715000000000
```

### `nimbus team purge --user <externalId> [--yes]`

GDPR-purge all data for a user across the team. Irreversible; prompts for confirmation unless `--yes` (or `--force`) is passed.

```bash
nimbus team purge --user alice@acme.com --yes
```

---

## Identity & Access

Enterprise SSO/OIDC and SCIM provisioning for the Phase 6 federation layer (Slice 3). Identity gates **federation only** — local `ask` / `search` are never affected. Disabled by default; enable via the `[identity]` / `[scim]` sections in `nimbus.toml`. Raw ID/refresh tokens and the SCIM bearer live only in the Vault (invariant I18); ID tokens are validated (RS256) on every session.

### `nimbus identity login`

Start the OIDC device-code login flow. The Gateway prints a verification URL and a user code; open the URL in a browser and enter the code to complete sign-in. This is the default subcommand (`nimbus identity` with no argument runs `login`).

```bash
nimbus identity login
```

---

### `nimbus identity status`

Show the current operator session (issuer, subject/email, validity window) as JSON.

```bash
nimbus identity status
```

---

### `nimbus identity logout`

Clear the current operator session and remove the Vault-stored tokens.

```bash
nimbus identity logout
```

---

### `nimbus identity list-bindings <email>`

List the federation peer bindings for a provisioned user.

```bash
nimbus identity list-bindings alice@acme.com
```

---

### `nimbus identity bind <email> <peerId>` / `unbind <peerId>`

Administratively bind a provisioned user to a federation peer (or remove the binding). Credential-mutating; CLI-only (not exposed to the desktop UI).

```bash
nimbus identity bind alice@acme.com peer:aabbcc
nimbus identity unbind peer:aabbcc
```

---

### `nimbus scim status`

Show the SCIM provisioning endpoint status (enabled, user count) as JSON. This is the default subcommand (`nimbus scim` with no argument runs `status`).

```bash
nimbus scim status
```

---

### `nimbus scim set-token <token>`

Store the SCIM bearer token (the trust anchor the IdP presents on SCIM 2.0 requests) in the Vault. Credential-mutating; CLI-only.

```bash
nimbus scim set-token "$SCIM_BEARER"
```

---

### `nimbus scim list-users`

List the SCIM-provisioned users as JSON.

```bash
nimbus scim list-users
```

---

### `nimbus scim deprovision <email>`

Deprovision a user. Marks the SCIM user inactive and auto-revokes their federation grants/bindings. Credential-mutating; CLI-only.

```bash
nimbus scim deprovision alice@acme.com
```

---

## Org Policy

Signature-verified organization policy for the Phase 6 federation layer (Slice 4). Enforcement reads a resolved, monotonic-stricter `EnforcedPolicy` — never the raw policy TOML — and resolution is tighten-only and fail-closed to the last-valid/baseline policy (invariant `I22`). Channel↔namespace bindings and resource→owner ownership for ChatOps live in `[policy.chatops.*]`.

### `nimbus policy show`

Display the current org policy as JSON. This is the default subcommand (`nimbus policy` with no argument runs `show`).

```bash
nimbus policy show
```

---

### `nimbus policy verify`

Verify the org policy signature and print the validation result as JSON.

```bash
nimbus policy verify
```

---

### `nimbus policy sign <file.toml>` / `nimbus policy push <file.toml>`

Sign a policy TOML file and apply it. `push` is an alias for `sign`.

```bash
nimbus policy sign ./org-policy.toml
nimbus policy push ./org-policy.toml
```

---

### `nimbus policy trust <pubkeyBase64>`

Pin an org-policy anchor public key (base64). Subsequent policies must verify against a trusted anchor.

```bash
nimbus policy trust BASE64_PUBKEY
```

---

### `nimbus policy refetch`

Fetch the latest policy from the configured policy source and print the result as JSON.

```bash
nimbus policy refetch
```

---

## ChatOps

A bidirectional Slack/Teams `@nimbus` bot (Phase 6 Slice 5). Read queries are answered from the shared index; structured write commands (`@nimbus run <action> service=<svc> …`) route to the resolved resource owner's HITL approval before executing — the bot never bypasses the consent gate (invariant `I23` bounds the operational reply surface). Disabled by default; enable via the `[chatops]` section in `nimbus.toml`. Channel↔namespace bindings and resource→owner ownership live in the signed org policy (`[policy.chatops.*]`). The subcommands are local/CLI-only (forbidden over the LAN wire); only `chatops.status` is exposed to the desktop UI.

### `nimbus chatops status`

Show whether ChatOps is enabled and, per platform, whether the transport is connected and how many policy-bound channels it serves. Default subcommand (`nimbus chatops` with no argument).

```bash
nimbus chatops status
```

### `nimbus chatops start` / `nimbus chatops stop`

Start or stop the bot transports (Slack Socket Mode connection / Teams webhook dispatch).

```bash
nimbus chatops start
nimbus chatops stop
```

### `nimbus chatops test "<message>"`

Dry-run the command parser against a message without sending anything — prints the parsed `read` / `write` / `refused` result. Useful for checking how a phrasing is interpreted.

```bash
nimbus chatops test "run deployment.rollback service=payment-service version=v1.4"
```

---

## Tribal-Knowledge Extraction

Detects repeated questions in an allowlisted set of Slack/Teams channels and, on your HITL approval, captures a synthesized Q&A into a config-pinned shared knowledge base (Notion/Confluence) — Phase 6 Slice 6c, behind invariant `I25` (the KB write destination comes from local config only, never the caller). Disabled by default; enable via the `[tribal]` section in `nimbus.toml`. The subcommands are local/CLI-only (forbidden over the LAN wire); only `tribal.status` / `tribal.list` are exposed to the desktop UI.

**Configuration (`nimbus.toml`):**

```toml
[tribal]
enabled = true
match = "embedding"            # or "embedding+llm" for a precision second pass
min_occurrences = 3            # fire a suggestion after N occurrences of a question
window_days = 14               # within this rolling window
cooldown_days = 30             # after capture/dismiss, suppress re-suggestion this long
watch_channels = ["C123ABC"]   # REQUIRED non-empty when enabled (fail-closed privacy boundary)

# At least one capture destination — the owner's local config is the ONLY source of the
# destination (I25); a `--target` selector on capture just picks which one.
[tribal.notion]
database_id = "<notion-database-id>"

[tribal.confluence]
space_key = "ENG"
parent_page_id = "<parent-page-id>"
```

> **Deployment note (Slack):** seeing non-mention channel messages requires the deployed Slack app manifest to subscribe to the `message.channels` bot event. Without it the watcher only sees `@nimbus` mentions (degraded, not broken). **Cost note:** every watched-channel question is embedded locally (MiniLM, no network) before the cheap question-classifier and the channel allowlist short-circuit non-questions — keep `watch_channels` scoped to the channels where Q&A actually happens.

### `nimbus tribal status`

Show whether the watcher is enabled and how many clusters are tracked. Default subcommand.

```bash
nimbus tribal status
```

### `nimbus tribal start` / `nimbus tribal stop`

Pause/resume ingestion of inbound messages without restarting the gateway.

### `nimbus tribal list [status]`

List tracked clusters, optionally filtered by `pending` / `suggested` / `captured` / `dismissed`.

```bash
nimbus tribal list suggested
```

### `nimbus tribal capture <cluster-id> [--target notion|confluence]`

Synthesize a draft answer + citations for a cluster and write it to the KB **after your HITL approval**. `--target` is required only when both `[tribal.notion]` and `[tribal.confluence]` are configured; the destination database/space/parent is always taken from local config, never from the command. Also available in-chat as `@nimbus tribal capture <cluster-id>`.

```bash
nimbus tribal capture tq_ab12cd34ef56 --target notion
```

### `nimbus tribal dismiss <cluster-id>` · `nimbus tribal scan`

`dismiss` suppresses a cluster (enters cooldown); `scan` re-fires suggestions for any pending cluster that already crossed the threshold.

---

## Sharing

Publish a redacted, signed, verifiable copy of an agent session — Phase 6 Slice 8, behind invariant `I27`. An outbound share leaves the machine **only** through the share gate: default + caller-supplied redaction is applied, the LOCAL owner approves the exact redacted preview via the `share.publish` HITL action, the body is signed with the Vault-only `share.signing.privkey`, and the share record is persisted to the `share_records` table (schema V41/V42). A denied or timed-out approval emits nothing (fail-closed). The write/owner-action subcommands (`create`, `prune`, `approve`/`reject`) are local/CLI-only — forbidden over the LAN wire so a remote peer can never trigger or approve an outbound publish; only the read-only verify/list/pubkey surfaces are LAN- and Tauri-reachable.

### `nimbus share create <session-id>`

Publish a redacted, signed copy of a session. By default the share is written to a local file; choose a sink with the flags below. The command blocks on the `share.publish` HITL approval of the redacted preview and prints the resulting content hash on success.

| Flag | Effect |
| --- | --- |
| `--out <file>` | Write the signed share bundle to `<file>` (default sink is a file). |
| `--http` | POST the bundle to the config-pinned `[share.http_sink]` (SSRF-safe; the only host `--http` may target). |
| `--to-peer <id>` | Send the bundle to a paired federation peer. |
| `--as-recipe` | Share a declarative recipe (DAG of params) instead of the raw transcript. |
| `--redact <pattern>` | Add a redaction pattern (repeatable); applied on top of the default redaction set. |
| `--expires <dur>` | Expiry as `30s` / `15m` / `12h` / `7d`; omit for no expiry. |

```bash
nimbus share create sess_ab12cd34 --out ./my-session.share
nimbus share create sess_ab12cd34 --as-recipe --redact "internal-host" --expires 7d
```

Precedence when multiple sinks are given: `--out` (file) > `--http` > `--to-peer` > default file.

### `nimbus share list [--all]`

List persisted share records (content hash, kind, creation time). `--all` includes expired records.

```bash
nimbus share list
```

### `nimbus share prune`

Delete expired `share_records` rows and report how many were removed. Local-only.

```bash
nimbus share prune
```

### `nimbus share pubkey` · `nimbus share approve|reject <request-id>` · `nimbus verify-share <file|url>`

`pubkey` prints this gateway's share-signing public key (so recipients can verify). `approve`/`reject` answer a pending `share.publish` approval prompt by request id (the LOCAL-owner action — never answerable over LAN). `nimbus verify-share` checks a received share file or URL: it reports whether the signature is valid, whether the content hash matches, and whether the share has expired.

```bash
nimbus share pubkey
nimbus verify-share ./received.share
```

---

## Egress Ledger & Provenance

Prove what (if anything) a query sent off your machine, and inspect the append-only egress ledger — Phase 6 / S1 (PR #698), behind invariant `I29`. Every gated action appends exactly one `egress_ledger` row at the executor chokepoint **before** the connector dispatch (a `blocked` row on a denied action; an append failure aborts the dispatch). The ledger is BLAKE3-hash-chained and append-only; its head advances if — and only if — a real outbound action ran. Verification is offline and timing-safe (invariant `I10`). The only mutation of `egress_ledger` is the owner-HITL-gated `nimbus egress prune`, which writes a continuing tombstone rather than rewriting history.

### `nimbus prove "<query>"`

Run a query and prove its outbound footprint. The command snapshots the ledger head **before** the query, runs it through the same blocking agent path as `nimbus ask`, snapshots the head **after**, and prints the delta:

```text
outbound egress events during this query, in the covered classes: N
```

`0 ✓` means the query was answered from the local index without any event **in the covered classes** — the classes named in the `(scope: …)` clause the same line prints. It is not a claim that no packet left the machine: traffic outside those classes (for example the remote intent classifier `ask` attempts before falling back to the local answer) is not ledgered and does not appear in this count. The `not observed:` line names the classes that are excluded. A non-zero count is followed by the per-event egress report (see `nimbus egress` below) so you can see exactly what went where.

| Flag | Effect |
| --- | --- |
| `--receipt` / `--sign` | Sign the printed egress report with the gateway's egress-attestation key (prints a `receipt: digest=… sig=…` line) when the count is non-zero. |

```bash
nimbus prove "what did Alice say about the launch?"
# outbound egress events during this query, in the covered classes: 0 ✓

nimbus prove "open a GitHub issue for the flaky test" --receipt
# outbound egress events during this query, in the covered classes: 1
#   2026-06-21 14:03:11  github.issues.create         ok
# receipt: digest=… sig=…
```

The first positional non-flag argument is the query; flags may appear in any position.

### `nimbus egress` / `nimbus egress verify`

`nimbus egress` (no subcommand) prints the egress report: the outbound-event count, the completeness tier, and one line per ledger row (`timestamp`, `method`, `result status`). Before printing, the chain is verified offline; if the chain is **degraded/unverifiable** the report prints `indeterminate` and exits non-zero — it never reports a false `0` (a broken chain is unverifiable, not proof of no egress).

`nimbus egress verify` runs the standalone offline integrity check and prints `[ok]` with the verified row count, or `[FAIL]` with the row index of the chain break (timing-safe comparison, invariant `I10`).

| Flag | Effect |
| --- | --- |
| `--since <dur>` | Restrict the report to events newer than the duration (`24h` / `30m` / `7d` — the shared `--since` grammar, same as `nimbus query --since`; `nimbus audit` has no `--since`). |
| `--json` | Emit the full result (rows, completeness, verify status, receipt) as JSON. |
| `--sign` | Attach a signed attestation receipt to the report. |

```bash
nimbus egress
# outbound egress events: 3 (tier: complete)
#   2026-06-21 09:12:04  slack.messages.send          ok
#   ...

nimbus egress --since 24h --json
nimbus egress verify
# [ok]   egress chain integrity — 128 rows verified
```

### `nimbus egress prune (--before <ISO|epoch> | --older-than <duration>)`

Trim old ledger rows under retention. This is the **sole** mutation of `egress_ledger` and is gated by the LOCAL owner's HITL approval (it prompts inline; deny removes nothing). Rather than rewriting the hash chain, prune writes a **continuing tombstone** so verification of the remaining chain still holds. Provide the cutoff in exactly one of two **mutually exclusive** forms — supplying both is an error:

| Flag | Effect |
| --- | --- |
| `--before <ISO\|epoch>` | Absolute cutoff: an ISO date (`2026-01-01`) or an epoch-millisecond integer. Rows at/after the cutoff are kept. |
| `--older-than <duration>` | Relative cutoff: `now − duration` (`7d` / `24h` / `30m`), reusing the shared `--since` duration grammar. |

```bash
nimbus egress prune --older-than 30d
# [ok] pruned 42 egress rows (tombstone written)

nimbus egress prune --before 2026-01-01
# [denied] prune not approved — nothing removed   (HITL deny)
```

---

## Admin Console

Local-only helpers for the admin read-surface (Phase 6 Slice 4). The read-surface bearer is the Vault credential `http_api.deployment_token` — the same bearer that protects the `I13` HTTP write surface. The CLI talks to the gateway IPC-only and never holds the Vault, so `console` and `token` print a resolver command rather than echoing the secret; both are local-only (no gateway round-trip).

### `nimbus admin status`

Show the admin read-surface status as JSON. This is the default subcommand (`nimbus admin` with no argument runs `status`).

```bash
nimbus admin status
```

---

### `nimbus admin console`

Print the admin console URL with the bearer carried in the URL **fragment** (never the query string, so it is not sent to servers or written to access logs). Resolve the bearer with `nimbus vault get http_api.deployment_token` and open the printed URL in a browser.

```bash
nimbus admin console
# Admin console: http://127.0.0.1:<NIMBUS_HTTP_PORT>/admin#token=$(nimbus vault get http_api.deployment_token)
```

---

### `nimbus admin token`

Print the Vault key name (`http_api.deployment_token`) that holds the read-surface bearer, with the command to print its value.

```bash
nimbus admin token
```

---

## Local LLM

### `nimbus llm status`

Show every LLM route registered with the Gateway — a `(provider, model)` pair, e.g.
`ollama/qwen3:8b` — and that route's own live availability. One provider vendor (e.g.
`ollama`, backed by a single daemon) can register several routes at once via
`[llm.local.<name>]`; each is listed and probed independently, so a shared daemon
missing one of its two configured models shows only that route as unavailable.

```text
nimbus llm status [--json]
```

**Output columns:**

| Column    | Description |
|-----------|-------------|
| Route     | The route id, `"<providerId>/<modelName>"` |
| Provider  | The provider vendor id, e.g. `ollama`, `llamacpp` |
| Model     | The model name this route registers |
| Local     | Whether the route's provider runs on this machine (`provider.isLocal`) |
| Available | Whether this specific route is reachable right now |
| Context   | The route's configured context window, or `—` when not reported |

**Available column detail:** `yes`, or one of two distinguishable failure reasons —
`no (provider unreachable)` when the daemon itself did not respond, or
`no (model not pulled)` when the daemon is up but this route's specific model is not
among the models it reports. These are deliberately kept apart (`provider_unreachable`
vs. `model_absent`) because the fix differs: start the daemon vs. pull the model. An
unrecognised reason string degrades to `no (<reason>)` rather than a fixed label, so a
future reason value is still legible.

There is no per-task-type decision or `Reason` column any more, and no
`falls back to …` text — every route is listed on equal footing with its own
availability; which one `generate()` would actually pick for a given task is a
function of `[llm].prefer_local`, `[llm].route_priority`, and the reasoning
capability floor, not something this command renders per row.

**Flags:**

| Flag     | Description |
|----------|-------------|
| `--json` | Emit machine-readable JSON instead of the table |

**Example — table:**

```text
Route                 Provider  Model               Local  Available                 Context
------------------------------------------------------------------------------------------------
ollama/qwen3:8b       ollama    qwen3:8b            yes    yes                       8192
ollama/gemma3:12b     ollama    gemma3:12b          yes    no (model not pulled)     —
llamacpp/model.gguf   llamacpp  model.gguf          yes    no (provider unreachable) —
```

**Example — JSON:**

```json
[
  {
    "routeId": "ollama/qwen3:8b",
    "providerId": "ollama",
    "modelName": "qwen3:8b",
    "isLocal": true,
    "available": true,
    "reason": "ok",
    "contextWindow": 8192
  },
  {
    "routeId": "ollama/gemma3:12b",
    "providerId": "ollama",
    "modelName": "gemma3:12b",
    "isLocal": true,
    "available": false,
    "reason": "model_absent"
  }
]
```

The JSON form is the gateway's `routes` array emitted verbatim — a route with no
reported `contextWindow` simply omits the key (never a fabricated `null` or `0`),
which is why the table above renders `—` for it instead of a number.

### `nimbus llm use`

Pin a task type (`classification`, `reasoning`, `summarisation`, or `agent_step`) to a
specific registered route, so that task always tries this route FIRST — ahead of
`[llm].route_priority` and the `prefer_local` ordering alike.

```text
nimbus llm use <task> <routeId>
```

Run `nimbus llm status` first to see the exact route ids this build has registered
(`"<providerId>/<modelName>"`, e.g. `ollama/llama3.2:latest`).

Both the task type and the route id are validated against what is CURRENTLY
registered before anything is written — fail-closed, unlike a stale pin at read time
(which degrades to normal ordering rather than an outage). An unknown task name or an
unregistered route id is refused with a message listing the valid options, and nothing
is persisted.

This command writes `<task> = "<routeId>"` under `[llm.tasks]` in `nimbus.toml` — the
same table a human can hand-edit directly, and the same one `nimbus llm status`'s
routing and boot both read (`config/nimbus-toml.ts`'s `parseNimbusTomlLlmSection`).
Both forms end up agreeing because there is exactly one table, never a second
database-backed store shadowing it. (`nimbus config set` is not that second form here
— it targets a single flat `section.key` pair and does not address a nested table
header like `[llm.tasks]`.) The pin also takes effect on the running Gateway
immediately, with no restart required, in addition to persisting for the next one.

**Example:**

```bash
nimbus llm use classification ollama/llama3.2:latest
```

```text
Pinned "classification" to "ollama/llama3.2:latest" in [llm.tasks].
Applied immediately — no restart needed — and persisted for the next one.
```

---

## Diagnostics and Observability

### `nimbus doctor`

Run environment health checks and print actionable remediation steps. Useful as a first step when something isn't working.

```bash
nimbus doctor
```

**Checks performed:**

- Bun minimum version requirement
- Linux: `secret-tool` available (libsecret)
- Gateway IPC reachable
- Configuration file validates
- Index total item count (warns if zero — suggests connecting a service)
- Per-connector health table
- Voice (when `voice.enabled = true` in config): `whisper-cli` on PATH, `ffmpeg` on PATH, platform TTS available (`espeak-ng` on Linux, `say` on macOS, PowerShell SAPI on Windows)
- Vector search: whether `sqlite-vec` actually loaded on the gateway's connection, and if not, why

**Exit codes:** `0` = all healthy, `1` = warnings, `2` = hard failures.

> **Exit code 2 when `sqlite-vec` is not loaded.** The vector-search check reports `[fail]`, not
> `[warn]`, because semantic search, hybrid ranking and session-memory recall are all off when it
> fires — the same severity the sibling `Embeddings: unavailable` line already carries. On macOS
> Bun links Apple's system SQLite, which has extension loading compiled out, so this needs a full
> SQLite build to be present at all; **released macOS builds now ship one** beside the binaries, so
> a normal install is unaffected. It remains reachable on a **dev checkout** on a machine with
> neither that bundled library nor a Homebrew one (`brew install sqlite`, or `NIMBUS_SQLITE_PATH`),
> where `nimbus doctor` exits `2`. Keyword search is unaffected either way. A gateway too old to
> report the field leaves the line out entirely and the exit code unchanged.

#### `nimbus doctor --fix-keyring`

**Linux only** (issue #1168). Creates and unlocks a fresh default Secret Service keyring
collection on a headless Linux box where none exists yet — the `no-collection` Vault state
`nimbus doctor` reports when a Secret Service provider (e.g. `gnome-keyring`) is running over
D-Bus but has never created a default collection. It runs the whole sequence (create the
`~/.local/share/keyrings` directory at `0700`, unlock `gnome-keyring-daemon` inside a fresh D-Bus
session, poll for ownership of `org.freedesktop.secrets` to close a D-Bus name-ownership race,
re-assert `0600` on the keyring files it writes) inside one ephemeral `dbus-run-session`, then
verifies the result with a live `secret-tool` store + lookup + clear round-trip.

```bash
nimbus doctor --fix-keyring
nimbus doctor --fix-keyring --dry-run
```

- `--dry-run` prints the same plan without writing anything or spawning `dbus-run-session`.
- On macOS and Windows this is a no-op (`[ok]`, exit `0`) — those platforms use their native
  credential stores (Keychain / DPAPI) and never reach the Secret Service probe.
- **It refuses to run if any keyring material already exists** — an exact `login.keyring`, any
  other `*.keyring` file, or a `default`-alias pointer already present under
  `~/.local/share/keyrings` — to avoid destroying stored credentials. Back up and remove the
  existing keyring yourself first if you intend to reset it.
- It does not apply to every failing Vault state: `not-installed` (missing `secret-tool` and
  friends) and `locked` (a keyring already exists, just locked) are not fixed by this command —
  `nimbus doctor`'s own output names the right remedy for those states, which is the
  `dbus-run-session -- bash -c 'echo "" | gnome-keyring-daemon --unlock --components=secrets;
  nimbus start'` wrapper, needed on every `nimbus start`, not just once.

**Exit codes:** `0` = fixed (or not applicable / dry run), `2` = refused (missing binaries,
pre-existing keyring material, or verification failed).

---

### `nimbus diag`

Capture a full diagnostic snapshot — index metrics, connector health, query latency percentiles, recent errors, system info. Safe to share with support.

```bash
nimbus diag
nimbus diag --json
```

**Output includes:** Gateway version, platform, uptime, active profile, SQLite size, item counts by service, FTS5 coverage, embedding coverage, p50/p95/p99 query latency, connector health summary, recent sync errors.

---

### `nimbus diag slow-queries`

List the slowest queries recorded in the latency ring buffer.

```bash
nimbus diag slow-queries
nimbus diag slow-queries --limit 20
nimbus diag slow-queries --since 1h
nimbus diag slow-queries --json
```

---

### `nimbus serve`

Start a read-only local HTTP API on `localhost`. Off by default. Useful for scripts, CI pipelines, and the `@nimbus-dev/client` library.

```bash
nimbus serve
nimbus serve --port 7474        # Default port: 7474
```

**Endpoints:**

| Endpoint | Description |
|---|---|
| `GET /v1/audit` | Recent audit log entries |
| `GET /v1/connectors` | List connectors and health states |
| `GET /v1/health` | Gateway health summary |
| `GET /v1/items` | List indexed items (supports `service`, `type`, `since`, `until`, `limit` query params) |
| `GET /v1/items/:id` | Get a single item by ID |
| `GET /v1/metrics/dora` | DORA metrics for a service (supports `service`, `since` query params) |
| `GET /v1/metrics/stats` | One DORA-family or related operational metric as a bucketed time series, over the same service config as `/v1/metrics/dora` at a different resolution (`service`, `metric`, `window_ms`, `bucket_ms`; all positive, at most 400 buckets). Its metric set is **wider** than that route's: the same four DORA metrics plus `pr-merges` and `incidents-opened`. Buckets are disjoint, so a line between points is meaningful; an unknown service is **refused** rather than answered softly, because a series has nothing honest to place-hold |
| `GET /v1/openapi.json` | Machine-readable OpenAPI 3.1 schema for this API |
| `GET /v1/people` | List people graph entries |
| `GET /v1/people/:id` | Get a single person record |
| `GET /v1/preflight/deploy` | Pre-deploy check: active P1 incidents, failing CI, merge conflicts |

**Write endpoints** — the complete `WRITE_ROUTE_ALLOWLIST` (invariant `I13`); every write not on this list is rejected:

| Endpoint | Description |
|---|---|
| `POST /v1/deployments` | Record a deployment annotation (bearer `http_api.deployment_token`) |
| `POST /scim/v2/Users`, `PATCH /scim/v2/Users/{id}`, `DELETE /scim/v2/Users/{id}` | SCIM v2 provisioning (bearer `identity.scim.bearer`) |
| `PUT /v1/admin/policy` | Admin-console org-policy write (admin bearer; signed with the Vault-only anchor key) |
| `POST /v1/messaging/teams/events` | ChatOps Teams inbound (Bot Framework JWT validated in-route) |
| `POST /v1/clips`, `POST /v1/clips/pair/confirm` | Web-clipper ingest and pairing confirm (invariant `I30`) |
| `POST /v1/briefs`, `POST /v1/briefs/{id}/sources`, `POST /v1/briefs/{id}/run`, `POST /v1/briefs/{id}/save` | Research-brief create / feed source / synthesize / save (labeled clipper token) |
| `POST /v1/agents/{agent}` | Run a built-in agent and return its brief (labeled clipper token, `agents` scope) |
| `POST /v1/items/fetch` | Targeted single-item fetch from a configured connector (labeled clipper token, `fetch` scope) |

All read endpoints are `localhost`-only and use `SQLITE_OPEN_READONLY`. Every write route carries bearer (or in-route) authentication, a per-route body cap, per-token rate limiting (60 req/min by default; `POST /v1/clips` tightens to 20), and audit-on-rejection. There is no authentication required for read endpoints because the socket is owner-only at the OS level.

---

## Database

### `nimbus db verify`

Run non-destructive integrity checks on the local index. Safe to run at any time.

```bash
nimbus db verify
nimbus db verify --json
nimbus db verify --json | jq -r '.findings[] | select(.status == "fail") | .label'
```

**Checks:** SQLite `integrity_check`, FTS5 consistency, `vec_items_384` rowid alignment, orphaned sync tokens, schema version match, foreign key integrity.

**Exit codes:** `0` = all pass, `1` = at least one finding. `--json` does not change them.

**`--json` shape.** `{ clean: boolean, findings: [{ label, status: "ok" | "fail", detail? }], exitCode: number }`. The gateway's pre-rendered human report is dropped, not embedded; `exitCode` is both reported in the document and applied to the process.

---

### `nimbus db repair`

Run targeted recovery actions for any findings reported by `nimbus db verify`. Writes a structured repair report to the audit log. `--yes` is **mandatory**, not a confirmation skip: there is no interactive prompt, and without the flag the command exits with `Usage: nimbus db repair --yes` — including under `--json`, which emits nothing in that case.

```bash
nimbus db repair --yes
nimbus db repair --yes --json
```

**`--json` shape.** The structured repair report: `{ outcomes: [{ action, status: "applied" | "skipped" | "error", detail? }], repairedAt: string }`, where `action` is one of `vec_orphan_delete` / `fts5_rebuild` / `orphaned_sync_tokens_delete` / `foreign_key_cascade_delete` and `repairedAt` is an ISO timestamp. The pre-rendered human report is dropped, not embedded.

**Repair actions:** Delete orphaned vec rows + re-queue resync, FTS5 rebuild, delete unrecoverable rows, remove orphaned sync tokens.

---

### `nimbus db snapshot`

Create a manual snapshot of the local index database.

```bash
nimbus db snapshot
```

The command takes no arguments and prints the path of the snapshot it wrote. Snapshots are stored under `<dataDir>/snapshots/`, named `nimbus-<epoch-ms>.db.gz`. (`<dataDir>/backups/` is a different directory — it holds the automatic pre-migration backups listed by `nimbus db backups list`.)

---

### `nimbus db restore <snapshot>`

Restore the index from a snapshot. The Gateway must be stopped first — the command refuses to run while a live Gateway process is detected. `<snapshot>` is a `.db.gz` **path**, resolved relative to the current directory and not looked up inside the snapshots directory, so paste the path column from `nimbus db snapshots list`. `--yes` is required to actually overwrite `nimbus.db`: without it the command prints the exact `--yes` invocation and exits `0` having changed nothing.

```bash
nimbus stop
nimbus db snapshots list
nimbus db restore <dataDir>/snapshots/nimbus-1776249000000.db.gz --yes
```

---

### `nimbus db snapshots list` / `nimbus db backups list`

List available snapshots and pre-migration backups.

```bash
nimbus db snapshots list
nimbus db backups list
```

---

### `nimbus db snapshots prune`

Delete old snapshots, keeping the most recent `--keep-last N` (default 7, clamped to 1–100). `--yes` is mandatory — without it the command exits with the usage line, and there is no interactive prompt. There is no `nimbus db prune`; it exits with `Unknown db subcommand: prune`. Pre-migration backups (`nimbus db backups list`) are not touched.

```bash
nimbus db snapshots prune --yes
nimbus db snapshots prune --yes --keep-last 10
```

---

## Index Maintenance

### `nimbus index add <path>`

Register a local git repository as a blame/index root without hand-editing `nimbus.toml`. The path is resolved to an absolute path and sent to the Gateway, which canonicalizes it, verifies it is an existing directory containing a `.git` entry, and persists it to `registered-roots.json`. The registered root is merged with the `[[filesystem.roots]]` TOML set on the next Gateway start (TOML wins on collision), at which point the git-commit, blame, and other filesystem syncables begin indexing it.

```bash
nimbus index add .
nimbus index add /path/to/repo
```

Output is `Registered blame root: <path>` for a new root, or `Already registered: <path>` if it was already present (idempotent).

**Security:** `filesystem.ensureRoot` is CLI-only — the `filesystem` namespace is in `FORBIDDEN_OVER_LAN` (invariant I5), so a remote peer can never register an indexing root on your machine. A path that is not an existing directory, or lacks a `.git` entry, is rejected (this structurally rejects roots like `C:\` or `/`).

### `nimbus index reembed`

Selectively re-embed indexed items to a target embedding model. Useful when switching between local MiniLM (384-dim, `vec_items_384`) and OpenAI `text-embedding-3-small` (1536-dim, `vec_items_1536`) — both tables can coexist; this command backfills missing chunks for a chosen model.

```bash
nimbus index reembed --model openai:text-embedding-3-small --item-type slack:message --dry-run
nimbus index reembed --model openai:text-embedding-3-small --service slack --yes
nimbus index reembed --model Xenova/all-MiniLM-L6-v2 --yes --json
```

**Flags:**

| Flag | Required | Description |
|---|---|---|
| `--model <id>` | yes | Target embedding model id. v1 values: `openai:text-embedding-3-small` (needs vault key `openai.api_key`) or `Xenova/all-MiniLM-L6-v2` (local, no key required). |
| `--item-type <key>` | no | Filter to one logical type. Accepts `"service:type"` (exact) or `"type"` alone. |
| `--service <name>` | no | Restrict to a single connector service. |
| `--limit N` | no | Cap the number of items to process. |
| `--batch-size N` | no | Items per batch; default 100, clamped to `1..256`. |
| `--dry-run` | no | Compute the candidate count and emit a `reembedDone` notification without writing. |
| `--yes` | yes (non-dry) | Confirmation gate; required for any non-`--dry-run` invocation. |
| `--json` | no | Suppress progress output; print the final summary as one JSON object. |

**Behaviour:** the CLI subscribes to `index.reembedProgress` / `index.reembedDone` / `index.reembedError` notifications, issues the `index.reembed` request, and streams progress lines (`progress: 50/200 (skipped 0)`) by default. Re-running is idempotent — items already embedded against the target model are skipped, so retrying after a transient API failure is safe.

**Exit codes:** `0` = run completed (any number of skips); operator re-runs to retry skipped items. `1` = fatal abort (vault key missing, unknown model, auth failure, Gateway down).

**Security:** `index.reembed` and `index.reembedCancel` are CLI-only — both methods are in `FORBIDDEN_OVER_LAN` (invariant I5) and absent from the Tauri renderer allowlist (invariant I7).

---

### `nimbus index health`

Index **quality** report — why query results are weak, before you conclude the product is. Read-only: one `index.health` call, no HITL, no writes.

```bash
nimbus index health
nimbus index health --stale-days 30
nimbus index health --json
```

**Flags:**

| Flag | Required | Description |
|---|---|---|
| `--stale-days N` | no | Age above which a connector counts as stale. Default **7**. A malformed or negative value is a hard error client-side, because `Number("")` is `0` and silently treating that as the threshold would mark the entire index stale. |
| `--all` | no | Also list connectors holding zero indexed items. Off by default: the gateway registers a `sync_state` row for **every** known connector at boot, so a real install has ~90 empty rows that bury the handful in use. The omission is always disclosed with a count, and `--json` is never filtered. |
| `--json` | no | The raw report, for machine consumption. Always complete — `--all` affects only the human render. |

**What it reports:**

- **Per-connector embedding coverage** — the share of that connector's items with at least one `embedding_chunk` row. An unembedded item is invisible to semantic search. This is genuinely per-connector; `diag.snapshot`'s `embeddingCoveragePercent` is a single global figure and cannot say *which* connector is uncovered.
- **Stale connectors**, with the reason distinguished: `threshold_exceeded` (synced, but longer ago than the threshold), `never_synced` (a `sync_state` row exists with no timestamp), and `no_sync_record` (items are indexed for a service with no `sync_state` row at all). Different causes, different fixes.
- **Item types with sparse metadata** — counts of items missing `url`, `modified_at` or `metadata`, per type.
- **A 0–100 confidence score**, `0.6 × embedding coverage + 0.4 × freshness`. Coverage is weighted higher because the two fail differently: an unembedded item cannot be retrieved at all, while a stale one is retrievable and merely out of date. Freshness is weighted by **items**, not by connector count, so nine empty fresh connectors cannot mask one stale connector holding everything.

**An empty index reports no score at all**, not zero — `confidence` is `null` with `confidenceUnavailableReason: "empty_index"`. Zero would read as a verdict on quality when the truth is that there is nothing yet to judge.

**Unknown sync state is treated as stale, never as fresh.** A connector with no sync record could be freshly synced or years cold; assuming the former would inflate the one number a user acts on.

**`nimbus doctor` integration:** doctor calls `index.health` separately (not via `diag.snapshot`, which the desktop polls — the report is several `GROUP BY` scans and does not belong on a polled path) and prints `[warn] Index confidence: N/100` below **60**. Exactly 60 passes. A gateway too old to serve the method leaves doctor silent rather than inventing a verdict.

**Exit codes:** `0` always for a successful report — it is a read command. Gateway-down surfaces as the usual connection error.

---

### `nimbus index rebody`

Re-fetch indexed **depth** for rows that are missing some of it. The full-body store (schema **V48**) lifted the 512-character cap to 16 KiB for `PROSE_HEAVY_TYPES`, but only for connectors that were migrated to pass a declared-full `body:` — existing rows synced before that migration (or by a connector that has not been migrated) are left with `item.body_complete = 0`: text that is genuinely gone from the local index and can only be recovered by re-fetching from the source API. `rebody` works by **clearing a connector's sync watermark** (`scheduler_state.cursor`) and letting the existing sync run from scratch, so a real run is real outbound API traffic against a live connector, not a local recompute.

Bodies were the first kind of depth, and are no longer the only one. A row is **recoverable** when its body is incomplete **or** its service's `metadata.meta_v` is below the version that service is required to carry — `REBODY_REQUIRED_META_VERSION` in `packages/gateway/src/ipc/index-rebody-rpc.ts`, today `jira` and `linear` at version 1 (the ticket-depth contract: issue type, normalized `status_category`, and the created/resolved/due timestamps). The two reasons are reported **separately**, never summed: `pending`/`pendingBefore`/`pendingAfter` count missing bodies, `pendingMeta`/`pendingMetaBefore`/`pendingMetaAfter` count stale metadata. A row can be behind on both; they are two questions about the same rows, not a partition. A service with no entry in `REBODY_REQUIRED_META_VERSION` keeps body-only eligibility exactly as before.

```bash
nimbus index rebody --dry-run
nimbus index rebody --service slack --yes
nimbus index rebody --type issue --limit 3 --yes --json
nimbus index rebody --service jira --since 365 --yes
```

**Flags:**

| Flag | Required | Description |
|---|---|---|
| `--service <name>` | no | Restrict to a single connector service. |
| `--type <t>` | no | Restrict the dry-run candidate scan to one item `type` (does not itself limit which connector re-syncs — see Behaviour). |
| `--limit N` | no | Cap the number of connectors targeted by a real (non-dry) run; a malformed value is a hard error, not silently ignored, because it bounds how many connectors get an unbounded full-account network re-walk. |
| `--since <days>` | no | Widen the **cold-start** window a connector re-walks, for this run only. Honored by the connectors that read `SyncContext.historyFloorMs` — today `jira` and `linear`; **every other connector silently ignores it** and keeps its own `initialSyncDepthDays` (30). Like `--limit`, a malformed value is a hard error client-side, and a window reaching before 1970 is rejected by the gateway. Over 3650 days the CLI prints a typo warning but still honors the value. |
| `--dry-run` | no | Report per-service pending counts — missing bodies (`body_complete = 0`) and, separately, stale metadata — without clearing any watermark or making any network call. |
| `--yes` | yes (non-dry) | Confirmation gate; required for any non-`--dry-run` invocation. Omitting both `--dry-run` and `--yes` prints the planned action and exits without doing anything. |
| `--json` | no | Suppress progress/prose output; print the final summary as one JSON object. |

There is deliberately **no `--only-truncated` flag**. A sync fetches by page and time window, not by item id — no connector exposes a per-item fetch — so a flag that tried to target only the rows marked incomplete would suppress writes for already-complete items (free) while every API request still happened, saving zero rate-limit budget. It is not a planned follow-up; it is not implementable against the current connector contract.

**Behaviour:** invoking with **neither** `--dry-run` nor `--yes` makes **no IPC call at all** — it prints the planned flags (echoing `--service`/`--type`/`--limit`/`--since` if given) plus the same cost caveat shown below, then exits; it reports no pending counts, because it never asks the gateway for any. **`--dry-run`** does make the call (`{ ..., dryRun: true }`) and computes and returns the whole-index `pending` grouping by service (never scoped to `--service`/`--type` — those filters pick which connector(s) a real run targets, not which rows the summary counts) plus a `cannotImprove` list, without clearing any watermark or making any network call to a connector. A service lands in `cannotImprove` when it is not in `REBODY_IMPROVABLE_SERVICES` (`packages/gateway/src/ipc/index-rebody-rpc.ts`) — the inclusion list of services whose connector passes a declared-full `body:` for every item type it writes today. As of 2026-08-04, that list is thirteen services: `bitbucket`, `confluence`, `discord`, `github`, `gmail`, `jira`, `linear`, `notion`, `obsidian`, `outlook`, `slack`, `snyk`, `teams` — a service with a mixed migration state (e.g. `zoom`, which migrated `zoom:transcript` but not `zoom:meeting`; or the locally-generated `nimbus` bucket, which migrated `web_clip` and `research_brief` but not `glossary_term`) is deliberately left out, because `rebody`'s pending count is grouped by service only, not by `(service, type)`. An unmigrated or newly-added connector defaults to cannot-improve — an over-cautious warning, never a false promise. **`--yes`** (without `--dry-run`) runs for real: it clears the sync watermark for each targeted service (so a `forceSync` failure — rate limit, auth — still leaves the connector armed for its next scheduled tick, surfaced as a warning) and reports `pendingBefore`/`pendingAfter` plus `succeeded`/`failed` counts. An explicit `--service` (optionally narrowed by `--type`) is validated against the actual **recoverable** rows before anything is touched — a typo'd or unknown service, or a `--service`/`--type` combination with nothing recoverable **by body or by metadata version**, is rejected rather than silently spending API quota on a connector with nothing to recover.

**Cost is not proportional to the pending counts shown**, and the CLI prints this caveat on every dry run and every real run: most connectors resume from a bounded recent window even from a cleared watermark (e.g. Slack, Jira's cold-start JQL floor, or Confluence's cold-start CQL floor — the latter recovers roughly the last 30 days of page edits, not the whole wiki). Notion alone has no delta sync and re-walks the **entire** account regardless of how few items are actually pending — for it, `rebody` can be tens of thousands of requests to recover bodies for a handful of rows.

**`--since` and that bounded window.** The 30-day cold-start floor is exactly what makes a Jira or Linear backfill useless without `--since`: clearing the watermark re-walks only the last 30 days, so closed historical tickets are never revisited and their metadata stays stale forever. `--since <days>` hands the scheduler a one-shot absolute floor (epoch ms) that the connector uses **in place of** its own 30-day default — but only on a **cold start**. An established cursor is always more recent and always wins, so the floor cannot cause a re-walk on subsequent scheduled ticks. The floor is held **in gateway memory only** and is consumed by the first run that completes: a restart drops it (the safe direction — ask again rather than silently re-walking history forever), while a run that failed without advancing its watermark keeps it for the retry. When a real run with `--since` reports failed services, the CLI says both halves of this out loud.

**Exit codes:** `0` = run completed (dry or real, any number of per-service failures — see `failedServices` in `--json` output). `1` = fatal abort (malformed params, Gateway down).

---

### `nimbus index regraph`

Re-run the graph populator over every indexed item via `index.regraph`. Needed because a populator change only reaches existing rows when they next re-sync, and historical items may never re-sync. Threads the same service-identity resolver the live sync path uses, so `correlates_with` edges between resolver-bound deployments/incidents survive the backfill instead of being cleared. Idempotent — safe to re-run.

```bash
nimbus index regraph
nimbus index regraph --json
```

**Options:**

| Flag | Description |
|---|---|
| `--json` | Machine-readable JSON output (otherwise a one-line summary) |

**Output:** `regraph: scanned <n>, graphed <n>, skipped <n>` — `graphed` counts only items that actually wrote graph rows (not every item dispatched); `skipped > 0` prints a `WARN` to stderr pointing at the gateway log for per-item errors.

**Read-only relative to connectors:** no live API call — it re-derives graph edges from data already in the local index. It does write to the local database (`graph_entity` / `graph_relation`); no HITL.

---

## Telemetry

Telemetry is **opt-in** and **aggregate-only**. No content, query text, file names, or credentials are ever included. Disabled by default.

### `nimbus telemetry show`

Show the current telemetry configuration and a preview of the next payload.

```bash
nimbus telemetry show
```

**Payload preview includes:** `connector_error_rate`, `sync_duration_p50_ms`, `connector_health_transitions`, `extension_installs_by_id`, `cold_start_ms`, query latency percentiles. All values are aggregate counters — no content.

---

### `nimbus telemetry disable`

Disable telemetry and clear any queued payloads.

```bash
nimbus telemetry disable
```

To re-enable: `nimbus config set telemetry.enabled true`

---

## Extensions

### `nimbus extension install <path|url|package>`

Install a third-party extension. Accepts a local path, URL, or npm package name. The manifest SHA-256 is verified before installation.

```bash
nimbus extension install @community/nimbus-notion
nimbus extension install ./nimbus-my-connector
nimbus extension install https://example.com/nimbus-ext.tar.gz
```

---

### `nimbus extension list [--tree] [--json]`

List installed extensions with their status (`enabled` / `disabled` / `disabled (signature)`).

`disabled (signature)` means the Gateway hard-disabled the extension at startup because its Ed25519 manifest signature did not verify (I16) — it is **not** the same as an extension you disabled yourself. Such a row is bold red on a TTY and carries an annotation line naming the machine-readable reason:

```text
  com.example.notion@2.0.0 [signature: signature_failed]
```

The four reasons are `publisher_key_missing`, `publisher_key_mismatch`, `signature_failed` and `signature_malformed`. Run `nimbus extension info <id>` for the remediation — the remedies differ (a key problem is fixed by `nimbus extension sync`; a signature problem is not). Separately, the `(unverified)` badge in the **Publisher** column means the manifest declares no publisher at all, which is the normal state of an unsigned extension and says nothing about verification having failed.

`--tree` — print an ASCII dependency forest of installed extensions with their forward-dep edges; cycle-safe; NO_COLOR-aware (T2 PR 4).

```bash
nimbus extension list
nimbus extension list --json
nimbus extension list --tree
```

---

### `nimbus extension info <id> [--deps] [--json]`

Show details for an installed extension. `--deps` appends a Dependencies section showing forward deps (extensions this one requires) and reverse deps (extensions that depend on this one) from the `extension_dependency` table (T2 PR 4).

When the extension was hard-disabled by the startup signature check (I16), the `Enabled:` line names the reason and the remediation follows below it:

```text
Enabled:   no  (signature verification failed: publisher_key_missing)
…
Extension com.example.notion v2.0.0 failed signature verification at startup (publisher_key_missing) and was disabled.
No publisher key is cached for it. Re-fetch keys: nimbus extension sync — or reinstall with a key you already hold: nimbus extension install <path> --publisher-key <path>
```

```bash
nimbus extension info com.example.notion
nimbus extension info com.example.notion --deps
nimbus extension info com.example.notion --deps --json
```

---

### `nimbus extension enable <name>` / `disable <name>`

```bash
nimbus extension enable nimbus-notion
nimbus extension disable nimbus-notion
```

---

### `nimbus extension remove <name> [--yes] [--force] [--json]`

Uninstall an extension and remove its process. Does not delete the extension's Vault entries automatically — use `nimbus connector remove` first if the extension registered connectors.

If other installed extensions depend on this one, the remove is refused unless `--force` is passed. With `--force`, the removal proceeds after a warning listing the affected dependents; the startup completeness guard will hard-disable those dependents on the next Gateway start via `MissingDependencyRegistry` (T2 PR 4).

```bash
nimbus extension remove nimbus-notion
nimbus extension remove nimbus-notion --force
nimbus extension remove nimbus-notion --yes --json
```

---

### `nimbus extension update [<id>] [--check] [--to <version>] [--json]`

Apply a cached auto-update bump (T2 PR 3). Without an id, lists pending updates the daemon detected on its last poll; with `--check`, forces an immediate registry poll first. With an `<id>`, applies the cached bump for that extension after HITL consent (`extension.autoUpdate` for a forward bump, `extension.downgrade` for a backward one).

```bash
nimbus extension update --check                       # force poll + list
nimbus extension update                                # list cached only
nimbus extension update com.example.notion             # apply cached toVersion
nimbus extension update com.example.notion --to 1.0.0  # roll back to a cached _prev
nimbus extension update com.example.notion --json
```

Exit code is `0` on success, `1` on apply failure (with a stderr hint — e.g. `publisher_key_missing` directs the user to `nimbus extension sync`).

---

### `nimbus extension downgrade <id> --to <version> [--json]`

Roll an installed extension back to a cached `_prev/<version>/` (T2 PR 3). The `<version>` must already exist on disk under the extension's `_prev/` directory — typically the version the auto-update flow saved when the user accepted the previous bump.

```bash
nimbus extension downgrade com.example.notion --to 1.0.0
nimbus extension downgrade com.example.notion --to 1.0.0 --json
```

Fires the `extension.downgrade` HITL action type so the consent prompt clearly distinguishes the direction from a forward update.

---

### `nimbus extension keygen [--out <path>] [--force]`

Generate a new Ed25519 keypair for signing extension manifests. The private key is saved to `~/.nimbus/publisher-key` (or `<path>`) with `0600` permissions. The public key (base64) is printed to stdout. Use `--force` to overwrite an existing key.

```bash
nimbus extension keygen
nimbus extension keygen --out ./my-publisher-key
```

---

### `nimbus extension sign <ext-dir> [--key <path>]`

Sign an extension manifest (`nimbus.extension.json`) in the specified directory using the private key at `~/.nimbus/publisher-key` (or `<path>`). The `signature` field is injected directly into the manifest file.

```bash
nimbus extension sign ./nimbus-my-connector
nimbus extension sign ./nimbus-my-connector --key ./my-publisher-key
```

---

### `nimbus extension sync [--dry-run] [--json]`

Poll the registry to check the status of installed publishers. Detects key rotations and revoked publishers, then triggers a re-verification of all installed extensions for affected publishers.

```bash
nimbus extension sync
nimbus extension sync --dry-run
nimbus extension sync --json
```

---

### `nimbus scaffold extension`

Scaffold a new extension package from the `@nimbus-dev/sdk` template. The extension id is positional and the package is always created at `./<id>/` in the current working directory — there is no `--name` or `--output` flag (`--name` would be taken as the id and create a directory literally called `--name`).

```bash
nimbus scaffold extension my-connector    # creates ./my-connector/
```

---

### `nimbus test`

Run contract tests for an extension against the `@nimbus-dev/sdk` manifest contract, followed by the extension's own `bun test` suite.

```bash
nimbus test                     # In extension root directory
nimbus test ./nimbus-my-connector
```

---

## Workflows

### `nimbus workflow save <name> --file <path>`

Save a YAML script as a named reusable workflow pipeline. The **name is positional** and the file comes from the required `--file` flag; there is no `--name` flag. If the YAML declares a different `name:`, the CLI warns and saves under the name you passed.

```bash
nimbus workflow save weekly-cleanup --file ./weekly-cleanup.yml
nimbus workflow save weekly-cleanup --file ./weekly-cleanup.yml --description "Friday tidy-up"
```

`--description <text>` overrides the description parsed from the file.

---

### `nimbus workflow list`

List saved workflow pipelines.

```bash
nimbus workflow list
```

---

### `nimbus workflow run <name>`

Run a named workflow pipeline. Same engine and same flags as [`nimbus run`](#nimbus-run) — it executes immediately unless a preview is asked for; HITL gated.

```bash
nimbus workflow run weekly-cleanup
nimbus workflow run weekly-cleanup --dry-run    # Preview only
nimbus workflow run weekly-cleanup --no-ttv     # Preview first, abort if any step is flagged HITL; otherwise run
```

---

### `nimbus workflow delete <name>`

Delete a saved workflow pipeline.

```bash
nimbus workflow delete weekly-cleanup
```

---

## Sessions

### `nimbus session list` / `clear` / `recall`

Inspect, clear, and recall content from RAG sessions. Each `nimbus ask` opens a session that accumulates context across turns; these subcommands operate on those sessions over the IPC `session.*` surface.

```bash
nimbus session list                                # All active sessions (JSON)
nimbus session clear                               # Clear every session
nimbus session clear <sessionId>                   # Clear one session
nimbus session recall <sessionId> <query>          # Top-K=8 recall from the session's chunks
```

Output is JSON in all forms.

---

## Watchers

### `nimbus watch list` / `pause <id>` / `resume <id>`

Inspect and toggle scheduling on watchers over the IPC `watcher.*` surface. Watcher creation and editing flow through the `nimbus workflow` family (watchers are workflow pipelines with a trigger).

```bash
nimbus watch list                # All watchers + enabled state + last-fired time
nimbus watch pause <watcher-id>  # Stop firing without deleting
nimbus watch resume <watcher-id> # Re-enable a paused watcher
```

Output is JSON in all forms.

---

## People

Query the cross-service people graph. Resolves identities across GitHub, GitLab, Slack, Linear, Jira, Notion, and more without a network call.

### `nimbus people list [--unlinked] [--limit N] [--not-reviewed [--since 7d]] [--explain] [--json]`

List people in the graph. `--unlinked` restricts the output to identities that have not yet been merged into a person; `--limit N` caps the rows (default 100).

```bash
nimbus people list
nimbus people list --unlinked --limit 50
nimbus people list --not-reviewed --since 7d          # nobody with a review in the last 7 days
nimbus people list --not-reviewed --since 7d --json
```

**`--not-reviewed`** is the people-side negation predicate: people with no outgoing `reviewed` edge newer than the cutoff. Note the `list` — it is a subcommand, not decoration; `nimbus people --not-reviewed` exits with "Unknown people subcommand". It carries the same contract as the [`nimbus query` negation flags](#negation-predicates), with one difference worth knowing:

- **`--since` here is a real window.** Unlike `--no-downstream-incident`'s fixed correlation window, this one filters the `reviewed` edges themselves, so it means what you expect. It is parsed by the same duration parser `nimbus query --since` uses, so `7d` / `24h` / `2w` behave identically across both commands. Omitting `--since` widens the predicate to "no `reviewed` edge ever" rather than silently narrowing to an unstated recent window.
- **The substrate probe is windowed by that same `--since`.** A global, all-time count of `reviewed` edges would pass on edges that are all older than your window — the exact state in which "nobody reviewed this week" and "nothing synced for this week" are indistinguishable. So the command refuses on that ambiguity (exit `1`, message to stderr, or a `missing_substrate` document to stdout under `--json`) instead of returning every graphed person as a false clean answer. Widening `--since`, or syncing a connector that populates PR review activity and running `nimbus index regraph`, is the remediation it prints.
- **People with no graph entity are excluded and counted.** The predicate joins through `graph_entity`, so a person who was never graphed cannot be evaluated; they are dropped (the fail-closed direction) and reported in the `Gaps:` line rather than silently vanishing from the count.

A plain `nimbus people list` still returns exactly what it always did — a bare array under `--json`. Only a `--not-reviewed` or `--explain` call returns the wrapped `{ people, gaps?, explain? }` document.

---

### `nimbus people search <query> [--limit N]`

Search the graph by name or handle. `--limit N` caps the rows (default 25).

```bash
nimbus people search elena
nimbus people search elena --limit 10
```

---

### `nimbus people get <id>`

Show the details for a single person.

```bash
nimbus people get person:abc123
```

---

### `nimbus people items <id> [--limit N]`

List the indexed items attributed to a person. `--limit N` caps the rows (default 50).

```bash
nimbus people items person:abc123
nimbus people items person:abc123 --limit 20
```

---

### `nimbus people link <id-a> <id-b>`

Merge two people: `id-b` is folded into `id-a` (`id-a` survives).

```bash
nimbus people link person:abc123 person:def456
```

---

## Clip (Web Clipper)

> The browser extension that pairs with these commands ships from its own repo,
> [nimbus-agent/nimbus-web-clipper](https://github.com/nimbus-agent/nimbus-web-clipper)
> (Chrome + Firefox, MV3). The `nimbus clip …` commands below manage the gateway-side
> pairing tokens it uses.

### `nimbus clip pair [--label <device>] [--scopes <a,b>]`

Open a browser-extension pairing session and print the one-time code **plus the gateway URL** to enter in the extension's Options page. The code expires after 2 minutes. `--label` gives the paired device a human-readable name; if omitted the gateway assigns one.

`--scopes` sets what the minted token is allowed to reach. It takes a comma-separated list drawn
from six names:

| Scope | Unlocks |
|---|---|
| `clip` | `POST /v1/clips` (save a clip) and `POST /v1/clips/related` (related-items read) |
| `briefs` | The research-briefs write routes (`POST /v1/briefs`, `.../sources`, `.../run`, `.../save`) and `GET /v1/briefs/*` |
| `agents` | The browser-reachable agent-invocation route: `POST /v1/agents/{agent}`, `GET /v1/agents/runs/{id}`, `GET /v1/agents` |
| `resolve` | The local reads: `GET /v1/items/resolve` (resolve-by-URL), `GET /v1/items/resolve-file` (resolve a forge file coordinate to a local checkout path), `GET /v1/items/resolve-ids` (resolve item ids back to their references), and `GET /v1/services/resolve` (resolve a repo URN to the configured service that claims it — the only one of the four that reads `nimbus.toml` rather than the index) |
| `fetch` | The targeted fetch-on-miss write: `POST /v1/items/fetch` — makes an outbound request through a configured connector, so it is a separate scope from `resolve`'s purely local reads |
| `egress` | The egress-ledger reads: `GET /v1/egress`, `GET /v1/egress/head`, `GET /v1/egress/verify`, `GET /v1/egress/prove` |

If `--scopes` is omitted, the minted token is granted `clip,briefs` — the two surfaces that shipped
before scopes existed. **A client paired before this change holds exactly `clip,briefs` and gains
nothing new automatically** — its token was minted (or is read back) as a bare string, which parses
as that same pair. Use `nimbus clip scopes` (below) to grant it more without re-pairing.

The scope set you pass here is what actually gets minted: it is recorded on the pairing window at
the moment you run this command and is not something the browser extension can influence when it
redeems the code.

The printed URL is the gateway's loopback HTTP origin (`http://127.0.0.1:<port>`), derived from `NIMBUS_HTTP_PORT`. If the gateway is running without the HTTP surface, the command instead warns you to restart it with `nimbus serve --port 7474` — without that surface the extension has nothing to reach.

```bash
nimbus clip pair
nimbus clip pair --label work-chrome
nimbus clip pair --label work-chrome --scopes clip,briefs
```

```text
Pairing "work-chrome" — in the browser extension's Options page, enter:
  Gateway URL:  http://127.0.0.1:7474
  Pairing code: 429040
Enter it within 2 minutes.
```

---

### `nimbus clip scopes <label> --set <a,b>`

Change a paired client's scopes in place — no re-pairing, no new token. `<label>` must match an
existing paired device (see `nimbus clip status`); `--set` takes the same comma-separated scope list
as `pair --scopes` above and replaces the label's scope set entirely (it is not additive).

This is how a client paired before scopes existed picks up `agents`/`resolve`/`fetch` once a route
consumes them, or how you narrow an over-broad grant without disrupting the device's existing token.

```bash
nimbus clip scopes work-chrome --set clip,briefs,agents
```

```text
Scopes for "work-chrome" are now: clip,briefs,agents
```

---

### `nimbus clip list [--tag <t>] [--limit N] [--json]`

List saved web clips, newest first. `--tag` filters to clips carrying that exact tag
(matched in SQL, so `--limit` stays correct). `--limit` defaults to 50 (invalid values fall
back to the default). `--json` emits structured rows (`id, title, url, clippedAt, tags, mode,
wordCount`) for scripting.

```bash
nimbus clip list
nimbus clip list --tag rust --limit 20
nimbus clip list --json
```

---

### `nimbus clip delete <id|url>` / `nimbus clip delete --all [--yes]`

Delete clips. A `nimbus:` argument is treated as a clip ID (from `clip list`); anything else
is treated as a page URL and every clip from that page (the article plus any text selections)
is removed. `--all` clears every clip but is guarded: without `--yes` it only reports how many
would be deleted. Deleting a missing id/url is idempotent (`Deleted 0 clips.`).

```bash
nimbus clip delete https://blog.example.com/rust-async
nimbus clip delete nimbus:clip:abc123…
nimbus clip delete --all --yes
```

---

### `nimbus clip status`

List all paired browser devices — shows each device's label, its token fingerprint (never the raw
token), and its granted scopes, plus whether research briefs are enabled.

```bash
nimbus clip status
```

```text
  work-chrome   3f9a1c2e...   clip,briefs
briefs: enabled
```

---

### `nimbus clip revoke <label|--all>`

Revoke a specific paired device's token by label, or revoke all paired devices with `--all`.

```bash
nimbus clip revoke work-chrome
nimbus clip revoke --all
```

---

## Vault

### `nimbus vault set <key> <value>`

Store a secret in the Vault under the given key.

```bash
nimbus vault set github.pat ghp_xxxx
```

---

### `nimbus vault get <key>`

Retrieve and print a Vault secret. Because the value echoes to the terminal, the command first prompts `Secrets echo to this terminal. Continue?` and prints nothing if you decline.

```bash
nimbus vault get github.pat
```

---

### `nimbus vault list [prefix]`

List Vault key names (never values). Keys are scoped per connector and per profile. An optional `prefix` filters the listing.

```bash
nimbus vault list
nimbus vault list github          # Only keys starting with "github"
```

The single positional argument is the prefix filter — there is no `--profile` flag (passing one would be read as the prefix and match nothing). Profile scoping comes from `NIMBUS_PROFILE` or `nimbus profile switch`.

---

### `nimbus vault delete <key>`

Delete a specific Vault entry. Use `nimbus connector remove` for full connector cleanup.

```bash
nimbus vault delete github.pat
```

---

## Audit

### `nimbus audit`

Show the local audit log. Every action the agent takes — including every HITL decision — is recorded here before execution.

```bash
nimbus audit
nimbus audit --limit 100
nimbus audit --json
nimbus audit --limit 100 --json | jq -r '.[] | select(.hitlStatus == "rejected") | .actionType'
```

`--limit` (default 50) and `--json` are the only flags parsed. There is no `--service` or `--since` **filtering** here — such arguments are silently ignored, and the most recent `--limit` rows are returned regardless; `--json` changes the rendering only, never the row set.

**Columns:** `Timestamp`, `Action`, `Status` (`approved` / `rejected` / `not_required`), `Reason` (the HITL reject reason from `action_json`; `—` when absent).

**`--json` shape.** A JSON array of the raw `audit.list` rows: `{ id, actionType, hitlStatus, actionJson, timestamp }`, newest first, honouring `--limit` (default 50). `actionJson` stays the **string** the chain stored — it is not parsed for you, so a row whose payload is malformed still appears rather than being dropped; the human table's "Reason" column is that string's `hitlRejectReason` field. `--json` applies to the listing only; `nimbus audit verify` and `nimbus audit export` have their own output contracts.

---

### `nimbus audit verify`

Verify the BLAKE3 chain integrity of the audit log. Each row stores `row_hash = BLAKE3(prev_hash || canonical_row_bytes)`; this command walks the chain and reports the first break, if any.

```bash
nimbus audit verify              # Verify chain since the last successful checkpoint
nimbus audit verify --full       # Verify the entire chain from row 1
```

`--full` is the only flag `audit verify` reads; there is no `--since` / row-id start.

**Exit codes:** `0` = chain intact, `1` = break detected (output names the first broken row id and the reason — e.g. `prev_hash mismatch`, `row_hash mismatch`, `missing predecessor`).

A break indicates either tampering or unsynchronized writes. A break is a hard finding — file an internal issue and capture a `nimbus audit export` snapshot before any other action.

---

### `nimbus audit export`

Export the full audit log as a JSON array. Suitable for backup, compliance handoff, or external SIEM ingestion.

```bash
nimbus audit export --output ./audit-2026-04-30.json
```

The exported payload includes `row_hash` and `prev_hash` for each row, so the chain can be re-verified offline. The output file is written with `Bun.write` and overwrites without prompting — pick a fresh path.

---

## Data Sovereignty

Nimbus stores all your indexed data and credentials locally. The `nimbus data` family lets you take a portable, encrypted backup of that state, restore it on another machine, or perform a service-scoped GDPR deletion. Bundles are protected by an Argon2id-derived key envelope; a 12-word BIP39 recovery seed is generated once and shown only at export time.

### `nimbus data export`

Create an encrypted, portable backup of the local index, the audit log, and (where supported) Vault credential references.

```bash
nimbus data export --output ./nimbus-2026-04-30.tar.gz --passphrase "long-strong-passphrase"
nimbus data export --output ./meta-only.tar.gz --passphrase "..." --no-index
```

**Required flags:**

| Flag | Description |
|---|---|
| `--output <path>` | Destination `.tar.gz`. Overwrites without prompting. |
| `--passphrase <pw>` | Argon2id-derived key. Choose a long passphrase — there is no recovery if you lose both this and the recovery seed. |

**Optional flags:**

| Flag | Description |
|---|---|
| `--no-index` | Skip the SQLite index; export only credential references and audit log. Smaller bundle, faster restore. |

On first export, the Gateway generates a 12-word BIP39 recovery seed and prints it once. **Store it offline.** Subsequent exports reuse the same seed (it is bound to the Gateway, not to a single bundle), so either the passphrase *or* the seed can decrypt any bundle from this Gateway.

---

### `nimbus data import <bundle>`

Restore a previously exported bundle. The Gateway must be stopped before running this command; the index is replaced atomically.

```bash
nimbus data import ./nimbus-2026-04-30.tar.gz --passphrase "..."
nimbus data import ./nimbus-2026-04-30.tar.gz --recovery-seed "word1 word2 ... word12"
```

Provide **either** `--passphrase` or `--recovery-seed`, not both. The output reports the count of credentials restored and a count of OAuth entries that may need re-authentication on the next sync (refresh tokens that were rotated upstream since the export).

**Version-compatibility note:** A bundle from a Gateway with a higher schema version cannot be imported into an older Gateway. Upgrade the target Gateway first.

---

### `nimbus data delete --service <name>`

Service-scoped GDPR deletion. Removes all index rows, embeddings, audit log entries, and Vault credentials associated with the named connector. Irreversible.

```bash
nimbus data delete --service slack --dry-run     # Preview only — no changes
nimbus data delete --service slack --yes         # Execute — required for non-interactive
```

**Flags:**

| Flag | Description |
|---|---|
| `--service <name>` | Connector to purge (`github`, `slack`, `google_drive`, …) |
| `--dry-run` | Print the preflight (item count, vault entry count) and exit |
| `--yes` | Required to execute the deletion (the CLI is non-interactive) |

The preflight is always printed — even with `--yes` — so the deletion blast radius is recorded in the audit log before the destructive write.

---

## Performance Benchmarking

### `nimbus bench`

Run the perf harness against one or all measurement surfaces. Surfaces are pre-defined synthetic workloads (intent classification, sync throughput, query latency, etc.) that produce comparable numbers across runs and machines.

```bash
nimbus bench --surface S2-a --runs 5 --reference     # Reference run — interactive protocol confirm
nimbus bench --surface S2-a --runs 5 --gha           # CI run — auto-tag with platform
nimbus bench --all --gha --corpus medium             # Every registered surface
```

**Required (one of):**

| Flag | Description |
|---|---|
| `--surface <id>` | A registered surface id. Shipped in v0.1.0: `S1`, `S2-a`/`-b`/`-c`, `S3`, `S4`, `S5`, `S6-drive`/`-gmail`/`-github`, `S7-a`/`-b`/`-c`, `S8-l<L>-b<B>` (12-cell embedding cross-product), `S9`, `S10`, `S11-a`/`-b`. See `packages/gateway/src/perf/surfaces/` and `SURFACE_REGISTRY` in `packages/gateway/src/perf/bench-cli.ts` for the canonical list. |
| `--all` | Run every registered surface back-to-back |

**Tagging (one of, required):**

| Flag | Description |
|---|---|
| `--reference` | Tag the run as `reference-m1air`. Interactive protocol confirmation is required by default — see [`docs/perf/reference-runner-setup.md`](./perf/reference-runner-setup.md) |
| `--protocol-confirmed` | Non-interactive equivalent for CI dispatch from `.github/workflows/_perf-reference.yml`. Do not pass this from a developer machine — the protocol gate exists to catch dirty environments before the number lands in `history.jsonl` |
| `--gha` | Tag as `gha-<os>` (auto-derived from `process.platform`) |

**Optional:**

| Flag | Description |
|---|---|
| `--corpus <tier>` | `small` *(default)* / `medium` / `large` — fixture size |
| `--runs <N>` | Per-surface invocations (default: 5) |
| `--history <path>` | `history.jsonl` override — defaults to `packages/gateway/src/perf/history.jsonl` |
| `--fixture-cache <p>` | Fixture cache directory override |

The harness writes a structured `HistoryLine` per surface/run to `history.jsonl`. Surface implementations live under `packages/gateway/src/perf/surfaces/`; the bench runner is `packages/gateway/src/perf/bench-runner.ts`. The surface table and SLO thresholds live in [`docs/perf/slo.md`](./perf/slo.md) + [`docs/perf/baseline.md`](./perf/baseline.md).

---

## Updates

### `nimbus update`

Check for or apply a Nimbus software update. Updates are downloaded, verified against an Ed25519 signature, and then handed off to the platform installer. No update is applied until the binary signature is confirmed.

```bash
nimbus update --check               # Print current vs. latest version; exit 1 if update available, 0 if current
nimbus update                       # Download, verify signature, prompt for confirmation, run installer
nimbus update --yes                 # Skip confirmation prompt (for scripted/unattended use)
```

**Options:**

| Flag | Description |
|---|---|
| `--check` | Check-only mode — no download, no install |
| `--yes` | Skip the "Apply update?" confirmation |

**Security:** The downloaded binary's SHA-256 hash is computed and verified against the Ed25519-signed manifest before any installer is invoked. A tampered binary is rejected and automatically rolled back.

**Headless note:** When the Gateway starts in headless mode (no Tauri connection detected) and an update is available, it prints a one-line hint to stdout: `"A new version of Nimbus is available (X.Y.Z). Run 'nimbus update' to install."`

**Environment overrides:** `NIMBUS_UPDATER_URL` overrides the manifest URL. `NIMBUS_UPDATER_DISABLE=true` disables all update checks.

---

## Share & Virality

Export, verify, and forward signed session snapshots and recipe DAGs. All outbound shares leave the machine through the share-gate (`share.create` / `share.publish` HITL action, invariant `I27`). Forwarding re-routes an existing share to a federation peer; the inner body and origin signature are never altered (the forwarder appends its own hop signature). Inbound shares are viewable artifacts only — never auto-merged or auto-executed (invariant spec §9.4).

### `nimbus share create <session-id> [--out <file>] [--http] [--to-peer <peerId>] [--expires <dur>] [--redact <field>]... [--as-recipe]`

Create and emit a signed share for a session. Requires your HITL approval before the share leaves the machine. The HITL preview shows the exact redacted content that will be exported.

```bash
nimbus share create sess_abc123 --out ./share.json
nimbus share create sess_abc123 --http
nimbus share create sess_abc123 --to-peer peer_xyz --expires 7d
nimbus share create sess_abc123 --as-recipe --out ./recipe.json
```

**Flags:**

| Flag | Description |
|---|---|
| `--out <file>` | Write the share to a local file |
| `--http` | Emit to the configured HTTP sink |
| `--to-peer <peerId>` | Send directly to a paired federation peer |
| `--expires <dur>` | Expiry duration: `30s`, `5m`, `2h`, `7d`, etc. |
| `--redact <field>` | Redact a field from the share body (repeatable) |
| `--as-recipe` | Emit a declarative V42 recipe DAG instead of a transcript |

---

### `nimbus share list [--all]`

List share records in the local store. Without `--all`, expired shares are excluded.

```bash
nimbus share list
nimbus share list --all
```

---

### `nimbus share prune`

Delete all expired share records from the local store.

```bash
nimbus share prune
```

---

### `nimbus share pubkey`

Print this gateway's Ed25519 share-signing public key (base64). Recipients can use this to verify the origin signature on shares you send.

```bash
nimbus share pubkey
```

---

### `nimbus share approve <request-id>` / `nimbus share reject <request-id>`

Respond to a pending HITL share-approval request. The `request-id` is printed when a share is created and shown in the TUI consent panel.

```bash
nimbus share approve req_abc123
nimbus share reject req_abc123
```

---

### `nimbus share forward <contentHash> --to-peer <peerId>`

Forward an already-emitted share (identified by its content hash) to a federation peer. Requires your HITL `share.publish` approval before the forwarded envelope leaves the machine. The inner body and origin signature are byte-identical across all hops; the forwarder appends only its own hop signature. `federation.shareForward` is local-only and cannot be triggered over LAN by a remote peer (invariant global-constraints §8).

```bash
nimbus share forward sha256:abc123 --to-peer peer_xyz456
```

Prints `delivered <contentHash>` when the peer accepted immediately, or `queued <contentHash>` when the peer is offline and the share will be retried.

---

### `nimbus share inbox [--all]`

List inbound forwarded shares received from federation peers. Each row shows a provenance attribution chip, the content hash, and the share kind. Without `--all`, only unread/unacknowledged shares are shown.

```bash
nimbus share inbox
nimbus share inbox --all
```

**Example output:**

```text
forwarded from alice, 2 hops away  sha256:abc123  transcript
from bob (direct)                  sha256:def456  recipe
```

---

### `nimbus verify-share <file|url> [--replay] [--allow-unsigned]`

Verify the Ed25519 signature and content hash of a share file or URL. With `--replay`, re-execute the session steps against the current local index and compare results.

```bash
nimbus verify-share ./share.json
nimbus verify-share https://example.com/share.json --replay
```

Prints `signature: VALID` or `INVALID`, plus expiry status. With `--replay`, also prints a per-step divergence report and a summary.

**Replay refuses an unverifiable share.** A share file is untrusted input: replay executes the tool calls it names against your live, credentialed connectors. So if the signature, content hash or expiry check fails, `--replay` aborts before any outbound call and exits non-zero. `--allow-unsigned` overrides that, and should be used only for a share you produced yourself.

Two further limits apply to replay, both reported rather than silent: only tools whose id ends in a recognised read verb are executed (anything else is reported `skipped-non-read`), and no more than 256 steps run per replay — any excess is printed as "further step(s) were NOT executed".

---

## LAN Remote Access

Encrypted, relay-free remote access between machines on the same network. Disabled by default (`[lan] enabled = false` in `nimbus.toml`). Enable via `nimbus config set lan.enabled true`.

All traffic is E2E encrypted with NaCl box (X25519 DH + XSalsa20-Poly1305). A set of exfiltration- and management-class methods is forbidden over LAN regardless of peer grants (`FORBIDDEN_OVER_LAN` in `packages/gateway/src/ipc/lan-rpc.ts`, invariant I5) — forbidden namespaces include (but are not limited to) `vault.*`, `updater.*`, `lan.*`, `profile.*`, `audit.*`, `data.*`, `security.*`, `chatops.*`, `tribal.*`, `team.*`, `teamvault.*`, `hitl.*`, `identity.*`, and `scim.*`, plus the full-method forbids `connector.addMcp`, the `extension.*` management methods, `index.reembed` / `index.reembedCancel`, the federation management/asker methods (`federation.discover` / `pair` / `peers` / `namespace.*` / `consentRespond` / `ask*`), and the share owner-action chokepoints `share.create` / `share.prune` / `share.approvalRespond` (the I27 outbound-publish gate). The read-only share methods (`share.verify` / `list` / `get` / `pubkey`) and the answering methods `federation.query` / `federation.expertise` / `federation.invoke` (gated by I17 / I19) stay admitted.

### `nimbus lan status`

Show LAN server state: whether LAN is enabled, whether a pairing window is open, and the listen address. This is the default subcommand (`nimbus lan` with no argument runs `status`).

```bash
nimbus lan status
```

---

### `nimbus lan open`

Open a 5-minute pairing window and print a one-time pairing code (with its expiry). A peer pairs against this window using the code.

```bash
nimbus lan open
```

---

### `nimbus lan close`

Close the active pairing window early.

```bash
nimbus lan close
```

---

### `nimbus lan peers`

List all paired peers with their ID, write-allowed flag, and display name.

```bash
nimbus lan peers
```

---

### `nimbus lan grant <peerId>`

Allow a peer to call write and HITL-gated methods. Read-only by default after pairing.

```bash
nimbus lan grant abc123
```

---

### `nimbus lan revoke <peerId>`

Remove a peer's write grant. They remain paired but are restricted to read-only methods.

```bash
nimbus lan revoke abc123
```

---

### `nimbus lan remove <peerId>`

Unpair a peer. Their stored public key is deleted; any active session is terminated.

```bash
nimbus lan remove abc123
```

---

## Exit Codes

| Code | Meaning |
|---|---|
| `0` | Success |
| `1` | General error / warnings (e.g. `nimbus doctor` warnings, `nimbus db verify` findings) |
| `2` | Hard failure (e.g. `nimbus doctor` hard failures, Gateway unreachable) |

---

## Environment Variables

| Variable | Purpose |
|---|---|
| `NIMBUS_TELEMETRY_ENABLED` | Override `[telemetry].enabled` |
| `NIMBUS_TELEMETRY_ENDPOINT` | Override `[telemetry].endpoint` |
| `NIMBUS_CONFIG_DIR` | Override the platform config directory — **config only**. There is no data-directory override: the data directory is not relocatable by any `NIMBUS_*` variable except `NIMBUS_DEMO=1`, which moves config, data and logs into the isolated demo subtree `<dataDir>/demo` (invariant I41; the one exception is a gateway launched directly from a shell that exports `NIMBUS_GATEWAY_LOG_PATH`, which `nimbus --demo start` always overrides) rather than repointing the real ones (on Linux the real data directory follows `XDG_DATA_HOME`) — and additionally uses a separate IPC endpoint and an in-memory vault, neither of which lives under that subtree. |
| `NIMBUS_DEMO` | `1` runs the CLI and any Gateway it starts against the isolated demo root (invariant I41). Unset, empty or `0` is off; any other value is refused. Cannot be combined with `NIMBUS_CONFIG_DIR` or `NIMBUS_GATEWAY_SOCKET` — the combination is refused, because a demo process honouring either would reach your real config, Vault or gateway. A demo Gateway opens no OS credential store (an in-memory vault), does not reap Windows AppContainer profiles, and ignores `NIMBUS_HTTP_PORT` / `NIMBUS_METRICS_PORT`. |
| `NIMBUS_PROFILE` | Set the active profile at launch |
| `NIMBUS_EMBEDDING_MODEL_DIR` | Path to pre-downloaded MiniLM model weights (headless bundle) |
| `NIMBUS_EMBEDDINGS` | Set to `false` to disable background embedding generation after index upserts |
| `NIMBUS_ENGINE_CONTEXT_WINDOW_ITEMS` | Top-N index items passed in full to the agent after ranked search (1–200; default 10) |
| `NIMBUS_SEARCH_PRIORITY_JSON` | Per-service search priority weights (0–1) as a JSON object e.g. `{"github":0.8,"slack":0.7}` |
| `NIMBUS_ASK_MAX_STEPS` | Mastra tool-loop depth for `nimbus ask` sessions (1–64) |
| `NIMBUS_MAX_AGENT_DEPTH` | Maximum sub-agent recursion depth for multi-agent tasks (1–10; default 3) |
| `NIMBUS_MAX_TOOL_CALLS_PER_SESSION` | Hard cap on total tool calls per session (1–200; default 20) |
| `NIMBUS_RUN_QUERY_BENCH` | Set to `1` to enable strict `< 100ms` p95 assertion in the query latency benchmark |
| `NIMBUS_LOG_LEVEL` | `debug` / `info` / `warn` / `error` (default: `info`) |
| `NIMBUS_SQLITE_PATH` | **macOS only.** Path to a full `libsqlite3.dylib`. Checked first, ahead of the `libsqlite3.dylib` released builds ship beside the binaries and then the Homebrew prefixes (`/opt/homebrew/opt/sqlite/lib/`, then `/usr/local/opt/sqlite/lib/`). Bun links Apple's system SQLite on macOS, which has extension loading compiled out, so sqlite-vec — and therefore vector search, hybrid ranking and session-memory recall — needs one of these present; on a released install the bundled one always is, and this variable is an override rather than a requirement. Mainly useful on a dev checkout, where `process.execPath` is `bun` and no library sits beside it. Ignored on Linux and Windows, which use Bun's own full build. `nimbus doctor` reports the resolved state. |
| `NIMBUS_UPDATER_URL` | Override the update manifest URL (default: official endpoint) |
| `NIMBUS_UPDATER_DISABLE` | Set to `true` to disable all auto-update checks |
| `NIMBUS_EXTENSIONS_REGISTRY_URL` | Extension registry base URL; the auto-update polling daemon is only constructed when this is set |
| `NIMBUS_EXTENSIONS_DISABLE_AUTO_UPDATE` | Set to `1` to hard-disable the extension auto-update polling daemon at Gateway init |
| `NIMBUS_LAN_PORT` | Override the LAN TCP listen port (default: `7475`) |
| `NIMBUS_DEV_UPDATER_PUBLIC_KEY` | Override the embedded Ed25519 updater public key — for tests only |

---

## Platform Notes

| Platform | IPC Socket | Config Dir | Data Dir |
|---|---|---|---|
| Windows 10+ | `\\.\pipe\nimbus-gateway` | `%APPDATA%\Nimbus` | `%LOCALAPPDATA%\Nimbus\data` |
| macOS 13+ | `$TMPDIR/nimbus-gateway.sock` | `~/Library/Application Support/Nimbus` | `~/Library/Application Support/Nimbus` (same root as the config dir — there is no `/data` segment) |
| Ubuntu 22.04+ | `$XDG_RUNTIME_DIR/nimbus-gateway.sock` (falls back to the OS temp dir) | `~/.config/nimbus` | `~/.local/share/nimbus` |

---

## See Also

- [`README.md`](./README.md) — Quick start and overview
- [`architecture.md`](./architecture.md) — Subsystem design and data flow
- [`roadmap.md`](./roadmap.md) — Phase acceptance criteria and sequencing
- [`SECURITY.md`](./SECURITY.md) — Security model and vulnerability reporting
- [`docs/contributors/extension-author-walkthrough.md`](./contributors/extension-author-walkthrough.md) — Writing a connector extension