HTTP API: product

What this repository's product does for a person, as the features under the layer's features section declare it: each feature made of modules, commands, kinds, rules, documents, decisions, claims, use cases, Cockpit areas and web surfaces it names, with the interfaces it is exposed through, every count, the moments it answers and what is guaranteed derived from those references. The matrix of features against interfaces, the providers the tool has an adapter for, and the model's own validation. The homepage is a reader of this module and holds no inventory of its own.

Rendered from docs/generated/openapi.json, which the executable generates from its capability registry and CI refuses stale. The raw document is at /openapi.json; a running server serves the same document at its own /openapi.json and Swagger UI at /swagger.

product

GET /api/v1/product/domains product.domains

The domains

The few things the product controls, each declared once under the layer's features section with its promise and the failure it answers, and each holding the stable features that name it: their interfaces, the distinct claims, use cases, rules and capabilities behind them, and the operational moments they answer, all derived. A domain lists no features; a feature names its domain. The default is the stable set; pass status=any for every domain.

query
behaviorally_verified
benchmark required
cache process (max_entries=4)
MCP tool majordomus_product_domains
MCP resource {"name": "product-domains", "uri": "majordomus://product/domains"}
$ product domains

Query parameters

name	type	required	description	examples
status	string	no	Only domains of this status. Absent means the stable ones; pass `any` for every domain the model holds.	any: "any"

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/product/domains?status=any"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	DomainList	The domains: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

GET /api/v1/product/feature product.feature

One feature

One product feature in full: the record as its file declares it, and everything derived from what it names — the capabilities of its modules with their tools, routes and command-line paths, the commands with their summaries, the objects of its kinds counted, the rules with their class and whether the tool enforces them, the documents, the decisions, the claims with their status, the use cases, the Cockpit areas and web surfaces with their routes, the moments it answers, and the interfaces all of that adds up to.

query
behaviorally_verified
benchmark required
cache process (max_entries=64)
MCP tool majordomus_feature
$ product show

Query parameters

name	type	required	description	examples
id	string	yes	The feature's id, as `product.features` gives it. This is also its slug and its route.	first-feature: "benchmarks"

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/product/feature?id=benchmarks"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	ResolvedRefs	One feature: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

GET /api/v1/product/features product.features

The features

Every product feature this repository declares, narrowed by any of the facets the model derives — featured, area, domain, module, command, surface, text — with the interfaces each is exposed through, the counts behind it and what is guaranteed about it, none of which its file states. The default is the stable set; pass status=any for the drafts too.

query
behaviorally_verified
benchmark required
cache process (max_entries=32)
MCP tool majordomus_features
MCP resource {"name": "product", "uri": "majordomus://product"}
$ product list

Query parameters

name	type	required	description	examples
featured	boolean	no	Only the features the homepage shows.	featured: true
status	string	no	Only features of this status. Absent means the stable ones; pass `any` for everything the model holds.
area	string	no	Only features serving this operational area.	by-area: "context"
domain	string	no	Only features filed under this product domain.	by-domain: "completion"
module	string	no	Only features made of this capability module.
command	string	no	Only features made of this shell command.
surface	string	no	Only features exposed through this surface: `cli`, `api`, `mcp`, `cockpit`, `docs`.
q	string	no	Case-insensitive text, matched against the identity, the titles, the headline, the summary, the tags and the body.

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/product/features?featured=true&area=context&domain=completion"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	FeatureList	The features: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

GET /api/v1/product/matrix product.matrix

Features against interfaces

Every feature against the command line, the HTTP API, MCP, the Cockpit and the documentation, each mark derived from what the feature names; then every builtin module of the executable, every public command of the shell tool and every kind of the layer with the stable features that name it. A row with no feature is reported as a gap rather than hidden.

query
behaviorally_verified
benchmark required
cache process (max_entries=2)
MCP tool majordomus_product_matrix
MCP resource {"name": "product-matrix", "uri": "majordomus://product/matrix"}
$ product matrix

