One repository.Many interfaces.

Majordomus discovers a repository once, reads it into typed models, and derives its interfaces from them: the HTTP API and its OpenAPI description, Swagger UI, MCP, the Cockpit's generic pages and this site. The command line is declared a second time, in clap, and checked against the registry.

“Discover and model a fact once, and derive every interface from it.”

docs/SURFACES.md · the invariant

Repository

The tracked tree is the source of truth

prismatic-majordomus/

.ai/the layer: policy, rules, ADRs, skills
apps/the Rust executable and its capabilities
bin/the entry points
lib/the shell tool
share/kinds, schemas, the design
docs/manuals and generated documents
test/the cases
site/this website and the data derived for it
justfilethe workflows

RepositoryEnvironment

one typed value, built by one resolver

projectthe crate manifest
repository.ai/manifest.yaml
vcsone git status
toolchainsthe manifests that declare them
layerthe index, counted per kind
workflowsjust --dump
providersthe policy's projections
servicesroute constants and the lease

- Command linemajordomus env Local workthe snapshot in a terminal
- HTTP API/api/v1/environment Programmatic accessJSON, described by OpenAPI
- Swagger UI/swagger
  Try the APIa page over /openapi.json
- MCPmajordomus mcp Tools for agentsthe tool majordomus_environment
- Cockpit/cockpit Visual overviewrendered by the executable
- Shell entry.envrc Entering the directorythe banner, drawn on every cd
- DocumentationGitHub Pages This sitegenerated from the repository

Key principles

One declarationMCP, HTTP and OpenAPI are built from it; the CLI is checked against it
Discoveredenumerated through sources.yaml, never registered by hand

Typedan object that does not validate is a diagnostic
Deterministicthe OpenAPI document: maps sorted, no timestamp

Provenanceevery field names where it came from
Checkeda hand edit of a derived file is refused or reported

Discovery

Enumeration governed by a declaration

The rootthe executable finds the repository
The manifest.ai/manifest.yaml names the layer
Kinds and schemasshare/kinds.yaml and share/schemas/
Sourcessources.yaml classes, read from the git index
Diagnosticsa file that does not validate is excluded and named

Canonical model

Typed, with provenance

environment/mod.rs

RepositoryEnvironment {
  schema, generated_at,
  resolution,
  project, repository,
  vcs,
  toolchains: [ .. ],
  layer, workflows,
  providers: [ .. ],
  services: [ .. ],
  reasoning?,
  diagnostics: [ .. ],
  provenance: [ .. ],
}

Resolved in full or fast; both produce the same type, and a value nothing resolved is absent, never zero.

Derived interfaces

Same registry, every surface

Surface	Where
CLI	majordomus
HTTP	/api/v1/
OpenAPI	/openapi.json
Swagger	/swagger
MCP	majordomus mcp
Cockpit	/cockpit
Docs	GitHub Pages

197 operations in 58 modules, described by one OpenAPI document.

Feedback loop

Detect, regenerate, check

The tree moves
Index rebuilt
majordomus generate
derive-check

the model