The dossier-runtime verb set

dossier-runtime is the control plane for the loop — one command surface that stands up a client’s sovereign tenant and runs all three faces (Brain, Agency, Ladder) over it. This page is the canonical, exhaustive reference for its verbs.

Note

This reference is generated against the real dossier-runtime --help output. Until the package is published you invoke it from the build: node ./packages/runtime/dist/cli.js <verb> …. Once published the same verbs run as dossier-runtime <verb> … — the flags are identical.

Synopsis

dossier-runtime provision    --root <dir> --client <id> [--vertical <v>] [--no-git]
dossier-runtime list         --root <dir>
dossier-runtime run          --root <dir> --client <id> (--source-dir <dir> | --url <seed>) [--site] [--dry-run] [--no-git]
dossier-runtime site         --root <dir> --client <id> [--build]
dossier-runtime readout      --root <dir> --client <id>
dossier-runtime drain        --root <dir> --client <id> [--agentic [--subscription] [--model <m>] [--max-turns <n>] [--max-budget <usd>]] [--max-tasks <n>] [--worker <id>] [--no-commit]
dossier-runtime review-queue --root <dir> --client <id>
dossier-runtime approve      --root <dir> --client <id> --task <id> [--by <name>]
dossier-runtime reject       --root <dir> --client <id> --task <id> [--reason <why>] [--by <name>]
dossier-runtime deprovision  --root <dir> --client <id>

Common flags

These two scope nearly every verb:

Flag	Meaning
--root <dir>	Tenants root — the parent directory of every tenant’s siloed subtree.
--client <id>	Tenant / client id; a single safe path segment.

Output convention

Every verb writes a human summary to stderr and a machine-readable JSON result to stdout — so the CLI composes cleanly in scripts and pipelines. Run any verb with --help for its exact flag list.

Verbs at a glance

Verb	Purpose	Key inputs	Output
provision	Stand up a tenant’s siloed workspace (OKF repo + manifest, git by default).	--root, --client, --vertical?	The tenant record (paths, vcs).
list	List provisioned tenants under a root.	--root	Tenant summaries.
run	Provision (idempotent) then run the loop: ingest → extract → emit → commit.	--root, --client, --source-dir | --url	The loop result (per-stage status).
site	Render a tenant’s OKF repo as a static docs site.	--root, --client, --build?	The render plan (and build result).
readout	Ladder. Compute the deterministic L2 adoption readout. Read-only.	--root, --client	The Now/Next/Later ledger.
drain	Agency. Run one bounded board-drain over the tenant’s task atoms.	--root, --client, --agentic?	The drain outcome.
review-queue	List tasks awaiting a human decision (status: review).	--root, --client	The review queue.
approve	Bless agent work: review → done, compounded into git. Human-only.	--root, --client, --task	The disposition + commit.
reject	Send work back: review → backlog (re-claimable).	--root, --client, --task	The disposition.
deprovision	Remove a tenant’s entire subtree.	--root, --client	What was removed.

The drain → review-queue → approve/reject arc is the Agency’s human gate: agents propose, a human disposes. See DEC-0053 for the runtime topology and its invariants.

---

provision

Stand up a tenant’s siloed workspace — its OKF repo, a manifest, and (by default) its own git history.

dossier-runtime provision --root ./clients --client acme-co --vertical digital-experience-agency

Flag	Meaning
--root <dir>	Tenants root (required).
--client <id>	Tenant id (required).
--vertical <v>	Vertical preset id (e.g. digital-experience-agency).
--known-external <csv>	Ids that live outside this repo (e.g. knowledge-model).
--no-git	Provision without git. Default: one client = one git repo.

Guarantee: idempotent and fully offline — no network, no key. run calls it for you, so you rarely invoke it directly.

list

List the provisioned tenants under a root.

dossier-runtime list --root ./clients

Flag	Meaning
--root <dir>	Tenants root (required).

Output: each tenant’s clientId, tenantRoot, and vcs. Read-only, offline.

run

Provision (idempotent) then run the full loop over one source: ingest → extract → emit → commit. Exactly one source must be given.

# Learn a directory of clean markdown/HTML
dossier-runtime run --root ./clients --client acme-co --source-dir ./acme-docs --subscription

# Learn a public website (keyless crawler)
dossier-runtime run --root ./clients --client acme-co --url https://acme.example.com

Flag	Meaning
--source-dir <dir>	Directory of clean markdown/HTML to ingest. (Pick one source.)
--url <seed>	Public page to crawl + learn; repeatable. Keyless by default. (Pick one source.)
--pages <n>	Max pages to crawl from the --url seeds (default 1).
--connector <name>	Web connector: http (default, keyless) or firecrawl (premium; needs FIRECRAWL_API_KEY).
--subscription	Extract via the claude CLI (your subscription) — no API key.
--reconcile	Merge this pass into the existing KB by id + confidence (preserve human-curated atoms, flag — never delete — vanished ones) instead of overwriting.
--site	After the loop, render the tenant as a static docs site (build-side; run from the repo root).
--dry-run	Run every stage but write/commit nothing.
--no-git	Run without git.

