Documentation
Every document in the repository, rendered from the same Markdown GitHub shows.
Reference
Generated from the repository: the interfaces from the capability registry, the objects from the index of the .ai/ layer. Each count below is read from the registry at build time.
- 3550
Capabilities
Every operation, with its source, tests and the surfaces it reaches.
- 120
Command-line operations
The command reference, generated from the executable's argument parser.
- 212
HTTP routes
The HTTP API reference, one page per tag, rendered from the OpenAPI document.
- 206 · 3387
MCP tools · resources
What an MCP client can call and read.
- 94
Modules
The capability modules of the executable.
- JSON
Machine-readable
/openapi.jsonfor the API, and/docs/index.jsonfor every page and kind listed here.
Every kind of object the layer holds
From site/data/publication.toml, which declares for every kind where it is published or why it is not, joined to the index.
| kind | objects | published |
|---|---|---|
| adr | 166 | Decisions — a page per object |
| application | 5 | /applications/ |
| area | 9 | /why/ |
| audience | 8 | /why/ |
| claim | 250 | /guarantees/ |
| command | 31 | /commands/ |
| context | 39 | /context/ |
| critique | 37 | A critique is the adversarial pass over one intent's plan, written by a worker, and work started under the intent without it or with a blocking finding open fails intent validation (ADR 0073). It is planning state of this repository; what the plan became is published on /plan/. |
| deployment | 1 | A deployment object carries the target a release is published to. Its rendered artifacts are in the repository and its state is on the Cockpit; a public page would say only what /docs/install/ already says. |
| derive-offload | 1 | The derive-offload declaration names the machines of this repository's owner that a branch's derive may run on, and the limits each must meet; `majordomus offload` reads it. It is an operating record of one cluster, and a public page would publish the owner's host addresses without telling a reader anything about Majordomus. |
| distribution-model | 1 | The distribution model is the input the release matrix, the installer and /docs/install/ are all generated from. The generated pages are the publication; the model behind them is not a second one. |
| document | 353 | A document of the layer is prose already published where it belongs — /docs/, /method/, /context/ — and a second address for the same words is the duplication this file exists to prevent. |
| domain | 6 | /domains/ |
| feature | 29 | /features/ |
| gap | 5 | A gap is what one worker observed of the repository against an intent's criteria at one commit (ADR 0073). It is a dated input to planning, superseded by the next observation, and the work it suggested is published on /plan/. |
| implementation | 52 | An implementation object is a source file a claim names. It is reachable from the claim that names it and from the repository; a page rendering a Rust module is the source browser GitHub already is. |
| intent | 43 | An intent's stage and criteria are derived on every read from the plan and the evidence ledger (ADR 0070); a static page would freeze a derivation at the commit the site was built from. The milestones that realise an intent are published on /plan/, and `majordomus intent show` and the Cockpit's /cockpit/intents answer for the intent itself. |
| issue | 1034 | /plan/ |
| knowledge | 58 | Curated knowledge is written for the worker reading the layer, not for a visitor: it is the orientation a session starts from, and it changes with the work rather than with the product. |
| mesh-declaration | 1 | The mesh declaration is one checkout's identity on the local network. It is operational state of an installation, not a fact about the product. |
| milestone | 111 | /plan/ |
| moment | 38 | /why/ |
| policy | 1 | /policy/ |
| profile | 4 | /profiles/ |
| prompt | 5 | A prompt is an input to a provider, rendered with the repository's own state. Published on its own it would read as documentation of something a visitor cannot run. |
| release-record | 37 | /changelog/ |
| rule | 191 | Rules — a page per object |
| scope | 1 | The scope declares which paths of this checkout the tool reads. It is a fact about this repository's layout, and /context/ is where a visitor is told about layout. |
| session | 91 | /sessions/ |
| skill | 8 | /skills/ |
| taxonomy | 10 | /why/ |
| test | 654 | A test object is a case file. What it proves is published — on /guarantees/ for the claim and on the rule's own page for the rule — and that is the direction a reader asks in. |
| use-case | 49 | /use-cases/ |
| workspace | 1 | A workspace records an external place work is done (a ChatGPT project, an issue tracker). It names accounts and surfaces of the people working here, not of the product. |
-
docs/DESIGN.md
Prismatic Majordomus
the founding specification: problem, thesis, models, boundaries, what is intentionally absent
-
docs/HOW_IT_WORKS.md
How Majordomus works
how the tool works as one repository model with many projections: authored, discovered, derived, observed and inferred state; the capability declaration and every surface derived from it, including where the command line and the Cockpit are still written by hand; the rule proof ladder from declared to evidenced; sessions, context, handover, planning, the peer board and the mesh; publication and versions; the surface, governance and mesh maps; how routes, navigation and order are kept true; the architecture debt, measured; and an answer key to the questions a technical reader should be able to answer
-
docs/GUIDE.md
Guide
what a team gets from the tool and why, then every part of it in turn: how it works, the commands to see it, the test cases that prove it and how finished it is; the first ten minutes; running the proof yourself and keeping the run as evidence; and what it does not do yet
-
docs/TWO_FOLDER_CONSOLIDATION.md
Two-folder consolidation
what the repository writes into a tree today, verified against the code and the running binary, and the ordered slices that reduce it to `.ai/**` and `.majordomus/**` with reversible bridges
-
docs/CLI.md
CLI specification
every command: behaviour, reads, writes, exit-code contract, target output
-
docs/SCHEMAS.md
File schemas
every file: schema, a concrete example, which command reads and writes it
-
docs/CONCEPTS.md
Concepts
the vocabulary, and the two outcomes people confuse
-
docs/CONTEXT.md
Scoped context
scoped context: what a context document is, how the effective context for a path is composed and ordered, what wins in a conflict, how a change is traced to the documents it affects, and the sync check
-
docs/DOCTRINE.md
Doctrine
what rules are enforced, what enforces each one, how the wiring is verified, the three enforcement modes and why a declared review exemption carries its reason, the proof graph and the ten states a rule's proof can be in, and what was deliberately left out
-
docs/CONTINUITY.md
Continuity
how work survives the session doing it: the durable records, why transcripts are not state, how context is selected and records resolved
-
docs/KNOWLEDGE.md
Knowledge
what a knowledge record is, how candidates are derived at every episode boundary from the ledger and git without a model, the promotion act, every command with its reads and writes, the rules that enforce it, and what the next worker is told
-
docs/PLANNING.md
Planning
milestones as executable outcome specifications, issues as execution contracts, the dependency graph, derived status, execution waves, evidence, and the projections
-
docs/PERFORMANCE.md
Performance truth
where a command's time goes (`MJ_TIMING=1`), what was slow and the shape of every fix, `majordomus bench` and its cold and warm distributions, local runs against the tracked baseline, the regression check and the budgets, and how to work on performance
-
docs/ROADMAP.md
The roadmap
the graph between milestones: identity against version, the gate that makes a dependency real before the next step starts, derived ordering, claim linkage, and how a milestone is added
-
docs/DOGFOODING.md
Dogfooding
the one rule: Majordomus cannot recommend a development discipline it does not use itself — and what following it costs
-
docs/LAUNCH.md
Launch kit
what to paste when somebody asks what Majordomus is: the link to send, the install command, one-sentence and longer descriptions, three proof points with the page behind each, and what not to claim
-
docs/ARCHIVE.md
Archiving the repository
snapshots of the tracked tree that can leave the machine: what travels and what cannot, why the generated projections are dropped by reading `.gitattributes` rather than a second list, how the file modes and a git index survive to the far end, the profiles, and how to add one
-
docs/INSTALL.md
Installing Majordomus
installing the tool: the one-line installer, pinning a version, choosing where it goes, the supported platforms, upgrading, uninstalling, CI use, the security model and troubleshooting
-
docs/BUILD_CACHE.md
The build cache, as a person sees it
what a person sees of the mesh build cache: how a Rust build starts sccache with the store as its second level, the one line a local-only build leaves, and the gate that refuses a build around the cache
-
docs/DISTRIBUTION.md
Distribution
how the tool is packaged, published and installed: the one canonical model, what derives from it, the trust path, adding a platform, releasing, and recovering from a bad release
-
docs/COMMIT.md
The commit
the commit as a value: the one grammar the changelog and the judge share, the policy declared as data with its subject width measured from this history, the scope vocabulary learned from the log rather than kept in a table, the plan fingerprinted against repository, worktree, HEAD and change set, and where each of the three moments enforces it
-
docs/RELEASE.md
The release
the release: the changelog composed from the layer's release records, the decisions dated inside each release's window and the conventional commits in its range; the version authored in one place, its projection for the shell tool, and the one command that writes it; the bump the commits imply and the evidence for it; and every surface derived from both
-
docs/CATALOGUE.md
The catalogue
the use-case and application registries: what they are for, how they differ from the why pages, the schema, and how to extend them
-
docs/ADOPTION.md
Adoption
day one, week one, several workers, removal
-
docs/ADOPTION_FIRST_RUN.md
First run in a foreign repository
forensic finding, closed: what `doctor` reported in a repository that is not this one, why the findings tracked the tool's own distribution rather than the adopting repository, and the release stamp that now scopes them
-
docs/HANDBOOK.md
The handbook
the handbook: one interactive page per language, built from this tree; what is written and what is derived, and the gate that refuses a change which removes what a chapter rests on
-
docs/PERSONAL_MODE.md
Personal mode: Majordomus as one person's instrument
personal mode, the tool as one person's instrument with nothing left in git: who it is for, why it is ordinary practice, the measured way from personal to shared, the per-clone exclude file, a private policy with one projection and one enforcement, filesystem discovery for the server, how each part of the tool fits, and what was and was not measured
-
docs/ENTRY.md
Entering the repository
entering the repository: what converges on its own and what is asked for, the three commands of the shared server, what each standing means, what is deliberately not automatic and why, and what to run when it does not come up
-
docs/ENTRY_AUDIT.md
Repository entry: what is automatic, what is decorative, and where it breaks
forensic finding, 2026-09-10: what converges on its own when a person or an agent enters this repository — executable, shared server, episode, peer, continuation — and what does not; the root causes ranked, the matrix, the dependency graph, and the plan by stage
-
docs/ECONOMICS.md
Economics
the question, what is measured and how each number is labelled, control and treatment, how runs become a statement, and what is not measured
-
docs/EXTRACTION_REPORT.md
Extraction Report
how the design was derived: root cause, pattern ledger, rejected patterns, risks, plan
-
docs/COMMANDS.md
The command graph
the command graph: the three declarations it composes, stable identities, the effect model and the exposure policy derived from it, the generated workflow bridge and its compatibility aliases, the one completion engine every surface asks, repository entry, and what adding a command costs (nothing)
-
docs/DYNAMICITY.md
Canonical ownership and derivation
canonical ownership: what may be written down twice, what must be derived, and which entities still have no owner
-
docs/COCKPIT_IDE_AUDIT.md
The Cockpit as a development surface: baseline, archaeology and gap matrix
forensic finding, 2026-09-10: what the Cockpit would need in order to become a development surface — the governance preflight and its two defects, the two-program split, the system run end to end with every command and response recorded, the gap matrix, the drift audit, and the phased plan with the failures that must be fixed first
-
docs/DEVELOPMENT_RUNTIME.md
The development runtime
the development runtime: which program owns the semantics of the plan, tasks, sessions, context, executions, peers, evidence and completion, the measured inventory of every one of them, the storage each is decided to keep, the two event tiers, the derivation chain anything exposed must follow, what each surface may and may not decide, and the ranked gaps between that boundary and the code
-
docs/generated/openapi.json
HTTP API
The projection of a repository's AI layer: every rule, prompt, session and project record under .ai/, the capabilities that read them and the declared commands that change them, served over MCP, HTTP and the command line from one registry.
-
docs/CAPABILITIES.md
Capabilities
the Rust executable's capability model: one definition, and MCP, HTTP, OpenAPI, Swagger UI, the command line and the generated reference derived from it; what is canonical, how to extend it, how it fails
-
docs/SURFACES.md
How Majordomus derives its surfaces
how the system fits together: canonical state, discovery, typed registries, derived models, governance and evidence, and every surface projected from them — what is authored, discovered, derived, observed and inferred, a capability and a rule traced end to end, the generation matrix, a claim audit with file references, and the architecture debt that remains
-
docs/USE_CASES.md
Executable use cases
executable use cases: one file each under `.ai/repo/use-cases/`, the scenario that proves it against the tool, evidence, observed maturity, coverage gated by policy, impact analysis, scaffolding, and what the site derives from it
-
docs/PRODUCT.md
Product
the product features as objects of the layer: what a feature file may hold, what every surface derives from it, the public projection boundary and its allow-list, what the homepage and the `/features/` pages render, and what is refused
-
docs/WHY.md
Why
the operational failure modes this tool answers, as objects of the layer: the three kinds, the flow from one Markdown file to every projection, what is authored and what is derived, and what enforces each
-
docs/SCOPE.md
The repository scope
the repository scope: what a worker reads and what it never reads, declared once in `.ai/repo/scope.yaml`, how a path is judged (name, size, content), what the executable does with it, and `majordomus scope`
-
docs/EXECUTIONS.md
Executions
the execution plane: running a capability as work that can be watched — the model, the lifecycle, the typed event protocol, the live channel and its guarantees, what each interface offers, the limits and what happens at each, and what it deliberately does not do
-
docs/COCKPIT.md
The Cockpit
the Cockpit: the registry rendered as pages for a person, what makes it a projection rather than a dashboard, the graph and health models, the browser layer and what happens without it, the security decisions, the asset pipeline
-
docs/MAJORDOMUS_UI.md
`majordomus ui`
`majordomus ui`, the primary surface: how it differs from the Cockpit, where every value on it comes from and how a missing one reads, how the first screen stays fast with slow panels on routes of their own, the page without JavaScript, the assets and gates that hold it, and how a screen is added
-
docs/WEB.md
The web surface
the web surface: every surface discovered from its producer rather than registered, the two reserved namespaces (`/docs` is documentation, `/swagger` is Swagger UI), what a surface declares, how to add one, how the documentation is built for its mount and served safely, and what is enforced where
-
docs/EDITORS.md
Editors and agents
what Zed and Google Antigravity read from the repository: the skills and tasks projected by `majordomus generate editors`, ownership and conflict refusal, what is left to the person (MCP, settings, permissions) and why
-
docs/ENVIRONMENT.md
The repository environment
the repository environment: one typed snapshot of what a checkout is — project, layer, version control, toolchains, workflows, provider projections, local services — with a provenance entry for every value; the full and the fast resolution, the cache under `.ai/local/`, and the direnv adapter that renders it without reading the repository itself
-
docs/PREFLIGHT.md
The preflight
the preflight: what is proven about a checkout rather than what it is — a verdict per claim (git, episode, briefing, task, handover, policy, rules, ADRs, server and surfaces, peers, test runs, enforcement, projections, generated docs, deployment) with the evidence behind it; the nine verdicts, what entry reads and never reads, the measured cost, and what to run for each verdict
-
docs/BACKLOG.md
Backlog
the four quantities that grow on their own — open pull requests, worktrees, branches, running servers; why GitHub can never merge a pull request of this repository and what lands one instead; the commands that measure and reduce each
-
docs/INTEGRATION.md
Pull-request integration
pull-request integration: every open pull request classified against the current master with its evidence, the fourteen dispositions, the deterministic rank, one merge at a time with a re-plan after each, refreshing a branch, the cleanup threshold, the lease and the audit trail (ADR 0101)
-
docs/INTEGRATION_ROLLOUT.md
Integration rollout record
the record of each integration rollout stage of ADR 0101 §13: what was run against the real repository, with which released executable and under which rule and ADR versions, what it answered, and that nothing moved
-
docs/WORKTREES.md
Worktrees
the branch-to-worktree topology: `<repo>-wt/<branch>` derived from git identity and never registered, the standings and diagnostic codes, the commands, the lifecycle, the layered enforcement, the fingerprint-verified migration, failure modes and recovery
-
docs/OFFLOAD.md
The derive offload
the derive offload: a branch's derive run on a declared cluster machine in its turn — the commands and exit codes, the `derive-offload` declaration, host choice by free space and queue length, the FIFO queue with dead-waiter removal, the bundle round trip with its refusals and a build directory of each derive's own, and the board and mesh etiquette
-
docs/MCP.md
MCP surface
the read-only MCP surface of the Rust executable: what it serves, what decides that, how it fails, what it refuses to serve
-
docs/BRIEF.md
The session brief
the session brief: `majordomus brief` and `brief.session` — one line and a few about what surrounds a session (its episode and task, the peers of every board, the mesh, the integration queue, the derive lock), who composes it, the policy switch, and the Claude Code mod that keeps a session briefed and awake
-
docs/MESH.md
Majordomus Mesh
the mesh: how running Majordomus instances discover each other — Ed25519 node identity, one signed bounded envelope over multicast, broadcast and rendezvous, one registry, deny-unknown trust, the off-by-default declaration, the threat model, and how to operate and extend it
-
docs/MONITOR.md
The monitor
the monitor: everything that happens around a repository in one stream — mesh sessions, claims, handovers and reviews, the executor's outcomes, GitHub's pull requests and runs — with the noise folded away, what names you first, one cursor across every source, and the command, MCP, HTTP and Cockpit surfaces
-
docs/BLACKBOARD.md
The peer blackboard
the peer blackboard: who works on what across every checkout's board and every linked machine, one projection of the board, the mesh journal and the monitor — workers keyed by explicit identifiers, the claims that meet, the reviews and handovers that wait, and what could not be read
-
docs/MODELS.md
The model catalogue
the model catalogue: vendors and models declared once in share/models.yaml with provenance and no fabricated facts, and the explainable routing that names why every candidate was chosen or excluded
-
docs/REASONING.md
Reasoning
provider-independent reasoning: material uncertainty assessed with evidence, optional advisors discovered by capability and consulted through one transport contract, disagreement settled by experiment rather than count, conclusions and review recorded, and the state carried across sessions, with no advisor required
-
docs/COVERAGE.md
Coverage: one measurement, two questions
test coverage of the Rust executable: one measurement (scripts/rust-coverage), the crate floor and the session/continuity domain, and the changed-code differential gate of #214 that refuses new debt while leaving untouched legacy debt alone
-
docs/DESIGN_SYSTEM.md
The design system
the design system: the one declaration every surface is rendered from, the pipeline from `share/design/tokens.yaml` to the site, the Cockpit and the executable's own pages, how to add a role, a status word or a type step without touching a consumer, how drift is caught, and how to read a page that looks wrong
-
docs/DIAGRAMS.md
Diagrams and charts
diagrams and charts on the site: one viewer for every Mermaid diagram (zoom, pan, full screen, download, tracing), the addresses `#diagram-<name>` and `#diagram-<name>:<node>`, node links inferred at build from the identities the generated data carries, and charts drawn from the tables a page already renders
-
docs/UI.md
UI conformance
UI conformance: the page set and the width set discovered rather than listed, the responsive, semantic, component and WCAG invariants a browser checks over every page, what the build normalises in markup it did not write, and where the report is
-
docs/GITHUB_PAGES_ARCHITECTURE.md
GitHub Pages architecture
how the website is derived from the repository and checked for drift
-
docs/QUALITY.md
Public API quality
what the Rust crate's exported surface is held to: documentation that says more than the signature, an executable example on everything that carries behaviour, a module boundary something exercises, and every command of the command line accounted for against the capability registry — the codes, the ratchet, and the golden path for adding a command
-
docs/RUSTDOC.md
The crate's reference
the crate's rustdoc reference at `/rustdoc`: produced by the invocation its gate proves, declared as a web surface from the crate, served by `majordomus serve`, checked item by item against the crate's own inventory, composed into the site from the topology, deployed with it and verified at the public URL; local use, the gates and cases, and what to run when a page, a link, an asset or the source revision is wrong
-
docs/EVIDENCE.md
Evidence
a claim's proof as a recorded execution rather than a test path that resolves: the test identity derived from the matrix, the seven proof states and how each is derived, why `proven` and `inputs unchanged` are never one state, the ledger's shape and its retention decision, recording a run, the four capabilities with their projections, both directions of the join, the gate and its ratchet, and the limits
-
docs/DELIVERY.md
Delivery
whether a product feature exists, computed rather than recorded: the six dimensions of the delivery invariant, the three verdicts and why unknown is never pass, delivery and the development stage as two types, how each dimension is derived from git and the public identity, the reuse of `scripts/pages`, and what phase 1 leaves unknown
-
docs/CI.md
Continuous integration
how a change is validated: the validation workflow over repository-owned gates, the planner and its model of what can affect what, the gates and how to run each locally, the caches and artifacts, the executable as a build output, the parallel suite and probe, the platform policy, and where the measurements live
-
docs/SHELL.md
Shell automation
shell automation under migration: the inventory of every unit and its disposition, the `shell check` that refuses a shell unit no exemption declares and an exemption whose unit is gone, the exemption format, and how a unit is migrated out of the list
-
docs/GITHUB_PAGES_PERFORMANCE.md
GitHub Pages performance
how a push becomes public: the publication path separated from the gates that decide merging, controlled against external latency, the derived trigger, the input fingerprint that replaces a generation, the caches and what each is worth, the budgets and where they live, how publication itself is measured, and the bottlenecks that remain
-
docs/PAGES_STATUS.md
GitHub Pages performance status
the current numbers behind that document: the controlled budgets, the paths that start a publication, and the last measured build-and-check path per platform. Generated from `.ai/repo/ci/pages.yaml` and `.ai/repo/benchmarks/pages/`; never edited
-
docs/SITE_REVIEW.md
Site review
route audit, ownership of site facts, validation performed
-
AGENTS.md
Repository contract
The operating contract for this repository, itself generated by majordomus update.
-
docs/generated/web.json
Web surface
Every surface this repository exposes over HTTP, and the names that are reserved.