No parameters.

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/product/matrix"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	Matrix	Features against interfaces: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

GET /api/v1/product/providers product.providers

The providers

Every provider the tool has an adapter for — one per template the distribution ships — with the bootstraps this repository's policy renders through it, the client configuration it carries for the shared MCP server, and the hooks the policy wires. The set is the templates; nothing here is a list of vendors.

query
behaviorally_verified
benchmark required
cache process (max_entries=2)
MCP tool majordomus_providers
MCP resource {"name": "providers", "uri": "majordomus://product/providers"}
$ product providers

No parameters.

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/product/providers"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	ProviderList	The providers: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

GET /api/v1/product/validate product.validate

Validate the model

Every finding over the product model: a reference that resolves to nothing, with the nearest candidate; a duplicate identity; a file name that disagrees with its id; a draft that is featured; a stable feature under its floors; and every module, command or kind that no stable feature names. Errors make the model invalid; warnings do not.

query
behaviorally_verified
benchmark required
cache process (max_entries=2)
MCP tool majordomus_product_validate
$ product validate

No parameters.

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/product/validate"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	ProductValidationReport	Validate the model: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

Schemas

The components only this tag's operations use. Each row is the type's own field, its doc comment the description; a type another page owns links there.

AdrRef

object

One architecture decision the feature names.

property	type	required	description
id	string	yes	The declared id.
title	string	yes	The title.
status	string	yes	`proposed`, `accepted`, `superseded` or `rejected`.
path	string	yes	Repository-relative path.

Used by ResolvedRefs

CapabilityRef

object

One capability of a module the feature names, with the projections the registry declares for it.

property	type	required	description
id	string	yes	The canonical id.
title	string	yes	The title.
kind	string	yes	`query`, `command` or `resource`.
stability	string	yes	Where it stands.
tool	string \| null	no	The MCP tool name, when exposed as one.
resource	string \| null	no	The MCP resource URI, when exposed as one.
route	string \| null	no	`METHOD /path`, when exposed over HTTP.
cli	string \| null	no	The words after `majordomus`, when exposed on the command line.

Used by ModuleRef

ClaimRef

object

One claim the feature names, with the status the matrix gives it.

property	type	required	description
id	string	yes	The claim id.
claim	string	yes	The sentence.
status	string	yes	`guaranteed`, `advisory`, `planned` or `rejected`.
test	string \| null	no	The test that settles it, as `docs/CLAIMS.yaml` records it — the one field that makes a claim checkable rather than stated. Absent where the claim declares none, and where it declares `-`: a planned or rejected claim has nothing to run yet, and rendering a dash as a test would be a projection inventing evidence.

Used by ResolvedDomain ResolvedRefs

CockpitAreaRef

object

One area of the Cockpit the feature names.

property	type	required	description
id	string	yes	The area id.
title	string	yes	The label the Cockpit shows.
route	string	yes	The route under the running server.

Used by ResolvedRefs

CommandRef

object

One public command of the shell tool the feature names, as share/commands.yaml declares it.

property	type	required	description
id	string	yes	The command.
summary	string	yes	One line.
stage	string \| null	no	The lifecycle stage it belongs to.
read_only	boolean	yes	Whether it writes nothing.

Used by ResolvedRefs

DocRef

object

One document the feature names.

property	type	required	description
path	string	yes	Repository-relative path.
title	string \| null	no	The title, when the document has one.

Used by ResolvedRefs

DomainCounts

object

How much stands behind a domain: sums and distinct counts over its stable features.

use majordomus_cli::product::DomainCounts;
let empty = DomainCounts::default();
assert_eq!(empty.features, 0);
let v = serde_json::to_value(&empty).unwrap();
for key in ["features", "claims", "tested", "use_cases", "rules", "enforced_rules", "capabilities", "moments"] {
    assert_eq!(v[key], 0, "{key} is published, and zero for a domain nothing names");
}

