Documentation
Every document in the repository, rendered from the same Markdown GitHub shows.
-
docs/DESIGN.md
Prismatic Majordomus
the v0.1 specification: problem, thesis, models, boundaries, what is intentionally absent
-
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, 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/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/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/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/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 two statements of the version and the one command that writes them; 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: what `doctor` reports in a repository that is not this one, why 109 of its findings cannot be satisfied there, and the decision that needs making
-
docs/ECONOMICS.md
Economics
the claim it refuses to make, what v0.1 controls without measuring, where the cost actually is, what the ledger alone can measure, and what honest measurement would take
-
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/generated/openapi.json
HTTP API
The read-only projection of a repository's AI layer: every rule, prompt, session and project record under .ai/, and the capabilities that read 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/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/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/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/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/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/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/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/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.