Command line

majordomus

Majordomus control plane: a data-driven MCP server over the repository's .ai/ layer

The Rust executable of Majordomus. It reads the repository's provider-neutral AI layer under .ai/ and serves it to MCP clients over stdio. Almost every capability is a query; the few that change anything declare themselves as commands and are listed by `capabilities list --kind command`. Most of the task lifecycle (init, start, check, finish, doctor, ...) is the shell tool bin/majordomus in the same repository. Development semantics are converging onto capabilities of this registry one at a time (ADR 0040); until one has, this executable does not implement that command.

majordomus <COMMAND>

/docs/cli/ — this command on its own page

Subcommands: mcp, serve, capabilities, generate, bench, scope, web, why, devtask, distribution, env, commands, completion, worktree, prs, offload, convergence, commit, product, release, quality, run, executions, devcontext, guard, mesh, monitor, models, reasoning, evidence, served, deploy, rules, intent, delivery, plan, economics, entity, shell, layout, pack, dashboard, brief, blackboard, skills, knowledge, continuity.

Arguments: none.

majordomus mcp

Serve the repository's AI layer to an MCP client over stdio

majordomus mcp [OPTIONS]

/docs/cli/mcp/ — this command on its own page

Examples

• See what would be served, without serving it

  Builds the registry and the index of the repository in the working directory and prints the repository, the capabilities, the objects and every diagnostic, then exits. Nothing is served and nothing is written.

  $ majordomus mcp --inspect

  What it asserts: exits 0; prints repository, capabilities.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

• The same, as one JSON document for a script

  The shape `--inspect` prints for a person, as JSON: the repository, its discovery mode, the capabilities and the diagnostics, deterministic and safe to diff.

  $ majordomus mcp --inspect --format json

  What it asserts: exits 0; prints one JSON document carrying /repository/repository/root, /tools.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

• Serve one MCP client on stdio

  The form an MCP client spawns: JSON-RPC frames in on stdin, frames out on stdout, logs on stderr, and the session ends at end of input. `--standalone` keeps this process to itself: no shared server, no HTTP, nothing written anywhere.

  $ majordomus mcp --standalone

  What it asserts: answers initialize and tools/list on stdio, and exits 0 at end of input.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus serve

Serve the same capabilities over HTTP on the loopback interface, with the home page, /openapi.json, /swagger and the documentation under /docs/

majordomus serve [OPTIONS] [COMMAND]

/docs/cli/serve/ — this command on its own page

Subcommands: status, ensure, stop.

Examples

• Serve the same capabilities over HTTP on a free port

  Port 0 asks the operating system for a free port; the address is logged on stderr. `/` is the home page, generated from the surfaces this process resolved; the document at /openapi.json is the same one `majordomus generate` commits; /swagger is the Swagger UI over it; /docs/ is this repository's documentation when it has been built for that mount.

  $ majordomus serve --port 0

  What it asserts: binds a port, answers GET /openapi.json, exits 0 when stopped.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus serve status

Where this checkout's server stands — absent, starting, ready, outdated or stale — and every server of the repository

majordomus serve status [OPTIONS]

/docs/cli/serve/status/ — this command on its own page

Examples

• Where this checkout's server stands, and every server of the repository

  The standing of this checkout's server measured against what this executable would serve, the lease it holds, and every checkout git registers for the repository with its own server. Asked of the running server when there is one, so that the answer includes the lease that process holds; answered locally otherwise.

  $ majordomus serve status

  What it asserts: exits 0; prints standing.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus serve ensure

Make sure a ready server serves this checkout: start one when there is none or the lease is stale, wait for one that is starting, and report where it stands

majordomus serve ensure [OPTIONS]

/docs/cli/serve/ensure/ — this command on its own page

Examples

• Make sure a server serves this checkout, and let it end when idle

  Starts a server as a process of its own when none answers, waits until it is ready, and prints one line: the standing, the address, the pid. Run again, it finds the server ready and starts nothing. `--idle` is how long the started server outlives its last peer; one second here, so that the example leaves nothing behind.

  $ majordomus serve ensure --idle 1 --wait 30

  What it asserts: exits 0; prints ready.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus serve stop

Stop this checkout's server — the one its lease names, when it answers for this checkout — and wait for that server's lease to go, which another process taking the checkout over does not undo

majordomus serve stop [OPTIONS]

/docs/cli/serve/stop/ — this command on its own page

Examples

• Stop this checkout's server, when there is one

  Signals the server this checkout's lease names, when it answers for this checkout, and waits for that server's lease to go — the one it read, by its token, so a second process taking the checkout over in the same instant is reported rather than mistaken for a server that would not stop. A checkout with no lease has nothing to stop, and says so.

  $ majordomus serve stop

  What it asserts: exits 0; prints nothing to stop.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus capabilities

Introspect the capability registry: what exists, where it came from, how it is exposed

majordomus capabilities [OPTIONS] <COMMAND>

/docs/cli/capabilities/ — this command on its own page

Subcommands: list, describe, schema, projections, validate.

majordomus capabilities list

Every capability, one line each, with its projections

majordomus capabilities list [OPTIONS]

/docs/cli/capabilities/list/ — this command on its own page

Examples

• Which capabilities the command line itself dispatches to

  One line per capability exposed through the `cli` projection, with the projections of each. The registry answers this; no list of capabilities is written in the command line's own declaration.

  $ majordomus capabilities list --exposure cli

  What it asserts: exits 0; prints capabilities.list, capabilities.describe.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

• Every capability as one JSON document

  The whole registry for a script: each capability with its kind, its provenance and every projection it has.

  $ majordomus capabilities list --format json

  What it asserts: exits 0; prints one JSON document carrying /capabilities.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus capabilities describe

One capability by canonical id: schemas, provenance, every projection

majordomus capabilities describe [OPTIONS] <ID>

/docs/cli/capabilities/describe/ — this command on its own page

Examples

• One capability in full, by its canonical id

  Its kind, its input and output schemas, where it was composed, and every projection of it: the MCP tool or resource, the HTTP route, the CLI path.

  $ majordomus capabilities describe objects.get

  What it asserts: exits 0; prints objects.get, GET /api/v1/object.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus capabilities schema

The canonical input or output JSON Schema of one capability

majordomus capabilities schema [OPTIONS] <ID>

/docs/cli/capabilities/schema/ — this command on its own page

Examples

• The canonical output schema of a capability

  The JSON Schema the MCP and OpenAPI projections are derived from; `--side input` prints the schema of what the capability accepts.

  $ majordomus capabilities schema objects.get --side output

  What it asserts: exits 0; prints one JSON document carrying /title.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus capabilities projections

Where each capability is projected, and every claim its surface does not answer

majordomus capabilities projections [OPTIONS]

/docs/cli/capabilities/projections/ — this command on its own page

Examples

• Every exposure a capability claims that its surface does not answer

  `rows: 0` is the closure `project.interfaces-are-projections` asks for: every declared command line, route and tool is answered by the surface that carries it. The commands no capability claims are reported beside it, as the measure of how much of the command line is still hand-written.

  $ majordomus capabilities projections --unmet

  What it asserts: exits 0.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

• Where one module's capabilities appear

  A row per capability with the command line, HTTP route and MCP tool it reaches, so a capability that exists but is reachable from nowhere is visible as one.

  $ majordomus capabilities projections --module worktree

  What it asserts: exits 0; prints worktree.topology, majordomus worktree topology.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus capabilities validate