property	type	required	description
features	integer (uint)	yes	Stable features filed under it.
claims	integer (uint)	yes	Distinct claims its features name.
tested	integer (uint)	yes	Distinct claims that are guaranteed and name the test that settles them: what the claims declare, not whether a recorded run supports them (that verdict is the evidence ledger's).
use_cases	integer (uint)	yes	Distinct use cases its features name.
rules	integer (uint)	yes	Distinct rules its features name.
enforced_rules	integer (uint)	yes	Distinct rules among them the tool enforces.
capabilities	integer (uint)	yes	Distinct capabilities behind its features.
moments	integer (uint)	yes	Distinct operational moments its features answer.

Used by ResolvedDomain

DomainList

object

Every domain of the product, each with what its features add up to.

property	type	required	description
schema	string	yes	`SCHEMA`.
fingerprint	string	yes	The hash of the model's sources and derived facts.
count	integer (uint)	yes	How many domains are listed.
domains	array of ResolvedDomain → ResolvedDomain	yes	The domains, in presentation order: the stable ones, or every one with status=any.

Used by product.domains

DomainMember

object

One stable feature of a domain, as a card shows it.

use majordomus_cli::product::{DomainMember, Surfaces};
let m = DomainMember {
    id: "finish-contract".into(),
    label: "Finish contract".into(),
    title: "Done is a contract".into(),
    headline: "A worker does not define its own completion.".into(),
    route: "/features/finish-contract/".into(),
    featured: true,
    surfaces: Surfaces::default(),
    claims: 3,
    tested: 2,
    use_cases: 1,
};
let v = serde_json::to_value(&m).unwrap();
assert_eq!(v["tested"], 2);
assert_eq!(v["surfaces"]["cli"], false);

property	type	required	description
id	string	yes	The feature id.
label	string	yes	The name a narrow column shows: the short title, or the title.
title	string	yes	The feature as a heading.
headline	string	yes	The feature's promise.
route	string	yes	`/features/<id>/`.
featured	boolean	yes	Whether the homepage shows it as a chapter.
surfaces	Surfaces → Surfaces	yes	The interfaces it is exposed through.
claims	integer (uint)	yes	How many claims it names.
tested	integer (uint)	yes	How many of them are guaranteed and name the test that settles them.
use_cases	integer (uint)	yes	How many use cases show it in use.

Used by ResolvedDomain

DomainRef

object

A domain as a feature points at it: enough for a breadcrumb.

use majordomus_cli::product::DomainRef;
let crumb = DomainRef {
    id: "context".into(),
    title: "Context".into(),
    route: "/domains/context/".into(),
};
let v = serde_json::to_value(&crumb).unwrap();
assert_eq!(v["route"], "/domains/context/");
assert_eq!(serde_json::from_value::<DomainRef>(v).unwrap(), crumb);

property	type	required	description
id	string	yes	The domain id.
title	string	yes	The domain as a heading.
route	string	yes	`/domains/<id>/`.

Used by ResolvedRefs

EpisodeSource

"hooks" | "connection" | "none"

How an episode boundary can be drawn for one provider.

Three words, because three things are true of different providers and collapsing them into "supported / not supported" is what let this tool report one provider and stay silent about five others. A provider that fires its own events is not the same as one that fires none but speaks MCP, and neither is the same as one that can do nothing.

The words are the declaration's own, and a word outside them is refused rather than read as none:

use majordomus_cli::share::EpisodeSource;
let read: EpisodeSource = serde_json::from_str("\"connection\"").unwrap();
assert_eq!(read, EpisodeSource::Connection);
assert_eq!(EpisodeSource::default(), EpisodeSource::None, "undeclared reads as none");
assert!(serde_json::from_str::<EpisodeSource>("\"hook\"").is_err(), "hooks, plural");

hooksThe provider fires its own session events and a hook this tool installs draws the boundary from them. The strongest form: it sees a window somebody closed.
connectionThe provider fires no session event, but its client attaches to this repository's shared MCP server, and the connection is the boundary (ADR 0103).
noneNeither. Nothing can say when this provider's episode began or ended, and the tool reports that rather than implying a capability nobody has.

Used by ProviderOffers

FeatureCounts

object

How much stands behind a feature, every number derived.

property	type	required	description
capabilities	integer (uint)	yes	Builtin capabilities of the modules it names.
mcp_tools	integer (uint)	yes	MCP tools among them.
mcp_resources	integer (uint)	yes	MCP resources among them, plus one per object of the kinds it names.
http_routes	integer (uint)	yes	HTTP routes among them.
cli_paths	integer (uint)	yes	Command-line paths of the executable among them.
commands	integer (uint)	yes	Public commands of the shell tool it names.
objects	integer (uint)	yes	Objects of the kinds it names.
rules	integer (uint)	yes	Rules it names.
enforced_rules	integer (uint)	yes	Rules the tool enforces among them.
docs	integer (uint)	yes	Documents it names.
adrs	integer (uint)	yes	Decisions it names.
claims	integer (uint)	yes	Claims it names.
use_cases	integer (uint)	yes	Use cases it names.
moments	integer (uint)	yes	Moments it answers.

Used by FeatureSummary ResolvedRefs

FeatureEvidence

object

What is guaranteed about a feature, counted from the claims it names: never a word a person wrote about the feature's maturity.

property	type	required	description
claims	map of integer (uint)	yes	Claims by status: `guaranteed`, `advisory`, `planned`, `rejected`.
modules	map of integer (uint)	yes	The modules it names by stability.

Used by FeatureSummary ResolvedDomain ResolvedRefs

FeatureList

object

The features as a client reads them.

property	type	required	description
schema	string	yes	`SCHEMA`.
fingerprint	string	yes	The hash of the model's sources and derived facts.
counts	ProductCounts → ProductCounts	yes	The counts.
surfaces	array of SurfaceInfo → SurfaceInfo	yes	The surface vocabulary, with how many stable features each exposes.
features	array of FeatureSummary → FeatureSummary	yes	The matching features, in presentation order.

Used by product.features

FeatureSummary

object

One feature as a listing shows it: everything a card needs and nothing a page needs.

property	type	required	description
id	string	yes	The identity and the slug.
title	string	yes	The feature as a heading.
label	string	yes	The name a narrow column shows: the short title, or the title.
headline	string	yes	The promise a visitor reads first.
summary	string	yes	One line: what it does.
status	string	yes	`stable`, `draft` or `deprecated`.
weight	integer (uint32)	yes	Presentation order.
featured	boolean	yes	Whether the homepage shows it.
domain	string \| null	no	The product domain it belongs to, when it names one.
areas	array of string	yes	The operational areas it serves.
audiences	array of string	yes	The audiences it is written for.
tags	array of string	yes	Free tags.
route	string	yes	Derived: `/features/<id>/`.
surfaces	Surfaces → Surfaces	yes	Derived: the interfaces it is exposed through.
counts	FeatureCounts → FeatureCounts	yes	Derived: how much stands behind it.
evidence	FeatureEvidence → FeatureEvidence	yes	Derived: what is guaranteed.

Used by FeatureList

KindRef

object

One object kind the feature names, with how many objects of it the layer holds.

property	type	required	description
name	string	yes	The kind.
objects	integer (uint)	yes	Objects of this kind in the index.

Used by ResolvedRefs

Matrix

object

Every feature against every interface, and every module, command and kind against the features that name it.

property	type	required	description
schema	string	yes	`SCHEMA`.
surfaces	array of SurfaceInfo → SurfaceInfo	yes	The surface vocabulary.
rows	array of MatrixRow → MatrixRow	yes	One row per feature of any status but deprecated, in presentation order.
modules	array of ProductCoverage → ProductCoverage	yes	Every builtin module of the executable with the stable features that name it.
commands	array of ProductCoverage → ProductCoverage	yes	Every public command of the shell tool with the stable features that name it.
kinds	array of ProductCoverage → ProductCoverage	yes	Every kind of the layer a feature can present, with the stable features that name it.

Used by product.matrix

MatrixRow

object

One row of the matrix: a feature and the surfaces it is exposed through.

property	type	required	description
id	string	yes	The feature id.
label	string	yes	The name a narrow column shows.
route	string	yes	`/features/<id>/`.
status	string	yes	`stable` or `draft`.
surfaces	Surfaces → Surfaces	yes	The surfaces, by id, in the vocabulary's order.
exposed	array of string	yes	The surface ids that are true.
proven	integer (uint)	yes	How many of the claims this feature names are guaranteed and name the test that settles them. A surface column says where a feature is reachable; this says what of it is proven, which is the question a reader of a compliance table is actually asking.
claims	integer (uint)	yes	How many claims it names at all, so `proven` has its denominator beside it rather than in another table.

Used by Matrix

ModuleRef

object

One capability module the feature names.

property	type	required	description
id	string	yes	The module id.
title	string	yes	The short name.
description	string	yes	One paragraph.
stability	string \| null	no	Where the module stands, when it declared it.
source_path	string	yes	Repository-relative path of the file its descriptors were composed in.
capabilities	array of CapabilityRef → CapabilityRef	yes	The builtin capabilities it composes, in id order.

Used by ResolvedRefs

MomentRef

object

One operational moment the feature answers: derived from the moments that name any of the feature's commands, capabilities, claims or rules.

property	type	required	description
id	string	yes	The moment id.
title	string	yes	The title.
hook	string	yes	The first-person line an index shows.
route	string	yes	`/why/<id>/`.

Used by ResolvedDomain ResolvedRefs

ProductCounts

object

How much the model holds. Every count anywhere is one of these.

property	type	required	description
features	integer (uint)	yes	Stable features.
features_all	integer (uint)	yes	Features of every status, drafts included.
featured	integer (uint)	yes	Stable features the homepage shows.
providers	integer (uint)	yes	Providers the tool has an adapter for.
modules	integer (uint)	yes	Builtin modules of the executable, and how many a stable feature names.
modules_covered	integer (uint)	yes	Modules a stable feature names.
commands	integer (uint)	yes	Public commands of the shell tool.
commands_covered	integer (uint)	yes	Commands a stable feature names.
kinds	integer (uint)	yes	Kinds of the layer a feature can present.
kinds_covered	integer (uint)	yes	Kinds a stable feature names.

Used by FeatureList ProductValidationReport

ProductCoverage

object

One thing of the product — a module, a public command, a kind — and the features that name it. Empty means the product page says nothing about it, which is a gap the validation reports and the matrix shows rather than hides.

property	type	required	description
id	string	yes	The id.
title	string	yes	The title.
features	array of string	yes	The stable features that name it.

Used by Matrix

ProductFinding

object

One thing wrong with the product model, named where it is, with the nearest candidate when there is one.

property	type	required	description
severity	Severity → Severity	yes	`error` or `warning`.
code	string	yes	`unknown_reference`, `duplicate_identity`, `missing_content`, `uncovered`, ...
path	string	yes	The repository-relative file the finding is in, or the registry it is about.
id	string \| null	no	The record's identity, when one record owns the finding.
field	string \| null	no	The front-matter key the finding is about, when one key owns it.
message	string	yes	What is wrong, in one sentence.
did_you_mean	string \| null	no	The nearest existing name, when the value looks like a typo of one.

Used by ProductValidationReport

ProductProvider

object

One provider the tool has an adapter for, discovered from the templates the distribution ships and decorated with what this repository does with it.

property	type	required	description
id	string	yes	The provider id: the template's file stem.
title	string	yes	The name a person knows it by.
bootstraps	array of ProviderBootstrap → ProviderBootstrap	yes	The bootstraps this repository's policy renders through it: target, mode, whether every worker loads it.
client_config	string \| null	no	The client configuration at the repository root that starts the shared MCP server for this provider, when the repository carries it.
hooks	array of string	yes	The enforcement entries of the policy wired by this provider's hooks.
scratch_roots	array of string	no	The scratch roots this provider creates checkouts of its own under, as declared: the worktree topology reports a checkout there as a session's scratch checkout and never moves it (ADR 0024).
offers	ProviderOffers → ProviderOffers	no	What it can do about the session lifecycle, and where each answer was verified (`share/providers.yaml`, ADR 0103). The capability, never the wiring: `hooks` says the vendor fires session events, not that this repository has installed anything to receive them. The other half — what is wired here, and whether driving it produced anything — is `majordomus capture status`, which reads this same declaration and joins it with the tree. It is not restated here because only the shell tool holds the adapter table and can run a shim, and a second account it could not compute correctly is worse than one reader more.

Used by ProviderList

ProductValidationReport

object

What the model's own validation found.

property	type	required	description
valid	boolean	yes	True when nothing is an error. Warnings do not make it false.
errors	integer (uint)	yes	How many findings are errors.
warnings	integer (uint)	yes	How many findings are warnings.
counts	ProductCounts → ProductCounts	yes	The counts the model reached.
findings	array of ProductFinding → ProductFinding	yes	The findings, errors first, then by file.

Used by product.validate

PromptSource

"hook" | "none"

Whether the person's raw prompt can be captured below the model for one provider.

There is no connection here and there must not be: an MCP server is handed tool calls, never the prompt that produced them. Prompt capture is provider-specific and the declaration says so rather than pretending the connection can stand in for it.

use majordomus_cli::share::PromptSource;
assert_eq!(serde_json::from_str::<PromptSource>("\"hook\"").unwrap(), PromptSource::Hook);
assert!(serde_json::from_str::<PromptSource>("\"connection\"").is_err(),
        "no connection can observe a prompt");
assert_eq!(PromptSource::default(), PromptSource::None);

hookThe provider hands the raw prompt to a command before the model runs.
noneIt does not. Nothing this tool can do makes the prompt observable.

Used by ProviderOffers

ProviderBootstrap

object

One bootstrap a provider renders.

property	type	required	description
target	string	yes	The target file, repository-relative.
mode	string	yes	`file` or `region`.
always_loaded	boolean	yes	Loaded by every worker without asking.

Used by ProductProvider

ProviderList

object

Every provider.

property	type	required	description
count	integer (uint)	yes	How many.
providers	array of ProductProvider → ProductProvider	yes	Each, in id order.

Used by product.providers

ProviderOffers

object

What one provider can do about the session lifecycle, and where that was verified.

Every cell carries its evidence. A capability asserted with no citation is the defect this type exists to make impossible: before it, a provider absent from a shell table was silently unsupported and a provider present in one was silently capable, and no surface could tell a reader which vendor page either answer came from — capture status enumerated the one provider that had an adapter and said nothing whatever about the other five this distribution declares. The rule project.a-provider-capability-cites-its-evidence refuses a declaration without one.

A provider that declares nothing is none on both axes with empty evidence — the state that rule refuses, so the gap is a finding rather than a silent "unsupported":

use majordomus_cli::share::{EpisodeSource, PromptSource, ProviderOffers};
let undeclared = ProviderOffers::default();
assert_eq!((undeclared.episode, undeclared.prompts), (EpisodeSource::None, PromptSource::None));
assert!(undeclared.episode_evidence.is_empty() && undeclared.prompts_evidence.is_empty());
let generic: ProviderOffers = serde_json::from_value(serde_json::json!({
    "episode": "connection", "episode_evidence": "ADR 0103",
    "prompts": "none", "prompts_evidence": "MCP carries no prompt",
})).unwrap();
assert_eq!(generic.episode, EpisodeSource::Connection);

property	type	required	description
episode	EpisodeSource → EpisodeSource	yes	How the episode boundary is drawn for this provider.
episode_evidence	string	yes	Where `episode` was verified: a vendor documentation URL, or the statement that no such documentation exists and what was searched for it.
prompts	PromptSource → PromptSource	yes	Whether the raw prompt can be captured below the model.
prompts_evidence	string	yes	Where `prompts` was verified, on the same terms as `episode_evidence`.

Used by ProductProvider

ResolvedDomain

object

One domain, resolved: the record as its file declares it, and everything derived from the stable features that name it.

The declared record is flattened, so a reader sees one object: the domain's own fields beside its derived members and counts.

use majordomus_cli::product::{Domain, DomainCounts, FeatureEvidence, ResolvedDomain, Surfaces};
let domain: Domain = serde_json::from_value(serde_json::json!({
    "id": "context", "title": "Context", "status": "stable",
    "headline": "h", "problem": "p",
}))
.unwrap();
let resolved = ResolvedDomain {
    domain,
    features: vec![],
    surfaces: Surfaces::default(),
    moments: vec![],
    claim_refs: vec![],
    use_case_refs: vec![],
    counts: DomainCounts::default(),
    evidence: FeatureEvidence::default(),
};
let v = serde_json::to_value(&resolved).unwrap();
assert_eq!(v["id"], "context", "the record is flattened into the resolved view");
assert_eq!(v["counts"]["features"], 0);

property	type	required	description
id	string	yes	The identity, the slug and the file name.
title	string	yes	The domain as a heading: one word or two.
headline	string	yes	What the product does about this domain, in one sentence.
problem	string	yes	The operational failure this domain answers, in one sentence.
status	string	yes	`stable`, `draft` or `deprecated`.
weight	integer (uint32)	no	Presentation order, lowest first.
tags	array of string	no	Free tags.
route	string	no	Derived: `/domains/<id>/`. Never authored; the schema refuses a `route` key.
source	string	no	Derived: the repository-relative file the record came from.
body	string	no	The Markdown body, without its front matter.
features	array of DomainMember → DomainMember	yes	Derived: the stable features that name it, in presentation order.
surfaces	Surfaces → Surfaces	yes	Derived: the interfaces any of its features is exposed through.
moments	array of MomentRef → MomentRef	yes	Derived: the operational moments its features answer, in the catalogue's order.
claim_refs	array of ClaimRef → ClaimRef	yes	Derived: the distinct claims its features name, with their status and test.
use_case_refs	array of UseCaseRef → UseCaseRef	yes	Derived: the distinct use cases its features name.
counts	DomainCounts → DomainCounts	yes	Derived: how much stands behind it.
evidence	FeatureEvidence → FeatureEvidence	yes	Derived: what is guaranteed, by claim status.

Used by DomainList

ResolvedRefs

object

One feature, resolved: the record as its file declares it, and everything derived.

property	type	required	description
id	string	yes	The identity, the slug and the file name.
title	string	yes	The feature as a heading.
short_title	string \| null	no	Two or three words for a card or a matrix row.
headline	string	yes	The promise a visitor reads first.
summary	string	yes	One line: what it does.
status	string	yes	`stable`, `draft` or `deprecated`.
weight	integer (uint32)	no	Presentation order, lowest first.
featured	boolean	no	Whether the homepage shows it as a chapter.
domain	string \| null	no	The product domain it belongs to, by id: exactly one. Editorial; the domain's members are derived from this field and listed nowhere else.
areas	array of string	no	The operational areas of the why catalogue it serves.
audiences	array of string	no	The audiences of the why catalogue it is written for.
modules	array of string	no	Capability modules of the executable it is made of.
commands	array of string	no	Public commands of the shell tool it is made of.
kinds	array of string	no	Object kinds of the layer it is made of.
rules	array of string	no	Rules of the effective set that govern it, by id without the version.
docs	array of string	no	The documents that explain it, by repository-relative path.
adrs	array of string	no	The decisions behind it, by declared id.
claims	array of string	no	Claims that say what is guaranteed here.
use_cases	array of string	no	Use cases that show it in use.
cockpit	array of string	no	Areas of the Cockpit that show it.
web	array of string	no	Web surfaces of the topology it is offered through.
related	array of string	no	Features explicitly related to this one. The reverse is derived.
tags	array of string	no	Free tags.
route	string	no	Derived: `/features/<id>/`. Never authored; the schema refuses a `route` key.
source	string	no	Derived: the repository-relative file the record came from.
body	string	no	The Markdown body, without its front matter.
surfaces	Surfaces → Surfaces	yes	Derived: the interfaces it is exposed through.
module_refs	array of ModuleRef → ModuleRef	yes	Derived: the modules it names, each with its capabilities and their projections.
command_refs	array of CommandRef → CommandRef	yes	Derived: the shell commands it names, as the command registry declares them.
kind_refs	array of KindRef → KindRef	yes	Derived: the kinds it names, each with its object count.
rule_refs	array of RuleRef → RuleRef	yes	Derived: the rules it names, each with its class and whether it is enforced.
doc_refs	array of DocRef → DocRef	yes	Derived: the documents it names, with their titles.
adr_refs	array of AdrRef → AdrRef	yes	Derived: the decisions it names, with their status.
claim_refs	array of ClaimRef → ClaimRef	yes	Derived: the claims it names, with their status.
use_case_refs	array of UseCaseRef → UseCaseRef	yes	Derived: the use cases it names.
cockpit_refs	array of CockpitAreaRef → CockpitAreaRef	yes	Derived: the Cockpit areas it names, with their routes.
web_refs	array of SurfaceRef → SurfaceRef	yes	Derived: the web surfaces it names, with their mounts.
moments	array of MomentRef → MomentRef	yes	Derived: the moments that name any command, capability, claim or rule of this feature.
backlinks	array of string	yes	Derived: the features that name this one in their `related`.
counts	FeatureCounts → FeatureCounts	yes	Derived: how much stands behind it.
evidence	FeatureEvidence → FeatureEvidence	yes	Derived: what is guaranteed.
domain_ref	DomainRef \| null → DomainRef	no	Derived: the domain its `domain` names, with its title and route, when that resolves. Absent for a feature that names none or names one that does not exist.

Used by product.feature

RuleRef

object

One rule the feature names.

property	type	required	description
id	string	yes	The rule id, without the version.
identity	string	yes	The identity the index holds, with the version.
title	string	yes	The title.
class	string	yes	`blocking` or `advisory`.
enforced	boolean	yes	Whether a machine decides it: the block names a validator or tests, not only a reason a person reviews it.
path	string	yes	Repository-relative path.

Used by ResolvedRefs

SurfaceInfo

object

One surface of the vocabulary, as a client reads it.

property	type	required	description
id	string	yes	`cli`, `api`, `mcp`, `cockpit` or `docs`.
title	string	yes	The name a person reads.
route	string	yes	The route on the website where the surface is documented.
features	integer (uint)	yes	How many stable features it exposes.

Used by FeatureList Matrix

SurfaceRef

object

One web surface of the topology the feature names.

property	type	required	description
id	string	yes	The surface id.
title	string	yes	The title.
mount	string	yes	Where it is mounted.
category	string	yes	What it is for.

Used by ResolvedRefs

Surfaces

object

The interfaces a feature is exposed through, decided from what its references project and from nothing a file says. Each is a fact with a reason a reader can check: cli is true when a module of the feature has a capability with a command-line path or the feature names a shell command; api when a module has an HTTP route; mcp when a module has an MCP tool or resource, or the feature names a kind, since every object of the layer is an MCP resource; cockpit when the feature names a Cockpit area or a module, since every capability has a Cockpit page; docs when it names a document.

property	type	required	description
cli	boolean	yes	The command line: the executable's own, or the shell tool's.
api	boolean	yes	The HTTP routes under `/api/v1/`, and the OpenAPI document over them.
mcp	boolean	yes	MCP: a tool, or a resource.
cockpit	boolean	yes	The Cockpit.
docs	boolean	yes	The documentation.

Used by DomainMember FeatureSummary MatrixRow ResolvedDomain ResolvedRefs

UseCaseRef

object

One use case the feature names.

property	type	required	description
id	string	yes	The use case id.
title	string	yes	The title.
category	string \| null	no	The category it is filed under.

Used by ResolvedDomain ResolvedRefs