Guarantee — no silent network. Extraction calls a model, so run needs a transport: either ANTHROPIC_API_KEY in the environment, or --subscription. Without one it refuses rather than calling out quietly (this holds for --dry-run too, since it still extracts). Each successful pass commits one diff into the client’s own git history.

site

Render a tenant’s OKF repo as a static docs site.

dossier-runtime site --root ./clients --client acme-co --build

Flag	Meaning
--build	Build the site now. Without it, the command just prints the render command.

When building, this sets DOSSIER_KB to the tenant’s OKF repo and runs the docs build; run it from the monorepo root.

readout

The Ladder. Compute the client’s deterministic L2 adoption readout — a 4-axis score (value · risk · readiness · momentum) over their process/workflow atoms → a Now/Next/Later roadmap, plus the recommended wedge (where to start).

dossier-runtime readout --root ./clients --client acme-co

Output: the machine-readable ledger on stdout; a human summary on stderr (initiatives scored, the confidence floor, and the Now/Next/Later/Watch counts).

Guarantee — read-only. It reads the tenant’s own served OKF and writes nothing; the adoption-readout skill narrates the readout and emits the sovereign OKF artifact. The scoring is deterministic. See DEC-0067 for the spec.

drain

The Agency. Run one bounded board-drain over the tenant’s task atoms: claim the next claimable task (race-safe lease), do the bounded work, transition it, and (optionally) commit.

# Deterministic offline drain (no LLM, no network, no spend) — the default
dossier-runtime drain --root ./clients --client acme-co

# Live persona-grounded agent session (spends; needs a transport)
dossier-runtime drain --root ./clients --client acme-co --agentic --subscription --max-budget 1

Flag	Meaning
--agentic	Run the live persona-grounded multi-turn session. Spends — needs --subscription or ANTHROPIC_API_KEY; refuses without one. The agent carries each task to review and stops. Omit it to run the deterministic offline worker.
--model <alias>	Model for --agentic turns: haiku / sonnet / opus (default haiku).
--max-turns <n>	Hard ceiling on agent turns per task (--agentic).
--max-budget <usd>	Per-session hard spend cap (--agentic).
--max-tasks <n>	Tasks claimed this drain (default 1 = one task per session).
--worker <id>	The claimed_by identity recorded on the claim (default local-drain).
--no-commit	Don’t commit transitions to git.

Guarantees. Offline by default — no LLM, no network, no spend, a two-way door. Only one drain runs per tenant at a time (a race-safe lease); a drain that can’t run because a peer holds the lock, or because the budget envelope is spent, is a clean no-op (exit 0), not an error. Agent work always stops at review — a machine never marks a task done. See DEC-0053.

review-queue

List the tasks awaiting a human decision (status: review).

dossier-runtime review-queue --root ./clients --client acme-co

Output: each task’s id, title, assignee, and file path. Read-only.

approve

The human gate’s bless. Move a task review → done and compound it into the tenant’s git history. Human-only — this is the loop’s last hop.

dossier-runtime approve --root ./clients --client acme-co --task task-acme-onboard --by dakota

Flag	Meaning
--task <id>	The task to approve (required).
--by <name>	The human disposing, recorded for provenance (default human).

Guarantee: only a human runs this; a task that isn’t in review is rejected with a precise reason (a user error). On success the transition is committed into git.

reject

Send a task back: review → backlog, re-claimable. The reason is recorded on the task for the next claimant.

dossier-runtime reject --root ./clients --client acme-co --task task-acme-onboard --reason "needs a second source" --by dakota

Flag	Meaning
--task <id>	The task to reject (required).
--reason <why>	Recorded on the task for the next claimant.
--by <name>	The human disposing (default human).

deprovision

Remove a tenant’s entire subtree.

dossier-runtime deprovision --root ./clients --client acme-co

Output: { clientId, removed }. Idempotent — removing a tenant that doesn’t exist is a clean no-op.

---

Exit codes & guarantees

Code	Meaning
0	Success. (Also: a drain that cleanly didn’t run — peer lock held, board paused, or budget envelope spent.)
1	A stage failed (e.g. a loop stage errored), or an unexpected error.
2	A usage error — a missing required flag, an unknown verb, or a disposition on a task that isn’t in review.

Cross-cutting invariants the runtime upholds:

• No silent network. Any verb that would call a model refuses unless you’ve given it a transport (--subscription or ANTHROPIC_API_KEY).
• Confidence is capped. Agent-produced atoms are emitted at inferred, the agent floor; only a human promotes them.
• The human stays the gate. Agent work stops at review; only approve/reject disposes — and approve is the only path to done.
• One client = one tenant = one repo. Isolation is the file boundary, and every successful mutation is a diff in the client’s own git history.

The full rationale for each of these lives in the decision records — start with DEC-0053 (the runtime topology and its seven invariants).

See also

• Run your first loop in 15 minutes — the verbs in context.
• Install the Claude Code plugin — run them from Claude Code.
• The other CLIs: dossier-extract (the extraction moat) and dossier-mcp (serve one tenant over MCP) — invoked by the agents and skills the plugin ships.