Build the registry and every projection; exit 10 with every violation named

majordomus capabilities validate [OPTIONS]

/docs/cli/capabilities/validate/ — this command on its own page

Examples

• Prove the registry and every projection of it

  Builds the registry, the MCP and HTTP surfaces, the OpenAPI document, the command line's documentation and the benchmark coverage, and names every failure. Exit 10 when anything is unmet.

  $ majordomus capabilities validate

  What it asserts: exits 0; prints validate: 0 failure(s), OK cli.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus generate

Write the committed projections of the registry (docs/generated), or check that they are current

majordomus generate [OPTIONS] [TARGET]

/docs/cli/generate/ — this command on its own page

Examples

• Write every committed projection

  The OpenAPI document, the capability reference, the command-line reference and its JSON, the registry manifest, the benchmark matrix, the shell tool's allow-lists, the provider bootstraps and the site's registry dataset — all from the one registry and the one clap declaration.

  $ majordomus generate

  What it asserts: exits 0.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

• Refuse a tree whose projections are stale

  Writes nothing and compares instead: exit 0 when every committed projection is what the sources produce, exit 10 with each stale file named. This is the form CI runs.

  $ majordomus generate
  $ majordomus generate --check

  What it asserts: exits 0.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

• One target only

  Each target can be written on its own while a change is iterated on; `majordomus generate` with no target writes all of them.

  $ majordomus generate openapi

  What it asserts: exits 0.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

• Check one target without writing it

  `--check` composes with a target: here only the registry dataset the site renders is compared with what the sources produce, exit 10 naming it when it is stale.

  $ majordomus generate site
  $ majordomus generate site --check

  What it asserts: exits 0.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus bench

Time every externally callable operation (each capability directly, over MCP and over HTTP, and the transports' own operations), report coverage, compare with the accepted baseline

majordomus bench [OPTIONS] [COMMAND] [ID]

/docs/cli/bench/ — this command on its own page

Subcommands: coverage, baseline.

Examples

• Time the capabilities in process

  The quick profile takes few samples, and `--transport direct` measures the executor without spawning a server. Nothing is written under .ai/local/ with `--no-write`.

  $ majordomus bench --transport direct --profile quick --no-write --format json

  What it asserts: exits 0; prints one JSON document carrying /results, /profile.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus bench coverage

Every required target and whether it is covered; the denominator is generated from the registry

majordomus bench coverage [OPTIONS]

/docs/cli/bench/coverage/ — this command on its own page

Examples

• Every required benchmark target and whether it is covered

  The denominator is generated from the registry: every executable capability, on every transport it is exposed on, plus the transports' own operations.

  $ majordomus bench coverage --format json

  What it asserts: exits 0; prints one JSON document carrying /lines, /tallies.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

• Fail when a target is missing

  Exit 10 when any required target is uncovered or waived, so a capability that nothing times cannot be merged.

  $ majordomus bench coverage --check

  What it asserts: exits 0.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus bench baseline

The accepted baseline of this platform under .ai/repo/benchmarks/rust/

majordomus bench baseline [OPTIONS] <COMMAND>

/docs/cli/bench/baseline/ — this command on its own page

Subcommands: update.

majordomus bench baseline update

Run the benchmarks and record them as this platform's baseline (a reviewable, tracked file)

majordomus bench baseline update [OPTIONS]

/docs/cli/bench/baseline/update/ — this command on its own page

Examples

• Record this platform's accepted baseline

  Runs the benchmarks and writes the result under .ai/repo/benchmarks/rust/ as a tracked, reviewable file. The full profile is the default; the quick profile is for trying the path out. A dirty work tree is refused unless --allow-dirty says otherwise.

  $ majordomus bench baseline update --profile quick --allow-dirty

  What it asserts: exits 0.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus scope

The repository scope: what a worker reads and what it never reads; with paths, whether each is in or out and why

majordomus scope [OPTIONS] [PATHS]

/docs/cli/scope/ — this command on its own page

Examples

• What a worker reads of this repository

  With no path, the declaration itself and the tally: how many tracked files are in the scope and how many are out.

  $ majordomus scope

  What it asserts: exits 0.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

• Judge paths, and say which rule decided

  For each path: in or out, and the rule that decided it. `--check` exits 10 when any path given is out, which is how a hook refuses to read one.

  $ majordomus scope docs/CLI.md --format json

  What it asserts: exits 0; prints one JSON document carrying /0/verdict, /0/rule.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus web

The repository's web surfaces: what is exposed, where it is mounted, what produced it, and whether the topology is valid

majordomus web [OPTIONS] [COMMAND]

/docs/cli/web/ — this command on its own page

Subcommands: list, explain, validate, manifest, report, compose.

Examples

• The topology, from the command with no subcommand

  `web` with nothing after it lists, because listing is what a person wants when they ask what this repository exposes.

  $ majordomus web

  What it asserts: exits 0; prints ID, MOUNT.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus web list

Every discovered surface: id, kind, mount, producer

majordomus web list [OPTIONS]

/docs/cli/web/list/ — this command on its own page

Examples

• Every web surface this repository exposes

  The resolved topology, in route-precedence order: the routes the executable answers itself, the application's site, and every generated report that declared itself under the generated web root. Nothing is registered anywhere; each line was discovered.

  $ majordomus web list

  What it asserts: exits 0; prints MOUNT, /api/v1, /swagger.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus web explain

Why each surface exists and where each of its values came from

majordomus web explain [OPTIONS] [ID]

/docs/cli/web/explain/ — this command on its own page

Examples

• Why a surface exists and where each of its values came from

  For each field a reader could be surprised by — the mount, the kind, the directory — the source that decided it: a producer's own declaration, the site configuration, the capability registry, or the model's documented default.

  $ majordomus web explain swagger

  What it asserts: exits 0; prints swagger, came from.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus web validate

Check the topology's invariants; exit 10 on any error finding

majordomus web validate [OPTIONS]

/docs/cli/web/validate/ — this command on its own page

Examples

• Check the topology before anything serves or publishes it

  Two surfaces claiming one path, a surface nested inside another's subtree, a directory outside the generated root or one that walks out of the repository: each is a named finding with the surface, the value, its source and the fix. Exit 10 on any error finding. `--artifacts` also requires every static surface's directory and index to exist, which is what serving and publishing need.

  $ majordomus web validate

  What it asserts: exits 0; prints no conflict.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus web manifest

Write the resolved topology to the generated manifest

majordomus web manifest [OPTIONS]

/docs/cli/web/manifest/ — this command on its own page

Examples

• Write the resolved topology down for another tool to read

  The manifest under the generated web root is derived state: a publisher or a CI job may read it instead of resolving the topology again, and nothing may edit it, because the next run overwrites it from the same discovery.

  $ majordomus web manifest

  What it asserts: exits 0; prints web manifest, surface.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus web report

Render a generated report into its own surface under the generated web root

majordomus web report [OPTIONS] <COMMAND>

/docs/cli/web/report/ — this command on its own page

Subcommands: tests, benchmarks, ui, ui-snapshot, cockpit-snapshot.

majordomus web report tests

The test run: the behavioural cases' report, and the crate's own totals

majordomus web report tests [OPTIONS]

/docs/cli/web/report/tests/ — this command on its own page

Examples

• Render the suite's own results into the /tests surface

  The runner writes its report with `MJ_TEST_REPORT=<file> bash test/run.sh`; this renders it, keeps the machine-readable results beside the page, and declares the directory so discovery finds it. Without that file there is nothing to render and the command says so rather than publishing an empty page.

  $ majordomus web report tests --suite target/web/run.tsv

  What it asserts: exits 13.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus web report benchmarks

The benchmark run: a results document, or the accepted baseline

majordomus web report benchmarks [OPTIONS]

/docs/cli/web/report/benchmarks/ — this command on its own page

Examples

• Render a benchmark run into the /benchmarks surface

  Reads a results document — a run's own output, or an accepted baseline under the layer's benchmarks section, which have the same shape — and renders every measured target ordered by median. It measures nothing itself: a figure on the page is a figure a run produced.

  $ majordomus web report benchmarks --from .ai/repo/benchmarks/rust/baseline.macos-aarch64-debug.json

  What it asserts: exits 13.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus web report ui

The UI conformance audit, rendered as a section of the test surface (/tests/ui)

majordomus web report ui [OPTIONS]

/docs/cli/web/report/ui/ — this command on its own page

Examples

• Render the UI conformance audit into /tests/ui

  `scripts/ui audit` drives a browser over every page of the built site at every width the compiled stylesheet's breakpoints imply, and writes one results document; this renders it. The rendering is a section of the test surface rather than a surface of its own, because a conformance run is a test run and the topology refuses a surface mounted inside another's subtree. Without that document there is nothing to render and the command says so.

  $ majordomus web report ui --from target/web/run-ui.json

  What it asserts: exits 13.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus web report ui-snapshot

The UI itself, read once at this commit and written as static pages a publication carries at /ui (ADR 0141)

majordomus web report ui-snapshot [OPTIONS]

/docs/cli/web/report/ui-snapshot/ — this command on its own page

Examples

• Read the UI once and write it as the pages a publication carries at /ui

  Asks the UI in-process for every screen and panel and then, one page per family in turn until `--limit` pages or `--budget-seconds` are reached, for the pages they link to, and writes each as a file under target/web/ui-snapshot: links between them relative, a link only a running process answers led to the snapshot's page about the live UI, the script told not to read again, and every page stamped with the commit, the time and the executable that read it. The declaration beside it makes the directory a surface of every publication and of no process.

  $ majordomus web report ui-snapshot --limit 20

  What it asserts: exits 0; prints web report, ui-snapshot.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus web report cockpit-snapshot

The Cockpit itself, read once at this commit and written as static pages a publication carries at /cockpit (ADR 0147)

majordomus web report cockpit-snapshot [OPTIONS]

/docs/cli/web/report/cockpit-snapshot/ — this command on its own page

Examples

• Read the Cockpit once and write it as the pages a publication carries at /cockpit

  Asks the Cockpit in-process for every static route except the one page about this machine, then for the pages the UI's snapshot links to, then, one page per family in turn until `--limit` pages or `--budget-seconds` are reached, for the pages those link to, and writes each as a file under target/web/cockpit-snapshot. Links between them are relative; a link into the UI leads to the UI's snapshot when that holds the page; a form, a query or a page past the bound leads to the snapshot's page about the live Cockpit; no page carries a script, because the Cockpit's scripts talk to a process; and every page is stamped with the commit, the time and the executable that read it.

  $ majordomus web report cockpit-snapshot --limit 12

  What it asserts: exits 0; prints web report, cockpit-snapshot.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus web compose

Compose every published surface into one publishable tree

majordomus web compose [OPTIONS]

/docs/cli/web/compose/ — this command on its own page

Examples

• Compose every published surface into one publishable tree

  Each producer owns its own output directory; publication needs one tree, and the mapping is the resolved mount and nothing else. A surface that is discovered is published without a copy step being written anywhere, and a repository with nothing generated yet composes an empty tree rather than an error. Where a surface exists and its directory does not, composition refuses and names the producer to run.

  $ majordomus web compose --destination target/site

  What it asserts: exits 0.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus why

The operational moments this tool answers: the catalogue, one moment, the audiences and areas, a diagnosis of your own week, and the catalogue's own validation

majordomus why [OPTIONS] [COMMAND]

/docs/cli/why/ — this command on its own page

Subcommands: list, show, audiences, areas, diagnose, validate.

Examples

• The operational moments this repository holds

  `why` with nothing after it lists, because listing is what a person wants when they ask what this section is. The count on the last line is computed from the catalogue; no number anywhere is written down.

  $ majordomus why

  What it asserts: exits 0; prints SLUG, moment(s).

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus why list

Every operational moment, narrowed by any facet the catalogue reports

majordomus why list [OPTIONS]

/docs/cli/why/list/ — this command on its own page

Examples

• Every public moment, in presentation order

  Drafts are excluded unless `--all` is given. The facets a listing may be narrowed by are the ones the catalogue itself reports, so an audience or an area added as a file is a filter without anything being registered.

  $ majordomus why list

  What it asserts: exits 0; prints SLUG.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

• Only what one audience recognises

  Membership is declared by each moment and never listed in the audience's own file, so this answer is derived. An audience the catalogue does not have is an invalid input naming the ones it does, not an empty answer.

  $ majordomus why list --audience fixture-team

  What it asserts: exits 0; prints SLUG.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

• The same, as the shape the API and MCP answer with

  One domain model behind every projection: this document is what `GET /api/v1/why` returns and what the `majordomus_why` tool answers, including the derived facets and the catalogue's fingerprint.

  $ majordomus why list --format json

  What it asserts: exits 0; prints one JSON document carrying /counts/moments, /facets/audiences, /fingerprint.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus why show

One moment in full, with every relation derived from its metadata

majordomus why show [OPTIONS] <ID>

/docs/cli/why/show/ — this command on its own page

Examples

• One moment, with every relation derived from its metadata

  The record as its file declares it, then what nobody authored: the responsibilities its claims belong to, the moments that name it, and the moments nearest it by shared area, audience and tag.

  $ majordomus why show fixture-moment

  What it asserts: exits 0; prints fixture-moment, derived.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus why audiences

Every audience, with the moments that name it

majordomus why audiences [OPTIONS]

/docs/cli/why/audiences/ — this command on its own page

Examples

• Who recognises what, with the counts derived

  Each audience with how many public moments name it. The number is computed from the moments; an audience's own file never lists one.

  $ majordomus why audiences

  What it asserts: exits 0; prints SLUG, TITLE.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus why areas

Every operational area, with the moments that fall under it

majordomus why areas [OPTIONS]

/docs/cli/why/areas/ — this command on its own page

Examples

• The operational areas, with the counts derived

  The same relation read the other way: each area with the public moments that fall under it.

  $ majordomus why areas

  What it asserts: exits 0; prints SLUG, TITLE.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus why diagnose

What the symptoms you recognise imply: the areas they weigh towards and the mechanisms that answer them

majordomus why diagnose [OPTIONS]

/docs/cli/why/diagnose/ — this command on its own page

Examples

• The questionnaire, assembled from the catalogue's own signals

  With no selection there is nothing to diagnose, so the questions are printed instead of an empty answer. Every line is a signal a moment declares; nothing here is a list of questions.

  $ majordomus why diagnose

  What it asserts: exits 0; prints Which of these happened to you this week?.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

• What the symptoms you recognise imply

  A name is a signal id or a moment id. The answer is counting, not inference: each recommendation carries the moments that produced it, and there is no percentage because there is no model behind one.

  $ majordomus why diagnose --signal fixture-signal

  What it asserts: exits 0; prints moment(s) matched, fixture-moment.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus why validate

Every finding over the catalogue; exit 10 when any is an error

majordomus why validate [OPTIONS]

/docs/cli/why/validate/ — this command on its own page

Examples

• Check the catalogue before anything projects it

  A reference that resolves to nothing, with the nearest candidate; a duplicate identity; a file name that disagrees with its id; a public record that does not meet the floor its status promises. Exit 10 on any error.

  $ majordomus why validate

  What it asserts: exits 0; prints moment(s), valid.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus devtask

One issue or one milestone as an executable development scope: what was authored, where the plan graph puts it, what happened to it, whether a worker may start it — with the origin of every value on the value

majordomus devtask [OPTIONS] <COMMAND>

/docs/cli/devtask/ — this command on its own page

Subcommands: issue, milestone.

majordomus devtask issue

One issue as an executable development task, every field carrying where it came from

majordomus devtask issue [OPTIONS] <ID>

/docs/cli/devtask/issue/ — this command on its own page

Examples

• One issue as work to be done, not as metadata

  Identity, intent, status, milestone, dependencies, blockers, branches, commits, sessions and readiness in one answer, composed from the derivations that already own each half — the plan for the graph, `trace` for git, the canonical record for everything a person wrote. Nothing is manufactured: a key the record does not carry is `unknown` with the reason, never an empty string that reads as authored.

  $ majordomus devtask issue I0001

  What it asserts: exits 0; prints readiness, explicit.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

• The same, as the shape the API and MCP answer with

  One domain model behind every projection: this document is what `GET /api/v1/devtask/issue` returns and what the `majordomus_devtask` tool answers, with the four groups kept apart by the type — what a person authored, what the plan derives, what happened locally, and where the external projection stands — and a provenance on every field.

  $ majordomus devtask issue I0001 --no-git --format json

  What it asserts: exits 0; prints one JSON document carrying /declaration/title/provenance, /position/status/provenance, /readiness/state, /attestation/explicit.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

• An id the model does not declare is answered, not refused

  A typo that read as "nothing has been authored" is the one answer a work surface must never give, so an unknown id answers with `declared: false`, the readiness `undeclared`, and every canonical field `unknown` with the reason on it.

  $ majordomus devtask issue I9999 --no-git

  What it asserts: exits 0; prints undeclared.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus devtask milestone

One milestone as an executable dependency graph: ready, blocked, parallelizable, critical blockers, cycles

majordomus devtask milestone [OPTIONS] <ID>

/docs/cli/devtask/milestone/ — this command on its own page

Examples

• What to work on next in one outcome, and what to unblock first

  The issues partitioned by readiness, the critical blockers ordered by how much unfinished work each holds back, and the startable work partitioned into subsets that may genuinely run at the same time. A pure function of the canonical records — no git, no clock, no network — so two runs on two machines produce the same bytes and a reader derives nothing itself.

  $ majordomus devtask milestone foundation

  What it asserts: exits 0; prints READINESS.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

• The graph, as the shape the API and MCP answer with

  Every partition the plan implies and no surface should recompute: `ready`, `blocked`, `waiting`, `active`, `review`, `completion_blocked`, `complete`, `cancelled`, plus `critical_blockers`, `parallelizable` with the scope path behind each serialisation, and `cycles` as strongly connected components.

  $ majordomus devtask milestone foundation --format json

  What it asserts: exits 0; prints one JSON document carrying /counts/total, /ready, /critical_blockers, /parallelizable.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus distribution

How this project is packaged, published and installed: the platforms, the artifact names, the installer, the releases

majordomus distribution [OPTIONS] [COMMAND]

/docs/cli/distribution/ — this command on its own page

Subcommands: show, status, validate, targets, matrix, artifact, releases, metadata, build.

Examples

• How this project is installed

  `distribution` with nothing after it shows the model: the one-line install command, where an installation goes, and how many platforms a release builds. Every value comes from share/distribution.yaml, which is the only place any of them is written.

  $ majordomus distribution

  What it asserts: exits 0; prints binary, install, targets.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus distribution show

The model: the install command, where an installation goes, and every declared target

majordomus distribution show [OPTIONS]

/docs/cli/distribution/show/ — this command on its own page

Examples

• The distribution model as one JSON document

  The same answer as a document a script can read: the install command, the default locations, and every declared target with the artifact name the naming function derives for it. This is what the website's install block and the cockpit's install card render.

  $ majordomus distribution show --format json

  What it asserts: exits 0; prints one JSON document carrying /install_command, /targets.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus distribution status

Whether the advertised one-line installation works right now, and what is missing when it does not

majordomus distribution status [OPTIONS]

/docs/cli/distribution/status/ — this command on its own page

Examples

• Whether the published one-line installation works right now

  The operator's question — *can a machine that has never seen this project install it with the advertised command?* — answered from the distribution model and the release records, without touching the network. Each check names what was observed; a failing one names its cause and the command that changes it. Shown here in a repository that has published nothing, where the answer is no and the exit code is 10, which is what makes it usable as a check rather than as prose. `distribution validate` is the gate over the model itself; this is the gate over the state a user meets.

  $ majordomus distribution status

  What it asserts: exits 10.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus distribution validate

Every invariant of the model and of the release records; exit 10 with each violation named

majordomus distribution validate [OPTIONS]

/docs/cli/distribution/validate/ — this command on its own page

Examples

• Every invariant of the model and of the release records

  Refuses a duplicate target id or triple, two targets deriving one artifact name, a Linux target with no C library, a published target with nothing to build it on, an unbuilt target with no recorded reason, a base URL that is not HTTPS, and a release record that misses a supported target, renames an artifact or serves one from another host. Exits 10 with each violation named.

  $ majordomus distribution validate

  What it asserts: exits 0; prints distribution.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus distribution targets

Every declared target, one line each, with the artifact name it derives

majordomus distribution targets [OPTIONS]

/docs/cli/distribution/targets/ — this command on its own page

Examples

• Every platform, and whether a release builds it

  One line per declared target: its id, its Rust target triple, whether it is supported, experimental or unavailable, and how it is written in prose. The supported-platform table in the documentation and the installer's own refusal message are rendered from these same rows.

  $ majordomus distribution targets

  What it asserts: exits 0; prints RUST TARGET, supported.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus distribution matrix

The release build matrix, as the release workflow reads it

majordomus distribution matrix [OPTIONS]

/docs/cli/distribution/matrix/ — this command on its own page

Examples

• The release build matrix the workflow runs

  One entry per published target, with the runner it is built on, the packages that runner needs, and the artifact name with `{tag}` where a release's tag goes. The release workflow reads this and states no platform of its own; adding a target to the model adds a build here and nowhere else.

  $ majordomus distribution matrix

  What it asserts: exits 0; prints one JSON document carrying /include, /binary.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus distribution artifact

The archive name and root directory a target and a tag derive

majordomus distribution artifact [OPTIONS]

/docs/cli/distribution/artifact/ — this command on its own page

Examples

• What one target and one tag are called

  The one naming function, asked directly: the archive's name, the directory it unpacks into, and where a release publishes it. `scripts/release-package` asks this rather than composing a name, so a change to the naming function reaches the packaging without an edit.

  $ majordomus distribution artifact --target aarch64-apple-darwin --tag v0.2.0 --format json

  What it asserts: exits 0; prints one JSON document carrying /name, /root, /url.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus distribution releases

Every recorded release, newest first, and the one an unpinned installation resolves to

majordomus distribution releases [OPTIONS]

/docs/cli/distribution/releases/ — this command on its own page

Examples

• What has been published, and what an unpinned install resolves to

  Every release record this repository holds, newest first, and which of them the stable pointer names: the highest version among the stable, unwithdrawn records. The pointer is derived on every read and is authored nowhere.

  $ majordomus distribution releases

  What it asserts: exits 0.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus distribution metadata

The public metadata one release record publishes, rendered from the record alone

majordomus distribution metadata [OPTIONS]

/docs/cli/distribution/metadata/ — this command on its own page

Examples

• What one release record publishes

  The public metadata a record turns into, rendered from the record and the model alone: the release pipeline prints this before it commits anything, and the installer's own tests serve it as a release that never existed. Shown here in a repository that has published nothing, where the record does not exist and the command says which file it wanted and exits 10 rather than inventing one.

  $ majordomus distribution metadata --record .ai/repo/releases/v0.2.0.yaml

  What it asserts: exits 10.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus distribution build

What this executable is: version, target triple, profile, commit

majordomus distribution build [OPTIONS]

/docs/cli/distribution/build/ — this command on its own page

Examples

• What this executable is

  The crate version, the Rust target triple, the profile and the commit, all compiled in at build time. An installed binary answers this without a repository, a toolchain or git, which is what makes a support question answerable.

  $ majordomus distribution build

  What it asserts: exits 0; prints version, target, commit.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus env

What this checkout is: the project, version control, the toolchains it declares, what the layer holds, the workflows, the provider projections and the local services

majordomus env [OPTIONS] [COMMAND]

/docs/cli/env/ — this command on its own page

Subcommands: status, banner, export, enter, explain, preflight.

Examples

• What this checkout is

  `env` with nothing after it resolves the whole snapshot: the project and its version, the repository and its layer, version control, the toolchains the repository declares, what the layer holds counted per kind, the workflows the runner describes, the provider projections against the policy that renders them, and the local services. This is the resolution that counts the layer, so it builds the index and writes the cache the banner reads.

  $ majordomus env

  What it asserts: exits 0; prints project, repository, resolution.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus env status

The whole snapshot, resolved in full: what the layer holds is counted, and the cache the banner reads is written

majordomus env status [OPTIONS]

/docs/cli/env/status/ — this command on its own page

Examples

• The snapshot as one document

  The same value the HTTP route `/api/v1/environment` and the MCP resource `majordomus://environment` answer with, and the value the banner renders. Every field carries where it came from under `provenance`, and a value nothing could resolve is absent rather than zero.

  $ majordomus env status --format json

  What it asserts: exits 0; prints one JSON document carrying /schema, /project/version, /repository/name, /provenance.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus env banner

Render the snapshot for a terminal. Goes to standard error, never standard output, because direnv reads standard output as the environment it is setting

majordomus env banner [OPTIONS]

/docs/cli/env/banner/ — this command on its own page

Examples

• The two-line form, at a width you choose

  What `direnv` renders on entering the repository. It resolves fast — it never builds the index — and it writes to standard error, because direnv reads the standard output of a `.envrc` as the environment it is applying. `--width` renders as if the terminal were that wide, which is what makes the layout testable.

  $ majordomus env banner --mode compact --width 80

  What it asserts: exits 0.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus env export

The variable assignments a shell in this repository benefits from, for `eval`. Assignments only: no command, no side effect

majordomus env export [OPTIONS]

/docs/cli/env/export/ — this command on its own page

Examples

• The assignments a shell in this repository wants

  Assignments and nothing else, safe to `eval`: no command runs, no file is touched, and every value is quoted so that a repository path holding a quote or a `$(...)` cannot become shell code. This is the whole of what `.envrc` needs from Majordomus.

  $ majordomus env export --shell direnv

  What it asserts: exits 0; prints export MAJORDOMUS_ROOT=.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus env enter

Enter the repository: the assignments a shell here benefits from on standard output, the banner on standard error, the workflow bridge refreshed when a declaration behind it moved, and the runtime ensured — the whole of what entering this repository is, as one call, so that no person and no agent has to remember a sequence. Never builds, never reaches a remote network, and never waits for a server it started to answer

majordomus env enter [OPTIONS]

/docs/cli/env/enter/ — this command on its own page

Examples

• Everything entering this repository is, as one call

  What the file a shell evaluates on entry runs, and the only call it makes (ADR 0043): the assignments on standard output for `eval`, the banner on standard error, the workflow bridge refreshed when a declaration behind it moved, and the repository's shared server ensured when nothing is serving this checkout. It never builds, never ensures from an executable older than its sources, never waits for a server it started to answer, and never exits non-zero — a non-zero exit here would make direnv report that the whole environment failed. `--no-runtime` is what this example passes, because an example is not the place to start a server.

  $ majordomus env enter --shell direnv --no-banner --no-bridge --no-runtime

  What it asserts: exits 0; prints export MAJORDOMUS_ROOT=.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus env explain

Where each value came from: the file, command or constant that decided it, the resolver that read it, and how far it can be trusted

majordomus env explain [OPTIONS] [FIELD]

/docs/cli/env/explain/ — this command on its own page

Examples

• Where one value came from

  An inferred system without provenance is magic. Every field of the snapshot can name the file, command or compile-time constant that decided it, the resolver that read it, and whether it was read now, taken from the cache, or not resolved at all.

  $ majordomus env explain project.version

  What it asserts: exits 0; prints project.version, source, resolver.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus env preflight

Whether Majordomus is in force in this checkout, claim by claim, with the evidence behind each verdict: git, the episode and its briefing, the task and handover, the policy, rules and ADRs, the shared server and the surfaces it serves, the peer board, recorded test runs, rule enforcement, provider projections and the deployment. A verdict that asserts something is in force always names its evidence. Resolves fast, from the rule tally a `--full` run cached; the HTTP route `/api/v1/environment/preflight` and the MCP tool `majordomus_preflight` answer the same value

majordomus env preflight [OPTIONS]

/docs/cli/env/preflight/ — this command on its own page

Examples

• What is in force here, and what proves it

  One verdict per claim — `verified`, `active`, `fresh`, `stale`, `degraded`, `unavailable`, `failed`, `unknown` or `not_applicable` — and the evidence it rests on: the file, command or loopback answer that was read. A rule file on disk is not a rule anything enforces, an address that accepts a connection is not a server of this version, and a recorded test run at another commit does not verify this tree, so none of them is reported as one. `attention` lists what needs a look, most urgent first.

  $ majordomus env preflight --format json

  What it asserts: exits 0; prints one JSON document carrying /schema, /sections/0/checks/0/verdict, /attention.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus commands

Every command this repository offers, from whichever program offers it: the graph, one command, where each one is projected, and the workflow bridge derived from it

majordomus commands [OPTIONS] [COMMAND]

/docs/cli/commands/ — this command on its own page

Subcommands: list, show, explain, graph, bridge.

Examples

• Every command this repository offers

  The command graph, composed from the three declarations that already exist: the clap tree of this executable, the shipped command registry of the shell tool, and the recipes the workflow runner describes. One line per command, with the program that runs it and what running it changes.

  $ majordomus commands

  What it asserts: exits 0; prints commands, executable, read-only.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus commands list

Every command, one line each: what it is, what running it changes, and where it is projected

majordomus commands list [OPTIONS]

/docs/cli/commands/list/ — this command on its own page

Examples

• Only what reads

  The filters are the graph's own vocabulary rather than a search over text: `--effect read-only` is every command that changes nothing anywhere, which is the same predicate the exposure policy uses to decide what a machine surface may call.

  $ majordomus commands list --effect read-only

  What it asserts: exits 0; prints read-only.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus commands show

One command in full: its arguments, its effect, what it needs, and every surface that carries it

majordomus commands show [OPTIONS] <ID>

/docs/cli/commands/show/ — this command on its own page

Examples

• One command, and every surface that carries it

  The arguments with the source of each one's values, the effect, and the projections: the command line, the workflow recipe, the MCP tool, the HTTP route, the Cockpit and the page. A surface that withholds it says why.

  $ majordomus commands show executable.worktree.status

  What it asserts: exits 0; prints executable.worktree.status, projections.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus commands explain

Why one command appears where it does: the declaration it came from, the policy that placed it, and the reason for every surface that withholds it

majordomus commands explain [OPTIONS] <ID>

/docs/cli/commands/explain/ — this command on its own page

Examples

• Why a command appears where it does

  The same command with its provenance: the file that declares it, the reader that found it, the capability behind it when there is one, what it requires, and the file the exposure policy lives in. Nothing about a command's placement is a mystery a grep has to solve.

  $ majordomus commands explain executable.serve

  What it asserts: exits 0; prints declared in, policy.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus commands graph

The whole graph as one document, with its fingerprint and every diagnostic

majordomus commands graph [OPTIONS]

/docs/cli/commands/graph/ — this command on its own page

Examples

• The whole graph as one document

  Deterministic and fingerprinted: two builds over one tree produce the same bytes, which is what lets the workflow bridge, the completion index and the Cockpit all key on the fingerprint instead of regenerating.

  $ majordomus commands graph --format json

  What it asserts: exits 0; prints one JSON document carrying /schema, /fingerprint, /commands.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus commands bridge

Materialise the workflow bridge from the graph, and refresh the cache the completion reads; writes nothing when the graph has not changed

majordomus commands bridge [OPTIONS]

/docs/cli/commands/bridge/ — this command on its own page

Examples

• The workflow runner's recipes, derived

  Every command of both programs, written as a recipe that runs the canonical program with the caller's own arguments. It goes under .ai/local/cache/, which no commit carries, and it is rewritten only when the graph's fingerprint changes.

  $ majordomus commands bridge

  What it asserts: exits 0; prints bridge, recipe.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus completion

Completion for any surface, answered from the command graph: the candidates a shell asks for, and the one-time integration that asks

majordomus completion [OPTIONS] [COMMAND]

/docs/cli/completion/ — this command on its own page

Subcommands: query, init, install.

Examples

• The integration a person installs once

  With no subcommand, the shell integration for zsh. It contains no command, no flag and no identifier: every candidate comes from a query against the command graph of the repository the shell is in, so one integration serves every checkout and never goes stale.

  $ majordomus completion

  What it asserts: exits 0; prints completion query, compdef.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus completion query

The candidates for one command line, from the command graph. What a shell adapter calls on every TAB

majordomus completion query [OPTIONS] [WORD]

/docs/cli/completion/query/ — this command on its own page

Examples

• What a shell asks on every TAB

  The words of the command line and the position of the cursor; back come the candidates with their descriptions. The same call answers the workflow runner's completion with `--surface workflow`, resolving the recipe name to the command it bridges and then completing that command's own arguments.

  $ majordomus completion query --surface cli -- majordomus work

  What it asserts: exits 0; prints worktree.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus completion init

The shell integration to load once, which carries no command of its own and asks this executable for every candidate

majordomus completion init [OPTIONS]

/docs/cli/completion/init/ — this command on its own page

Examples

• The same, for bash

  A different shell's protocol, the same question. Both adapters read the words being completed, find the cursor, ask this executable and print what comes back.

  $ majordomus completion init --shell bash

  What it asserts: exits 0; prints completion query, complete -F.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus completion install

Put that integration into the shell's startup file, between managed markers, so that no one maintains it by hand

majordomus completion install [OPTIONS]

/docs/cli/completion/install/ — this command on its own page

Examples

• The one line a person adds to their shell, added for them

  Writes the integration into the shell's startup file between `# >>> MAJORDOMUS >>>` markers: nothing outside them is touched, running it twice changes nothing, and `--remove` takes it out again. It is never a side effect of anything else — installing into a person's home directory is its own decision, so it is its own command. `--dry-run` says what would change and writes nothing.

  $ majordomus completion install --shell zsh --dry-run

  What it asserts: exits 0.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus worktree

The branch-to-worktree topology: where every linked worktree belongs (`<repo>-wt/<branch>`), where each one is, and the lifecycle — create, migrate, repair, guard

majordomus worktree [OPTIONS] [COMMAND]

/docs/cli/worktree/ — this command on its own page

Subcommands: status, list, topology, root, path, inspect, create, ensure, migrate, validate, doctor, guard, repair, remove, cleanup, uncommitted, trunk, branches.

Examples

• Where am I, and is that where I belong?

  `worktree` with nothing after it answers the question a worker asks before starting: which branch this is, whether this directory is that branch's canonical worktree (or the primary checkout on the trunk), what is uncommitted here, and how many errors the whole topology carries. The same answer from the primary checkout and from four directories deep inside a linked worktree.

  $ majordomus worktree

  What it asserts: exits 0; prints branch, worktree, container.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus worktree status

Where this call is — branch, worktree, canonical or not, uncommitted work — and how many errors the whole topology carries; exit 10 when this worktree is out of place

majordomus worktree status [OPTIONS]

/docs/cli/worktree/status/ — this command on its own page

Examples

• The current worktree as one document

  The same answer as JSON: the repository, the container, the trunk and how it was decided, this worktree with its standing and diagnostics, and whether it is where it belongs. This is what the MCP tool `majordomus_worktree_status` and `GET /api/v1/worktrees/status` answer.

  $ majordomus worktree status --format json

  What it asserts: exits 0; prints one JSON document carrying /worktree/standing, /container/path, /trunk/source, /canonical.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus worktree list

Every registered worktree with its standing, one line each; exit 10 when the topology has an error

majordomus worktree list [OPTIONS]

/docs/cli/worktree/list/ — this command on its own page

Examples

• Every worktree, the misplaced ones obvious

  The primary checkout first, then every linked worktree with its standing, its branch, where it belongs when it is somewhere else, and its uncommitted work. The primary checkout is exempt from the path rule and held to the trunk rule instead.

  $ majordomus worktree create feature/example
  $ majordomus worktree list

  What it asserts: exits 0; prints PRIMARY, CANONICAL, -wt/feature/example.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus worktree topology

The whole topology: repository, container, trunk, every worktree, every branch without a worktree, every diagnostic; exit 10 when it has an error

majordomus worktree topology [OPTIONS]

/docs/cli/worktree/topology/ — this command on its own page

Examples

• The whole topology as one document

  The repository, the container, the trunk, every worktree, every branch with or without a worktree, every diagnostic with its code and remedy, and the tallies. This is what the MCP resource `majordomus://worktrees`, the tool `majordomus_worktrees`, `GET /api/v1/worktrees` and the Cockpit all render.

  $ majordomus worktree topology --format json

  What it asserts: exits 0; prints one JSON document carrying /container/path, /trunk/branch, /worktrees/0/standing, /branches/0/name, /tallies/worktrees, /valid.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus worktree root

Print the container every linked worktree belongs under, and nothing else: `cd "$(majordomus worktree root)"`

majordomus worktree root [OPTIONS]

/docs/cli/worktree/root/ — this command on its own page

Examples

• The container, for the shell

  Prints the container and nothing else, so a shell can use it: `cd "$(majordomus worktree root)"`. It is the primary checkout's sibling named with `-wt`, derived from git's own identity and never from the current directory — which is why running this inside a linked worktree does not answer a container inside that worktree.

  $ majordomus worktree root

  What it asserts: exits 0; prints -wt.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus worktree path

Print the canonical path of a branch, and nothing else: `cd "$(majordomus worktree path feature/x)"`. Derived from the name; the branch need not exist

majordomus worktree path [OPTIONS] <BRANCH>

/docs/cli/worktree/path/ — this command on its own page

Examples

• The canonical path of a branch, for the shell

  A child process cannot change its parent shell's directory, so nothing here pretends to: this prints one path and the shell does the rest — `cd "$(majordomus worktree path feature/x)"`. The path is the branch name under the container, hierarchy kept; the branch need not exist yet.

  $ majordomus worktree path feature/providers/streaming

  What it asserts: exits 0; prints -wt/feature/providers/streaming.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus worktree inspect

One branch: its canonical path, whether it exists, what occupies the path, the worktree holding it, and what stands in the way

majordomus worktree inspect [OPTIONS] <BRANCH>

/docs/cli/worktree/inspect/ — this command on its own page

Examples

• One branch, before creating its worktree

  Where the branch's worktree belongs, whether the branch exists, whether anything occupies the path, and what would stand in the way. For a branch that does not exist yet, the answer is the path `worktree create` would use and the command to run.

  $ majordomus worktree inspect feature/new-dashboard

  What it asserts: exits 0; prints -wt/feature/new-dashboard, does not exist yet.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus worktree create

Create the canonical worktree of a branch. A branch that does not exist here is fetched from the trunk's remote and taken up when the remote has it; otherwise it is created from --base, else from the remote's trunk fetched now (the local trunk only when the remote cannot be read, and then said, with how far behind). The path is derived; none may be given

majordomus worktree create [OPTIONS] [BRANCH]

/docs/cli/worktree/create/ — this command on its own page

Examples

• Start work on a branch without deciding where it goes

  Creates the branch `feature/improve-cli` from the trunk and checks it out in a new worktree at `<repository>-wt/feature/improve-cli`. No path is given and none may be: the destination follows from the repository's identity and the branch name, so the same command in the same repository always produces the same path — from the primary checkout, and from inside another worktree.

  $ majordomus worktree create feature/improve-cli

  What it asserts: exits 0; prints -wt/feature/improve-cli, feature/improve-cli (new.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus worktree ensure

The canonical worktree of a branch: created when absent, answered when present, refused when the branch is checked out somewhere else

majordomus worktree ensure [OPTIONS] <BRANCH>

/docs/cli/worktree/ensure/ — this command on its own page

Examples

• The canonical worktree, whether or not it exists yet

  `ensure` is `create` for a caller that does not care whether the worktree is already there: it creates it when it is absent and answers the existing one when it is present. What a script or an agent runs before starting on a branch.

  $ majordomus worktree create feature/improve-cli
  $ majordomus worktree ensure feature/improve-cli

  What it asserts: exits 0; prints exists, -wt/feature/improve-cli.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus worktree migrate

Bring every misplaced worktree to its canonical path, dirty state included, with a fingerprint taken before and after each move; --plan shows the steps and changes nothing

majordomus worktree migrate [OPTIONS]

/docs/cli/worktree/migrate/ — this command on its own page

Examples

• What it would take to bring every worktree home

  `--plan` shows each misplaced worktree with where it belongs, how it would move, the uncommitted work that moves with it, and what blocks it, and changes nothing. Without `--plan` the movable steps are carried out: each worktree is fingerprinted, moved with `git worktree move`, fingerprinted again at its new path, and reported as moved only when the two are equal.

  $ majordomus worktree migrate --plan

  What it asserts: exits 0; prints nothing to migrate.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus worktree validate

Every error of the topology, and nothing else; exit 10 when there is one

majordomus worktree validate [OPTIONS]

/docs/cli/worktree/validate/ — this command on its own page

Examples

• Is the topology valid?

  Every error-level diagnostic and nothing else, then the verdict; exit 10 when there is an error. What a script gates on.

  $ majordomus worktree validate

  What it asserts: exits 0; prints worktree topology: valid.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus worktree doctor

Every diagnostic of the topology, errors, warnings and facts, each with its code and remedy; exit 10 when there is an error

majordomus worktree doctor [OPTIONS]

/docs/cli/worktree/doctor/ — this command on its own page

Examples

• Every diagnostic, with its code and its remedy

  Errors, warnings and facts — a misplaced worktree, a stale registration, a detached HEAD, the primary checkout off the trunk, an unknown trunk — each under a stable code the API and the Cockpit carry too, each with the command that addresses it.

  $ majordomus worktree doctor

  What it asserts: exits 0; prints worktree topology: valid.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus worktree guard

May a mutation proceed from here? Exit 0 in a canonical worktree, in the primary checkout on the trunk, or detached; exit 10 with the reason otherwise. What the pre-commit hook asks

majordomus worktree guard [OPTIONS]

/docs/cli/worktree/guard/ — this command on its own page

Examples

• May a commit proceed from here?

  The pre-commit hook's question. Exit 0 in a branch's canonical worktree, in the primary checkout on the trunk, or on a detached HEAD; exit 10 with the diagnostic and the remedy when a feature branch is being worked on somewhere it does not belong. The hook stays one line; this is the logic.

  $ majordomus worktree guard

  What it asserts: exits 0; prints worktree guard: ok.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus worktree repair

Drop git's registrations of worktrees whose directories are gone, and repair the administrative links of the ones that exist. Deletes no directory

majordomus worktree repair [OPTIONS]

/docs/cli/worktree/repair/ — this command on its own page

Examples

• What git would forget

  `repair` drops git's registrations of worktrees whose directories no longer exist and lets git repair the administrative links of the ones that do. It deletes no directory and touches no branch; `--dry-run` reports what it would drop and changes nothing.

  $ majordomus worktree repair --dry-run

  What it asserts: exits 0; prints nothing to prune.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus worktree remove

Remove one linked worktree by branch or path. Never the primary checkout, never a branch, never uncommitted work without --force

majordomus worktree remove [OPTIONS] <SELECTOR>

/docs/cli/worktree/remove/ — this command on its own page

Examples

• Remove a worktree, and keep its branch

  Removes the worktree and nothing else. The branch it held still exists: worktree lifecycle and branch lifecycle are separate, and deleting a branch is a git command a person types deliberately. A worktree with uncommitted work is refused rather than removed.

  $ majordomus worktree create feature/improve-cli
  $ majordomus worktree remove feature/improve-cli

  What it asserts: exits 0; prints removed, feature/improve-cli still exists.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus worktree cleanup

The branches merged into the trunk whose worktree is clean or absent: what could be removed. Removes nothing without --remove

majordomus worktree cleanup [OPTIONS]

/docs/cli/worktree/cleanup/ — this command on its own page

Examples

• What could go, and what it would take

  Every branch merged into the trunk whose worktree is clean or absent, with the two commands that would remove the worktree and then the branch. Derived state only: nothing is deleted here, and a dirty or unmerged worktree is never listed.

  $ majordomus worktree cleanup

  What it asserts: exits 0; prints cleanup-eligible.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus worktree uncommitted

Every linked worktree holding uncommitted work: how many paths, how old the oldest change, what holds it (an active task, an open episode, a process inside) and whether it is abandoned, with the command that would put it on a remote ref. Reads every worktree and writes none

majordomus worktree uncommitted [OPTIONS]

/docs/cli/worktree/uncommitted/ — this command on its own page

Examples

• Work no commit carries, and whether anything holds it

  Every linked worktree holding staged, unstaged, untracked or conflicted paths, with the count, the age of the oldest change, the task, episode or process that holds it, and `abandoned` when nothing does and it is older than the policy's session.stranded_after. A repository with no linked worktree has nothing to list; the reading writes nothing either way.

  $ majordomus worktree uncommitted

  What it asserts: exits 0; prints 0 with uncommitted work, nothing was changed.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus worktree trunk

How far this checkout and the local trunk are from the remote trunk, as of the last fetch, judged against the policy's checkout.trunk_distance: current, lagging, stale, unjudged or unmeasured, with the commands that bring it current. Fetches nothing; exit 10 when stale

majordomus worktree trunk [OPTIONS]

/docs/cli/worktree/trunk/ — this command on its own page

Examples

• How far this checkout is from the remote trunk

  The checkout's HEAD and the local trunk counted against the remote-tracking trunk, as of the last fetch, and judged against the policy's checkout.trunk_distance. A repository with no remote has nothing to be measured against and says so — `unmeasured`, never `current`; nothing is fetched either way.

  $ majordomus worktree trunk

  What it asserts: exits 0; prints unmeasured, no remote-tracking branch.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus worktree branches

Every local branch, one per line, for a shell completion that wants the live set

majordomus worktree branches [OPTIONS]

/docs/cli/worktree/branches/ — this command on its own page

Examples

• The live branch set, for completion

  Every local branch, one per line, nothing else. A shell completion for `worktree path`, `create` or `remove` reads this rather than a list kept anywhere, so a branch created a second ago completes.

  $ majordomus worktree branches

  What it asserts: exits 0.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus prs

Pull-request integration: every open pull request classified against the current master with its evidence, the ranked plan, and the executor that merges the next provably safe one — one at a time, re-planning after each (ADR 0101)

majordomus prs [OPTIONS] [COMMAND]

/docs/cli/prs/ — this command on its own page

Subcommands: status, plan, explain, refresh, drain, cleanup, repair, events, trains, brief, prove-dry-run.

Examples

• The queue, before the forge was ever observed

  `prs` with nothing after it is `prs status`. It reads the last recorded forge observation and never reaches the network, so in a checkout where `prs refresh` has never run it has nothing to rank: it says so, names the command that observes, and exits 10.

  $ majordomus prs

  What it asserts: exits 10.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus prs status

Every open pull request with its disposition, risk and reason, in rank order, from the last recorded observation; exit 10 when the observation is stale or absent

majordomus prs status [OPTIONS]

/docs/cli/prs/status/ — this command on its own page

Examples

• The ranked queue as one document

  Every open pull request's assessment in rank order — disposition, lane, reasons, the master and head it was decided against, evidence, risk, overlaps — with the next merge and the tallies. The same value `GET /api/v1/pull-requests` and the MCP tool `majordomus_pull_requests` answer. With no observation recorded it exits 10.

  $ majordomus prs status --format json

  What it asserts: exits 10.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus prs plan

What the executor would do next: the next merge, the pull requests that need master brought in, and the lanes; nothing is changed

majordomus prs plan [OPTIONS]

/docs/cli/prs/plan/ — this command on its own page

Examples

• What the executor would do next

  The next merge, the pull requests that need master brought in, and the repair, cleanup and held lanes. The plan is void after any merge: the executor observes again before its next step. With no observation recorded it exits 10.

  $ majordomus prs plan

  What it asserts: exits 10.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus prs explain

Why one pull request is where it is: the revisions it was decided against, every piece of evidence, its rank and the factors behind it

majordomus prs explain [OPTIONS] <NUMBER>

/docs/cli/prs/explain/ — this command on its own page

Examples

• Why one pull request is where it is

  The revisions it was decided against, every piece of evidence, its rank and the factors behind it. The same answer `GET /api/v1/pull-requests/explain?number=` gives. With no observation recorded it exits 10.

  $ majordomus prs explain 1

  What it asserts: exits 10.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus prs refresh

Observe the forge now (the GitHub CLI and one `git fetch`) and record the observation; the only read that reaches the network

majordomus prs refresh [OPTIONS]

/docs/cli/prs/refresh/ — this command on its own page

Examples

• Observing the forge, where there is none

  `refresh` is one of the three `prs` commands that reach the network: it asks the GitHub CLI about the repository, its branch protection and its open pull requests, and fetches their heads. A repository with no GitHub remote cannot be observed, and the answer is exit 12 — unusable, never an empty queue.

  $ majordomus prs refresh

  What it asserts: exits 12.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus prs drain

Merge the next ready pull request, verify it landed, observe again, and repeat — at most `--max` merges; `--dry-run` decides without acting

majordomus prs drain [OPTIONS]

/docs/cli/prs/drain/ — this command on its own page

Examples

• A dry run starts from a fresh observation

  Even a dry run observes the forge first — a decision is never taken from the recorded observation — so where the forge cannot be reached it stops with exit 12 before deciding anything, and nothing is merged, refreshed or recorded.

  $ majordomus prs drain --dry-run

  What it asserts: exits 12.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus prs cleanup

Close the pull requests whose work is provably on master already; without `--apply` it only lists them

majordomus prs cleanup [OPTIONS]

/docs/cli/prs/cleanup/ — this command on its own page

Examples

• Cleanup lists before it closes, and observes before it lists

  Without `--apply` cleanup only lists the pull requests whose work is provably on master; either way it observes the forge first, so where there is none it exits 12.

  $ majordomus prs cleanup

  What it asserts: exits 12.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus prs repair

Bring master into one named pull request whose only conflict with it is over derived (`merge=derived`) files. Eligible only when the classification says it is behind master and its merge conflicts on no authored path; an authored conflict is refused, naming the files. A dry run by default, decided offline on the last recorded observation, like `status`. With `--apply` it takes the integration lease, observes the forge again, records the act on the trail first, and merges master in a scratch worktree, derives, commits and pushes a fast-forward leased on the observed head; it never merges into master. Exit 10 on a refusal or an absent observation, 12 when it could not act

majordomus prs repair [OPTIONS] <TARGET>

/docs/cli/prs/repair/ — this command on its own page

Examples

• A repair is decided on the recorded observation, or not at all

  The dry run, which is the default, is a read: it decides whether the named pull request may have master brought in from the queue the last recorded observation built, as `prs status` does, and reaches no network. Where nothing was ever observed there is no classification to decide from, so it exits 10 and names `prs refresh`; nothing is merged, pushed or recorded.

  $ majordomus prs repair 1

  What it asserts: exits 10.

  Tested by apps/majordomus-cli/tests/cli_examples.rs, which runs the command against the built executable and asserts what the page states.

majordomus prs events

The audit trail: every selection, merge, refusal, stale decision and closure this checkout's executor recorded

majordomus prs events [OPTIONS]

/docs/cli/prs/events/ — this command on its own page