{ "openapi": "3.1.0", "jsonSchemaDialect": "https://spec.openapis.org/oas/3.1/dialect/base", "info": { "title": "Majordomus", "version": "0.5.0", "summary": "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.", "description": "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.\n\n**One registry, every interface a projection.** Every operation here is a capability of the registry and nothing is declared for HTTP alone. `operationId` is the capability's canonical id; the same capability answers as the MCP tool `x-majordomus-mcp` names and as the command `x-majordomus-cli` names, where its exposure says so, through one executor with one cache. A change to a capability's description or input type reaches this document, the MCP schema, the command line and the generated reference on the next start; nothing is edited by hand.\n\n**Loopback, unauthenticated, read-only.** The first `majordomus mcp` in a repository binds this server beside its stdio session and logs the URL; `majordomus serve` binds it alone. It listens on 127.0.0.1, asks for no credentials, and never writes to the repository: whoever can reach the socket can read the layer, and nobody can change it through it. `GET /` is the home page and lists every surface; `/swagger` is Swagger UI over this document; `/docs/` is this repository's own documentation; `/mcp` is MCP over HTTP for a second client.\n\n**Binding.** `GET` binds every top-level property of the capability's input as a query parameter, coerced by the schema's type (integers, numbers and booleans are parsed, everything else is text); `POST` binds the input as the JSON body. An unknown parameter is an invalid input, not ignored. Every failure is one JSON body, `{ \"error\": { \"code\", \"message\" } }`: 400 `invalid_input`, 404 `not_found`, 422 `refused` (a command's alone), 500 `internal`; 405 `method_not_allowed` names a path that exists under another method.\n\n**Examples are benchmark cases.** Every example in this document is one of the capability's own benchmark cases, the inputs the benchmarks time and the tests replay against a real socket: an operation without an example is an operation without a case, and the executable does not compile in that state. `x-majordomus-benchmark` and `x-majordomus-cache` carry the policies; `x-majordomus-stability` and `x-majordomus-provenance` say how far a capability is proved and where it was declared.\n\n**Generated, committed, checked.** This document is rendered from the registry at every request and committed as `docs/generated/openapi.json`; `majordomus generate --check` derives it again and refuses a stale copy, and CI runs that check on every push, so the committed document, the served one and the reference on the site are the same document.", "license": { "name": "MIT", "identifier": "MIT" }, "contact": { "name": "Majordomus", "url": "https://github.com/korczis/prismatic-majordomus" } }, "externalDocs": { "description": "The API reference, rendered from this document.", "url": "https://majordomus.dev/docs/api/" }, "servers": [ { "url": "/", "description": "The shared server `majordomus mcp` binds, or `majordomus serve`; loopback, the port in its log." } ], "tags": [ { "name": "artifacts", "description": "What `majordomus generate` writes: every document with the encodings it is committed in — JSON for a program, YAML beside it, Markdown for a reader — each with its schema, its source and its hash, reconciled with the working tree. The declaration is the generator's own manifest; nothing here keeps a list." }, { "name": "capabilities", "description": "The registry seen through itself: every capability with its kind, stability, provenance, exposures, benchmark and cache policy, and one capability in full." }, { "name": "commands", "description": "Every command this repository offers, from whichever program offers it: the Rust executable, the shell tool that carries the task lifecycle, and the workflows the repository declares for a person to run. Composed from the three declarations that already exist — the clap tree, the shipped command registry and the workflow runner's own dump — never from a list. Each command carries what running it changes, what it needs, where its argument values come from, and every surface that carries it, with the reason when one does not." }, { "name": "continuity", "description": "What this checkout's lifecycle is holding: the open episode, the record the next worker would resume from with the label that says how far to trust it, the newest progress note, and what is blocking acceptance. Read from the local half of the layer, which this process serves to the worker in front of it and never publishes." }, { "name": "deploy", "description": "The deployments this repository declares, read from the canonical objects the index holds, and whether they would work — decided against the capability registry this process built and the workspace it sits in. Every operation is a read: a deployment is changed by the trusted command line and by CI, never over HTTP and never by an MCP client." }, { "name": "design", "description": "The one declaration of how every surface of this tool looks — the semantic roles, the status vocabulary, the type scale, the theme contract — as this executable carries it: its fingerprint, its tokens, what any one of them means, and whether the colours it pairs are readable on one another. The stylesheets the site and the Cockpit load, the tokens the executable's own pages compile in, and the dataset the site's templates read are all projections of it; a page compares its `--mj-design` with this fingerprint to know whether it is wearing the design this executable was built with." }, { "name": "directories", "description": "The layer's directories as a hierarchy: the contract each one declares, what it owes and which contract said so, and the chain that applies to it once inheritance is resolved." }, { "name": "distribution", "description": "How this project is packaged, published and installed: the platforms a release builds, the artifact names the one naming function derives, the installer's canonical command, the releases that were published, and what this build itself is. Every answer comes from share/distribution.yaml and the release records; no surface here states a fact of its own." }, { "name": "environment", "description": "What this checkout is right now: the project and its version, the repository and its layer, version control, the toolchains it declares, what the layer holds, the workflows a person can run, the provider projections and the local services — one typed snapshot, with a provenance entry for every value in it. The direnv banner, the Cockpit's overview and this route are renderings of the same value." }, { "name": "executions", "description": "Running a capability of this registry as work that can be watched: started, followed event by event over the live channel, read back afterwards, and asked to stop. In memory; an execution does not outlive the process that accepted it." }, { "name": "graph", "description": "The graphs derived from the registry and the index: the executable's own capability registry, the shape of the layer, the rule dependencies, the decisions and what they put in force, and the use cases and what they exercise. Canonical nodes and edges; a rendering library is a consumer, never the shape." }, { "name": "health", "description": "Whether what this process serves is healthy, decided by the engines that already decide it: the index's diagnostics, the registry builder, the benchmark projection's coverage, the comparison `generate --check` makes and the lease reading `server.status` answers from. No check here has an opinion of its own." }, { "name": "objects", "description": "The declarative objects of the repository's AI layer: rules, prompts, profiles, policy, documents, milestones, issues, claims, and whatever kinds the repository adds; listed, read by URI, and searched." }, { "name": "obligations", "description": "What a task owes before it may be called completed, and whether the evidence that discharged each obligation still describes this tree. The vocabulary is data the distribution ships and answers in any clone; the closure is read from the local half of the layer, which this process serves to the worker in front of it and never publishes. Read, never written: `majordomus evidence` records, and a second writer for one ledger would be a second account of the same events." }, { "name": "peers", "description": "The clients attached to this repository's shared server, named by their own initialize, and what each announced it is working on. In memory; gone with the process." }, { "name": "perf", "description": "This process's work counters and phase timings: what happened once at startup and what happens per call, for the structural tests and the benchmark evidence." }, { "name": "plan", "description": "The milestone and issue model of this repository, and everything derived from it that nobody authored: the status of each record, the dependency graphs above and below the milestone boundary, the topological execution waves, the roadmap order, the milestone being executed and the one issue to take next. Status is never stored — a record says what happened to it and the status follows from that and from the state of its dependencies — so no file can contradict the graph. The four operations that write a lifecycle marker into a record stay on the command line: a capability of this registry never writes to the repository." }, { "name": "product", "description": "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." }, { "name": "quality", "description": "What this executable's own public surface is held to, measured from its syntax tree: 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 rules are project.rust-public-api-quality and project.operation-transport-parity; this is the measurement of them." }, { "name": "release", "description": "What this project has shipped and what it would ship next, derived rather than maintained: the changelog composes the layer's release records, the decisions dated inside each release's window and the conventional commits in its range; the version report reads the two places the version is stated and says what the commits since the last release imply it should become." }, { "name": "repository", "description": "The repository this process serves: its layer, its git state, the state of the index built from it, and its scope: what a worker reads of it and what it never reads." }, { "name": "server", "description": "The shared server of this checkout and of every other checkout of the same git repository: what each lease says, whether the server it names answers, whether what answers is the code on disk at this executable's version, and how many peers each one holds." }, { "name": "trace", "description": "Which branches and commits realised an issue, and which issue and milestone a commit served — derived from git and from the canonical project model on every call, stored nowhere. A branch names an issue when one of its path components is an issue id; a commit belongs to the issue whose branches hold it; a commit no such branch holds is reported as unattributed rather than left out, because work with no execution contract is what a traceability report exists to make visible. Pull requests are a GitHub fact and this executable makes no network call: `scripts/traceability` reads them and joins them to this answer over the branch name." }, { "name": "web", "description": "What this repository exposes over HTTP, resolved from the producers that make it rather than from a register anybody maintains: the routes the executable answers itself, the documentation build, and every generated report that declared its own mount. The same resolution serves the router, renders the home page and composes a publication." }, { "name": "why", "description": "The operational failure modes this tool is a response to: the moments a reader recognises, the audiences that recognise them, the areas they fall under, and what a reader's own symptoms imply. Every entry is a file under the layer's why section; nothing here holds a list, and a moment added there is answered by all of these without a registration anywhere." }, { "name": "worktree", "description": "Where every linked git worktree of this repository belongs and where each one is. The container is the primary checkout's sibling named with `-wt`, the path under it is the branch name with its hierarchy kept, and both are derived from git's own identity — the common directory, the registered worktrees, the branches — never from a registry, a configuration or the current directory. A worktree somewhere else is a typed diagnostic with a remedy; the migration that repairs it is a command-line operation of the same service." } ], "paths": { "/api/v1/artifacts": { "get": { "operationId": "artifacts.list", "summary": "List the generated artifacts", "description": "The manifest `majordomus generate` commits as docs/generated/artifacts.json, reconciled with the working tree: every document with the encodings it is written in, and every file with its format, schema, source, size, hash and whether the file on disk still matches. Optionally narrowed to one document or one encoding. Reads only; `majordomus generate` writes and `majordomus generate --check` is the byte-for-byte verdict.", "tags": [ "artifacts" ], "parameters": [ { "name": "document", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only the artifacts of this document (`registry`, `cli`, `openapi`, ...)." }, { "name": "format", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/ArtifactFormat" }, { "type": "null" } ] }, "description": "Only the artifacts written in this encoding.", "examples": { "one-encoding": { "value": "yaml" } } } ], "responses": { "200": { "description": "List the generated artifacts: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactReport" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "artifacts.list", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::artifacts" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "process", "max_entries": 8, "ttl_seconds": 5 }, "x-majordomus-mcp": { "tool": "majordomus_artifacts", "resource": { "uri": "majordomus://artifacts", "name": "artifacts" } } } }, "/api/v1/capabilities": { "get": { "operationId": "capabilities.list", "summary": "List capabilities", "description": "Every capability of this executable and this repository, summarised: kind, module, stability, provenance, the projections it declares, its benchmark and cache policy; the schemas are answered by capabilities.describe.", "tags": [ "capabilities" ], "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only capabilities of this kind: `query`, `command` or `resource`.", "examples": { "queries": { "value": "query" } } }, { "name": "exposure", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only capabilities exposed through this projection: `mcp`, `http` or `cli`." } ], "responses": { "200": { "description": "List capabilities: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityList" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "capabilities.list", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::capabilities" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "process", "max_entries": 16 }, "x-majordomus-mcp": { "tool": "majordomus_capabilities" }, "x-majordomus-cli": "capabilities list" } }, "/api/v1/capabilities/projections": { "get": { "operationId": "capabilities.projections", "summary": "Where each capability is projected", "description": "A row per capability with the command line, HTTP route, MCP tool and MCP resource it reaches, whether every exposure it declares is answered by that surface, and the runnable commands no capability claims. Derived from the registry and the clap declaration; nothing is written down.", "tags": [ "capabilities" ], "parameters": [ { "name": "module", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only capabilities composed in this module." }, { "name": "unmet", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Only the capabilities whose declared exposures are not all answered by their\nsurface. Empty is the closure the rule asks for.", "examples": { "all": { "value": false }, "unmet": { "value": true } } } ], "responses": { "200": { "description": "Where each capability is projected: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClosureMatrix" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "capabilities.projections", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::capabilities" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "process", "max_entries": 8 }, "x-majordomus-mcp": { "tool": "majordomus_projections" }, "x-majordomus-cli": "capabilities projections" } }, "/api/v1/capability": { "get": { "operationId": "capabilities.describe", "summary": "Describe one capability", "description": "One capability by canonical id: its kind, schemas, provenance, stability, exposures, benchmark and cache policy.", "tags": [ "capabilities" ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The canonical id, e.g. `repository.info` or `rule.majordomus.scope-integrity@1`.", "examples": { "repository-info": { "value": "repository.info" } } } ], "responses": { "200": { "description": "Describe one capability: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Capability" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "capabilities.describe", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::capabilities" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_capability" }, "x-majordomus-cli": "capabilities describe" } }, "/api/v1/changelog": { "get": { "operationId": "release.changelog", "summary": "The changelog", "description": "Every release the layer records, newest first, with the work that has not been released leading. A section's decisions are the ADRs dated inside that release's window, its changes the conventional commits in its range, its artifacts the record's own evidence. Nothing in it is authored, and a section that could not be read says so rather than appearing empty.", "tags": [ "release" ], "parameters": [ { "name": "version", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One version, or `unreleased`; every section when absent.", "examples": { "one-version": { "value": "0.3.1" } } } ], "responses": { "200": { "description": "The changelog: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseChangelog" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "release.changelog", "x-majordomus-kind": "query", "x-majordomus-stability": "implemented", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::release" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_changelog", "resource": { "uri": "majordomus://changelog", "name": "changelog" } } } }, "/api/v1/command": { "get": { "operationId": "commands.get", "summary": "One command in full", "description": "One command by its canonical identity: its arguments with the source of each one's values, what running it changes, what it needs, where it came from, and every surface that carries it — with the reason a machine surface withholds it when one does.", "tags": [ "commands" ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The identity, `executable.worktree.status`.", "examples": { "worktree-status": { "value": "executable.worktree.status" } } } ], "responses": { "200": { "description": "One command in full: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandNode" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "commands.get", "x-majordomus-kind": "query", "x-majordomus-stability": "implemented", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::commands" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_command" } } }, "/api/v1/commands": { "get": { "operationId": "commands.list", "summary": "Every command, one line each", "description": "The commands this repository offers, filtered by the program that runs them, by what running them changes, or by text. A summary rather than the whole graph: enough to choose a command, and never so much that a client has to read every argument of every command to find one.", "tags": [ "commands" ], "parameters": [ { "name": "origin", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only the commands of one program: `executable`, `tool` or `workflow`.", "examples": { "one-program": { "value": "executable" } } }, { "name": "effect", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only the commands whose effect is at most this one: `read_only`,\n`local_mutation`, `repository_mutation`, `network_mutation`, `destructive`.", "examples": { "read-only": { "value": "read_only" } } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only the commands matching this text in their invocation, summary, tags or identity." } ], "responses": { "200": { "description": "Every command, one line each: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandIndex" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "commands.list", "x-majordomus-kind": "query", "x-majordomus-stability": "implemented", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::commands" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_commands", "resource": { "uri": "majordomus://commands", "name": "commands" } } } }, "/api/v1/commands/graph": { "get": { "operationId": "commands.graph", "summary": "The whole command graph", "description": "The graph as one document, with its fingerprint and every diagnostic its build found: a duplicate identity, a recipe name two commands would take, an annotation that names a command which no longer exists. Deterministic — two builds over one tree produce the same document — so a client may cache against the fingerprint.", "tags": [ "commands" ], "parameters": [], "responses": { "200": { "description": "The whole command graph: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandGraphReport" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "commands.graph", "x-majordomus-kind": "query", "x-majordomus-stability": "implemented", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::commands" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_command_graph" } } }, "/api/v1/continuity": { "get": { "operationId": "continuity.state", "summary": "What the lifecycle is holding", "description": "The open episode, the active task, the handover and checkpoint that resolve for this worktree and branch, each with its divergence label, the unresolved questions that refuse completion, and the record tallies. Selection is two-tiered and never repository-wide: a record from an unrelated worktree or branch is not offered, because a briefing that is quietly about somebody else is worse than none. Absence is reported as absence.", "tags": [ "continuity" ], "parameters": [], "responses": { "200": { "description": "What the lifecycle is holding: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Continuity" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "continuity.state", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::continuity" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "process", "max_entries": 2, "ttl_seconds": 2 }, "x-majordomus-mcp": { "tool": "majordomus_continuity", "resource": { "uri": "majordomus://continuity", "name": "continuity" } } } }, "/api/v1/deployment": { "get": { "operationId": "deploy.get", "summary": "One deployment", "description": "One deployment by its identity, typed, with the repository-relative file it was read from.", "tags": [ "deploy" ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The deployment's `id`.", "examples": { "first-deployment": { "value": "majordomus" } } } ], "responses": { "200": { "description": "One deployment: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentView" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "deploy.get", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::deploy" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_deployment" } } }, "/api/v1/deployments": { "get": { "operationId": "deploy.list", "summary": "Deployments", "description": "Every deployment the layer declares, typed: the application, the package and binary shipped, the address the process listens on, the routes a platform polls, the resources, the machine count, the region, the build inputs, the measured budgets and the provider's own facts. An object of the kind this executable cannot read is reported with the reason rather than skipped.", "tags": [ "deploy" ], "parameters": [], "responses": { "200": { "description": "Deployments: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentList" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "deploy.list", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::deploy" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_deployments", "resource": { "uri": "majordomus://deployments", "name": "deployments" } } } }, "/api/v1/deployments/check": { "get": { "operationId": "deploy.check", "summary": "Would these deployments work", "description": "Every refusal the declared deployments earn locally: a health route no capability registers, a package or binary the workspace does not produce, a build input that does not resolve, more machines running than exist, a hosted process that would bind loopback. Each names the file, the key, the value observed and the correction. Nothing here contacts the provider.", "tags": [ "deploy" ], "parameters": [], "responses": { "200": { "description": "Would these deployments work: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentCheck" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "deploy.check", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::deploy" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "process", "max_entries": 2, "ttl_seconds": 5 }, "x-majordomus-mcp": { "tool": "majordomus_deploy_check" } } }, "/api/v1/design": { "get": { "operationId": "design.system", "summary": "The design system", "description": "What the design is: the fingerprint every stylesheet carries, the identity, the type stacks, the theme contract with the pre-paint statement every surface runs, the audit widths, how many tokens of each kind, and every generated file the declaration is projected into.", "tags": [ "design" ], "parameters": [], "responses": { "200": { "description": "The design system: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignReport" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "design.system", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::design" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_design", "resource": { "uri": "majordomus://design", "name": "design" } } } }, "/api/v1/design/contrast": { "get": { "operationId": "design.contrast", "summary": "Whether the declared colours can be read", "description": "Every foreground the design puts on a ground, in both themes, measured against WCAG 2.1 AA: the pair, the palette entries behind it, the ratio and the threshold. The pairs are not a list — they are derived from the declaration, which files each status's text with its own ground, and from the primitives that consume it, where a rule that sets a colour and a background states a pair and a rule that sets only a colour states a foreground that lands on every ground a container sets. A pair below the threshold is a finding that names the role, the ground, the theme, the measured ratio and the required one.", "tags": [ "design" ], "parameters": [], "responses": { "200": { "description": "Whether the declared colours can be read: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContrastReport" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "design.contrast", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::design" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_design_contrast" } } }, "/api/v1/design/explain": { "get": { "operationId": "design.explain", "summary": "What a design token means", "description": "One token by name or by the custom property it becomes: what it is for, what it resolves to in each theme, which Flowbite names are synonyms of it, which state words it colours, and which generated files it reaches.", "tags": [ "design" ], "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "A role (`fg`), a status (`ok`), a state word (`succeeded`), a type step (`meta`), a\npalette entry (`gray-600`), or the custom property any of them becomes (`--mj-fg`).", "examples": { "role": { "value": "fg" }, "state": { "value": "succeeded" } } } ], "responses": { "200": { "description": "What a design token means: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "design.explain", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::design" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_design_explain" } } }, "/api/v1/design/tokens": { "get": { "operationId": "design.tokens", "summary": "The design tokens", "description": "Every token of the design, explained: roles with their light and dark values, statuses with their text, ground and border and the state words filed under them, the type scale, the layout values, the theme contract, the palette. Narrow it to one kind.", "tags": [ "design" ], "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/TokenKind" }, { "type": "null" } ] }, "description": "Only tokens of this kind.", "examples": { "roles": { "value": "role" } } } ], "responses": { "200": { "description": "The design tokens: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenList" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "design.tokens", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::design" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_design_tokens" } } }, "/api/v1/directories": { "get": { "operationId": "directories.list", "summary": "The layer's directory contracts", "description": "Every directory of the layer the index knows, with the contract it declares, whether it owes one and which contract decided, and — for a named path, or when asked for everywhere — the effective chain composed from the root down, least specific first.", "tags": [ "directories" ], "parameters": [ { "name": "path", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One directory, repository-relative and inside the layer. Its effective chain is\nalways resolved. Absent means every directory of the layer.", "examples": { "one-directory": { "value": ".ai/repo/rules" } } }, { "name": "effective", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Resolve the effective chain for every directory, not only for a named one.", "examples": { "effective-everywhere": { "value": true } } }, { "name": "state", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/DirectoryState" }, { "type": "null" } ] }, "description": "Only directories in this state: `documented`, `exempt` or `owed`.", "examples": { "owed": { "value": "owed" } } } ], "responses": { "200": { "description": "The layer's directory contracts: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryReport" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "directories.list", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::directories" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "process", "max_entries": 8, "ttl_seconds": 5 }, "x-majordomus-mcp": { "tool": "majordomus_directories", "resource": { "uri": "majordomus://directories", "name": "directories" } } } }, "/api/v1/distribution": { "get": { "operationId": "distribution.model", "summary": "The distribution model", "description": "The one-line install command, where an installation goes, and every declared target with the artifact name it derives. This is what the installation page, the landing page's install block and the cockpit's install card render; none of them holds a platform list of its own.", "tags": [ "distribution" ], "parameters": [], "responses": { "200": { "description": "The distribution model: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DistributionReport" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "distribution.model", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::distribution" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_distribution" }, "x-majordomus-cli": "distribution show" } }, "/api/v1/distribution/artifact": { "get": { "operationId": "distribution.artifact", "summary": "The artifact of a target", "description": "The archive name a target and a tag derive, the directory it unpacks into, and where a release publishes it. The one naming function answers; the release pipeline asks it rather than composing a name in a workflow file.", "tags": [ "distribution" ], "parameters": [ { "name": "target", "in": "query", "required": true, "schema": { "type": "string" }, "description": "A target's id or its Rust target triple.", "examples": { "first-published-target": { "value": "aarch64-apple-darwin" } } }, { "name": "tag", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The tag, `v` and a version. `{tag}` asks for the name with the placeholder left in.", "examples": { "first-published-target": { "value": "v0.0.0" } } } ], "responses": { "200": { "description": "The artifact of a target: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseArtifactView" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "distribution.artifact", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::distribution" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_artifact" }, "x-majordomus-cli": "distribution artifact" } }, "/api/v1/distribution/build": { "get": { "operationId": "distribution.build", "summary": "This build", "description": "What this executable is: the version of the crate it was built from, the Rust target triple, the profile, and the commit — all compiled in at build time, so an installed binary answers without a repository, a toolchain or git.", "tags": [ "distribution" ], "parameters": [], "responses": { "200": { "description": "This build: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildReport" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "distribution.build", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::distribution" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_build" }, "x-majordomus-cli": "distribution build" } }, "/api/v1/distribution/releases": { "get": { "operationId": "distribution.releases", "summary": "Published releases", "description": "Every release this repository recorded, newest first, and the one an unpinned installation resolves to: the highest version among the stable, unwithdrawn records. The pointer is derived here and never authored anywhere.", "tags": [ "distribution" ], "parameters": [], "responses": { "200": { "description": "Published releases: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleasesReport" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "distribution.releases", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::distribution" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_releases" }, "x-majordomus-cli": "distribution releases" } }, "/api/v1/distribution/status": { "get": { "operationId": "distribution.status", "summary": "Whether the published installation works", "description": "Whether a machine that has never seen this project can install it right now with the advertised one-line command, and when it cannot, which link in the chain is missing and what changes it. Derived from the distribution model and the release records alone: it reaches no network, so it is as fast as any other local query and answers offline. The served bytes are proved by the release pipeline's smoke phase, not guessed at here.", "tags": [ "distribution" ], "parameters": [], "responses": { "200": { "description": "Whether the published installation works: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallabilityReport" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "distribution.status", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::distribution" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_install_status" }, "x-majordomus-cli": "distribution status" } }, "/api/v1/environment": { "get": { "operationId": "environment.status", "summary": "The repository environment", "description": "One snapshot of this checkout: project identity, repository identity, version control, declared toolchains, 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 with the address a running server published. Every value carries where it came from.", "tags": [ "environment" ], "parameters": [ { "name": "probe_services", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Contact the local address a running server published, to say whether it answers.\nOff by default: a served request should not open a socket to another server on\nbehalf of its caller, and the caller usually is that server.", "examples": { "default": { "value": false } } } ], "responses": { "200": { "description": "The repository environment: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepositoryEnvironment" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "environment.status", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::environment" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "process", "max_entries": 4, "ttl_seconds": 3 }, "x-majordomus-mcp": { "tool": "majordomus_environment", "resource": { "uri": "majordomus://environment", "name": "environment" } } } }, "/api/v1/environment/explain": { "get": { "operationId": "environment.explain", "summary": "Where an environment value came from", "description": "The provenance of the snapshot: for each field, what decided it — a compile-time constant, a file, a command, or the cache — which resolver read it, and how far it can be trusted. Narrow it to one field, or to a prefix, by name.", "tags": [ "environment" ], "parameters": [ { "name": "field", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The field in dotted form (`services.url`, `capabilities.objects`); every field when\nabsent.", "examples": { "one-field": { "value": "project.version" } } } ], "responses": { "200": { "description": "Where an environment value came from: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentProvenance" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "environment.explain", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::environment" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_environment_explain" } } }, "/api/v1/executions": { "get": { "operationId": "executions.list", "summary": "List executions", "description": "Every execution this process remembers, newest first, narrowed by state or by capability. The counts beside them — remembered, active, queued, live channels — are what a control plane shows without asking a second question.", "tags": [ "executions" ], "parameters": [ { "name": "state", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/ExecutionState" }, { "type": "null" } ] }, "description": "Only executions in this state." }, { "name": "capability", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only executions of this capability." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "uint", "minimum": 0 }, "description": "How many, newest first; the default and the bound are both `200`.", "examples": { "recent": { "value": 50 } } } ], "responses": { "200": { "description": "List executions: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionList" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "executions.list", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::executions" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_executions", "resource": { "uri": "majordomus://executions", "name": "executions" } }, "x-majordomus-cli": "executions list" } }, "/api/v1/executions/cancel": { "post": { "operationId": "executions.cancel", "summary": "Ask an execution to stop", "description": "Set the execution's cancellation flag and say so on its stream. Cancellation is cooperative: a task looks at its flag and stops, and a capability whose policy says it is not cancellable runs to completion — which the answer says rather than pretending otherwise.", "tags": [ "executions" ], "requestBody": { "required": true, "description": "The input of `executions.cancel`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelInput" } } } }, "responses": { "200": { "description": "Ask an execution to stop: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelReport" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "422": { "description": "`refused`: The command was understood and turned down for the reason the message gives.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "executions.cancel", "x-majordomus-kind": "command", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::executions" }, "x-majordomus-benchmark": { "policy": "waived", "reason": "transient_state" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_execution_cancel" }, "x-majordomus-cli": "executions cancel" } }, "/api/v1/executions/demonstrate": { "get": { "operationId": "executions.demonstrate", "summary": "Demonstrate an execution", "description": "Walk a given number of steps, reporting each one, logging a line and advancing progress, then finish — or fail at a step you name. It exists so that an operator, a probe and an end-to-end test can prove the whole path works without waiting for real work: it reads nothing, writes nothing, and its only effect is the events it produces. It looks at its cancellation flag between steps and while it waits, so cancelling it stops it.", "tags": [ "executions" ], "parameters": [ { "name": "steps", "in": "query", "required": false, "schema": { "type": "integer", "format": "uint64", "minimum": 0, "default": 3 }, "description": "How many steps to walk through.", "examples": { "immediate": { "value": 1 } } }, { "name": "delay_ms", "in": "query", "required": false, "schema": { "type": "integer", "format": "uint64", "minimum": 0, "default": 0 }, "description": "How long each step takes, in milliseconds. Bounded at ten seconds a step, so this\ncannot be used to hold a worker.", "examples": { "immediate": { "value": 0 } } }, { "name": "fail_at", "in": "query", "required": false, "schema": { "type": "integer", "format": "uint64", "minimum": 0 }, "description": "Fail on this step instead of completing, to show what a failure looks like." } ], "responses": { "200": { "description": "Demonstrate an execution: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DemonstrateReport" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "executions.demonstrate", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::executions" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_demonstrate_execution" } } }, "/api/v1/executions/events": { "get": { "operationId": "executions.events", "summary": "An execution's event history", "description": "The retained events of one execution, oldest first, after a sequence number. This is what a browser reads after a reload and what a client reads after a reconnect: the page carries the cursor to open the live channel with, so nothing is missed between the history and the stream.", "tags": [ "executions" ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The execution's id." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "format": "uint64", "minimum": 0 }, "description": "Only events after this sequence number: the cursor a reconnecting client holds." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "uint", "minimum": 0 }, "description": "How many, oldest first; the default and the bound are both `500`." } ], "responses": { "200": { "description": "An execution's event history: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventHistory" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "executions.events", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::executions" }, "x-majordomus-benchmark": { "policy": "waived", "reason": "transient_state" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_execution_events" }, "x-majordomus-cli": "executions events" } }, "/api/v1/executions/get": { "get": { "operationId": "executions.get", "summary": "One execution", "description": "The whole of what is known about one execution: its state, its input as it was stored, its steps, its progress, its diagnostics, and its output or its error. Taken under one lock, so a snapshot that says it succeeded carries what it produced.", "tags": [ "executions" ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The execution's id." } ], "responses": { "200": { "description": "One execution: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionView" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "executions.get", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::executions" }, "x-majordomus-benchmark": { "policy": "waived", "reason": "transient_state" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_execution" }, "x-majordomus-cli": "executions show" } }, "/api/v1/executions/protocol": { "get": { "operationId": "executions.protocol", "summary": "The live channel's contract", "description": "Where the WebSocket is, how a subscription and a reconnect are expressed, what the server writes, and the JSON Schema of every message — derived from the Rust types that implement it, so a client validating against this is validating against the implementation. OpenAPI cannot describe a socket; this is where that contract lives.", "tags": [ "executions" ], "parameters": [], "responses": { "200": { "description": "The live channel's contract: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolReport" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "executions.protocol", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::executions" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_execution_protocol", "resource": { "uri": "majordomus://executions/protocol", "name": "execution-protocol" } }, "x-majordomus-cli": "executions protocol" } }, "/api/v1/executions/start": { "post": { "operationId": "executions.start", "summary": "Start a capability as an execution", "description": "Run any executable capability of this registry as an execution: the input is checked against that capability's own input schema, the work is queued, and this answers at once with the execution's id and the links to follow it. Nothing waits for the handler. The capability runs through the same executor every other interface calls, so there is no second implementation of anything.", "tags": [ "executions" ], "requestBody": { "required": true, "description": "The input of `executions.start`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartInput" }, "examples": { "demonstrate": { "value": { "capability": "executions.demonstrate", "input": { "steps": 1, "delay_ms": 0 } } } } } } }, "responses": { "200": { "description": "Start a capability as an execution: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionView" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "422": { "description": "`refused`: The command was understood and turned down for the reason the message gives.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "executions.start", "x-majordomus-kind": "command", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::executions" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_execution_start" }, "x-majordomus-cli": "run" } }, "/api/v1/graph": { "get": { "operationId": "graph.get", "summary": "Derive one graph", "description": "One graph by id: its nodes and edges with the vocabularies that say what each kind means, the file every node was derived from, and whether the result is acyclic. Deterministic for a given tree and executable.", "tags": [ "graph" ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The graph's id, as `graph.list` gives it (`registry`, `layer`, `rules`, `adrs`,\n`use-cases`).", "examples": { "adrs": { "value": "adrs" }, "composed": { "value": "composed" }, "layer": { "value": "layer" }, "product": { "value": "product" }, "registry": { "value": "registry" }, "rules": { "value": "rules" }, "use-cases": { "value": "use-cases" }, "why": { "value": "why" } } } ], "responses": { "200": { "description": "Derive one graph: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Graph" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "graph.get", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::graph" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "process", "max_entries": 16 }, "x-majordomus-mcp": { "tool": "majordomus_graph" } } }, "/api/v1/graphs": { "get": { "operationId": "graph.list", "summary": "List graphs", "description": "Every graph this executable derives: its id, what it shows, and what it is derived from.", "tags": [ "graph" ], "parameters": [], "responses": { "200": { "description": "List graphs: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphList" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "graph.list", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::graph" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_graphs", "resource": { "uri": "majordomus://graphs", "name": "graphs" } } } }, "/api/v1/health": { "get": { "operationId": "health.report", "summary": "Health of this process", "description": "Every dimension of what this process serves — the layer as it was read, the registry, the scope, version control, benchmark coverage, the committed registry manifest, the shared server of this checkout and the attached peers — each decided by the engine that owns it, with the command that reproduces the verdict.", "tags": [ "health" ], "parameters": [], "responses": { "200": { "description": "Health of this process: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "health.report", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::health" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "process", "max_entries": 4, "ttl_seconds": 5 }, "x-majordomus-mcp": { "tool": "majordomus_health", "resource": { "uri": "majordomus://health", "name": "health" } } } }, "/api/v1/live": { "get": { "operationId": "health.live", "summary": "Liveness", "description": "Is this process alive: the cheapest true statement this executable can make about itself, with the version that answered. No filesystem traversal, no index build, no network — this is what a hosting platform polls, and it must cost nothing to say.", "tags": [ "health" ], "parameters": [], "responses": { "200": { "description": "Liveness: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Liveness" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "health.live", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::health" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" } } }, "/api/v1/object": { "get": { "operationId": "objects.get", "summary": "Get one object", "description": "One object by URI (majordomus:///): metadata, provenance and content; a URI a query projects (majordomus://repository) answers that query as a JSON document. The same resolution serves the MCP resource read.", "tags": [ "objects" ], "parameters": [ { "name": "uri", "in": "query", "required": true, "schema": { "type": "string" }, "description": "`majordomus:///`, or a URI a query projects\n(`majordomus://repository`).", "examples": { "first-object": { "value": "majordomus://adr/adr-0001" }, "repository": { "value": "majordomus://repository" } } } ], "responses": { "200": { "description": "Get one object: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceView" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "objects.get", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::objects" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_get" } } }, "/api/v1/objects": { "get": { "operationId": "objects.list", "summary": "List objects", "description": "List the declarative objects of the repository's AI layer, optionally by kind or tag.", "tags": [ "objects" ], "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only objects of this kind; the kinds present are listed by `repository.info`. A kind\nthe repository does not have is an invalid input, not an empty answer.", "examples": { "first-kind": { "value": "adr" } } }, { "name": "tag", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only objects whose metadata tags include this tag." } ], "responses": { "200": { "description": "List objects: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectList" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "objects.list", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::objects" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_list" } } }, "/api/v1/objects/verify": { "get": { "operationId": "objects.verify", "summary": "Verify the index against the working tree", "description": "Read every file the layer was built from and compare it with what this process is serving. The index is built once at start-up and kept, which is what makes every other request cost nothing and what makes a file edited afterwards be served as it was; this is how a running server says whether that has happened, without being restarted to find out. A file that is one object is compared byte for byte; a collection file, whose objects the index keeps as members rather than as text, is compared by size, and every finding says which comparison was made. It reads every file of the layer, so it reports its progress file by file and stops when it is asked to.", "tags": [ "objects" ], "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only objects of this kind." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "uint", "minimum": 0 }, "description": "How many objects to read at most; every one of them when absent.", "examples": { "bounded": { "value": 25 } } } ], "responses": { "200": { "description": "Verify the index against the working tree: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyReport" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "objects.verify", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::objects" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_verify_objects" } } }, "/api/v1/obligations": { "get": { "operationId": "obligations.vocabulary", "summary": "Every obligation there is", "description": "The tokens a task may declare in `requires`: what each one asks of a worker, the command that discharges it, the pathspecs its evidence is hashed over, and whether its fact is remote and therefore bound to a commit rather than to a tree. Shipped data, identical in every clone, so this answers in a checkout that has never run the lifecycle.", "tags": [ "obligations" ], "parameters": [], "responses": { "200": { "description": "Every obligation there is: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Vocabulary" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "obligations.vocabulary", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::obligations" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "process", "max_entries": 2 }, "x-majordomus-mcp": { "tool": "majordomus_obligations", "resource": { "uri": "majordomus://obligations", "name": "obligations" } } } }, "/api/v1/obligations/closure": { "get": { "operationId": "obligations.closure", "summary": "What this task still owes", "description": "Every obligation the active task declared, joined with what the vocabulary says about it and with the evidence that does or does not discharge it: what is owed, what is discharged, and what has gone stale — with the recorded input hash and the tree's current one, or the recorded commit and its label, so a reader can see against what. The judgement is the one `finish` applies, reproduced rather than re-decided, and the staleness words are the repository's only four. A checkout with no task reports that, rather than reporting nothing owed.", "tags": [ "obligations" ], "parameters": [], "responses": { "200": { "description": "What this task still owes: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Closure" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "obligations.closure", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::obligations" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "process", "max_entries": 2, "ttl_seconds": 2 }, "x-majordomus-mcp": { "tool": "majordomus_obligation_closure", "resource": { "uri": "majordomus://obligations/closure", "name": "obligation-closure" } } } }, "/api/v1/peers": { "get": { "operationId": "peers.list", "summary": "List peers", "description": "Every client attached to this shared server: id, the client's own name and version from its initialize, transport, when it attached, when it was last seen, and what it announced. In-memory, gone with the process.", "tags": [ "peers" ], "parameters": [], "responses": { "200": { "description": "List peers: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeerList" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "peers.list", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::peers" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_peers" } } }, "/api/v1/peers/announce": { "post": { "operationId": "peers.announce", "summary": "Announce what this peer is working on", "description": "Tell the other peers of this shared server what the calling session is doing and which paths it expects to touch. Changes this process's memory only; the repository is never written. Needs an MCP session: over plain HTTP there is no caller.", "tags": [ "peers" ], "requestBody": { "required": true, "description": "The input of `peers.announce`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnounceInput" }, "examples": { "default": { "value": { "intent": "benchmark: announcing", "scope": [ "apps/majordomus-cli" ] } } } } } }, "responses": { "200": { "description": "Announce what this peer is working on: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Announced" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "422": { "description": "`refused`: The command was understood and turned down for the reason the message gives.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "peers.announce", "x-majordomus-kind": "command", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::peers" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_announce" } } }, "/api/v1/perf": { "get": { "operationId": "perf.counters", "summary": "Performance counters", "description": "The counters of this process: repository scans, index and registry builds, schema generations, projection builds, executions, handler invocations, cache hits, misses and evictions, and the phase timings, as they stand now.", "tags": [ "perf" ], "parameters": [], "responses": { "200": { "description": "Performance counters: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSnapshot" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "perf.counters", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::perf" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_perf" } } }, "/api/v1/plan": { "get": { "operationId": "plan.model", "summary": "The whole derived plan", "description": "Every milestone and issue with its derived status, wave, rank, both directions of its graph and its counts; the execution waves; both dependency graphs as edges; every validation finding; and the plan's header with the active milestone derived. The one value every other capability of this module answers out of. Derived on every call: a transition writes a lifecycle marker into a record between two calls, and a plan answered from a snapshot would send two workers to one issue.", "tags": [ "plan" ], "parameters": [], "responses": { "200": { "description": "The whole derived plan: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "plan.model", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::plan" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_plan", "resource": { "uri": "majordomus://plan", "name": "plan" } } } }, "/api/v1/plan/issues": { "get": { "operationId": "plan.issues", "summary": "The issues, filtered by what the graph derived", "description": "One record per issue with its derived status, its wave, the dependencies it declares, the ones that are not DONE (plus `milestone:` when the gate holds the whole outcome back), the issues that depend on it, the paths it touches and its evidence tally. Filtering by `status: READY` is the ready set and by `status: BLOCKED` the blocked set; nothing here is a separate derivation.", "tags": [ "plan" ], "parameters": [ { "name": "milestone", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only issues of this milestone. Default: every issue of the plan.", "examples": { "one-milestone": { "value": "M000" } } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only issues in this derived status — `READY` for the ready set, `BLOCKED` for the\nblocked set. The vocabulary travels with every answer, so a caller never has to know\nwhich statuses exist.", "examples": { "ready": { "value": "READY" } } }, { "name": "wave", "in": "query", "required": false, "schema": { "type": "integer", "format": "uint32", "minimum": 0 }, "description": "Only issues in this execution wave." } ], "responses": { "200": { "description": "The issues, filtered by what the graph derived: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanIssueList" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "plan.issues", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::plan" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_plan_issues" } } }, "/api/v1/plan/next": { "get": { "operationId": "plan.next", "summary": "The one issue to take now", "description": "The lowest-wave READY issue of the active milestone, highest priority first, then id. The active milestone can have nothing ready while another one does — one waiting on its own acceptance evidence, for instance — so the search widens to the whole plan rather than answering `none` and sending a worker away from work that is genuinely executable. This is what an agent asks before it starts.", "tags": [ "plan" ], "parameters": [ { "name": "milestone", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Restrict the answer to one milestone. Default: the whole plan, and for `next` the\nactive milestone with the rest of the plan as the fallback.", "examples": { "one-milestone": { "value": "M000" } } } ], "responses": { "200": { "description": "The one issue to take now: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanNextIssue" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "plan.next", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::plan" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_plan_next" } } }, "/api/v1/plan/record": { "get": { "operationId": "plan.record", "summary": "One milestone or issue, with everything derived about it", "description": "A milestone with its issues in full, or an issue with the issues it waits on in full. The record's own prose stays where it has always been — `majordomus://issue/` returns the file — and this answers what the file cannot say about itself: what its status is, where it sits in the graph, and what is between it and being executable.", "tags": [ "plan" ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The id of a milestone or an issue, as its file is named (`I0001`, `work-graph-github`).", "examples": { "issue": { "value": "I0001" }, "milestone": { "value": "M000" } } } ], "responses": { "200": { "description": "One milestone or issue, with everything derived about it: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanRecord" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "plan.record", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::plan" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_plan_record" } } }, "/api/v1/plan/roadmap": { "get": { "operationId": "plan.roadmap", "summary": "The milestones in derived order", "description": "The milestone graph laid out by rank, with `order` breaking ties inside a rank only, and the first unblocked unfinished milestone as `now` and the one after it as `next`. Nothing in the sequence is authored: a milestone whose prerequisites are not real cannot be nominated, which is what makes `each step is gated by the previous one being real` an invariant rather than a sentence.", "tags": [ "plan" ], "parameters": [], "responses": { "200": { "description": "The milestones in derived order: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanRoadmap" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "plan.roadmap", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::plan" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_plan_roadmap" } } }, "/api/v1/plan/status": { "get": { "operationId": "plan.status", "summary": "Where the plan stands", "description": "Every milestone with its derived status and its issues counted by status, the milestone a worker is executing now, the next ready issue in full, and the plan's own totals. The counts are keyed by the declared vocabulary, which travels with the answer, so a status added to the engine appears here without anything being edited.", "tags": [ "plan" ], "parameters": [ { "name": "milestone", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Restrict the answer to one milestone. Default: the whole plan, and for `next` the\nactive milestone with the rest of the plan as the fallback.", "examples": { "one-milestone": { "value": "M000" } } } ], "responses": { "200": { "description": "Where the plan stands: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanStatusReport" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "plan.status", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::plan" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_plan_status" } } }, "/api/v1/plan/validate": { "get": { "operationId": "plan.validate", "summary": "What the model refuses", "description": "Every finding the derivation produced, in the order it produced them: a dependency on something that is not an issue, a cycle, an issue executing ahead of its dependencies or of its milestone's gate, an issue with no acceptance criteria, evidence missing under a completion date, a milestone whose graph contradicts itself, two issues of one wave sharing a path. A failure means the model is invalid; a warning means it is legal and worth reading.", "tags": [ "plan" ], "parameters": [], "responses": { "200": { "description": "What the model refuses: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanValidation" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "plan.validate", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::plan" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_plan_validate" } } }, "/api/v1/plan/waves": { "get": { "operationId": "plan.waves", "summary": "What may run at the same time", "description": "The topological layering of the issue graph: an issue enters a wave only once every dependency has left it, so its wave is one past the longest path to it. Sharing a wave is a necessary condition for running two issues at once, not a sufficient one — overlapping scope serialises them, and every such overlap is reported beside the waves rather than left for two workers to discover in a merge conflict.", "tags": [ "plan" ], "parameters": [ { "name": "milestone", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Restrict the answer to one milestone. Default: the whole plan, and for `next` the\nactive milestone with the rest of the plan as the fallback.", "examples": { "one-milestone": { "value": "M000" } } } ], "responses": { "200": { "description": "What may run at the same time: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanWaveReport" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "plan.waves", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::plan" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_plan_waves" } } }, "/api/v1/product/feature": { "get": { "operationId": "product.feature", "summary": "One feature", "description": "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.", "tags": [ "product" ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The feature's id, as `product.features` gives it. This is also its slug and its route.", "examples": { "first-feature": { "value": "benchmarks" } } } ], "responses": { "200": { "description": "One feature: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvedRefs" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "product.feature", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::product" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "process", "max_entries": 64 }, "x-majordomus-mcp": { "tool": "majordomus_feature" }, "x-majordomus-cli": "product show" } }, "/api/v1/product/features": { "get": { "operationId": "product.features", "summary": "The features", "description": "Every product feature this repository declares, narrowed by any of the facets the model derives — featured, area, 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.", "tags": [ "product" ], "parameters": [ { "name": "featured", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Only the features the homepage shows.", "examples": { "featured": { "value": true } } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only features of this status. Absent means the stable ones; pass `any` for\neverything the model holds." }, { "name": "area", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only features serving this operational area.", "examples": { "by-area": { "value": "context" } } }, { "name": "module", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only features made of this capability module." }, { "name": "command", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only features made of this shell command." }, { "name": "surface", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only features exposed through this surface: `cli`, `api`, `mcp`, `cockpit`, `docs`." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Case-insensitive text, matched against the identity, the titles, the headline, the\nsummary, the tags and the body." } ], "responses": { "200": { "description": "The features: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureList" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "product.features", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::product" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "process", "max_entries": 32 }, "x-majordomus-mcp": { "tool": "majordomus_features", "resource": { "uri": "majordomus://product", "name": "product" } }, "x-majordomus-cli": "product list" } }, "/api/v1/product/matrix": { "get": { "operationId": "product.matrix", "summary": "Features against interfaces", "description": "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.", "tags": [ "product" ], "parameters": [], "responses": { "200": { "description": "Features against interfaces: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Matrix" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "product.matrix", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::product" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "process", "max_entries": 2 }, "x-majordomus-mcp": { "tool": "majordomus_product_matrix", "resource": { "uri": "majordomus://product/matrix", "name": "product-matrix" } }, "x-majordomus-cli": "product matrix" } }, "/api/v1/product/providers": { "get": { "operationId": "product.providers", "summary": "The providers", "description": "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.", "tags": [ "product" ], "parameters": [], "responses": { "200": { "description": "The providers: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderList" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "product.providers", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::product" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "process", "max_entries": 2 }, "x-majordomus-mcp": { "tool": "majordomus_providers", "resource": { "uri": "majordomus://product/providers", "name": "providers" } }, "x-majordomus-cli": "product providers" } }, "/api/v1/product/validate": { "get": { "operationId": "product.validate", "summary": "Validate the model", "description": "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.", "tags": [ "product" ], "parameters": [], "responses": { "200": { "description": "Validate the model: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductValidationReport" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "product.validate", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::product" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "process", "max_entries": 2 }, "x-majordomus-mcp": { "tool": "majordomus_product_validate" }, "x-majordomus-cli": "product validate" } }, "/api/v1/quality": { "get": { "operationId": "quality.report", "summary": "Public API quality report", "description": "The crate's exported surface measured against the repository's rules: how many items are documented and exampled, how many modules are documented, exampled and behaviourally tested, how the canonical operations stand against the command line, HTTP, OpenAPI and MCP, and one finding per violation carrying a stable code, the rule that requires it, its file and line, why it matters and what to do about it.", "tags": [ "quality" ], "parameters": [ { "name": "code", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only findings carrying this code (`RUST_PUBLIC_MISSING_EXAMPLE`). All of them when\nabsent. A code nothing recognises is refused rather than answered with an empty\nlist, so a typo cannot read as a clean report." }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only findings whose file path starts with this, repository-relative\n(`apps/majordomus-cli/src/web`). All of them when absent." }, { "name": "summary_only", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Answer with the counts and leave the findings out. For a caller that wants the\nstate of the crate and not the list of what to do about it.", "examples": { "default": { "value": false } } }, { "name": "include_baselined", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Include the findings the ratchet already accepts, which are left out by default.\n\nThe default is what a gate wants: only what is new. This is what a person paying the\ndebt down wants, and it is what `--write-baseline` must ask for — a baseline written\nfrom a report that had the baseline applied to it would empty the file, accepting\nnothing and failing on everything the next time it ran.", "examples": { "default": { "value": false } } } ], "responses": { "200": { "description": "Public API quality report: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QualityAnswer" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "quality.report", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::quality" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "process", "max_entries": 8, "ttl_seconds": 10 }, "x-majordomus-mcp": { "tool": "majordomus_quality", "resource": { "uri": "majordomus://quality", "name": "quality" } }, "x-majordomus-cli": "quality report" } }, "/api/v1/ready": { "get": { "operationId": "health.ready", "summary": "Readiness", "description": "Can this process serve traffic: the registry and the index it built at start-up, already resident, and how the layer read. Only local initialisation — never an external provider, a database or another service, because a readiness check that probes a dependency fails a deployment for something that is not this process.", "tags": [ "health" ], "parameters": [], "responses": { "200": { "description": "Readiness: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Readiness" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "health.ready", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::health" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" } } }, "/api/v1/release/version": { "get": { "operationId": "release.version", "summary": "The version, and the one the commits imply", "description": "The version the crate manifest declares, the version the shell tool prints, and whether they agree — the same question `scripts/release-version --check` gates on. Then the bump the conventional commits since the last release imply, the version it would produce, and the commits themselves as the evidence for it.", "tags": [ "release" ], "parameters": [], "responses": { "200": { "description": "The version, and the one the commits imply: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseVersionReport" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "release.version", "x-majordomus-kind": "query", "x-majordomus-stability": "implemented", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::release" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_release_version" } } }, "/api/v1/repository": { "get": { "operationId": "repository.info", "summary": "Repository and index state", "description": "The repository root, layer sections, git state, discovery mode, kinds present, every diagnostic, and the capability registry counted.", "tags": [ "repository" ], "parameters": [], "responses": { "200": { "description": "Repository and index state: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepositoryReport" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "repository.info", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::repository" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_repository", "resource": { "uri": "majordomus://repository", "name": "repository" } } } }, "/api/v1/scope": { "get": { "operationId": "repository.scope", "summary": "The repository scope", "description": "The scope declaration as read, where it came from (the repository's own or the distribution's default), and every tracked file tallied against it: how many are in, how many are out for each reason, and which.", "tags": [ "repository" ], "parameters": [], "responses": { "200": { "description": "The repository scope: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeReport" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "repository.scope", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::repository" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_scope", "resource": { "uri": "majordomus://scope", "name": "scope" } }, "x-majordomus-cli": "scope" } }, "/api/v1/scope/classify": { "get": { "operationId": "repository.scope_classify", "summary": "Judge a path against the scope", "description": "Whether a repository-relative path is in or out of the scope, the reason when it is out, and the pattern or limit that decided; an existing file is judged by name, then size, then content.", "tags": [ "repository" ], "parameters": [ { "name": "path", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Repository-relative, forward slashes; `./` is stripped. An absolute path or a\n`..` segment is an invalid input.", "examples": { "first-object": { "value": ".ai/repo/adrs/0001-rust-cli-and-stdio-mcp.md" }, "layer-file": { "value": ".ai/manifest.yaml" }, "local-half": { "value": ".ai/local/state/current.yaml" }, "secret": { "value": "config/.env" }, "undeclared": { "value": "node_modules/left-pad/index.js" } } } ], "responses": { "200": { "description": "Judge a path against the scope: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Classification" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "repository.scope_classify", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::repository" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_scope_classify" } } }, "/api/v1/search": { "get": { "operationId": "objects.search", "summary": "Search objects", "description": "Case-insensitive substring search over identities, titles, descriptions and content.", "tags": [ "objects" ], "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Case-insensitive substring, matched against identity, title, description and content.", "examples": { "common-word": { "value": "the" }, "no-hit": { "value": "zqx-nothing-carries-this" } } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only objects of this kind; a kind the repository does not have is an invalid input." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "uint64", "minimum": 1, "maximum": 200 }, "description": "At most this many hits (default 20, at most 200).", "examples": { "no-hit": { "value": 5 } } } ], "responses": { "200": { "description": "Search objects: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "objects.search", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::objects" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "process", "max_entries": 64 }, "x-majordomus-mcp": { "tool": "majordomus_search" } } }, "/api/v1/server": { "get": { "operationId": "server.status", "summary": "The shared server, and every server of the repository", "description": "Where this checkout's server stands — absent, starting, ready, outdated or stale — measured against what this executable would serve; the lease this process holds when it is the server; and every checkout git registers for the repository, the primary first, each with its lease, its standing and the reason, and the peers its server reports. Read from the lease files and the servers on every call; nothing is cached, because the leases are written by other processes.", "tags": [ "server" ], "parameters": [], "responses": { "200": { "description": "The shared server, and every server of the repository: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerStatus" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "server.status", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::server" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_server", "resource": { "uri": "majordomus://server", "name": "server" } }, "x-majordomus-cli": "serve status" } }, "/api/v1/trace": { "get": { "operationId": "trace.report", "summary": "The whole work graph above the branch", "description": "Every issue at least one branch names with its branches and commits, every declared issue no branch names, and the newest stretch of the trunk with each commit attributed to the issue whose branches hold it or reported as unattributed. The tallies count both sides, so the proportion of the trunk that no execution contract accounts for is a number rather than an impression. Read from git on every call: the history changes outside this process.", "tags": [ "trace" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "uint", "minimum": 0 }, "description": "How many trunk commits to attribute, newest first. Default: 50. Anything above 2000\nis read as 2000 — a traceability report is a reading, not a history export.", "examples": { "ten": { "value": 10 } } } ], "responses": { "200": { "description": "The whole work graph above the branch: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraceReport" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "trace.report", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::trace" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_traceability", "resource": { "uri": "majordomus://traceability", "name": "traceability" } } } }, "/api/v1/trace/commit": { "get": { "operationId": "trace.commit", "summary": "What contract this commit served", "description": "One commit with the issue and milestone it served, or the fact that none can be found. Attributed when exactly one issue's branches hold it, ambiguous when branches naming two issues do, and unattributed when no branch naming an issue holds it at all — which is either work committed without an execution contract or a branch deleted after its merge, and the answer says so rather than guessing between them.", "tags": [ "trace" ], "parameters": [ { "name": "commit", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Anything git resolves to a commit: a full or abbreviated object name, a ref, `HEAD`,\n`master~3`.", "examples": { "head": { "value": "HEAD" } } } ], "responses": { "200": { "description": "What contract this commit served: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitAttribution" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "trace.commit", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::trace" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_trace_commit" } } }, "/api/v1/trace/issue": { "get": { "operationId": "trace.issue", "summary": "What realised this issue", "description": "One issue with the branches that name it — local, and remote-tracking where only the remote still has the branch — and, for each, the commits it holds that the trunk did not: measured against the trunk while the branch is open, and against the first parent of the merge commit that brought it in once it is merged. A branch that reached the trunk without a merge commit of its own says so and claims nothing, because its commits cannot be told from the trunk's. The milestone comes from the canonical issue record, which is the one edge here that git does not hold, and `declared` says whether the project model has this id at all — a repository with no plan still gets the branches, and a typo still cannot read as work nobody did.", "tags": [ "trace" ], "parameters": [ { "name": "issue", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The issue id, as the project model spells it (`I1305`). An id the model does not\ndeclare is answered with `declared: false` rather than refused, and rather than\nanswered with a bare empty trace: a typo that read as \"nothing realised this issue\"\nis the one answer this capability must never give.", "examples": { "first-issue": { "value": "I0001" } } } ], "responses": { "200": { "description": "What realised this issue: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueTrace" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "trace.issue", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::trace" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_trace_issue" } } }, "/api/v1/web/surfaces": { "get": { "operationId": "web.surfaces", "summary": "Every web surface, resolved", "description": "The web topology in route-precedence order, with each surface's mount, category, visibility, kind, producer, artifact, runtime feature and the provenance of every value a reader could be surprised by; and which ids are served, published and offered to a person. Answered from the resolution this process serves from, so it cannot disagree with what the router routes or what the home page lists.", "tags": [ "web" ], "parameters": [], "responses": { "200": { "description": "Every web surface, resolved: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SurfaceReport" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "web.surfaces", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::web" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "process", "max_entries": 2, "ttl_seconds": 5 }, "x-majordomus-mcp": { "tool": "majordomus_web_surfaces", "resource": { "uri": "majordomus://web", "name": "web" } } } }, "/api/v1/why": { "get": { "operationId": "why.list", "summary": "The catalogue", "description": "Every operational moment this repository holds, narrowed by any of the facets the catalogue itself reports, with the audiences, the areas, the derived filters and the counts. The default is the public catalogue; pass status=any for the drafts too.", "tags": [ "why" ], "parameters": [ { "name": "audience", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only moments this audience recognises.", "examples": { "by-audience": { "value": "agency" } } }, { "name": "area", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only moments in this operational area." }, { "name": "tag", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only moments carrying this tag." }, { "name": "severity", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only moments of this severity." }, { "name": "frequency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only moments of this frequency." }, { "name": "lifecycle", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only moments at this stage of work." }, { "name": "capability", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only moments naming this capability of the executable." }, { "name": "command", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only moments naming this command." }, { "name": "featured", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Only moments the homepage features." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only moments of this status. Absent means the public ones (`stable`); pass `any`\nfor everything the catalogue holds." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Case-insensitive text, matched against the identity, the titles, the hook, the\nsummary, the tags, the aliases, the signals, the examples and the body.", "examples": { "search": { "value": "context" } } } ], "responses": { "200": { "description": "The catalogue: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogueView" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "why.list", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::why" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "process", "max_entries": 32 }, "x-majordomus-mcp": { "tool": "majordomus_why", "resource": { "uri": "majordomus://why", "name": "why" } }, "x-majordomus-cli": "why list" } }, "/api/v1/why/areas": { "get": { "operationId": "why.areas", "summary": "Operational areas", "description": "Every operational area the catalogue declares, each with the public moments that fall under it. Membership is derived from the moments and is never listed in an area's own file.", "tags": [ "why" ], "parameters": [], "responses": { "200": { "description": "Operational areas: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AreaList" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "why.areas", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::why" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "process", "max_entries": 4 }, "x-majordomus-mcp": { "tool": "majordomus_why_areas", "resource": { "uri": "majordomus://why/areas", "name": "why-areas" } }, "x-majordomus-cli": "why areas" } }, "/api/v1/why/audiences": { "get": { "operationId": "why.audiences", "summary": "Audiences", "description": "Every audience the catalogue declares, each with the public moments that name it. Membership is derived from the moments and is never listed in an audience's own file.", "tags": [ "why" ], "parameters": [], "responses": { "200": { "description": "Audiences: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudienceList" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "why.audiences", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::why" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "process", "max_entries": 4 }, "x-majordomus-mcp": { "tool": "majordomus_why_audiences", "resource": { "uri": "majordomus://why/audiences", "name": "why-audiences" } }, "x-majordomus-cli": "why audiences" } }, "/api/v1/why/diagnose": { "get": { "operationId": "why.diagnose", "summary": "Diagnose a selection", "description": "What a reader's own symptoms imply: the moments the selection resolves to, the operational areas and audiences they weigh towards, and the capabilities, commands, claims, rules and use cases that answer them — each carrying the moments that produced it. Counting, not inference: there is no weighting and no percentage.", "tags": [ "why" ], "parameters": [ { "name": "signals", "in": "query", "required": false, "schema": { "type": "string", "default": "" }, "description": "Signal ids or moment ids, separated by commas. Empty selects nothing and is\nanswered with an empty diagnosis rather than an error.", "examples": { "three-moments": { "value": "abandoned-worktree,api-changed-contract-did-not,code-without-an-issue" } } } ], "responses": { "200": { "description": "Diagnose a selection: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Diagnosis" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "why.diagnose", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::why" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "process", "max_entries": 32 }, "x-majordomus-mcp": { "tool": "majordomus_why_diagnose" }, "x-majordomus-cli": "why diagnose" } }, "/api/v1/why/moment": { "get": { "operationId": "why.moment", "summary": "One moment", "description": "One operational moment in full: what it looks like, why it happens, what it costs, what this tool does about it, and every relation derived from its metadata — the responsibilities its claims belong to, the moments that name it, and the moments nearest it by shared area, audience and tag.", "tags": [ "why" ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The moment's id, as `why.list` gives it. This is also its slug and its route.", "examples": { "first-moment": { "value": "abandoned-worktree" } } } ], "responses": { "200": { "description": "One moment: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MomentDetail" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "why.moment", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::why" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "process", "max_entries": 64 }, "x-majordomus-mcp": { "tool": "majordomus_why_moment" }, "x-majordomus-cli": "why show" } }, "/api/v1/why/validate": { "get": { "operationId": "why.validate", "summary": "Validate the catalogue", "description": "Every finding over the catalogue: a reference that resolves to nothing, with the nearest candidate; a duplicate identity; a file name that disagrees with its id; and a public record that does not meet the floor its status promises. Errors make the catalogue invalid; warnings do not.", "tags": [ "why" ], "parameters": [], "responses": { "200": { "description": "Validate the catalogue: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationReport" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "why.validate", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::why" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "process", "max_entries": 2 }, "x-majordomus-mcp": { "tool": "majordomus_why_validate" }, "x-majordomus-cli": "why validate" } }, "/api/v1/worktrees": { "get": { "operationId": "worktree.topology", "summary": "The whole topology", "description": "The repository, the container, the trunk and how it was decided, every registered worktree with its standing (primary, canonical, misplaced, detached, missing), its uncommitted work, its upstream distance and the issue its branch provably names, every local branch with or without a worktree and whether it is eligible for cleanup, every diagnostic with its code and remedy, and the tallies. Read from git on every call: the topology changes outside this process.", "tags": [ "worktree" ], "parameters": [], "responses": { "200": { "description": "The whole topology: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepositoryTopology" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "worktree.topology", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::worktree" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_worktrees", "resource": { "uri": "majordomus://worktrees", "name": "worktrees" } }, "x-majordomus-cli": "worktree topology" } }, "/api/v1/worktrees/inspect": { "get": { "operationId": "worktree.inspect", "summary": "One branch: where its worktree belongs and what is there", "description": "The canonical path of a branch, derived from its name alone, whether the branch exists, whether something occupies that path, the worktree holding the branch when one does, and what stands in the way of creating or migrating it. The answer for a branch that does not exist yet is the path `worktree create` would use.", "tags": [ "worktree" ], "parameters": [ { "name": "branch", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The branch, full name (`feature/improve-cli`). It need not exist: the canonical path\nderives from the name alone.", "examples": { "feature-branch": { "value": "feature/example" } } } ], "responses": { "200": { "description": "One branch: where its worktree belongs and what is there: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InspectReport" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "worktree.inspect", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::worktree" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_worktree_inspect" }, "x-majordomus-cli": "worktree inspect" } }, "/api/v1/worktrees/migration": { "get": { "operationId": "worktree.migration_plan", "summary": "What it would take to bring every worktree home", "description": "One step per misplaced worktree with a branch: where it is, where it belongs, how it would move, the uncommitted work that moves with it, and what blocks it; plus the exceptions the migration cannot address by design — detached worktrees, stale registrations, the primary checkout off the trunk — each with what a person does about it. Planning changes nothing; `majordomus worktree migrate` applies it with a fingerprint taken before and after every move.", "tags": [ "worktree" ], "parameters": [], "responses": { "200": { "description": "What it would take to bring every worktree home: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MigrationPlan" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "worktree.migration_plan", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::worktree" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_worktree_migration_plan" }, "x-majordomus-cli": "worktree migrate" } }, "/api/v1/worktrees/status": { "get": { "operationId": "worktree.status", "summary": "Where this is, and whether that is where it belongs", "description": "One worktree — the repository's own, or the one holding the directory the caller names — with its standing, its branch, its canonical path, its uncommitted work counted, whether it is where it belongs, and how many errors the whole topology carries. What an agent reads before it starts, and what the guard decides on.", "tags": [ "worktree" ], "parameters": [ { "name": "path", "in": "query", "required": false, "schema": { "type": "string" }, "description": "A directory inside one of this repository's worktrees; the answer is about that\nworktree. Relative to the primary checkout when relative (`.` is the primary\ncheckout itself). Default: the repository the server was started for. A path in\nanother repository is refused: the topology answers only about its own.", "examples": { "primary-checkout": { "value": "." } } } ], "responses": { "200": { "description": "Where this is, and whether that is where it belongs: the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusReport" } } } }, "400": { "description": "`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: The input names something the repository does not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "description": "`internal`: The capability failed for a reason of its own; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "default": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "x-majordomus-id": "worktree.status", "x-majordomus-kind": "query", "x-majordomus-stability": "behaviorally_verified", "x-majordomus-provenance": { "source": "builtin", "module": "majordomus_cli::capability::builtin::worktree" }, "x-majordomus-benchmark": { "policy": "required" }, "x-majordomus-cache": { "policy": "disabled" }, "x-majordomus-mcp": { "tool": "majordomus_worktree_status" }, "x-majordomus-cli": "worktree status" } } }, "components": { "schemas": { "ActiveTask": { "type": "object", "properties": { "id": { "type": "string", "description": "The task id." }, "task": { "type": "string", "description": "What is being worked on." }, "profile": { "type": "string", "description": "The execution profile it runs under." }, "outcome": { "type": "string", "description": "Its typed outcome so far: `active`, `handed_over`, or a finished one." }, "scope": { "type": "array", "items": { "type": "string" }, "description": "The paths it claims." }, "requires": { "type": "array", "items": { "type": "string" }, "description": "The obligations it owes before the outcome `completed` is available.\n\nBeside `scope` and not inside it, because the two are different promises: scope is\ncontainment — where a worker may write — and this is delivery. A change can sit\nentirely inside its scope and still be uncommitted on a laptop (ADR 0030).\n[`super::obligations`] is what judges each of these against its evidence; here it\nis reported as declared." }, "started_at": { "type": "string", "description": "When it started." }, "head": { "type": "string", "description": "The commit it started at." } }, "required": [ "id", "task", "profile", "outcome" ], "description": "The active task of this checkout, when there is one." }, "Actor": { "type": "object", "properties": { "kind": { "$ref": "#/components/schemas/ActorKind", "description": "Where the request came from." }, "peer": { "type": [ "string", "null" ], "description": "The peer id, for a call that arrived through an MCP session." } }, "required": [ "kind" ], "description": "Who asked, and which peer they are when this process knows." }, "ActorKind": { "oneOf": [ { "type": "string", "const": "http", "description": "An HTTP client, which includes the Cockpit." }, { "type": "string", "const": "mcp", "description": "An MCP client attached to this process." }, { "type": "string", "const": "cli", "description": "The command line of this process." }, { "type": "string", "const": "internal", "description": "This executable's own tests and benchmarks." } ], "description": "Who asked for the execution. Not an authorisation decision — this server authenticates\nnobody — but a fact worth carrying into the audit line and the UI." }, "AdrRef": { "type": "object", "properties": { "id": { "type": "string", "description": "The declared id." }, "title": { "type": "string", "description": "The title." }, "status": { "type": "string", "description": "`proposed`, `accepted`, `superseded` or `rejected`." }, "path": { "type": "string", "description": "Repository-relative path." } }, "required": [ "id", "title", "status", "path" ], "description": "One architecture decision the feature names." }, "AnnounceInput": { "type": "object", "additionalProperties": false, "properties": { "intent": { "type": "string", "description": "One line, in the peer's words: the task, the question, the intent." }, "scope": { "type": "array", "items": { "type": "string" }, "description": "Repository-relative paths the peer expects to touch. Informational: other peers\nread it to avoid a collision; nothing here enforces it.", "default": [] } }, "required": [ "intent" ], "description": "The input of `peers.announce`: what the calling peer is working on." }, "Announced": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/PeerId", "description": "`p1`, `p2`, ..." }, "client": { "$ref": "#/components/schemas/ClientInfo", "description": "The client behind it." }, "transport": { "$ref": "#/components/schemas/Transport", "description": "How it is attached." }, "connected_at": { "type": "string", "description": "When it attached, RFC 3339, UTC." }, "last_seen_seconds_ago": { "type": "integer", "format": "uint64", "minimum": 0, "description": "Seconds since its last message." }, "attached": { "type": "boolean", "description": "Whether the session is still attached. A peer that announced something and then\nwent away is kept and listed with `attached: false`: what it said it was working on\noutlives the connection that said it, because the work does." }, "announcement": { "anyOf": [ { "$ref": "#/components/schemas/Announcement" }, { "type": "null" } ], "description": "Its announcement, when it made one." }, "overlaps": { "type": "array", "items": { "$ref": "#/components/schemas/Overlap" }, "description": "Every other peer whose claimed scope meets this one. Empty is the ordinary case." } }, "required": [ "id", "client", "transport", "connected_at", "last_seen_seconds_ago", "attached" ], "description": "What `announce` answers: the peer as recorded, and who else is on that ground." }, "Announcement": { "type": "object", "properties": { "intent": { "type": "string", "description": "One line: the task or intent, in the peer's words." }, "scope": { "type": "array", "items": { "type": "string" }, "description": "Repository-relative paths the peer expects to touch; informational, never enforced here." }, "at": { "type": "string", "description": "When it was announced, RFC 3339, UTC." } }, "required": [ "intent", "scope", "at" ], "description": "What a peer said it is working on." }, "AnswerView": { "type": "object", "properties": { "uri": { "type": "string", "description": "The URI as given." }, "id": { "type": "string", "description": "The capability that answered (`repository.info`)." }, "kind": { "$ref": "#/components/schemas/CapabilityKind", "description": "Its kind: `query`." }, "identity": { "type": "string", "description": "The resource name a client lists (`repository`)." }, "title": { "type": "string", "description": "The capability's title." }, "description": { "type": [ "string", "null" ], "description": "The capability's description, when it has one." }, "answer": { "description": "The answer, as the capability's output schema describes it (`capabilities.describe`\ncarries that schema)." }, "provenance": { "$ref": "#/components/schemas/CapabilityProvenance", "description": "Where the capability comes from: the Rust module it is composed in." }, "media_type": { "type": "string", "description": "`application/json`." }, "content": { "type": "string", "description": "The answer as text: byte for byte what `resources/read` returns for the URI." } }, "required": [ "uri", "id", "kind", "identity", "title", "answer", "provenance", "media_type", "content" ], "description": "A URI a query projects (`majordomus://repository`), answered: the same fields a client\nreads on an [`ObjectView`] where they apply, the answer itself as data, and the text\n`resources/read` returns for the URI." }, "Arch": { "oneOf": [ { "type": "string", "const": "x86_64", "description": "64-bit x86, detected as `x86_64` or `amd64`." }, { "type": "string", "const": "aarch64", "description": "64-bit ARM, detected as `aarch64` or `arm64`." } ], "description": "A processor architecture." }, "AreaList": { "type": "object", "properties": { "count": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many." }, "areas": { "type": "array", "items": { "$ref": "#/components/schemas/AreaView" }, "description": "Each, with its derived membership, in presentation order." } }, "required": [ "count", "areas" ], "description": "Every area." }, "AreaView": { "type": "object", "properties": { "id": { "type": "string", "description": "The identity, the slug and the file name." }, "title": { "type": "string", "description": "The area." }, "summary": { "type": "string", "description": "One line: what falls under it." }, "status": { "type": "string", "description": "`stable`, `draft` or `deprecated`." }, "weight": { "type": "integer", "format": "uint32", "minimum": 0, "description": "Presentation order.", "default": 0 }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free tags.", "default": [] }, "route": { "type": "string", "description": "Derived: `/why/areas//`.", "default": "" }, "source": { "type": "string", "description": "Derived: the file it came from.", "default": "" }, "body": { "type": "string", "description": "The Markdown body." }, "moments": { "type": "array", "items": { "type": "string" }, "description": "Derived: the public moments that fall under it, in presentation order." }, "count": { "type": "integer", "format": "uint", "minimum": 0, "description": "Derived: how many." } }, "required": [ "id", "title", "summary", "status", "moments", "count" ], "description": "One area, with the membership nobody authored." }, "ArtifactFormat": { "oneOf": [ { "type": "string", "const": "json", "description": "A JSON document: pretty-printed, one trailing newline, provenance as members." }, { "type": "string", "const": "yaml", "description": "The same document in the layer's YAML, provenance as a comment banner." }, { "type": "string", "const": "markdown", "description": "Markdown for a reader, provenance as an HTML comment." }, { "type": "string", "const": "text", "description": "Line-oriented text another program reads: the shell tool's allow-lists,\nprovenance as `#` comments." } ], "description": "The encoding one generated artifact is written in." }, "ArtifactReport": { "type": "object", "properties": { "manifest": { "type": "string", "description": "The manifest this was read from, repository-relative." }, "present": { "type": "boolean", "description": "Whether the manifest is committed in this repository at all. A repository that has\nnever run `majordomus generate` has no generated tree, which is a fact about it and\nnot a failure of this call: every list below is then empty and every tally zero." }, "schema": { "type": "string", "description": "The schema the manifest carries, empty when there is none to read." }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentView" }, "description": "The documents, in the manifest's order." }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/ArtifactView" }, "description": "The files, in the manifest's order, after any filter." }, "tallies": { "$ref": "#/components/schemas/ArtifactTallies", "description": "The counts." }, "regenerate": { "type": "string", "description": "The command that rewrites every one of them." }, "verify": { "type": "string", "description": "The command that decides staleness byte for byte, which is stronger than the hash." } }, "required": [ "manifest", "present", "schema", "documents", "artifacts", "tallies", "regenerate", "verify" ], "description": "The answer of `artifacts.list`." }, "ArtifactState": { "oneOf": [ { "type": "string", "const": "current", "description": "The file is there and its bytes hash to what the manifest recorded." }, { "type": "string", "const": "stale", "description": "The file is there and its bytes differ: it was edited, or the generator moved on." }, { "type": "string", "const": "missing", "description": "The manifest names it and the tree does not have it." }, { "type": "string", "const": "present", "description": "The file is there and the manifest records no hash for it: the manifest's own\nencodings, which cannot hash themselves. `generate --check` compares them." } ], "description": "Where one generated file stands against the tree it is committed in." }, "ArtifactTallies": { "type": "object", "properties": { "documents": { "type": "integer", "format": "uint", "minimum": 0, "description": "Documents in the manifest." }, "artifacts": { "type": "integer", "format": "uint", "minimum": 0, "description": "Files in the manifest, after any filter." }, "current": { "type": "integer", "format": "uint", "minimum": 0, "description": "Hashes that match." }, "stale": { "type": "integer", "format": "uint", "minimum": 0, "description": "Hashes that do not." }, "missing": { "type": "integer", "format": "uint", "minimum": 0, "description": "Files the manifest names and the tree lacks." }, "present": { "type": "integer", "format": "uint", "minimum": 0, "description": "Files the manifest records no hash for." } }, "required": [ "documents", "artifacts", "current", "stale", "missing", "present" ], "description": "How many of each, so a caller needs no arithmetic of its own." }, "ArtifactView": { "type": "object", "properties": { "path": { "type": "string", "description": "Repository-relative path." }, "document": { "type": "string", "description": "The document it projects." }, "format": { "$ref": "#/components/schemas/ArtifactFormat", "description": "The encoding." }, "schema": { "type": [ "string", "null" ], "description": "The JSON Schema its content satisfies, when it declares one." }, "source": { "type": "string", "description": "One line: what it was derived from." }, "bytes": { "type": [ "integer", "null" ], "format": "uint64", "minimum": 0, "description": "The size the manifest recorded." }, "sha256": { "type": [ "string", "null" ], "description": "The hash the manifest recorded." }, "state": { "$ref": "#/components/schemas/ArtifactState", "description": "Where the file stands against it." } }, "required": [ "path", "document", "format", "source", "state" ], "description": "One generated file, as the manifest declares it and as the tree has it." }, "Attribution": { "oneOf": [ { "type": "string", "const": "attributed", "description": "Exactly one issue's branches contain it." }, { "type": "string", "const": "unattributed", "description": "No branch naming an issue contains it." }, { "type": "string", "const": "ambiguous", "description": "Branches naming more than one issue contain it." } ], "description": "What is known about the contract one commit served." }, "AudienceList": { "type": "object", "properties": { "count": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many." }, "audiences": { "type": "array", "items": { "$ref": "#/components/schemas/AudienceView" }, "description": "Each, with its derived membership, in presentation order." } }, "required": [ "count", "audiences" ], "description": "Every audience." }, "AudienceView": { "type": "object", "properties": { "id": { "type": "string", "description": "The identity, the slug and the file name." }, "title": { "type": "string", "description": "Who they are." }, "short_title": { "type": [ "string", "null" ], "description": "Two or three words for a filter chip." }, "summary": { "type": "string", "description": "One line: the working situation." }, "workflow": { "type": [ "string", "null" ], "description": "One line: how work flows for them." }, "status": { "type": "string", "description": "`stable`, `draft` or `deprecated`." }, "weight": { "type": "integer", "format": "uint32", "minimum": 0, "description": "Presentation order.", "default": 0 }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free tags.", "default": [] }, "route": { "type": "string", "description": "Derived: `/why/audiences//`.", "default": "" }, "source": { "type": "string", "description": "Derived: the file it came from.", "default": "" }, "body": { "type": "string", "description": "The Markdown body." }, "moments": { "type": "array", "items": { "type": "string" }, "description": "Derived: the public moments that name it, in presentation order." }, "count": { "type": "integer", "format": "uint", "minimum": 0, "description": "Derived: how many." } }, "required": [ "id", "title", "summary", "status", "moments", "count" ], "description": "One audience, with the membership nobody authored." }, "BenchmarkPolicy": { "oneOf": [ { "type": "object", "properties": { "policy": { "type": "string", "const": "required" } }, "required": [ "policy" ], "description": "Timed directly and through every exposure; coverage fails without a case." }, { "type": "object", "properties": { "reason": { "$ref": "#/components/schemas/WaiverReason", "description": "Why." }, "policy": { "type": "string", "const": "waived" } }, "required": [ "policy", "reason" ], "description": "Not timed, for the typed reason; coverage reports it as waived, never as covered." } ], "description": "Whether the capability is a benchmark target. `Required` is the default and the norm:\nevery executable capability is timed directly and through every transport it is\nexposed on, with the cases its input type provides." }, "BranchState": { "type": "object", "properties": { "name": { "type": "string", "description": "The branch, short." }, "head": { "type": "string", "description": "The commit it points at." }, "trunk": { "type": "boolean", "description": "This branch is the trunk." }, "expected_path": { "type": [ "string", "null" ], "description": "Where its work tree belongs." }, "worktree": { "type": [ "string", "null" ], "description": "Where it is checked out, when it is." }, "upstream": { "anyOf": [ { "$ref": "#/components/schemas/UpstreamState" }, { "type": "null" } ], "description": "The upstream and its distance." }, "merged_into_trunk": { "type": [ "boolean", "null" ], "description": "Reachable from the trunk. Absent when the trunk is unknown." }, "cleanup_eligible": { "type": "boolean", "description": "Merged into the trunk, not the trunk, and either not checked out or checked out in a\nwork tree known to be clean. Derived state, never acted on automatically." }, "issue": { "type": [ "string", "null" ], "description": "The issue this branch provably names." } }, "required": [ "name", "head", "trunk", "cleanup_eligible" ], "description": "One local branch, with or without a work tree." }, "BranchTrace": { "type": "object", "properties": { "name": { "type": "string", "description": "The ref, short: `feature/I1305-traceability`, or `origin/feature/I1305-traceability`\nwhen only the remote still has it." }, "remote": { "type": "boolean", "description": "True when the ref is a remote-tracking one and no local branch of the same name\nstands for it." }, "head": { "type": "string", "description": "The commit the ref points at." }, "integration": { "$ref": "#/components/schemas/Integration", "description": "How it stands to the trunk." }, "merge_commit": { "type": [ "string", "null" ], "description": "The merge commit that brought it into the trunk, when one did." }, "note": { "type": [ "string", "null" ], "description": "Why the commit list is what it is, when it is worth a sentence." }, "commits": { "type": "array", "items": { "$ref": "#/components/schemas/CommitRef" }, "description": "The commits this branch holds and the trunk did not, newest first, merges excluded." } }, "required": [ "name", "remote", "head", "integration", "commits" ], "description": "One branch that names an issue, with the commits it holds." }, "Budgets": { "type": "object", "additionalProperties": false, "properties": { "image_bytes": { "anyOf": [ { "$ref": "#/components/schemas/Positive" }, { "type": "null" } ], "description": "Largest accepted compressed image size.", "default": null }, "binary_bytes": { "anyOf": [ { "$ref": "#/components/schemas/Positive" }, { "type": "null" } ], "description": "Largest accepted stripped binary size.", "default": null }, "build_context_bytes": { "anyOf": [ { "$ref": "#/components/schemas/Positive" }, { "type": "null" } ], "description": "Largest accepted build context.", "default": null }, "cold_start_ms": { "anyOf": [ { "$ref": "#/components/schemas/Positive" }, { "type": "null" } ], "description": "Longest accepted time from a stopped machine to a served response.", "default": null }, "resident_memory_mb": { "anyOf": [ { "$ref": "#/components/schemas/Positive" }, { "type": "null" } ], "description": "Largest accepted resident set under load.", "default": null }, "blocking_check_ms": { "anyOf": [ { "$ref": "#/components/schemas/Positive" }, { "type": "null" } ], "description": "Longest accepted time for one liveness or readiness check.", "default": null }, "request_p99_ms": { "anyOf": [ { "$ref": "#/components/schemas/Positive" }, { "type": "null" } ], "description": "Longest accepted p99 for a served request.", "default": null } }, "description": "The measured figures this deployment is held to. Each is written by the run that\nmeasured it; an absent one has not been measured yet and is not a licence." }, "Build": { "type": "object", "additionalProperties": false, "properties": { "package": { "type": "string", "description": "The Cargo package that is built." }, "binary": { "type": "string", "description": "The binary target the image runs." }, "profile": { "type": "string", "description": "The Cargo profile the image is built under." }, "inputs": { "type": "array", "items": { "type": "string" }, "description": "The repository-relative paths the build context carries, and the only ones." }, "site": { "type": [ "string", "null" ], "description": "The directory the canonical site pipeline writes; absent means the image serves no\nsite.", "default": null } }, "required": [ "package", "binary", "profile", "inputs" ], "description": "What is shipped and what it is built from." }, "BuildReport": { "type": "object", "properties": { "version": { "type": "string", "description": "The version of the crate this executable was built from." }, "target": { "type": "string", "description": "The Rust target triple it was built for; the model names a target by the same string." }, "profile": { "type": "string", "description": "The cargo profile." }, "commit": { "type": "string", "description": "The commit, or `unknown` when it was built outside a work tree." }, "distribution_target": { "type": [ "string", "null" ], "description": "The target of the model this build matches, when the model declares one for the triple." } }, "required": [ "version", "target", "profile", "commit" ], "description": "What this executable is: enough to tell two builds apart without asking a repository." }, "CachePolicy": { "oneOf": [ { "type": "object", "properties": { "policy": { "type": "string", "const": "disabled" } }, "required": [ "policy" ], "description": "Every call runs the handler." }, { "type": "object", "properties": { "max_entries": { "type": "integer", "format": "uint", "minimum": 0, "description": "The most entries kept for this capability; the oldest is evicted first." }, "ttl_seconds": { "type": [ "integer", "null" ], "format": "uint64", "minimum": 0, "description": "Seconds an entry stays valid; `None` for the life of the process." }, "policy": { "type": "string", "const": "process" } }, "required": [ "policy", "max_entries" ], "description": "Results are kept in this process's memory, bounded, for equal inputs." } ], "description": "Whether, and how, the executor keeps results of this capability. Cache lives in the\nexecutor and nowhere else, so MCP, HTTP and the command line share one; the key is the\ncanonical id, the normalised input and the registry fingerprint, so a changed\nrepository never answers from an old entry." }, "CancelInput": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The execution's id." } }, "required": [ "id" ], "description": "The input of `executions.cancel`." }, "CancelReport": { "type": "object", "properties": { "outcome": { "type": "string", "description": "What asking achieved: `requested`, `already_requested` or `already_finished`." }, "cancellable": { "type": "boolean", "description": "Whether the capability declares that it looks at its cancellation flag. When it\ndoes not, the request is recorded and the execution runs to completion." }, "execution": { "$ref": "#/components/schemas/ExecutionView", "description": "The execution as it stands after the request." } }, "required": [ "outcome", "cancellable", "execution" ], "description": "The answer of `executions.cancel`." }, "CanonicalSchema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "The component name projections use (`RepositoryInfo`); `None` for an anonymous\nschema such as the empty input." }, "schema": { "description": "The schema itself, without `$schema`; nested types live under `$defs`." } }, "required": [ "schema" ], "description": "A JSON Schema with, when the type has one, a stable component name (the type's title)." }, "Capability": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/CapabilityId", "description": "The canonical identity." }, "module": { "$ref": "#/components/schemas/ModuleId", "description": "The module that composes it: the id's namespace for a builtin, the kind for a\ndeclarative object." }, "kind": { "$ref": "#/components/schemas/CapabilityKind", "description": "Query, command or resource." }, "title": { "type": "string", "description": "The short name every projection shows." }, "description": { "type": "string", "description": "The one-paragraph description every projection shows." }, "input": { "$ref": "#/components/schemas/CanonicalSchema", "description": "The canonical schema of the input; an empty object for a resource." }, "output": { "$ref": "#/components/schemas/CanonicalSchema", "description": "The canonical schema of the output; the object view for a resource." }, "provenance": { "$ref": "#/components/schemas/CapabilityProvenance", "description": "Where it came from." }, "exposure": { "$ref": "#/components/schemas/Exposure", "description": "Where it is projected; absence is explicit." }, "availability": { "$ref": "#/components/schemas/CapabilityAvailability", "description": "Where it means anything: classified from the kind and the transports above, so\nthat a projection reads a field instead of deciding for itself." }, "visibility": { "$ref": "#/components/schemas/CapabilityVisibility", "description": "Who it is for: classified from the same transports." }, "stability": { "$ref": "#/components/schemas/Stability", "description": "Where it stands." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free tags, from the declarative object's `tags` or the descriptor." }, "benchmark": { "$ref": "#/components/schemas/BenchmarkPolicy", "description": "Whether it is a benchmark target; the cases come from the input type." }, "cache": { "$ref": "#/components/schemas/CachePolicy", "description": "Whether the executor keeps its results." }, "execution": { "$ref": "#/components/schemas/ExecutionPolicy", "description": "What running it as an execution means: classified from the kind, so that a client\nreads a fact rather than deciding for itself." } }, "required": [ "id", "module", "kind", "title", "description", "input", "output", "provenance", "exposure", "availability", "visibility", "stability", "benchmark", "cache", "execution" ], "description": "The canonical descriptor. Everything a projection may say about a capability is here." }, "CapabilityAvailability": { "oneOf": [ { "type": "string", "const": "always", "description": "True in every environment, a published page with no server included: the layer's\nown content, which a build renders and a process serves from the same index." }, { "type": "string", "const": "runtime", "description": "A process must be running to answer: everything with a handler, whether it is\nreached over HTTP, over MCP or from the command line." }, { "type": "string", "const": "build_time", "description": "A value captured when the site was generated, rendered afterwards as the capture\nit is. Nothing classifies to this yet; the static projection of the graph is what\nwill declare it, and it is on the model so that a captured value can be labelled\nas captured instead of being shown as current." }, { "type": "string", "const": "authenticated", "description": "A process must be running and the caller must be one it has authenticated. Nothing\nin this repository authenticates a caller yet; a surface that does will say so\nhere rather than in the template that renders its link." } ], "description": "Where a capability means anything: the environment a caller must be in for it to\nanswer at all.\n\nThe published site and the running server are genuinely different places. Without this\non the model, every template grows its own idea of what works where — and the usual\nshape that takes is a condition on the page's own address, which is a rule hidden\nwhere nobody will find it and nothing can test it. This is the only thing a projection\nmay ask.\n\nIt is classified rather than declared: the facts that decide it — what kind of thing\nthis is and which transports it is projected through — are already on the descriptor,\nand asking each declaration to restate them would be the same knowledge written twice.\n[`Availability::classify`] is the one place the rule lives." }, "CapabilityId": { "type": "string", "description": "A stable, globally meaningful identity: a namespace, a dot, and a local part.\n`repository.info` and `objects.get` for executables; `.` for a\ndeclarative object (`rule.majordomus.scope-integrity@1`, `document.docs/CLI.md`,\n`policy..ai/repo/policy.yaml`).\n\nGrammar: the namespace matches `[a-z][a-z0-9_-]*`; the local part is non-empty and\ncarries no whitespace or control character, any other Unicode included, because it is\nopaque: a path, a versioned identity, or a name, as the kind's identity rule produced it." }, "CapabilityKind": { "oneOf": [ { "type": "string", "const": "query", "description": "Executable and read-only: a typed handler, an input schema, an output schema." }, { "type": "string", "const": "command", "description": "Executable with an effect on this process's in-memory state and nowhere else (a\npeer announcing itself): a typed handler, bound to `POST` over HTTP, and announced\nto MCP clients as not read-only." }, { "type": "string", "const": "resource", "description": "Declarative content the repository holds: read as it is, never executed." } ], "description": "What a capability is. Three kinds exist because three semantics exist: something that\nis executed and changes nothing, something that is executed and changes this process's\nown memory, and something that is read. Nothing of any kind writes to the repository.\n\nHow *long* a call takes is not a kind. A read that walks every file of the layer is\nstill a read, and the thing that makes it worth watching — that it reports as it goes\nand stops when it is asked to — is one property of its handler, declared with\n[`crate::capability::Executable::cancellable`] and carried on [`ExecutionPolicy`]." }, "CapabilityList": { "type": "object", "properties": { "count": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many capabilities matched the filters." }, "summary": { "$ref": "#/components/schemas/Summary", "description": "The whole registry, counted by kind, stability and projection." }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/CapabilitySummary" }, "description": "The matching capabilities, by id, without their schemas." } }, "required": [ "count", "summary", "capabilities" ], "description": "The answer of `capabilities.list`: the matching capabilities, summarised, and the\nregistry counted." }, "CapabilityProvenance": { "oneOf": [ { "type": "object", "properties": { "module": { "type": "string", "description": "The Rust module the descriptor was composed in." }, "source": { "type": "string", "const": "builtin" } }, "required": [ "source", "module" ], "description": "Written in Rust, in the named module of this executable.\nWritten in Rust, composed in `builtin.rs`." }, { "type": "object", "properties": { "path": { "type": "string", "description": "Repository-relative path." }, "directory": { "type": "string", "description": "The directory the path sits in, repository-relative; `.` for the root." }, "source_class": { "type": "string", "description": "The `sources.yaml` class that discovered the file." }, "section": { "type": [ "string", "null" ], "description": "The manifest section the path falls under, when it falls under one." }, "media_type": { "type": "string", "description": "IANA media type of the object's content." }, "member": { "type": [ "string", "null" ], "description": "For one member of a collection file, its key path in the file (`claims.3`)." }, "source": { "type": "string", "const": "declarative" } }, "required": [ "source", "path", "directory", "source_class", "media_type" ], "description": "Read from the repository's layer." } ], "description": "Where a capability came from. Never an absolute path." }, "CapabilityRef": { "type": "object", "properties": { "id": { "type": "string", "description": "The canonical id." }, "title": { "type": "string", "description": "The title." }, "kind": { "type": "string", "description": "`query`, `command` or `resource`." }, "stability": { "type": "string", "description": "Where it stands." }, "tool": { "type": [ "string", "null" ], "description": "The MCP tool name, when exposed as one." }, "resource": { "type": [ "string", "null" ], "description": "The MCP resource URI, when exposed as one." }, "route": { "type": [ "string", "null" ], "description": "`METHOD /path`, when exposed over HTTP." }, "cli": { "type": [ "string", "null" ], "description": "The words after `majordomus`, when exposed on the command line." } }, "required": [ "id", "title", "kind", "stability" ], "description": "One capability of a module the feature names, with the projections the registry\ndeclares for it." }, "CapabilitySummary": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/CapabilityId", "description": "The canonical identity." }, "module": { "$ref": "#/components/schemas/ModuleId", "description": "The module that composes it." }, "kind": { "$ref": "#/components/schemas/CapabilityKind", "description": "Query, command or resource." }, "title": { "type": "string", "description": "The short name." }, "description": { "type": "string", "description": "The one-paragraph description." }, "provenance": { "$ref": "#/components/schemas/CapabilityProvenance", "description": "Where it came from." }, "exposure": { "$ref": "#/components/schemas/Exposure", "description": "Where it is projected." }, "stability": { "$ref": "#/components/schemas/Stability", "description": "Where it stands." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free tags." }, "benchmark": { "$ref": "#/components/schemas/BenchmarkPolicy", "description": "Whether it is a benchmark target." }, "cache": { "$ref": "#/components/schemas/CachePolicy", "description": "Whether the executor keeps its results." } }, "required": [ "id", "module", "kind", "title", "description", "provenance", "exposure", "stability", "benchmark", "cache" ], "description": "One capability as a listing shows it: everything the descriptor says except its two\nschemas, which `capabilities.describe` answers for one capability. A listing of a\nrepository's registry runs to hundreds of entries; their schemas would be megabytes\nof the same object view repeated." }, "CapabilityVisibility": { "oneOf": [ { "type": "string", "const": "public", "description": "Offered to anyone who can reach the process: an HTTP route or an MCP entry." }, { "type": "string", "const": "developer", "description": "Offered to whoever runs the executable, and to nobody over a network." }, { "type": "string", "const": "internal", "description": "Projected nowhere. It exists, it is listed as existing, and no surface offers it." } ], "description": "Who a capability is for, and whether anything offers it.\n\nInternal is a statement, not an omission: a capability nothing projects is invisible\neither way, and the difference between deliberate and forgotten is exactly what this\nrecords." }, "Carries": { "oneOf": [ { "type": "string", "const": "text", "description": "Text: held to [`MINIMUM_TEXT`]." }, { "type": "string", "const": "non_text", "description": "A border or an outline: measured against [`MINIMUM_NON_TEXT`], reported, not enforced." } ], "description": "What a colour is doing where it was found." }, "CatalogueView": { "type": "object", "properties": { "schema": { "type": "string", "description": "[`SCHEMA`]." }, "fingerprint": { "type": "string", "description": "The hash of the catalogue's own sources: stable for a tree, and independent of the\nrest of the index, so two runs over one tree agree." }, "counts": { "$ref": "#/components/schemas/Counts", "description": "The counts." }, "moments": { "type": "array", "items": { "$ref": "#/components/schemas/MomentSummary" }, "description": "The matching moments, in presentation order." }, "audiences": { "type": "array", "items": { "$ref": "#/components/schemas/AudienceView" }, "description": "Every audience, with its derived membership." }, "areas": { "type": "array", "items": { "$ref": "#/components/schemas/AreaView" }, "description": "Every area, with its derived membership." }, "facets": { "$ref": "#/components/schemas/Facets", "description": "The filters, derived from the records." } }, "required": [ "schema", "fingerprint", "counts", "moments", "audiences", "areas", "facets" ], "description": "The whole catalogue as a client reads it." }, "Category": { "type": "object", "additionalProperties": false, "properties": { "paths": { "type": "array", "items": { "type": "string" }, "description": "Pathspecs anchored at the repository root.", "default": [] }, "names": { "type": "array", "items": { "type": "string" }, "description": "Patterns matched against the file name alone.", "default": [] } }, "description": "One category of `out`: pathspecs and file-name patterns." }, "Channel": { "oneOf": [ { "type": "string", "const": "stable", "description": "Resolved by `latest`." }, { "type": "string", "const": "prerelease", "description": "Published, addressable by its exact tag, never resolved by default." } ], "description": "Which releases an unpinned installation may resolve to." }, "CheckState": { "oneOf": [ { "type": "string", "const": "ok", "description": "The check holds." }, { "type": "string", "const": "failed", "description": "The check does not hold, and the public installation is affected." }, { "type": "string", "const": "unknown", "description": "The check could not be made here; it says nothing either way." } ], "description": "The state of one check in the installability report. Three states and no more: a check\neither holds, does not, or could not be made from what this process can see." }, "ClaimRef": { "type": "object", "properties": { "id": { "type": "string", "description": "The claim id." }, "claim": { "type": "string", "description": "The sentence." }, "status": { "type": "string", "description": "`guaranteed`, `advisory`, `planned` or `rejected`." } }, "required": [ "id", "claim", "status" ], "description": "One claim the feature names, with the status the matrix gives it." }, "Classification": { "type": "object", "properties": { "path": { "type": "string", "description": "The path, repository-relative, as judged." }, "verdict": { "$ref": "#/components/schemas/Verdict", "description": "In or out." }, "reason": { "anyOf": [ { "$ref": "#/components/schemas/Reason" }, { "type": "null" } ], "description": "Why it is out; absent when it is in." }, "rule": { "type": [ "string", "null" ], "description": "The pattern or limit that decided: the `in` pathspec, the `out` pattern, `binary`,\n`max_bytes` or `fixtures.max_bytes`; absent for `undeclared`." }, "exists": { "type": "boolean", "description": "Whether the path exists in the work tree; a path that does not is judged by name." }, "directory": { "type": "boolean", "description": "Whether the path is a directory; a directory is in when something beneath it can be." }, "bytes": { "type": [ "integer", "null" ], "format": "uint64", "minimum": 0, "description": "The size, when the path is an existing file." } }, "required": [ "path", "verdict", "exists", "directory" ], "description": "One path, judged." }, "CliExposure": { "type": "object", "properties": { "path": { "type": "array", "items": { "type": "string" }, "description": "The words after `majordomus`, e.g. `[\"capabilities\", \"list\"]`." } }, "required": [ "path" ], "description": "How a capability appears on the command line: the words after `majordomus`." }, "ClientInfo": { "type": "object", "properties": { "name": { "type": "string", "description": "`clientInfo.name`: `claude-code`, `codex`, `gemini-cli`, whatever the client sends." }, "version": { "type": "string", "description": "`clientInfo.version`." }, "title": { "type": [ "string", "null" ], "description": "`clientInfo.title`, when the client sends one." } }, "required": [ "name", "version" ], "description": "What a client said about itself in `initialize`." }, "Closure": { "type": "object", "properties": { "present": { "type": "boolean", "description": "Whether this checkout has a task to report about at all. False in a clone that has\nnever run the lifecycle, which is not a fault and is not \"nothing owed\"." }, "worktree": { "type": "string", "description": "The worktree this answer is about. Every reading below is scoped to it, and to no\nother checkout of the same repository." }, "branch": { "type": "string", "description": "The branch, or `DETACHED`." }, "head": { "type": "string", "description": "The commit this checkout is on." }, "working_tree": { "type": "string", "description": "`clean` or `dirty`." }, "task": { "anyOf": [ { "$ref": "#/components/schemas/ActiveTask" }, { "type": "null" } ], "description": "The active task, or `None`. Its `requires` is the list the entries below expand." }, "closed": { "type": "boolean", "description": "True when the task declares obligations and every one of them is discharged and\ncurrent — that is, when `majordomus.obligation-closure` would not refuse\n`finish --outcome completed`. False when anything is owed, stale or undeclared, and\nfalse when there is no task: nothing that does not exist is closed." }, "tallies": { "type": "object", "additionalProperties": { "type": "integer", "format": "uint", "minimum": 0 }, "description": "How many obligations stand where, by state word. Absent states are absent rather\nthan zero, so a reader never has to know the vocabulary to read the tallies." }, "obligations": { "type": "array", "items": { "$ref": "#/components/schemas/ObligationClosure" }, "description": "Every obligation the task declared, in the order it declared them." }, "findings": { "type": "array", "items": { "type": "string" }, "description": "What a reader should know before trusting any of the above: an unreadable\nvocabulary, a ledger that could not be read, a task that declares nothing. Empty is\nthe ordinary case." } }, "required": [ "present", "worktree", "branch", "closed", "tallies" ], "description": "What this checkout's active task owes, and how much of it is still true.\n\nA clone that has never run the lifecycle answers this too, and answers it as absence:\n`present` false, no task, and a finding saying so. \"Nothing owed\" and \"nothing to owe\nit\" are different facts, and a served instance must not report the second as the first.\n\n```\nuse majordomus_cli::capability::builtin::obligations::Closure;\nlet fresh: Closure = serde_json::from_str(\n r#\"{\"present\":false,\"worktree\":\"/srv/clone\",\"branch\":\"master\",\"closed\":false,\n \"tallies\":{},\n \"findings\":[\"no active task in this checkout (.ai/local/state/current.yaml); nothing owes anything here\"]}\"#,\n)\n.unwrap();\nassert!(!fresh.present && !fresh.closed, \"nothing that does not exist is closed\");\nassert!(fresh.task.is_none() && fresh.obligations.is_empty());\nassert_eq!(fresh.findings.len(), 1, \"absence is reported, not implied\");\n```" }, "ClosureMatrix": { "type": "object", "properties": { "rows": { "type": "array", "items": { "$ref": "#/components/schemas/Row" }, "description": "One row per capability, in id order." }, "unbacked": { "type": "array", "items": { "type": "string" }, "description": "Runnable commands of the command line that no capability claims, in command order." } }, "required": [ "rows", "unbacked" ], "description": "The whole matrix, with the findings and the debt beside it: one value that answers\n\"where does each capability appear, and is any claim unmet\"." }, "CockpitAreaRef": { "type": "object", "properties": { "id": { "type": "string", "description": "The area id." }, "title": { "type": "string", "description": "The label the Cockpit shows." }, "route": { "type": "string", "description": "The route under the running server." } }, "required": [ "id", "title", "route" ], "description": "One area of the Cockpit the feature names." }, "ColourPart": { "type": "object", "properties": { "part": { "type": "string", "description": "`fg`, `bg` or `line`." }, "css": { "type": "string", "description": "The custom property a surface reads." }, "light": { "$ref": "#/components/schemas/Resolved", "description": "In the light theme." }, "dark": { "$ref": "#/components/schemas/Resolved", "description": "In the dark theme." } }, "required": [ "part", "css", "light", "dark" ], "description": "One part of a colour token — a role has one, a status has its text, ground and border." }, "CommandArgument": { "type": "object", "properties": { "name": { "type": "string", "description": "The argument's id." }, "long": { "type": [ "string", "null" ], "description": "`--long`, without the dashes." }, "short": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1, "description": "`-s`, without the dash." }, "positional": { "type": "boolean", "description": "Given by position rather than by flag." }, "takes_value": { "type": "boolean", "description": "Takes a value at all; a flag does not." }, "required": { "type": "boolean", "description": "Must be given." }, "variadic": { "type": "boolean", "description": "Takes any number of values." }, "global": { "type": "boolean", "description": "Accepted by every command under the one that declares it." }, "help": { "type": "string", "description": "The help text, one line." }, "value_name": { "type": [ "string", "null" ], "description": "The placeholder, `PATH`." }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/CommandValueChoice" }, "description": "The values the declaration carries, each with its help." }, "defaults": { "type": "array", "items": { "type": "string" }, "description": "The defaults, as the declaration renders them." }, "source": { "$ref": "#/components/schemas/CommandValueSource", "description": "Where further values come from." }, "secrecy": { "$ref": "#/components/schemas/CommandSecrecy", "description": "How openly the value may be handled." } }, "required": [ "name", "positional", "takes_value", "required", "variadic", "global", "help", "source", "secrecy" ], "description": "One argument of a command, as the declaration gives it plus what can be inferred." }, "CommandAvailability": { "type": "object", "properties": { "available": { "type": "boolean", "description": "Can it be run here, now?" }, "reason": { "type": [ "string", "null" ], "description": "Why not, in one line, when it cannot." }, "requires": { "type": "array", "items": { "$ref": "#/components/schemas/CommandRequirement" }, "description": "What it needs, whether or not that is satisfied here." } }, "required": [ "available" ], "description": "Where a command means anything, and why not when it does not.\n\nDerived from the repository environment rather than declared per command, so that a\nprojection reads a field instead of re-deciding. The reason is carried because the\nanswer a person needs is never `false`." }, "CommandDeprecation": { "type": "object", "properties": { "reason": { "type": "string", "description": "Why, in one line." }, "replaced_by": { "anyOf": [ { "$ref": "#/components/schemas/CommandId" }, { "type": "null" } ], "description": "What to use instead." } }, "required": [ "reason" ], "description": "A command that is no longer the name to use." }, "CommandDiagnostic": { "type": "object", "properties": { "severity": { "$ref": "#/components/schemas/CommandDiagnosticSeverity", "description": "How bad." }, "code": { "type": "string", "description": "A stable code, for a gate to match on." }, "message": { "type": "string", "description": "What is wrong, in one line." }, "commands": { "type": "array", "items": { "$ref": "#/components/schemas/CommandId" }, "description": "The nodes it is about." }, "remedy": { "type": [ "string", "null" ], "description": "What to do about it." } }, "required": [ "severity", "code", "message" ], "description": "One thing the build found." }, "CommandDiagnosticSeverity": { "oneOf": [ { "type": "string", "const": "error", "description": "The graph is wrong and a projection built from it would be wrong." }, { "type": "string", "const": "warning", "description": "Worth saying; the graph stands." }, { "type": "string", "const": "info", "description": "A fact a reader may want." } ], "description": "How bad a finding is." }, "CommandEffect": { "oneOf": [ { "type": "string", "const": "read_only", "description": "Reads and answers. Changes nothing anywhere." }, { "type": "string", "const": "local_mutation", "description": "Writes only where the repository keeps a checkout's own state — the process's\nmemory, `.ai/local/`, a build directory. Nothing a commit would carry." }, { "type": "string", "const": "repository_mutation", "description": "Writes tracked files: generated artifacts, the worktree, git itself." }, { "type": "string", "const": "network_mutation", "description": "Reaches the network with an effect on the far side: a push, a deploy, a release." }, { "type": "string", "const": "destructive", "description": "Removes something a person would have to reconstruct." } ], "description": "What running a command changes. The one thing a surface policy is allowed to ask.\n\nThe order is the order of increasing consequence, and it is the order the derived\nexposure policy reads: a surface declares the strongest effect it will carry, and\nevery node at or below it is projected there. Nothing configures a surface per\ncommand." }, "CommandExecution": { "type": "object", "properties": { "origin": { "$ref": "#/components/schemas/CommandOrigin", "description": "Which program." }, "argv": { "type": "array", "items": { "type": "string" }, "description": "The words that precede the caller's arguments, the program's own name excluded." } }, "required": [ "origin", "argv" ], "description": "How a command is actually run: the program and the words before the caller's own.\n\nThis is what forbids a cycle. A projection renders an invocation from the execution\ndescriptor, so a generated bridge always spells the *canonical* program — never the\nsurface it is a bridge for." }, "CommandGraph": { "type": "object", "properties": { "schema": { "type": "string", "description": "The schema of this document." }, "fingerprint": { "type": "string", "description": "A hash of the semantic content: the identity a cache and a generated projection\nkey on. Nothing that varies between two runs over the same tree is in it." }, "commands": { "type": "array", "items": { "$ref": "#/components/schemas/CommandNode" }, "description": "Every command, in a deterministic order: origin, then path." }, "diagnostics": { "type": "array", "items": { "$ref": "#/components/schemas/CommandDiagnostic" }, "description": "What the build found." } }, "required": [ "schema", "fingerprint", "commands", "diagnostics" ], "description": "The whole graph." }, "CommandGraphReport": { "type": "object", "properties": { "graph": { "$ref": "#/components/schemas/CommandGraph", "description": "The graph." }, "errors": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many findings are errors; a projection refuses to write while this is not zero." } }, "required": [ "graph", "errors" ], "description": "The whole graph, with what its build found." }, "CommandId": { "type": "string", "description": "The canonical identity of one command.\n\nConstructed from the origin and the command path, never written by hand, so that a\nprojection cannot invent one and a rename of a display string cannot change one." }, "CommandIndex": { "type": "object", "properties": { "schema": { "type": "string", "description": "The schema of the graph these came from." }, "fingerprint": { "type": "string", "description": "The fingerprint of that graph: a client may cache against it." }, "total": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many commands the graph holds, before the filter." }, "commands": { "type": "array", "items": { "$ref": "#/components/schemas/CommandSummary" }, "description": "The commands that matched, in graph order." } }, "required": [ "schema", "fingerprint", "total", "commands" ], "description": "The commands this repository offers, filtered." }, "CommandInteractivity": { "oneOf": [ { "type": "string", "const": "non_interactive", "description": "Runs, answers, exits. Safe to call from a machine surface." }, { "type": "string", "const": "interactive", "description": "Asks the person something, or reads the body of a record from a terminal. A\nmachine surface that offered it would hang." }, { "type": "string", "const": "long_running", "description": "Serves until it is stopped. A request/response surface cannot carry it." } ], "description": "How a command behaves towards the caller's terminal and the caller's patience." }, "CommandNode": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/CommandId", "description": "The canonical identity." }, "origin": { "$ref": "#/components/schemas/CommandOrigin", "description": "Which program runs it." }, "path": { "type": "array", "items": { "type": "string" }, "description": "The words after the program's own name." }, "invocation": { "type": "string", "description": "The command line a person types, rendered once here." }, "summary": { "type": "string", "description": "One line." }, "description": { "type": [ "string", "null" ], "description": "The longer description, when the declaration carries one." }, "runnable": { "type": "boolean", "description": "Can it be run on its own, or does it only group the commands under it?" }, "arguments": { "type": "array", "items": { "$ref": "#/components/schemas/CommandArgument" }, "description": "The arguments, in declaration order." }, "execution": { "$ref": "#/components/schemas/CommandExecution", "description": "How it is run." }, "effect": { "$ref": "#/components/schemas/CommandEffect", "description": "What it changes." }, "interactivity": { "$ref": "#/components/schemas/CommandInteractivity", "description": "How it behaves towards a terminal." }, "stability": { "$ref": "#/components/schemas/Stability", "description": "Where it stands." }, "availability": { "$ref": "#/components/schemas/CommandAvailability", "description": "Where it means anything." }, "group": { "type": [ "string", "null" ], "description": "The group a person finds it under, when the declaration has groups." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free tags." }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Other names that resolve to this node, declared once here and honoured by every\nprojection that has a use for one." }, "deprecation": { "anyOf": [ { "$ref": "#/components/schemas/CommandDeprecation" }, { "type": "null" } ], "description": "Whether this is still the name to use." }, "provenance": { "$ref": "#/components/schemas/CommandProvenance", "description": "Where it came from." }, "projections": { "$ref": "#/components/schemas/CommandProjections", "description": "Where it appears." }, "entrypoint": { "type": [ "boolean", "null" ], "description": "Is this command an entry point of its group — the one a newcomer is offered?" } }, "required": [ "id", "origin", "path", "invocation", "summary", "runnable", "arguments", "execution", "effect", "interactivity", "stability", "availability", "provenance", "projections" ], "description": "One command, from whichever program offers it." }, "CommandOrigin": { "oneOf": [ { "type": "string", "const": "executable", "description": "The Rust executable, `apps/majordomus-cli`: the read-only interfaces, generation,\nintrospection, the servers. Declared by clap." }, { "type": "string", "const": "tool", "description": "The shell tool, `bin/majordomus`: the task lifecycle. Declared by the shipped\ncommand registry and dispatched by the tool itself." }, { "type": "string", "const": "workflow", "description": "A workflow the repository declares for a person to run — a `just` recipe that is\nnot a generated bridge. Declared by the justfile and read from the runner's dump." } ], "description": "Which program runs a command. Part of the identity, because the three are different\nprograms that share one name on the path." }, "CommandProjections": { "type": "object", "properties": { "cli": { "type": [ "string", "null" ], "description": "The command line, as typed." }, "workflow": { "type": [ "string", "null" ], "description": "The generated workflow bridge's recipe name." }, "mcp": { "type": [ "string", "null" ], "description": "The MCP tool name, when the capability behind it declares one." }, "http": { "type": [ "string", "null" ], "description": "The HTTP route, when the capability behind it declares one." }, "cockpit": { "type": [ "string", "null" ], "description": "The Cockpit address, when the surface carries it." }, "docs": { "type": "string", "description": "The page on the site. Every command has one." }, "withheld": { "type": [ "string", "null" ], "description": "Why a machine surface does not carry it, when one does not." } }, "required": [ "docs" ], "description": "Where one command appears, derived from its effect, its interactivity and its origin.\n\nEvery field is computed by [`super::policy`]. Nothing declares a projection, and no\nsurface keeps a list of what it carries: a surface asks the graph." }, "CommandProvenance": { "type": "object", "properties": { "declared_in": { "type": "string", "description": "The repository-relative file that declares it." }, "read_by": { "type": [ "string", "null" ], "description": "The command that reads that declaration, when a reader wants to reproduce it." }, "capability": { "anyOf": [ { "$ref": "#/components/schemas/CapabilityId" }, { "type": "null" } ], "description": "The capability this command runs, when it runs one." } }, "required": [ "declared_in" ], "description": "Where a node came from, in enough detail to open the file." }, "CommandRef": { "type": "object", "properties": { "id": { "type": "string", "description": "The command." }, "summary": { "type": "string", "description": "One line." }, "stage": { "type": [ "string", "null" ], "description": "The lifecycle stage it belongs to." }, "read_only": { "type": "boolean", "description": "Whether it writes nothing." } }, "required": [ "id", "summary", "read_only" ], "description": "One public command of the shell tool the feature names, as `share/commands.yaml`\ndeclares it." }, "CommandRequirement": { "oneOf": [ { "type": "string", "const": "repository", "description": "A git repository." }, { "type": "string", "const": "layer", "description": "The `.ai/` layer, initialised." }, { "type": "string", "const": "task", "description": "An active task record." }, { "type": "string", "const": "executable", "description": "The Rust executable, built." }, { "type": "string", "const": "workflow_runner", "description": "The workflow runner, installed." }, { "type": "string", "const": "rust_toolchain", "description": "A cargo workspace and a toolchain to build it." }, { "type": "string", "const": "site", "description": "The site sources and its generator." } ], "description": "One thing a command needs before it can run." }, "CommandSecrecy": { "oneOf": [ { "type": "string", "const": "public", "description": "Ordinary: may be logged, completed, shown." }, { "type": "string", "const": "sensitive", "description": "A path or an identifier that names something private. Shown, never logged." }, { "type": "string", "const": "secret", "description": "A credential. Never completed, never logged, never cached." } ], "description": "How openly a value may be handled." }, "CommandSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "The canonical identity." }, "invocation": { "type": "string", "description": "The command line a person types." }, "summary": { "type": "string", "description": "One line." }, "origin": { "type": "string", "description": "Which program runs it." }, "effect": { "type": "string", "description": "What running it changes." }, "group": { "type": [ "string", "null" ], "description": "The group it is found under." }, "projections": { "$ref": "#/components/schemas/CommandProjections", "description": "Where it appears." } }, "required": [ "id", "invocation", "summary", "origin", "effect", "projections" ], "description": "One command, as an index shows it: enough to choose, never enough to have to skim." }, "CommandValueChoice": { "type": "object", "properties": { "value": { "type": "string", "description": "The value as typed." }, "description": { "type": [ "string", "null" ], "description": "Its help, when the declaration carries one." } }, "required": [ "value" ], "description": "One value an argument accepts, from the declaration." }, "CommandValueSource": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "free" } }, "required": [ "kind" ], "description": "Nothing here knows the set; the caller types a value." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "enumerated" } }, "required": [ "kind" ], "description": "The declaration carries the values; they are on the argument." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "path" } }, "required": [ "kind" ], "description": "A path in the filesystem." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "repository_path" } }, "required": [ "kind" ], "description": "A path inside the repository." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "capability" } }, "required": [ "kind" ], "description": "A capability id, from the registry." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "command" } }, "required": [ "kind" ], "description": "A command id, from this graph." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "rule" } }, "required": [ "kind" ], "description": "A rule id, from the effective rule set." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "object_kind" } }, "required": [ "kind" ], "description": "An object kind, from the index." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "branch" } }, "required": [ "kind" ], "description": "A git branch in this repository." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "graph" } }, "required": [ "kind" ], "description": "A graph id, from the graph registry." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "moment" } }, "required": [ "kind" ], "description": "A moment id, from the why catalogue." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "shell" } }, "required": [ "kind" ], "description": "A shell name, from the shells the activation supports." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "secret" } }, "required": [ "kind" ], "description": "A secret. Never enumerated, never cached, never suggested." } ], "description": "Where a value for an argument comes from, when something in this repository knows the\nset.\n\nThis is the completion contract, and it is a property of the *argument*, not of a shell\nscript: the same source answers a shell's TAB, a generated form's select and a machine\nsurface's enumeration of what it will accept. Inference from the declaration comes\nfirst — a value-enum argument carries its own values, a `PATH` placeholder is a path —\nand only what cannot be inferred is annotated beside the command." }, "CommitAttribution": { "type": "object", "properties": { "commit": { "$ref": "#/components/schemas/CommitRef", "description": "The commit." }, "attribution": { "$ref": "#/components/schemas/Attribution", "description": "What is known." }, "issue": { "type": [ "string", "null" ], "description": "The issue, when exactly one claims it." }, "milestone": { "type": [ "string", "null" ], "description": "The milestone that issue belongs to, filled by the caller that has the index." }, "issues": { "type": "array", "items": { "type": "string" }, "description": "Every issue whose branches contain it: one when attributed, none when unattributed,\nmore than one when ambiguous." }, "branches": { "type": "array", "items": { "type": "string" }, "description": "The branches that contain it, by the names their refs carry." }, "reason": { "type": "string", "description": "Why the verdict is what it is, in one line a person can act on." } }, "required": [ "commit", "attribution", "issues", "branches", "reason" ], "description": "One commit and the contract it served, or the fact that none can be found." }, "CommitRef": { "type": "object", "properties": { "id": { "type": "string", "description": "The full object name." }, "short": { "type": "string", "description": "The abbreviated object name, as this repository abbreviates it." }, "author": { "type": "string", "description": "The author, as the commit records them." }, "date": { "type": "string", "description": "The author date, ISO 8601 as the commit records it." }, "subject": { "type": "string", "description": "The subject line." } }, "required": [ "id", "short", "author", "date", "subject" ], "description": "One commit, exactly as git names it. Nothing here is stored anywhere: the whole record\nis re-read from the object database on every call." }, "Comparison": { "oneOf": [ { "type": "string", "const": "content", "description": "Byte for byte against the content the index holds." }, { "type": "string", "const": "size", "description": "By size against the size the index recorded." } ], "description": "How closely a file could be compared with what the index holds.\n\nA file that is one object is compared byte for byte, because the index kept its whole\ncontent. A collection file holds one object per member, and what the index kept for each\nis that member as JSON rather than the file's text — so the strongest thing that can be\nsaid without re-parsing it is whether its size is what it was. The report says which\ncomparison was made rather than implying the stronger one." }, "Concurrency": { "type": "object", "additionalProperties": false, "properties": { "soft_limit": { "$ref": "#/components/schemas/Positive", "description": "Where the edge starts preferring another machine." }, "hard_limit": { "$ref": "#/components/schemas/Positive", "description": "Where it stops sending requests to this one." } }, "required": [ "soft_limit", "hard_limit" ], "description": "When the edge considers a machine loaded, in requests." }, "Confidence": { "oneOf": [ { "type": "string", "const": "exact", "description": "Read from its canonical source during this resolution." }, { "type": "string", "const": "cached", "description": "Read from a cache whose fingerprint still matches its inputs." }, { "type": "string", "const": "unknown", "description": "Not resolved." } ], "description": "How far a resolved value can be trusted." }, "ContainerView": { "type": "object", "properties": { "path": { "type": "string", "description": "The derived path." }, "suffix": { "type": "string", "description": "The suffix it was derived with." }, "exists": { "type": "boolean", "description": "It exists on disk. Created by the first worktree that needs it." } }, "required": [ "path", "suffix", "exists" ], "description": "The container, as the topology reports it." }, "Continuity": { "type": "object", "properties": { "present": { "type": "boolean", "description": "Whether this checkout's lifecycle has ever run: a ledger line, a task, an episode or\na record. False in a fresh clone, which is not a fault.\n\nIt is not \"the directory exists\". Several things create that directory before\nanything has been recorded in it, so a reader that took its presence for evidence\nwould be told the lifecycle had run in a checkout where it never had." }, "worktree": { "type": "string", "description": "The worktree this answer is about. Every selection below is scoped to it." }, "branch": { "type": "string", "description": "The branch, or `DETACHED`." }, "head": { "type": "string", "description": "The commit this checkout is on." }, "working_tree": { "type": "string", "description": "`clean` or `dirty`." }, "session": { "anyOf": [ { "$ref": "#/components/schemas/OpenSession" }, { "type": "null" } ], "description": "The open episode, or `None`." }, "task": { "anyOf": [ { "$ref": "#/components/schemas/ActiveTask" }, { "type": "null" } ], "description": "The active task, or `None`." }, "handover": { "anyOf": [ { "$ref": "#/components/schemas/Record" }, { "type": "null" } ], "description": "The record the next worker would resume from, or `None` when nothing resolves here." }, "checkpoint": { "anyOf": [ { "$ref": "#/components/schemas/Record" }, { "type": "null" } ], "description": "The newest progress note for this worktree and branch, or `None`." }, "blockers": { "type": "array", "items": { "type": "string" }, "description": "Unresolved questions on this branch. Every one refuses `finish --outcome completed`,\nwhichever task opened it." }, "tallies": { "type": "object", "additionalProperties": { "type": "integer", "format": "uint", "minimum": 0 }, "description": "How many records of each kind this checkout holds, against the policy's caps." }, "findings": { "type": "array", "items": { "type": "string" }, "description": "What a reader should know before trusting any of the above: a diverged record, a\nforeign open session, a malformed file that was skipped. Empty is the good case." } }, "required": [ "present", "worktree", "branch", "tallies" ], "description": "What the lifecycle of this checkout is holding." }, "ContractView": { "type": "object", "properties": { "id": { "type": "string", "description": "The document's identity; it survives a move, the file name does not." }, "path": { "type": "string", "description": "The document's path, repository-relative." }, "title": { "type": [ "string", "null" ], "description": "One line naming the directory." }, "description": { "type": [ "string", "null" ], "description": "One line saying what the directory is for." }, "status": { "type": "string", "description": "`active` or `deprecated`; a deprecated document is listed and never applied." }, "scope": { "type": "string", "description": "`directory`, `subtree` or `explicit`: how far the document reaches." }, "composition": { "type": "string", "description": "`extend`, `replace` or `final`: how it composes with what is above it." }, "order": { "type": "integer", "format": "int64", "description": "Ties within one depth are broken by this, then by path." }, "providers": { "type": "array", "items": { "type": "string" }, "description": "`*`, or the providers the document is written for." }, "audience": { "type": "array", "items": { "type": "string" }, "description": "Who it addresses; both when it says nothing." }, "tracks": { "type": "array", "items": { "type": "string" }, "description": "Pathspecs whose change names this document for review." }, "children_require_contract": { "type": [ "boolean", "null" ], "description": "Whether the directories below owe a contract, when this document says." }, "children_exempt": { "type": "array", "items": { "type": "string" }, "description": "Subtrees below this one that owe nothing: carried, not authored here." } }, "required": [ "id", "path", "status", "scope", "composition", "order", "providers", "audience" ], "description": "A directory contract as the document declares it, before anything is inherited." }, "ContrastReport": { "type": "object", "properties": { "fingerprint": { "type": "string", "description": "The fingerprint of the declaration measured." }, "standard": { "type": "string", "description": "The standard the thresholds come from." }, "minimum_text": { "type": "number", "format": "double", "description": "The ratio asked of text." }, "minimum_non_text": { "type": "number", "format": "double", "description": "The ratio asked of a non-text element that carries meaning." }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" }, "description": "The stylesheets read, and whether each was found." }, "measured": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many pairs were derived and measured." }, "pairs": { "type": "array", "items": { "$ref": "#/components/schemas/Measured" }, "description": "Every pair, in a stable order: theme, then what it carries, then the two tokens." }, "composed": { "type": "integer", "format": "uint", "minimum": 0, "description": "Declarations skipped because their value is composed at run time." }, "findings": { "type": "array", "items": { "type": "string" }, "description": "One line per enforced pair that falls short, naming role, ground, theme, measured\nratio and required ratio." }, "readable": { "type": "boolean", "description": "Whether every enforced pair reaches its threshold." } }, "required": [ "fingerprint", "standard", "minimum_text", "minimum_non_text", "sources", "measured", "pairs", "composed", "findings", "readable" ], "description": "Every pair the declaration and its consumers state, measured." }, "CounterSnapshot": { "type": "object", "properties": { "repository_scans": { "type": "integer", "format": "uint64", "minimum": 0, "description": "Enumerations of the repository's declared sources." }, "index_builds": { "type": "integer", "format": "uint64", "minimum": 0, "description": "Index builds." }, "registry_builds": { "type": "integer", "format": "uint64", "minimum": 0, "description": "Registry builds." }, "schema_generations": { "type": "integer", "format": "uint64", "minimum": 0, "description": "JSON Schemas derived from Rust types." }, "mcp_projection_builds": { "type": "integer", "format": "uint64", "minimum": 0, "description": "MCP tool and resource listings computed." }, "openapi_builds": { "type": "integer", "format": "uint64", "minimum": 0, "description": "OpenAPI documents built." }, "http_projection_builds": { "type": "integer", "format": "uint64", "minimum": 0, "description": "HTTP routers built." }, "graph_builds": { "type": "integer", "format": "uint64", "minimum": 0, "description": "Graphs derived from the registry and the index." }, "executions": { "type": "integer", "format": "uint64", "minimum": 0, "description": "Calls through the executor, every transport." }, "handler_invocations": { "type": "integer", "format": "uint64", "minimum": 0, "description": "Handlers actually run." }, "cache_hits": { "type": "integer", "format": "uint64", "minimum": 0, "description": "Executions answered from the cache." }, "cache_misses": { "type": "integer", "format": "uint64", "minimum": 0, "description": "Executions of a cached capability that ran the handler." }, "cache_evictions": { "type": "integer", "format": "uint64", "minimum": 0, "description": "Cache entries dropped." }, "phases": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PhaseTotals" }, "description": "Phase totals by phase name." } }, "required": [ "repository_scans", "index_builds", "registry_builds", "schema_generations", "mcp_projection_builds", "openapi_builds", "http_projection_builds", "graph_builds", "executions", "handler_invocations", "cache_hits", "cache_misses", "cache_evictions", "phases" ], "description": "The counters and phase totals of this process at one moment. Every value is a count\nor a duration this process measured; none is written anywhere by hand." }, "Counts": { "type": "object", "properties": { "moments": { "type": "integer", "format": "uint", "minimum": 0, "description": "Public moments." }, "moments_all": { "type": "integer", "format": "uint", "minimum": 0, "description": "Moments of every status, drafts included." }, "audiences": { "type": "integer", "format": "uint", "minimum": 0, "description": "Public audiences." }, "areas": { "type": "integer", "format": "uint", "minimum": 0, "description": "Public areas." }, "signals": { "type": "integer", "format": "uint", "minimum": 0, "description": "Signals across the public moments: the size of the questionnaire." }, "examples": { "type": "integer", "format": "uint", "minimum": 0, "description": "Concrete situations across the public moments." } }, "required": [ "moments", "moments_all", "audiences", "areas", "signals", "examples" ], "description": "How much the catalogue holds. Every count anywhere — a page, a heading, a report — is\none of these, so no number is ever written down." }, "CpuKind": { "oneOf": [ { "type": "string", "const": "shared", "description": "A fraction of a core: the cheap profile." }, { "type": "string", "const": "performance", "description": "A dedicated one." } ], "description": "What a machine's CPU is." }, "Declaration": { "type": "object", "additionalProperties": false, "properties": { "version": { "type": "integer", "format": "uint64", "minimum": 0, "description": "The format version; only [`SCOPE_VERSION`] is read." }, "in": { "type": "array", "items": { "type": "string" }, "description": "The allow-list: pathspecs anchored at the repository root." }, "out": { "$ref": "#/components/schemas/Out", "description": "What is never read; wins over `in`." } }, "required": [ "version", "in", "out" ], "description": "`scope.yaml`, typed. Unknown keys are refused by the type and by the `scope` schema." }, "DemonstrateReport": { "type": "object", "properties": { "steps": { "type": "integer", "format": "uint64", "minimum": 0, "description": "How many steps ran." }, "elapsed_ms": { "type": "integer", "format": "uint64", "minimum": 0, "description": "How long it took, in milliseconds." }, "observed": { "type": "boolean", "description": "Whether anything was watching: false when it was called directly rather than as an\nexecution, which is the difference this capability exists to show." } }, "required": [ "steps", "elapsed_ms", "observed" ], "description": "The answer of `executions.demonstrate`." }, "DeploymentCheck": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "True when no deployment earned a refusal." }, "decided": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many deployments were decided." }, "refusals": { "type": "array", "items": { "$ref": "#/components/schemas/Refusal" }, "description": "Every refusal, in the order the objects and their keys appear." } }, "required": [ "ok", "decided", "refusals" ], "description": "Whether the deployments this repository declares would work, decided locally: against\nthe capability registry this process built and the workspace it sits in." }, "DeploymentList": { "type": "object", "properties": { "count": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many." }, "deployments": { "type": "array", "items": { "$ref": "#/components/schemas/DeploymentView" }, "description": "Each, in identity order." }, "unreadable": { "type": "array", "items": { "$ref": "#/components/schemas/Refusal" }, "description": "Objects of the deployment kind this executable could not read, with why. A\nmalformed object is reported here rather than hidden by being skipped." } }, "required": [ "count", "deployments" ], "description": "Every deployment the layer declares." }, "DeploymentStatus": { "oneOf": [ { "type": "string", "const": "declared", "description": "The object exists and nothing is deployed from it yet." }, { "type": "string", "const": "active", "description": "It is deployed." }, { "type": "string", "const": "retired", "description": "It was, and the object is kept for the record." } ], "description": "Where a deployment stands.\n\n`Status` is the right name inside this module; the schema component namespace is flat,\nand `distribution::Status` answers a different question, so each says which it is." }, "DeploymentView": { "type": "object", "properties": { "file": { "type": "string", "description": "The repository-relative file the object lives in." }, "schema": { "type": "string", "description": "The format version; a version this executable does not read is refused." }, "kind": { "type": "string", "description": "Always `deployment`." }, "id": { "type": "string", "description": "The identity within the repository." }, "title": { "type": "string", "description": "One line naming it." }, "description": { "type": [ "string", "null" ], "description": "One line: what it serves and to whom.", "default": null }, "status": { "anyOf": [ { "$ref": "#/components/schemas/DeploymentStatus" }, { "type": "null" } ], "description": "Where it stands.", "default": null }, "application": { "type": "string", "description": "The application's name at the provider." }, "build": { "$ref": "#/components/schemas/Build", "description": "What is shipped and what it is built from." }, "listen": { "$ref": "#/components/schemas/Listen", "description": "The address the process listens on." }, "health": { "$ref": "#/components/schemas/HealthRoutes", "description": "The routes a platform polls." }, "resources": { "$ref": "#/components/schemas/Resources", "description": "What one machine is granted." }, "machines": { "$ref": "#/components/schemas/Machines", "description": "How many machines run." }, "region": { "type": "string", "description": "The region they run in." }, "budgets": { "$ref": "#/components/schemas/Budgets", "description": "The measured figures it is held to.", "default": { "image_bytes": null, "binary_bytes": null, "build_context_bytes": null, "cold_start_ms": null, "resident_memory_mb": null, "blocking_check_ms": null, "request_p99_ms": null } }, "provider": { "$ref": "#/components/schemas/Provider", "description": "The provider and its own facts." }, "created_at": { "type": [ "string", "null" ], "description": "When the object was written.", "default": null }, "updated_at": { "type": [ "string", "null" ], "description": "When it was last changed.", "default": null } }, "required": [ "file", "schema", "kind", "id", "title", "application", "build", "listen", "health", "resources", "machines", "region", "provider" ], "description": "One deployment as this process reads it, with where it came from." }, "DesignReport": { "type": "object", "properties": { "fingerprint": { "type": "string", "description": "SHA-256 of the declaration's canonical form." }, "design": { "type": "string", "description": "The first twelve digits, as every stylesheet carries them in `--mj-design`." }, "schema": { "type": "integer", "format": "uint64", "minimum": 0, "description": "The format version of the declaration." }, "source": { "type": "string", "description": "Where the declaration lives, repository-relative." }, "identity": { "$ref": "#/components/schemas/Identity", "description": "Who this is." }, "font": { "$ref": "#/components/schemas/Fonts", "description": "The two type stacks." }, "theme": { "$ref": "#/components/schemas/ThemeView", "description": "The theme contract." }, "viewports": { "type": "array", "items": { "type": "integer", "format": "uint32", "minimum": 0 }, "description": "The widths a browser audit measures every page at." }, "tallies": { "$ref": "#/components/schemas/TokenTallies", "description": "How many of each kind of token." }, "projections": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectionView" }, "description": "Every generated file the declaration is projected into." } }, "required": [ "fingerprint", "design", "schema", "source", "identity", "font", "theme", "viewports", "tallies", "projections" ], "description": "The design system: what it is and where it goes." }, "Desired": { "type": "object", "properties": { "host": { "type": "string", "description": "The interface the shared server binds by default." }, "port": { "type": "integer", "format": "uint16", "minimum": 0, "maximum": 65535, "description": "The port it asks for first." }, "version": { "type": "string", "description": "This executable's version." }, "executable": { "anyOf": [ { "$ref": "#/components/schemas/ExecutableIdentity" }, { "type": "null" } ], "description": "This executable, when it can be located." } }, "required": [ "host", "port", "version" ], "description": "What this executable would want a server of this checkout to be: the address it would\nbind, the version and the executable it would serve from. What `standing` is measured\nagainst.\n\n```\nuse majordomus_cli::capability::builtin::server::Desired;\nlet d = Desired { host: \"127.0.0.1\".into(), port: 8741, version: \"1.0.0\".into(), executable: None };\nlet v = serde_json::to_value(&d).unwrap();\nassert_eq!(v[\"port\"], 8741);\nassert!(v.get(\"executable\").is_none(), \"an executable that cannot be located is not written as null\");\n```" }, "Diagnosis": { "type": "object", "properties": { "moments": { "type": "array", "items": { "type": "string" }, "description": "The moments the selection resolved to, in presentation order." }, "unresolved": { "type": "array", "items": { "type": "string" }, "description": "Selected names that resolved to nothing." }, "areas": { "type": "array", "items": { "$ref": "#/components/schemas/Recommendation" }, "description": "Operational areas by how many selected moments fall under them, heaviest first." }, "audiences": { "type": "array", "items": { "$ref": "#/components/schemas/Recommendation" }, "description": "Audiences by how many selected moments they recognise, heaviest first." }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/Recommendation" }, "description": "Capabilities of the executable that answer the selected moments." }, "commands": { "type": "array", "items": { "$ref": "#/components/schemas/Recommendation" }, "description": "Commands that answer them." }, "claims": { "type": "array", "items": { "$ref": "#/components/schemas/Recommendation" }, "description": "Claims that say what is guaranteed." }, "doctrines": { "type": "array", "items": { "$ref": "#/components/schemas/Recommendation" }, "description": "Rules of the effective set that govern them." }, "use_cases": { "type": "array", "items": { "$ref": "#/components/schemas/Recommendation" }, "description": "Use cases that show the way out." }, "also_worth_reading": { "type": "array", "items": { "type": "string" }, "description": "Moments the selection did not include that share an area with one that it did." } }, "required": [ "moments", "unresolved", "areas", "audiences", "capabilities", "commands", "claims", "doctrines", "use_cases", "also_worth_reading" ], "description": "What a reader's selection implies, computed by counting rather than by inference.\n\nThe arithmetic is the whole model and is stated so a reader can check it: a selection\nresolves to a set of moments; an area or an audience scores the number of selected\nmoments that name it; a recommendation scores the number that name it and carries\ntheir ids. There is no weighting and no percentage, because there is no model behind\none." }, "Diagnostic": { "type": "object", "properties": { "severity": { "$ref": "#/components/schemas/Severity", "description": "How bad." }, "code": { "type": "string", "description": "A stable machine-readable code, e.g. `unknown_key`, `duplicate_identity`." }, "path": { "type": [ "string", "null" ], "description": "Repository-relative path of the file concerned, when there is one." }, "message": { "type": "string", "description": "What is wrong, for a person; the code is for a program." } }, "required": [ "severity", "code", "message" ], "description": "One finding about the declarative state, named by a stable code, tied to a path where\nthere is one, and carrying the command that reproduces it where there is one." }, "DiagnosticCode": { "oneOf": [ { "type": "string", "const": "worktree.path_mismatch", "description": "A linked work tree is not at its branch's canonical path." }, { "type": "string", "const": "worktree.container_occupied", "description": "A linked work tree occupies the container path itself." }, { "type": "string", "const": "worktree.nested", "description": "A linked work tree sits inside the primary checkout or inside another work tree." }, { "type": "string", "const": "worktree.destination_conflict", "description": "The canonical path of a branch is occupied by something that is not its work tree." }, { "type": "string", "const": "worktree.missing", "description": "A registered work tree's directory does not exist." }, { "type": "string", "const": "worktree.stale_registration", "description": "Git reports the registration as prunable." }, { "type": "string", "const": "worktree.branch_already_checked_out", "description": "A branch is checked out somewhere other than its canonical path." }, { "type": "string", "const": "worktree.detached", "description": "A linked work tree has no branch." }, { "type": "string", "const": "worktree.ephemeral", "description": "A linked work tree is a session's scratch checkout: under the temporary directory or\nunder the primary checkout's `.claude/worktrees/`." }, { "type": "string", "const": "worktree.primary_on_non_trunk", "description": "The primary checkout holds a branch that is not the trunk." }, { "type": "string", "const": "worktree.trunk_in_linked_worktree", "description": "The trunk is checked out in a linked work tree rather than the primary checkout." }, { "type": "string", "const": "worktree.path_escape", "description": "A derived path would leave the container. Cannot happen for a valid branch name." }, { "type": "string", "const": "worktree.invalid_branch_name", "description": "A branch name git accepted that this executable cannot derive a path for." }, { "type": "string", "const": "worktree.locked", "description": "A work tree is locked, so it cannot be moved until it is unlocked." }, { "type": "string", "const": "worktree.migration_verification_failed", "description": "A move happened and the fingerprint after it differs from the one before." }, { "type": "string", "const": "worktree.trunk_unknown", "description": "The trunk could not be determined." }, { "type": "string", "const": "worktree.case_collision", "description": "Two branch names map to one directory on a case-insensitive filesystem." }, { "type": "string", "const": "worktree.cross_device", "description": "A move crossed devices and was made by copy, repair and verification." } ], "description": "The stable machine name of everything that can be wrong with the topology. One code per\ncondition, reused by the command line, the API, MCP, the Cockpit, the tests and the\ndocumentation; the prose beside a code is rendered from the typed state." }, "DirectoryNode": { "type": "object", "properties": { "path": { "type": "string", "description": "Repository-relative, forward slashes." }, "depth": { "type": "integer", "format": "uint", "minimum": 0, "description": "Segments below the layer root; the root itself is 0." }, "parent": { "type": [ "string", "null" ], "description": "The directory above, when it is inside the layer." }, "children": { "type": "array", "items": { "type": "string" }, "description": "The directories immediately below, sorted." }, "state": { "$ref": "#/components/schemas/DirectoryState", "description": "Whether it carries the contract it owes." }, "requires_contract": { "type": "boolean", "description": "Whether a contract is owed here at all." }, "governed_by": { "type": [ "string", "null" ], "description": "The contract that made the requirement explicit, when one did." }, "exempted_by": { "type": [ "string", "null" ], "description": "The contract that released this subtree, when one did." }, "objects": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many objects of any kind the index holds directly in this directory." }, "contract": { "anyOf": [ { "$ref": "#/components/schemas/ContractView" }, { "type": "null" } ], "description": "The contract this directory declares, before inheritance." }, "effective": { "type": "array", "items": { "$ref": "#/components/schemas/EffectiveEntry" }, "description": "The contracts that apply here once inheritance is resolved, least specific first.\nPresent when the request asked for it, or when it asked about one path." } }, "required": [ "path", "depth", "state", "requires_contract", "objects" ], "description": "One directory of the layer, what it owes, and what applies to it." }, "DirectoryReport": { "type": "object", "properties": { "root": { "type": "string", "description": "The layer root the tree is rooted at." }, "tallies": { "$ref": "#/components/schemas/DirectoryTallies", "description": "The directories in each state." }, "directories": { "type": "array", "items": { "$ref": "#/components/schemas/DirectoryNode" }, "description": "Every directory asked for, sorted by path." } }, "required": [ "root", "tallies", "directories" ], "description": "The layer's directories, what each owes, and the contracts that apply." }, "DirectoryState": { "oneOf": [ { "type": "string", "const": "documented", "description": "It carries a context document of its own." }, { "type": "string", "const": "exempt", "description": "It owes none, because a contract above it says so." }, { "type": "string", "const": "owed", "description": "It owes one and has none." } ], "description": "Whether a directory of the layer carries the contract it owes." }, "DirectoryTallies": { "type": "object", "properties": { "directories": { "type": "integer", "format": "uint", "minimum": 0, "description": "Every directory of the layer the index knows." }, "documented": { "type": "integer", "format": "uint", "minimum": 0, "description": "Carrying a contract of their own." }, "exempt": { "type": "integer", "format": "uint", "minimum": 0, "description": "Released by a contract above them." }, "owed": { "type": "integer", "format": "uint", "minimum": 0, "description": "Owing a contract and carrying none." } }, "required": [ "directories", "documented", "exempt", "owed" ], "description": "How many directories are in each state." }, "DirtyState": { "type": "object", "properties": { "staged": { "type": "integer", "format": "uint", "minimum": 0, "description": "Entries with a change in the index." }, "unstaged": { "type": "integer", "format": "uint", "minimum": 0, "description": "Entries with a change in the work tree that is not in the index." }, "untracked": { "type": "integer", "format": "uint", "minimum": 0, "description": "Untracked, not ignored, files." }, "conflicted": { "type": "integer", "format": "uint", "minimum": 0, "description": "Entries with an unresolved merge conflict." }, "clean": { "type": "boolean", "description": "Nothing above is non-zero." }, "in_progress": { "type": [ "string", "null" ], "description": "A merge, rebase, cherry-pick, revert or bisect is in progress here." } }, "required": [ "staged", "unstaged", "untracked", "conflicted", "clean" ], "description": "Uncommitted work in a work tree, counted from `git status --porcelain`. Untracked\ncontent counts: it is exactly what a careless move loses." }, "DistributionReport": { "type": "object", "properties": { "binary": { "type": "string", "description": "The command a person types after installing." }, "repository": { "type": "string", "description": "`owner/name`, the only host release assets come from." }, "installer_url": { "type": "string", "description": "The installer's canonical URL." }, "install_command": { "type": "string", "description": "The one-line install command, composed from its parts." }, "install_and_init_command": { "type": "string", "description": "The same, initialising the repository afterwards." }, "next_command": { "type": "string", "description": "What a person runs next." }, "checksum": { "type": "string", "description": "The digest algorithm the installer verifies." }, "install_dir": { "type": "string", "description": "Where the launchers go by default." }, "prefix": { "type": "string", "description": "Where the versioned trees go by default." }, "latest_url": { "type": "string", "description": "Where the stable release metadata is published." }, "supported": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many targets a release builds." }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/TargetView" }, "description": "Every declared target, in the model's order." } }, "required": [ "binary", "repository", "installer_url", "install_command", "install_and_init_command", "next_command", "checksum", "install_dir", "prefix", "latest_url", "supported", "targets" ], "description": "The distribution, as a person or a script asks for it." }, "Divergence": { "oneOf": [ { "type": "string", "const": "exact", "description": "Written at this commit. Trust it." }, { "type": "string", "const": "advanced", "description": "Git has moved forward since. Trust it, and expect some of it to be done." }, { "type": "string", "const": "diverged", "description": "The recorded commit is not an ancestor: history was rewritten. Trust git, not this." }, { "type": "string", "const": "different_context", "description": "Another branch or another worktree. This record is not about your work." }, { "type": "string", "const": "unknown", "description": "Git could not answer, so this process says so rather than guessing `exact`." } ], "description": "How far a record's recorded commit is from the commit this checkout is on.\n\nThe four words are the shell tool's, deliberately. A reader that met `advanced` from one\nsurface and `stale` from another would have to learn the same four facts twice." }, "DocRef": { "type": "object", "properties": { "path": { "type": "string", "description": "Repository-relative path." }, "title": { "type": [ "string", "null" ], "description": "The title, when the document has one." } }, "required": [ "path" ], "description": "One document the feature names." }, "DocumentView": { "type": "object", "properties": { "id": { "type": "string", "description": "The document id, shared by every encoding of it." }, "schema": { "type": [ "string", "null" ], "description": "The schema id its structured encodings carry." }, "source": { "type": "string", "description": "One line: what it was derived from." }, "formats": { "type": "array", "items": { "$ref": "#/components/schemas/ArtifactFormat" }, "description": "The encodings, in the manifest's order." } }, "required": [ "id", "source", "formats" ], "description": "One document, and the encodings it is committed in." }, "DriftedObject": { "type": "object", "properties": { "path": { "type": "string", "description": "Its repository-relative path." }, "standing": { "$ref": "#/components/schemas/ObjectStanding", "description": "How it stands." }, "comparison": { "$ref": "#/components/schemas/Comparison", "description": "How it was compared." }, "objects": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many objects of the index came from it." }, "example_uri": { "type": "string", "description": "One of the URIs it holds, so a reader can see what is affected." }, "detail": { "type": "string", "description": "What is wrong, for a person." } }, "required": [ "path", "standing", "comparison", "objects", "example_uri", "detail" ], "description": "One file of the layer that is no longer what the index read." }, "Edge": { "type": "object", "properties": { "source": { "type": "string", "description": "The node the edge leaves." }, "target": { "type": "string", "description": "The node the edge enters." }, "kind": { "type": "string", "description": "One of the graph's declared edge kinds." } }, "required": [ "source", "target", "kind" ], "description": "One directed edge. Both ends are node ids of the same graph; a derivation that cannot\nresolve an end adds an external node rather than a dangling edge." }, "EffectiveEntry": { "type": "object", "properties": { "id": { "type": "string", "description": "The document's identity." }, "path": { "type": "string", "description": "The document's path." }, "depth": { "type": "integer", "format": "uint", "minimum": 0, "description": "Depth below the layer root; less is less specific and applies first." }, "order": { "type": "integer", "format": "int64", "description": "The declared order, the second sort key." }, "composition": { "type": "string", "description": "`extend`, `replace` or `final`." }, "reason": { "type": "string", "description": "Why it applies to this directory, in words." }, "local": { "type": "boolean", "description": "True for the directory's own document, false for one it inherits." } }, "required": [ "id", "path", "depth", "order", "composition", "reason", "local" ], "description": "One contract in a directory's effective chain, in the order it is applied." }, "EnvironmentProvenance": { "type": "object", "properties": { "resolution": { "$ref": "#/components/schemas/Resolution", "description": "How the snapshot behind these entries was resolved." }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/FieldSource" }, "description": "One entry per field, in the order the resolver produced them." } }, "required": [ "resolution", "fields" ], "description": "Where the values of one snapshot came from." }, "EnvrcApproval": { "oneOf": [ { "type": "object", "properties": { "outcome": { "type": "string", "const": "approved" } }, "required": [ "outcome" ], "description": "direnv accepted it: the next `cd` loads the environment." }, { "type": "object", "properties": { "outcome": { "type": "string", "const": "no_envrc" } }, "required": [ "outcome" ], "description": "The worktree has no `.envrc`; there is nothing to approve and nothing is blocked." }, { "type": "object", "properties": { "outcome": { "type": "string", "const": "direnv_absent" } }, "required": [ "outcome" ], "description": "direnv is not on the PATH; nothing was done, and nothing is blocked either, because\nnothing would load the file." }, { "type": "object", "properties": { "outcome": { "type": "string", "const": "differs" } }, "required": [ "outcome" ], "description": "The worktree's `.envrc` is not the primary checkout's, so the approval given there\ndoes not carry. `direnv allow` in the worktree, after reading it, is the person's." }, { "type": "object", "properties": { "outcome": { "type": "string", "const": "not_approved_in_primary" } }, "required": [ "outcome" ], "description": "The primary checkout's `.envrc` is not approved, so there is no approval to carry." }, { "type": "object", "properties": { "message": { "type": "string", "description": "direnv's standard error, or the error running it." }, "outcome": { "type": "string", "const": "failed" } }, "required": [ "outcome", "message" ], "description": "direnv was asked and refused, or could not be run; the message is its own." } ], "description": "What became of the `.envrc` of a worktree that was just created, found, or moved." }, "ErrorBody": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail", "description": "The one error." } }, "required": [ "error" ], "description": "The body of every error response." }, "ErrorDetail": { "type": "object", "properties": { "code": { "type": "string", "description": "What kind of failure it is: `invalid_input`, `not_found`, `method_not_allowed`,\n`refused`, `forbidden`, `too_large`, `unavailable` (a surface whose producer has not\nrun) or `internal`." }, "message": { "type": "string", "description": "The reason, for a person." } }, "required": [ "code", "message" ], "description": "What went wrong, as the HTTP projection names it." }, "EventHistory": { "type": "object", "properties": { "execution_id": { "type": "string", "description": "The execution the events belong to." }, "state": { "$ref": "#/components/schemas/ExecutionState", "description": "Where the execution stands now, so a client needs one request rather than two." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/ExecutionEvent" }, "description": "The events, oldest first." }, "last_sequence": { "type": "integer", "format": "uint64", "minimum": 0, "description": "The sequence of the last event here: the cursor for the next page, and the one to\nopen the live channel with." }, "more": { "type": "boolean", "description": "Whether more events follow this page right now." }, "truncated": { "type": "boolean", "description": "Whether events before this page had already been dropped by the store's bound." } }, "required": [ "execution_id", "state", "events", "last_sequence", "more", "truncated" ], "description": "The answer of `executions.events`: one page of an execution's retained history." }, "Evidence": { "type": "object", "properties": { "recorded_at": { "type": "string", "description": "When the line was appended." }, "head": { "type": "string", "description": "The commit the ledger's envelope stamped on it." }, "branch": { "type": "string", "description": "The branch it was recorded on." }, "kind": { "type": "string", "description": "How it was taken: `test`, `build`, `ci`, `artifact` or `manual`." }, "command": { "type": "string", "description": "The command that produced it. Narrative is not evidence, so one of this and\n`artifact` is always present." }, "artifact": { "type": "string", "description": "The reference it points at, such as a published URL." }, "result": { "type": "string", "description": "What the command said, when its output was the point." }, "session": { "type": "string", "description": "The episode that recorded it, when one was open." }, "inputs_hash": { "type": "string", "description": "The hash of the token's declared inputs at the moment it was taken. Empty for a\ntoken that declares none." } }, "required": [ "recorded_at", "head" ], "description": "The `task.evidence` line that discharged an obligation, as the ledger holds it.\n\nNothing older is consulted: evidence is superseded by evidence, and the ledger keeps\nthe history for a reader that wants it.\n```\nuse majordomus_cli::capability::builtin::obligations::Evidence;\nlet e: Evidence = serde_json::from_str(\n r#\"{\"recorded_at\":\"2026-09-09T21:01:00Z\",\"head\":\"f00ba7\",\"branch\":\"master\",\n \"kind\":\"ci\",\"command\":\"scripts/ci/reference-check\",\"inputs_hash\":\"7f68b9\"}\"#,\n)\n.unwrap();\nassert_eq!(e.head, \"f00ba7\", \"the envelope's commit is what a remote fact is judged against\");\nassert!(e.artifact.is_empty(), \"one of command and artifact; narrative is not evidence\");\n```" }, "Example": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique within the moment." }, "audience": { "type": "string", "description": "The audience this situation belongs to; must name an audience of the catalogue." }, "title": { "type": "string", "description": "One line naming the situation." }, "before": { "type": "string", "description": "What happens without the tool." }, "after": { "type": "string", "description": "What happens with it." } }, "required": [ "id", "audience", "title", "before", "after" ], "description": "One concrete situation, in one audience, with what happens today and what happens\ninstead." }, "ExecutableIdentity": { "type": "object", "properties": { "path": { "type": "string", "description": "The path the process was started from." }, "mtime": { "type": "integer", "format": "uint64", "minimum": 0, "description": "The file's modification time, seconds since the epoch." }, "size": { "type": "integer", "format": "uint64", "minimum": 0, "description": "The file's size in bytes." } }, "required": [ "path", "mtime", "size" ], "description": "The identity of the file an executable was started from: where it is, and the mtime\nand size of the file at that path. A server outlives its own binary — a rebuild replaces\nthe file under a process that keeps serving the code it loaded hours ago — and nothing\nabout the process itself says so. This is what makes that visible.\n\n```\nuse majordomus_cli::lease::ExecutableIdentity;\nlet recorded = ExecutableIdentity { path: \"/opt/majordomus\".into(), mtime: 1_700_000_000, size: 42 };\nlet text = serde_json::to_string(&recorded).unwrap();\nassert_eq!(serde_json::from_str::(&text).unwrap(), recorded);\n```" }, "ExecutionConcurrency": { "oneOf": [ { "type": "string", "const": "unrestricted", "description": "Any number at once. Every read is one of these: the index and the registry are\nimmutable for the life of the process, so concurrent readers cannot interfere." }, { "type": "string", "const": "serial", "description": "One at a time. A second execution of the same capability waits for the first, which\nis what a capability that changes anything — this process's own memory included —\nneeds in order to be reasoned about at all." } ], "description": "Whether two executions of one capability may overlap." }, "ExecutionDiagnostic": { "type": "object", "properties": { "severity": { "$ref": "#/components/schemas/Severity", "description": "How bad." }, "code": { "type": "string", "description": "A stable machine-readable code." }, "summary": { "type": "string", "description": "One line, for a person." }, "detail": { "type": [ "string", "null" ], "description": "The rest, when there is more." }, "suggestion": { "type": [ "string", "null" ], "description": "What to do about it, when there is something." } }, "required": [ "severity", "code", "summary" ], "description": "A structured finding an execution reported on its way, distinct from its outcome." }, "ExecutionEffect": { "oneOf": [ { "type": "string", "const": "read", "description": "Nothing changes. Every query and every resource of this executable." }, { "type": "string", "const": "process_state", "description": "This process's own memory changes, and nothing outside it." }, { "type": "string", "const": "repository_mutation", "description": "The repository changes.\n\nNothing classifies to this, and the doctrine of this tool is why: no capability of\nany kind writes to the repository. It is on the model so that the day one does, it\nsays so here — where a projection already reads it and a client already asks before\nrunning it — rather than in whichever page happens to render its button." } ], "description": "What running a capability changes outside the caller.\n\nClassified, never declared: it follows from the kind, which is the field a declaration\nalready carries. A projection reads this to decide whether to ask before running\nsomething — the Cockpit's confirmation is derived from it — instead of naming\ncapabilities it must treat carefully, which is a list that goes stale the day after it\nis written." }, "ExecutionError": { "type": "object", "properties": { "code": { "type": "string", "description": "`invalid_input`, `not_found`, `refused`, `internal`, `cancelled`, `unavailable`." }, "message": { "type": "string", "description": "What went wrong, for a person." }, "suggestion": { "type": [ "string", "null" ], "description": "What to do about it, when there is something." }, "correlation_id": { "type": "string", "description": "The execution this failure belongs to, so a log line and a UI agree." } }, "required": [ "code", "message", "correlation_id" ], "description": "Why an execution ended badly, in the repository's diagnostic vocabulary rather than in\nRust's: a code a program branches on, a sentence a person reads, and where to look.\n\nA panic message and a backtrace are never in here. The engine catches a panicking\nhandler and reports `internal` with the execution's correlation id; the panic itself is\non the process's own error stream, where the operator running the server can read it." }, "ExecutionEvent": { "type": "object", "properties": { "schema_version": { "type": "string", "description": "The protocol version, [`PROTOCOL_VERSION`]." }, "event_id": { "type": "string", "description": "The identity of this event: the execution's id and the sequence, so a client that\ndeduplicates needs no composite key of its own." }, "execution_id": { "$ref": "#/components/schemas/ExecutionId", "description": "The execution it is about." }, "sequence": { "type": "integer", "format": "uint64", "minimum": 0, "description": "Its position in that execution's stream, from 1, without gaps." }, "timestamp": { "type": "string", "description": "When the event was produced, RFC 3339 in UTC." } }, "required": [ "schema_version", "event_id", "execution_id", "sequence", "timestamp" ], "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "execution.created" }, "data": { "type": "object", "properties": { "capability": { "description": "The capability's canonical id.", "type": "string" }, "title": { "description": "Its title.", "type": "string" }, "input": { "description": "The input, with sensitive values already replaced." } }, "required": [ "capability", "title", "input" ] } }, "required": [ "type", "data" ], "description": "The execution was accepted and exists. Carries what it will run and with what,\nredacted, so a client that joins at the first event needs nothing else to render a\nheading." }, { "type": "object", "properties": { "type": { "type": "string", "const": "execution.queued" }, "data": { "type": "object", "properties": { "ahead": { "description": "How many executions are ahead of it.", "type": "integer", "format": "uint", "minimum": 0 } }, "required": [ "ahead" ] } }, "required": [ "type", "data" ], "description": "It is waiting for a worker." }, { "type": "object", "properties": { "type": { "type": "string", "const": "execution.started" } }, "required": [ "type" ], "description": "A worker picked it up and is about to enter the handler." }, { "type": "object", "properties": { "type": { "type": "string", "const": "execution.progress" }, "data": { "$ref": "#/components/schemas/ProgressView" } }, "required": [ "type", "data" ], "description": "How far along it is." }, { "type": "object", "properties": { "type": { "type": "string", "const": "execution.step.started" }, "data": { "type": "object", "properties": { "name": { "description": "The step's stable name.", "type": "string" }, "title": { "description": "One line for a reader.", "type": "string" } }, "required": [ "name", "title" ] } }, "required": [ "type", "data" ], "description": "A named phase was entered." }, { "type": "object", "properties": { "type": { "type": "string", "const": "execution.step.completed" }, "data": { "type": "object", "properties": { "name": { "description": "The step's stable name.", "type": "string" }, "ok": { "description": "Whether what it was asked to do happened.", "type": "boolean" }, "detail": { "description": "What it said, when it said anything.", "type": [ "string", "null" ] } }, "required": [ "name", "ok" ] } }, "required": [ "type", "data" ], "description": "A named phase finished." }, { "type": "object", "properties": { "type": { "type": "string", "const": "execution.log" }, "data": { "type": "object", "properties": { "stream": { "description": "Which stream it came from.", "$ref": "#/components/schemas/LogStream" }, "message": { "description": "The text, with control characters and terminal escapes already removed.", "type": "string" } }, "required": [ "stream", "message" ] } }, "required": [ "type", "data" ], "description": "A line of output." }, { "type": "object", "properties": { "type": { "type": "string", "const": "execution.diagnostic" }, "data": { "$ref": "#/components/schemas/ExecutionDiagnostic" } }, "required": [ "type", "data" ], "description": "A structured finding, distinct from the outcome." }, { "type": "object", "properties": { "type": { "type": "string", "const": "execution.cancelling" }, "data": { "type": "object", "properties": { "by": { "description": "Who asked, in one word.", "type": "string" } }, "required": [ "by" ] } }, "required": [ "type", "data" ], "description": "Cancellation was asked for; the handler has not stopped yet." }, { "type": "object", "properties": { "type": { "type": "string", "const": "execution.cancelled" } }, "required": [ "type" ], "description": "It stopped because it was asked to." }, { "type": "object", "properties": { "type": { "type": "string", "const": "execution.completed" }, "data": { "type": "object", "properties": { "output": { "description": "What the handler returned." } }, "required": [ "output" ] } }, "required": [ "type", "data" ], "description": "It finished, and the handler returned an output.\n\nThe output is on this event and not on one of its own, because a client must never\nbe able to read \"succeeded\" and find no result: the state and the value it produced\nare one fact and travel together." }, { "type": "object", "properties": { "type": { "type": "string", "const": "execution.failed" }, "data": { "type": "object", "properties": { "error": { "description": "Why.", "$ref": "#/components/schemas/ExecutionError" } }, "required": [ "error" ] } }, "required": [ "type", "data" ], "description": "It finished, and it did not." } ], "description": "One event about one execution.\n\n`sequence` is dense and starts at 1 within an execution: a client that has seen\nsequence `n` knows it has missed something when the next event it reads is not `n + 1`,\nand asks for the gap by cursor rather than reloading the world." }, "ExecutionId": { "type": "string", "description": "The identity of one execution: `x--<8 hex>`.\n\nThe shape is the layer's own — a task is `t-20260905034523-a9f1` — so that an id read\nin a log, a URL or a browser tab is recognisable as this repository's without a\ndependency on a UUID crate. The timestamp orders ids by creation for a reader; the\nsuffix, not the timestamp, is what makes two ids created in the same second differ." }, "ExecutionLinks": { "type": "object", "properties": { "self": { "type": "string", "description": "The snapshot: `GET /api/v1/executions/get?id=…`." }, "events": { "type": "string", "description": "The retained history: `GET /api/v1/executions/events?id=…`." }, "cancel": { "type": "string", "description": "Where to ask it to stop: `POST /api/v1/executions/cancel`." }, "websocket": { "type": "string", "description": "The live channel, from the beginning: `GET /events?execution=…`." }, "cockpit": { "type": "string", "description": "The page a person opens." } }, "required": [ "self", "events", "cancel", "websocket", "cockpit" ], "description": "Where to read more about one execution, in this server's own terms.\n\nEvery value is derived from the registry's declared routes and from the live channel's\nown constant, so a route that moves moves here too and no client holds a path this\nserver does not serve." }, "ExecutionList": { "type": "object", "properties": { "count": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many are answered here." }, "remembered": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many this process remembers in total, before the filter." }, "active": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many are not finished." }, "queued": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many are waiting for a worker." }, "live_channels": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many live channels are following them." }, "executions": { "type": "array", "items": { "$ref": "#/components/schemas/ExecutionView" }, "description": "The executions, newest first." } }, "required": [ "count", "remembered", "active", "queued", "live_channels", "executions" ], "description": "The answer of `executions.list`." }, "ExecutionPolicy": { "type": "object", "properties": { "effect": { "$ref": "#/components/schemas/ExecutionEffect", "description": "What it changes." }, "cancellable": { "type": "boolean", "description": "Whether asking it to stop does anything. A task looks at its cancellation flag; a\nquery and a command do not, and a client is told so rather than being given a\nbutton that lies." }, "concurrency": { "$ref": "#/components/schemas/ExecutionConcurrency", "description": "Whether two of them may overlap." } }, "required": [ "effect", "cancellable", "concurrency" ], "description": "What running a capability as an execution means: what it changes, whether asking it to\nstop achieves anything, and whether two of them may overlap.\n\nThe effect and the concurrency are classified from the kind by\n[`ExecutionPolicy::classify`], for the same reason [`Availability`] is: the facts are\nalready on the declaration, and asking each `capability!` block to restate them would be\none more thing that can disagree with itself.\n\nCancellability is the one thing the kind cannot decide, because it is a fact about the\nhandler: whether it looks at its cancellation flag and stops. A handler that does says\nso with [`crate::capability::Executable::cancellable`], and a client is then told\nwhether a Cancel button will achieve anything instead of being given one that lies." }, "ExecutionState": { "oneOf": [ { "type": "string", "const": "queued", "description": "Accepted, and no worker has picked it up." }, { "type": "string", "const": "running", "description": "The handler is running." }, { "type": "string", "const": "cancelling", "description": "Cancellation was asked for and the handler has not stopped yet." }, { "type": "string", "const": "succeeded", "description": "The handler returned an output." }, { "type": "string", "const": "failed", "description": "The handler returned an error, or the worker could not run it." }, { "type": "string", "const": "cancelled", "description": "It stopped because it was asked to." } ], "description": "Where an execution is in its life.\n\nThe transitions are the whole contract, and [`ExecutionState::may_move_to`] is the one\nplace they are written down: the engine asks before every change, the store refuses a\nmove it did not allow, and a client that reads a final state never sees it move again.\n\n```text\n queued ──► running ──┬──► succeeded\n │ ├──► failed\n │ └──► cancelling ──┬──► cancelled\n │ ├──► succeeded\n └──► cancelled └──► failed\n```\n\nThere is no `starting`. An in-process engine claims an execution and enters its handler\nin the same instant, so a state between the two would be one no client could ever\nobserve and every client would have to handle." }, "ExecutionView": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ExecutionId", "description": "The identity." }, "capability": { "type": "string", "description": "The capability that ran, by its canonical id." }, "title": { "type": "string", "description": "That capability's title, so a list needs no second lookup." }, "state": { "$ref": "#/components/schemas/ExecutionState", "description": "Where it is." }, "created_at": { "type": "string", "description": "When it was accepted, RFC 3339 in UTC." }, "started_at": { "type": [ "string", "null" ], "description": "When the handler was entered." }, "finished_at": { "type": [ "string", "null" ], "description": "When it reached a final state." }, "duration_ms": { "type": [ "integer", "null" ], "format": "uint64", "minimum": 0, "description": "How long it ran, in milliseconds, once it has finished." }, "input": { "description": "The input it was given, with every value the input schema marks sensitive replaced." }, "output": { "description": "What the handler returned, for a succeeded execution and never before." }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ExecutionError" }, { "type": "null" } ], "description": "Why it failed, for a failed execution and never before." }, "progress": { "anyOf": [ { "$ref": "#/components/schemas/ProgressView" }, { "type": "null" } ], "description": "The last progress the handler reported." }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/StepView" }, "description": "The steps it entered, in order." }, "diagnostics": { "type": "array", "items": { "$ref": "#/components/schemas/ExecutionDiagnostic" }, "description": "The findings it reported." }, "last_sequence": { "type": "integer", "format": "uint64", "minimum": 0, "description": "The sequence number of the last event: the cursor a client subscribes from." }, "event_count": { "type": "integer", "format": "uint64", "minimum": 0, "description": "How many events it has produced, including the ones no longer retained." }, "events_truncated": { "type": "boolean", "description": "Whether the retained event history has lost its oldest entries to the bound." }, "cancellable": { "type": "boolean", "description": "Whether asking to cancel this execution will do anything: the capability's policy." }, "actor": { "$ref": "#/components/schemas/Actor", "description": "Who asked for it." }, "repository": { "$ref": "#/components/schemas/RepositoryRef", "description": "Which repository it ran against." }, "correlation_id": { "type": "string", "description": "The id used in this process's logs and tracing spans for this execution; the\nexecution id itself, carried under the name a reader of a log expects." }, "links": { "$ref": "#/components/schemas/ExecutionLinks", "description": "Where to read more." } }, "required": [ "id", "capability", "title", "state", "created_at", "input", "last_sequence", "event_count", "events_truncated", "cancellable", "actor", "repository", "correlation_id", "links" ], "description": "One execution with the links to everything else about it." }, "Exemption": { "type": "object", "properties": { "reason": { "type": "string", "description": "The reason, as the policy names it." }, "items": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many items it covers." } }, "required": [ "reason", "items" ], "description": "A group of items the example policy does not apply to, with the reason it does not." }, "Exposure": { "type": "object", "properties": { "mcp": { "anyOf": [ { "$ref": "#/components/schemas/McpExposure" }, { "type": "null" } ], "description": "The MCP projection, when declared." }, "http": { "anyOf": [ { "$ref": "#/components/schemas/HttpExposure" }, { "type": "null" } ], "description": "The HTTP projection, when declared." }, "cli": { "anyOf": [ { "$ref": "#/components/schemas/CliExposure" }, { "type": "null" } ], "description": "The command-line projection, when declared." } }, "description": "The projections a capability declares. Absence is explicit: `None` means not exposed\nthere, and nothing infers an exposure a descriptor did not declare." }, "FacetValue": { "type": "object", "properties": { "value": { "type": "string", "description": "The value as a moment declares it." }, "label": { "type": "string", "description": "The name to show; the value itself when the taxonomy holds no title for it." }, "count": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many public moments carry it." } }, "required": [ "value", "label", "count" ], "description": "One selectable value of one facet, with how many public moments carry it. Every filter\na reader is offered is one of these; nothing anywhere lists the values by hand." }, "Facets": { "type": "object", "properties": { "audiences": { "type": "array", "items": { "$ref": "#/components/schemas/FacetValue" }, "description": "By audience." }, "areas": { "type": "array", "items": { "$ref": "#/components/schemas/FacetValue" }, "description": "By operational area." }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/FacetValue" }, "description": "By tag." }, "severities": { "type": "array", "items": { "$ref": "#/components/schemas/FacetValue" }, "description": "By severity." }, "frequencies": { "type": "array", "items": { "$ref": "#/components/schemas/FacetValue" }, "description": "By frequency." }, "lifecycle": { "type": "array", "items": { "$ref": "#/components/schemas/FacetValue" }, "description": "By stage of work." }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/FacetValue" }, "description": "By capability of the executable." }, "commands": { "type": "array", "items": { "$ref": "#/components/schemas/FacetValue" }, "description": "By command." } }, "required": [ "audiences", "areas", "tags", "severities", "frequencies", "lifecycle", "capabilities", "commands" ], "description": "The filters the catalogue offers, derived from the records rather than declared." }, "Fact": { "anyOf": [ { "type": "boolean", "description": "A yes or a no." }, { "type": "integer", "format": "int64", "description": "A whole number: an order, a version, a weight." }, { "type": "string", "description": "One short value." }, { "type": "array", "items": { "type": "string" }, "description": "Several short values." } ], "description": "One fact a node carries from its object's front matter, in the shapes a node can hold." }, "Feature": { "oneOf": [ { "type": "string", "const": "mcp", "description": "This process answers MCP over HTTP." }, { "type": "string", "const": "cockpit", "description": "This process serves the Cockpit." } ], "description": "A capability of the running process a surface needs in order to exist.\n\nThe registry describes the effective process, not the maximum one: a build or an\ninvocation that answers no MCP has no MCP surface, and the home page cannot link to\none. Stating the dependency as data is what keeps that automatic." }, "FeatureCounts": { "type": "object", "properties": { "capabilities": { "type": "integer", "format": "uint", "minimum": 0, "description": "Builtin capabilities of the modules it names." }, "mcp_tools": { "type": "integer", "format": "uint", "minimum": 0, "description": "MCP tools among them." }, "mcp_resources": { "type": "integer", "format": "uint", "minimum": 0, "description": "MCP resources among them, plus one per object of the kinds it names." }, "http_routes": { "type": "integer", "format": "uint", "minimum": 0, "description": "HTTP routes among them." }, "cli_paths": { "type": "integer", "format": "uint", "minimum": 0, "description": "Command-line paths of the executable among them." }, "commands": { "type": "integer", "format": "uint", "minimum": 0, "description": "Public commands of the shell tool it names." }, "objects": { "type": "integer", "format": "uint", "minimum": 0, "description": "Objects of the kinds it names." }, "rules": { "type": "integer", "format": "uint", "minimum": 0, "description": "Rules it names." }, "enforced_rules": { "type": "integer", "format": "uint", "minimum": 0, "description": "Rules the tool enforces among them." }, "docs": { "type": "integer", "format": "uint", "minimum": 0, "description": "Documents it names." }, "adrs": { "type": "integer", "format": "uint", "minimum": 0, "description": "Decisions it names." }, "claims": { "type": "integer", "format": "uint", "minimum": 0, "description": "Claims it names." }, "use_cases": { "type": "integer", "format": "uint", "minimum": 0, "description": "Use cases it names." }, "moments": { "type": "integer", "format": "uint", "minimum": 0, "description": "Moments it answers." } }, "required": [ "capabilities", "mcp_tools", "mcp_resources", "http_routes", "cli_paths", "commands", "objects", "rules", "enforced_rules", "docs", "adrs", "claims", "use_cases", "moments" ], "description": "How much stands behind a feature, every number derived." }, "FeatureEvidence": { "type": "object", "properties": { "claims": { "type": "object", "additionalProperties": { "type": "integer", "format": "uint", "minimum": 0 }, "description": "Claims by status: `guaranteed`, `advisory`, `planned`, `rejected`." }, "modules": { "type": "object", "additionalProperties": { "type": "integer", "format": "uint", "minimum": 0 }, "description": "The modules it names by stability." } }, "required": [ "claims", "modules" ], "description": "What is guaranteed about a feature, counted from the claims it names: never a word a\nperson wrote about the feature's maturity." }, "FeatureList": { "type": "object", "properties": { "schema": { "type": "string", "description": "[`SCHEMA`]." }, "fingerprint": { "type": "string", "description": "The hash of the model's sources and derived facts." }, "counts": { "$ref": "#/components/schemas/ProductCounts", "description": "The counts." }, "surfaces": { "type": "array", "items": { "$ref": "#/components/schemas/SurfaceInfo" }, "description": "The surface vocabulary, with how many stable features each exposes." }, "features": { "type": "array", "items": { "$ref": "#/components/schemas/FeatureSummary" }, "description": "The matching features, in presentation order." } }, "required": [ "schema", "fingerprint", "counts", "surfaces", "features" ], "description": "The features as a client reads them." }, "FeatureSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "The identity and the slug." }, "title": { "type": "string", "description": "The feature as a heading." }, "label": { "type": "string", "description": "The name a narrow column shows: the short title, or the title." }, "headline": { "type": "string", "description": "The promise a visitor reads first." }, "summary": { "type": "string", "description": "One line: what it does." }, "status": { "type": "string", "description": "`stable`, `draft` or `deprecated`." }, "weight": { "type": "integer", "format": "uint32", "minimum": 0, "description": "Presentation order." }, "featured": { "type": "boolean", "description": "Whether the homepage shows it." }, "areas": { "type": "array", "items": { "type": "string" }, "description": "The operational areas it serves." }, "audiences": { "type": "array", "items": { "type": "string" }, "description": "The audiences it is written for." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free tags." }, "route": { "type": "string", "description": "Derived: `/features//`." }, "surfaces": { "$ref": "#/components/schemas/Surfaces", "description": "Derived: the interfaces it is exposed through." }, "counts": { "$ref": "#/components/schemas/FeatureCounts", "description": "Derived: how much stands behind it." }, "evidence": { "$ref": "#/components/schemas/FeatureEvidence", "description": "Derived: what is guaranteed." } }, "required": [ "id", "title", "label", "headline", "summary", "status", "weight", "featured", "areas", "audiences", "tags", "route", "surfaces", "counts", "evidence" ], "description": "One feature as a listing shows it: everything a card needs and nothing a page needs." }, "FieldSource": { "type": "object", "properties": { "field": { "type": "string", "description": "The field, in dotted form: `services.cockpit.url`, `vcs.branch`." }, "value": { "type": [ "string", "null" ], "description": "The value as it appears in the snapshot, rendered for a person; absent for a field\nthat resolved to nothing." }, "source": { "type": "string", "description": "What decided it: a file, a command, a compile-time constant, the cache." }, "resolver": { "type": "string", "description": "The part of this executable that read it." }, "confidence": { "$ref": "#/components/schemas/Confidence", "description": "How certain the value is." } }, "required": [ "field", "source", "resolver", "confidence" ], "description": "Where one field of the snapshot came from. This is what makes an inferred system\ndebuggable: every fact can name the thing that decided it, so \"why does it say that\"\nis answered by the tool rather than by reading its source." }, "Finding": { "type": "object", "properties": { "severity": { "$ref": "#/components/schemas/Severity", "description": "`error` or `warning`." }, "code": { "type": "string", "description": "A short category: `unknown_reference`, `duplicate_identity`, `missing_content`, ..." }, "path": { "type": "string", "description": "The repository-relative file the finding is in." }, "id": { "type": [ "string", "null" ], "description": "The record's identity, when one record owns the finding." }, "field": { "type": [ "string", "null" ], "description": "The front-matter key the finding is about, when one key owns it." }, "message": { "type": "string", "description": "What is wrong, in one sentence." }, "did_you_mean": { "type": [ "string", "null" ], "description": "The nearest existing name, when the value looks like a typo of one." } }, "required": [ "severity", "code", "path", "message" ], "description": "One thing wrong with the catalogue, named where it is, with the nearest candidate when\nthere is one. A finding always carries enough to fix it without searching." }, "Fixtures": { "type": "object", "additionalProperties": false, "properties": { "paths": { "type": "array", "items": { "type": "string" }, "description": "Pathspecs anchored at the repository root.", "default": [] }, "names": { "type": "array", "items": { "type": "string" }, "description": "Patterns matched against the file name alone.", "default": [] }, "max_bytes": { "type": "integer", "format": "uint64", "minimum": 0, "description": "A fixture over this many bytes is out." } }, "required": [ "max_bytes" ], "description": "The `fixtures` category: where fixtures live and how large one may be." }, "Fly": { "type": "object", "additionalProperties": false, "properties": { "org": { "type": [ "string", "null" ], "description": "The organisation the application belongs to.", "default": null }, "force_https": { "type": [ "boolean", "null" ], "description": "Whether the edge redirects plain HTTP to HTTPS.", "default": null }, "concurrency": { "anyOf": [ { "$ref": "#/components/schemas/Concurrency" }, { "type": "null" } ], "description": "When the edge considers a machine loaded.", "default": null } }, "description": "Fly.io's own facts: what has no meaning for any other provider." }, "Fonts": { "type": "object", "additionalProperties": false, "properties": { "sans": { "type": "string", "description": "The system stack." }, "mono": { "type": "string", "description": "The monospace stack." } }, "required": [ "sans", "mono" ], "description": "The two type stacks." }, "GitIdentity": { "type": "object", "properties": { "common_dir": { "type": "string", "description": "The git directory every work tree of the repository shares, canonical." }, "id": { "type": "string", "description": "Its digest: the same for every checkout of one repository, different across\nrepositories, and never a path." }, "linked": { "type": "boolean", "description": "Whether this checkout is a linked work tree rather than the primary one." } }, "required": [ "common_dir", "id", "linked" ], "description": "The git repository a checkout belongs to, as distinct from the checkout itself.\n\n[`identity`] names a checkout: one server, one lease, one index per checkout root. Every\nlinked worktree of one git repository is a checkout of its own by that measure, and\nnothing in it said that they belong together. This does: the git directory every work\ntree shares (`git rev-parse --git-common-dir`) is the repository's identity, its digest\nis one value for every checkout of that repository, and `linked` says whether this\ncheckout is the primary one or a work tree hanging off it. `None` where git cannot be\nasked: a repository of the layer does not have to be version controlled.\n\n```\nuse majordomus_cli::repository::{git_identity, identity, GitIdentity};\nuse std::process::Command;\nlet dir = tempfile::tempdir().unwrap();\nlet root = dir.path().join(\"repo\");\nstd::fs::create_dir_all(&root).unwrap();\nlet git = |args: &[&str]| assert!(Command::new(\"git\").arg(\"-C\").arg(&root).args(args).status().unwrap().success());\ngit(&[\"init\", \"-q\", \".\"]);\ngit(&[\"-c\", \"user.email=t@example.com\", \"-c\", \"user.name=t\", \"commit\", \"-q\", \"--allow-empty\", \"-m\", \"init\"]);\nlet wt = dir.path().join(\"repo-wt\");\ngit(&[\"worktree\", \"add\", \"-q\", \"-b\", \"feature/x\", wt.to_str().unwrap()]);\n\nlet primary: GitIdentity = git_identity(&root).expect(\"a work tree\");\nlet linked: GitIdentity = git_identity(&wt).expect(\"a linked work tree\");\nassert_eq!(primary.id, linked.id, \"one repository\");\nassert_ne!(identity(&root), identity(&wt), \"two checkouts\");\nassert!(!primary.linked && linked.linked);\nassert!(!primary.id.contains('/'), \"a digest, never a path\");\n```" }, "GitInfo": { "type": "object", "properties": { "toplevel": { "type": "string", "description": "Absolute path of the work tree top level." }, "head": { "type": [ "string", "null" ], "description": "Full commit id of HEAD, or `None` in an unborn repository." }, "branch": { "type": [ "string", "null" ], "description": "Branch name, or `None` when detached or unborn." }, "working_tree": { "type": "string", "description": "`clean` or `dirty`, from `git status --porcelain`." } }, "required": [ "toplevel", "working_tree" ], "description": "What `git` said about the repository." }, "GitState": { "oneOf": [ { "$ref": "#/components/schemas/GitInfo", "type": "object", "properties": { "state": { "type": "string", "const": "available" } }, "required": [ "state" ], "description": "`git` answered; the facts follow." }, { "type": "object", "properties": { "reason": { "type": "string", "description": "What `git` said, or why it could not be run." }, "state": { "type": "string", "const": "unavailable" } }, "required": [ "state", "reason" ], "description": "`git` could not be asked, or the root is not a work tree; the reason says which." } ], "description": "What git says about the repository, or why it could not be asked." }, "GitWorkingTree": { "type": "object", "properties": { "head": { "type": [ "string", "null" ], "description": "The commit HEAD names, or `None` in a repository with no commits yet." }, "branch": { "type": [ "string", "null" ], "description": "The branch, or `None` when HEAD is detached or unborn." }, "detached": { "type": "boolean", "description": "Whether HEAD names a commit directly rather than a branch." }, "upstream": { "type": [ "string", "null" ], "description": "The upstream the branch tracks, when it tracks one." }, "ahead": { "type": [ "integer", "null" ], "format": "uint32", "minimum": 0, "description": "Commits this branch has that its upstream does not; `None` without an upstream." }, "behind": { "type": [ "integer", "null" ], "format": "uint32", "minimum": 0, "description": "Commits the upstream has that this branch does not; `None` without an upstream." }, "staged": { "type": "integer", "format": "uint32", "minimum": 0, "description": "Tracked files with staged changes." }, "modified": { "type": "integer", "format": "uint32", "minimum": 0, "description": "Tracked files changed in the work tree and not staged." }, "untracked": { "type": "integer", "format": "uint32", "minimum": 0, "description": "Files git does not track and is not ignoring." }, "conflicted": { "type": "integer", "format": "uint32", "minimum": 0, "description": "Files with an unresolved merge." }, "clean": { "type": "boolean", "description": "Whether nothing at all is staged, modified, untracked or conflicted." }, "changed_paths": { "type": "array", "items": { "type": "string" }, "description": "Every path that is not clean, repository-relative, in git's order. Used to decide\nwhether the cached tier is still valid, and shown to nobody." } }, "required": [ "detached", "staged", "modified", "untracked", "conflicted", "clean" ], "description": "The state of one work tree, as porcelain v2 reports it." }, "Graph": { "type": "object", "properties": { "id": { "type": "string", "description": "The identity, `[a-z][a-z0-9-]*`; the last segment of its route." }, "title": { "type": "string", "description": "The short name." }, "description": { "type": "string", "description": "One paragraph: what a reader learns from it." }, "source": { "type": "string", "description": "What it was derived from, in the repository's own words." }, "node_kinds": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Node kind to what that kind means." }, "edge_kinds": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Edge kind to what that edge asserts." }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/Node" }, "description": "Sorted by id." }, "edges": { "type": "array", "items": { "$ref": "#/components/schemas/Edge" }, "description": "Sorted." }, "metadata": { "$ref": "#/components/schemas/GraphMetadata", "description": "Counts and invariants." } }, "required": [ "id", "title", "description", "source", "node_kinds", "edge_kinds", "nodes", "edges", "metadata" ], "description": "A derived graph: what it is, where it came from, what its vocabularies mean, and the\nnodes and edges themselves." }, "GraphInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "The identity." }, "title": { "type": "string", "description": "The short name." }, "description": { "type": "string", "description": "One paragraph." }, "source": { "type": "string", "description": "What it is derived from." } }, "required": [ "id", "title", "description", "source" ], "description": "One graph the executable can derive: what it is, without deriving it." }, "GraphList": { "type": "object", "properties": { "count": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many." }, "graphs": { "type": "array", "items": { "$ref": "#/components/schemas/GraphInfo" }, "description": "Each, described but not derived." } }, "required": [ "count", "graphs" ], "description": "Every graph this executable derives." }, "GraphMetadata": { "type": "object", "properties": { "nodes": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many nodes." }, "edges": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many edges." }, "acyclic": { "type": "boolean", "description": "Whether the edges form a directed acyclic graph. Derived, never declared: a graph\nwhose contract is a DAG and whose answer here is `false` is a defect in the data." }, "truncated": { "type": "boolean", "description": "True when the derivation stopped at [`MAX_NODES`] and the graph is a prefix of\nwhat the repository holds." } }, "required": [ "nodes", "edges", "acyclic", "truncated" ], "description": "What a reader needs to know about the graph as a whole before drawing it." }, "Health": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/HealthStatus", "description": "The worst check's status." }, "tallies": { "type": "object", "additionalProperties": { "type": "integer", "format": "uint", "minimum": 0 }, "description": "How many checks stand where, by status word." }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/HealthCheck" }, "description": "Every dimension, in a stable order." } }, "required": [ "status", "tallies", "checks" ], "description": "The health of what this process serves." }, "HealthCheck": { "type": "object", "properties": { "id": { "type": "string", "description": "A stable id, `[a-z][a-z0-9-]*`." }, "title": { "type": "string", "description": "The short name." }, "status": { "$ref": "#/components/schemas/HealthStatus", "description": "Where it stands." }, "detail": { "type": "string", "description": "One line: what the engine decided and on what." }, "decided_by": { "type": "string", "description": "The engine that decided it, named so the reader knows what to fix." }, "evidence": { "type": "array", "items": { "type": "string" }, "description": "What reproduces the verdict: a command, or a path." }, "findings": { "type": "array", "items": { "type": "string" }, "description": "Findings behind the verdict, when the engine produced any: the diagnostic\nmessages, the stale files, the missing coverage lines." } }, "required": [ "id", "title", "status", "detail", "decided_by" ], "description": "One dimension of the system, decided by one engine, with what a reader needs to check\nit themselves." }, "HealthRoutes": { "type": "object", "additionalProperties": false, "properties": { "liveness": { "$ref": "#/components/schemas/Route", "description": "Is this process alive." }, "readiness": { "$ref": "#/components/schemas/Route", "description": "Can this process serve traffic." }, "grace_seconds": { "type": [ "integer", "null" ], "format": "uint32", "minimum": 0, "description": "How long the platform waits before the first check counts.", "default": null }, "interval_seconds": { "anyOf": [ { "$ref": "#/components/schemas/Positive" }, { "type": "null" } ], "description": "How often the platform polls liveness.", "default": null }, "timeout_seconds": { "anyOf": [ { "$ref": "#/components/schemas/Positive" }, { "type": "null" } ], "description": "How long one check may take before it counts as failed.", "default": null } }, "required": [ "liveness", "readiness" ], "description": "The routes a platform polls, and how often." }, "HealthStatus": { "oneOf": [ { "type": "string", "const": "ok", "description": "The engine that decides this dimension is satisfied." }, { "type": "string", "const": "warn", "description": "Nothing is broken and something is worth looking at." }, { "type": "string", "const": "fail", "description": "The engine that decides this dimension is not satisfied." }, { "type": "string", "const": "unknown", "description": "This process cannot decide it, and says so rather than reporting `ok`." } ], "description": "Where one dimension of the system stands. Ordered by severity, so the worst check\ndecides the whole." }, "HttpExposure": { "type": "object", "properties": { "method": { "$ref": "#/components/schemas/HttpMethod", "description": "The method." }, "path": { "type": "string", "description": "The absolute path, under [`HttpExposure::PREFIX`]." } }, "required": [ "method", "path" ], "description": "How a capability appears over HTTP. `GET` binds every top-level input property as a\nquery parameter; `POST` binds the input as the JSON request body. Paths are absolute\nand live under [`HttpExposure::PREFIX`]." }, "HttpMethod": { "oneOf": [ { "type": "string", "const": "GET", "description": "Read-only; the input is bound from the query string." }, { "type": "string", "const": "POST", "description": "The input is bound from the JSON body. No builtin uses it yet." } ], "description": "The HTTP methods a capability may be bound to." }, "Identity": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "The product name every surface shows." }, "mark": { "type": "string", "description": "The mark, relative to the design directory." }, "logo": { "type": "string", "description": "The full logo, relative to the design directory." }, "social": { "type": "string", "description": "The social preview image, relative to the design directory." } }, "required": [ "name", "mark", "logo", "social" ], "description": "Who this is." }, "InspectReport": { "type": "object", "properties": { "branch": { "type": "string", "description": "The branch asked about." }, "branch_exists": { "type": "boolean", "description": "The branch exists locally." }, "expected_path": { "type": "string", "description": "Where its work tree belongs." }, "destination_exists": { "type": "boolean", "description": "Something exists at that path." }, "worktree": { "anyOf": [ { "$ref": "#/components/schemas/WorktreeState" }, { "type": "null" } ], "description": "The work tree that holds the branch, when one does." }, "canonical": { "type": "boolean", "description": "The branch is checked out at its canonical path." }, "diagnostics": { "type": "array", "items": { "$ref": "#/components/schemas/TopologyDiagnostic" }, "description": "What stands in the way, if anything." } }, "required": [ "branch", "branch_exists", "expected_path", "destination_exists", "canonical", "diagnostics" ], "description": "One branch, inspected: where its work tree belongs and what is there." }, "InstallCheck": { "type": "object", "properties": { "id": { "type": "string", "description": "A short stable name: `model`, `version`, `targets`, `release`, `artifacts`, `metadata`." }, "state": { "$ref": "#/components/schemas/CheckState", "description": "Whether it holds." }, "observed": { "type": "string", "description": "What was observed, in one line." }, "cause": { "type": [ "string", "null" ], "description": "Why it does not hold. Absent when it does." }, "next": { "type": [ "string", "null" ], "description": "The command or action that would change it. Absent when there is nothing to do." } }, "required": [ "id", "state", "observed" ], "description": "One check: what was asked, what was seen, and — when it does not hold — why, and the\ncommand that changes it. The `cause` and `next` fields exist so that a report is\nactionable without a second document; a check that fails without naming its remedy is\na diagnostic nobody can act on." }, "InstallabilityReport": { "type": "object", "properties": { "installable": { "type": "boolean", "description": "True when every check holds: a stable release is recorded and complete." }, "summary": { "type": "string", "description": "One line for a person: what the state is, in the project's own terms." }, "local_version": { "type": "string", "description": "The version this tree would release." }, "stable_tag": { "type": [ "string", "null" ], "description": "The tag an unpinned installation resolves to, when a stable release is recorded." }, "required_targets": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many targets a release must publish for that release to be complete." }, "published_artifacts": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many of them the stable release actually publishes." }, "install_command": { "type": "string", "description": "The command a person would run, whether or not it currently works." }, "installer_url": { "type": "string", "description": "Where the installer is served." }, "latest_url": { "type": "string", "description": "Where the stable pointer is served." }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/InstallCheck" }, "description": "Every check, in the order they are worth reading." } }, "required": [ "installable", "summary", "local_version", "required_targets", "published_artifacts", "install_command", "installer_url", "latest_url", "checks" ], "description": "Whether the advertised one-line installation works right now, and if not, what is missing.\n\nThis answers the operator's actual question — *can a machine that has never seen this\nproject install it with the published command?* — from local state alone. It performs no\nnetwork access: a repository can be offline and this still answers, because everything it\nneeds is the distribution model and the release records the repository itself carries.\nWhat it cannot see it reports as `unknown` rather than guessing; the public half of the\nquestion is answered by the release workflow's smoke phase, which installs from the\npublished URL on every native runner and is the only thing that proves the public path." }, "Integration": { "oneOf": [ { "type": "string", "const": "open", "description": "Not reachable from the trunk: its commits are the ones the trunk does not have." }, { "type": "string", "const": "merged", "description": "Reachable from the trunk through a merge commit, which the trace names: its commits\nare the ones that merge brought in." }, { "type": "string", "const": "absorbed", "description": "Reachable from the trunk with no merge commit of its own — fast-forwarded, or\nrebased onto it. Its commits cannot be told from the trunk's and none are claimed." }, { "type": "string", "const": "unknown", "description": "The trunk is unknown, so there is nothing to measure the branch against." } ], "description": "How a branch stands to the trunk, which is what decides which commits are its own." }, "Interface": { "oneOf": [ { "type": "string", "const": "loopback", "description": "Reachable from this host alone: the local default, and what every local invocation\nkeeps." }, { "type": "string", "const": "all", "description": "Every interface. A hosted process needs it and a local one never does; stating it\nis the intent that replaces suppressing the bind warning." } ], "description": "Which interface a process listens on." }, "IssueTrace": { "type": "object", "properties": { "issue": { "type": "string", "description": "The issue id, as the project model spells it." }, "declared": { "type": "boolean", "description": "True when the project model declares this id. False is not an error and not an\nempty answer: it says the id was looked for and the model does not have it, which a\ncaller must be able to tell apart from \"declared, and nothing has realised it yet\".\nA repository with no project model at all answers `false` for every id rather than\nrefusing, because the branches naming an id are still derivable there." }, "milestone": { "type": [ "string", "null" ], "description": "The milestone the canonical issue record names. Git does not hold this edge and\nnothing here derives it: the caller with the index fills it in, and it is `null` in\na repository whose issue record does not name one." }, "trunk": { "type": [ "string", "null" ], "description": "The trunk every branch was measured against." }, "branches": { "type": "array", "items": { "$ref": "#/components/schemas/BranchTrace" }, "description": "The branches that name it, local first." }, "commits": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many distinct commits the branches hold between them." }, "complete": { "type": "boolean", "description": "True when every branch's commits could be derived. False when at least one reached\nthe trunk without a merge commit, so part of the work is not distinguishable." } }, "required": [ "issue", "declared", "branches", "commits", "complete" ], "description": "Everything git knows about one issue's realisation." }, "KindCount": { "type": "object", "properties": { "kind": { "type": "string", "description": "The kind, as `share/kinds.yaml` declares it." }, "count": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many objects of it the index holds." } }, "required": [ "kind", "count" ], "description": "How many valid objects of one kind the layer holds." }, "KindRef": { "type": "object", "properties": { "name": { "type": "string", "description": "The kind." }, "objects": { "type": "integer", "format": "uint", "minimum": 0, "description": "Objects of this kind in the index." } }, "required": [ "name", "objects" ], "description": "One object kind the feature names, with how many objects of it the layer holds." }, "LayerSummary": { "type": "object", "properties": { "state": { "$ref": "#/components/schemas/TierState", "description": "Where these numbers came from." }, "kinds": { "type": "array", "items": { "$ref": "#/components/schemas/KindCount" }, "description": "One entry per kind present, sorted by kind." }, "objects": { "type": [ "integer", "null" ], "format": "uint", "minimum": 0, "description": "How many objects the index holds." }, "capabilities": { "type": [ "integer", "null" ], "format": "uint", "minimum": 0, "description": "How many capabilities the registry holds." }, "invalid": { "type": [ "integer", "null" ], "format": "uint", "minimum": 0, "description": "How many files the layer declared that did not become objects." }, "degraded": { "type": [ "boolean", "null" ], "description": "Whether the layer read cleanly." } }, "required": [ "state" ], "description": "What the layer holds, counted per kind, plus the registry the executable composes.\nEvery number here comes from the index — the same objects every other surface serves —\nand never from counting files that match a pattern: a file that does not parse is not\na rule, and a count that says otherwise is a lie a person acts on." }, "LeaseView": { "type": "object", "properties": { "pid": { "type": "integer", "format": "uint32", "minimum": 0, "description": "The server's process id. Informational: nothing decides liveness from it." }, "url": { "type": [ "string", "null" ], "description": "The address, once bound." }, "started_at": { "type": "string", "description": "When the server took the lease, RFC 3339." }, "executable": { "anyOf": [ { "$ref": "#/components/schemas/ExecutableIdentity" }, { "type": "null" } ], "description": "The executable the server was started from, when it could be located." }, "version": { "type": [ "string", "null" ], "description": "The executable's version; absent for a server too old to have written one." } }, "required": [ "pid", "started_at" ], "description": "A lease as a reader sees it: what the server wrote about itself, without the token that\nmakes the file the server's own.\n\n```\nuse majordomus_cli::capability::builtin::server::LeaseView;\nlet view = LeaseView { pid: 7, url: Some(\"http://127.0.0.1:8741\".into()),\n started_at: \"2026-09-10T00:00:00Z\".into(), executable: None, version: Some(\"1.0.0\".into()) };\nlet v = serde_json::to_value(&view).unwrap();\nassert_eq!(v[\"pid\"], 7);\nassert!(v.get(\"token\").is_none() && v.get(\"root\").is_none());\n```" }, "Libc": { "oneOf": [ { "type": "string", "const": "gnu", "description": "GNU libc: the ordinary distributions." }, { "type": "string", "const": "musl", "description": "musl: Alpine, and any statically linked artifact." } ], "description": "The C library a Linux artifact is linked against." }, "LimitsView": { "type": "object", "properties": { "max_executions": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many executions are remembered." }, "max_events": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many events are retained per execution." }, "max_log_chars": { "type": "integer", "format": "uint", "minimum": 0, "description": "The longest a single log line may be." }, "max_running": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many executions run at once." }, "max_subscriber_queue": { "type": "integer", "format": "uint", "minimum": 0, "description": "How far a live channel may fall behind before it is told to resynchronise." } }, "required": [ "max_executions", "max_events", "max_log_chars", "max_running", "max_subscriber_queue" ], "description": "What this process's execution store keeps." }, "Listen": { "type": "object", "additionalProperties": false, "properties": { "port": { "$ref": "#/components/schemas/Port", "description": "The port, stated once for the process, the image and the provider configuration." }, "interface": { "$ref": "#/components/schemas/Interface", "description": "Which interface." } }, "required": [ "port", "interface" ], "description": "The address the process listens on." }, "Liveness": { "type": "object", "properties": { "alive": { "type": "boolean", "description": "Always `true`. A process that could not answer would not answer at all, which is\nthe signal." }, "version": { "type": "string", "description": "This executable's version, so a rolling deployment can tell which build answered." } }, "required": [ "alive", "version" ], "description": "The answer to \"is this process alive\": the cheapest true thing this executable can\nsay about itself. Deliberately not a summary of anything — a probe that grew an\nopinion would stop reporting the one fact the platform polls it for." }, "LogStream": { "oneOf": [ { "type": "string", "const": "stdout", "description": "The standard output of a child process the handler ran." }, { "type": "string", "const": "stderr", "description": "Its standard error." }, { "type": "string", "const": "handler", "description": "The handler itself, saying something it wants a reader to see." } ], "description": "Which stream a log line came from." }, "Machines": { "type": "object", "additionalProperties": false, "properties": { "count": { "$ref": "#/components/schemas/Positive", "description": "How many machines the application has." }, "min_running": { "type": "integer", "format": "uint32", "minimum": 0, "description": "How many stay running when idle." }, "autostart": { "type": "boolean", "description": "Whether a request to a stopped machine starts it." }, "autostop": { "type": "boolean", "description": "Whether an idle machine is stopped." } }, "required": [ "count", "min_running", "autostart", "autostop" ], "description": "How many machines run, and whether the platform may stop them." }, "Match": { "oneOf": [ { "type": "string", "const": "same_worktree_same_branch", "description": "Same repository, same worktree, same branch." }, { "type": "string", "const": "same_branch", "description": "Same repository, same branch, another worktree of it." } ], "description": "Which tier of the resolution rule matched. There is no third tier on purpose: a record\nfrom an unrelated worktree or branch is never offered." }, "Matrix": { "type": "object", "properties": { "schema": { "type": "string", "description": "[`SCHEMA`]." }, "surfaces": { "type": "array", "items": { "$ref": "#/components/schemas/SurfaceInfo" }, "description": "The surface vocabulary." }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/MatrixRow" }, "description": "One row per feature of any status but deprecated, in presentation order." }, "modules": { "type": "array", "items": { "$ref": "#/components/schemas/ProductCoverage" }, "description": "Every builtin module of the executable with the stable features that name it." }, "commands": { "type": "array", "items": { "$ref": "#/components/schemas/ProductCoverage" }, "description": "Every public command of the shell tool with the stable features that name it." }, "kinds": { "type": "array", "items": { "$ref": "#/components/schemas/ProductCoverage" }, "description": "Every kind of the layer a feature can present, with the stable features that name it." } }, "required": [ "schema", "surfaces", "rows", "modules", "commands", "kinds" ], "description": "Every feature against every interface, and every module, command and kind against the\nfeatures that name it." }, "MatrixRow": { "type": "object", "properties": { "id": { "type": "string", "description": "The feature id." }, "label": { "type": "string", "description": "The name a narrow column shows." }, "route": { "type": "string", "description": "`/features//`." }, "status": { "type": "string", "description": "`stable` or `draft`." }, "surfaces": { "$ref": "#/components/schemas/Surfaces", "description": "The surfaces, by id, in the vocabulary's order." }, "exposed": { "type": "array", "items": { "type": "string" }, "description": "The surface ids that are true." } }, "required": [ "id", "label", "route", "status", "surfaces", "exposed" ], "description": "One row of the matrix: a feature and the surfaces it is exposed through." }, "McpExposure": { "type": "object", "properties": { "tool": { "type": [ "string", "null" ], "description": "As a tool with this name (`[a-z0-9_]+`)." }, "resource": { "anyOf": [ { "$ref": "#/components/schemas/McpResource" }, { "type": "null" } ], "description": "As a readable resource." } }, "description": "How, if at all, a capability appears to an MCP client." }, "McpResource": { "type": "object", "properties": { "uri": { "type": "string", "description": "`majordomus:///`, or `majordomus://repository`." }, "name": { "type": "string", "description": "The short name a client lists; the identity for a declarative object." } }, "required": [ "uri", "name" ], "description": "An MCP resource: its URI and the short name a client lists." }, "Measured": { "type": "object", "properties": { "foreground": { "type": "string", "description": "The foreground token, as the declaration names it (`muted`, `ok`)." }, "foreground_entry": { "type": "string", "description": "The palette entry it resolves to in this theme." }, "foreground_value": { "type": "string", "description": "The literal that entry holds." }, "ground": { "type": "string", "description": "The ground token." }, "ground_entry": { "type": "string", "description": "The palette entry the ground resolves to in this theme." }, "ground_value": { "type": "string", "description": "The literal that entry holds." }, "theme": { "type": "string", "description": "`light` or `dark`." }, "carries": { "$ref": "#/components/schemas/Carries", "description": "Text, or a border." }, "ratio": { "type": "number", "format": "double", "description": "The measured ratio, to two decimal places." }, "required": { "type": "number", "format": "double", "description": "What the standard asks of this pair." }, "passes": { "type": "boolean", "description": "Whether it reaches it." }, "enforced": { "type": "boolean", "description": "Whether falling short is a finding. False for a border; see the module documentation." }, "seen": { "type": "string", "description": "Where the pair was read: the stylesheet and the selector that states it." } }, "required": [ "foreground", "foreground_entry", "foreground_value", "ground", "ground_entry", "ground_value", "theme", "carries", "ratio", "required", "passes", "enforced", "seen" ], "description": "One measured pair: a foreground on a ground, in one theme." }, "MigrationAction": { "oneOf": [ { "type": "string", "const": "move", "description": "One `git worktree move`." }, { "type": "string", "const": "move_via_staging", "description": "The worktree is the container itself: out to a staging path, then into the container." }, { "type": "string", "const": "copy_and_repair", "description": "The move crossed devices: copy, `git worktree repair`, verify, remove the original." }, { "type": "string", "const": "none", "description": "Nothing: the step is blocked." } ], "description": "How a step moves its worktree." }, "MigrationPlan": { "type": "object", "properties": { "schema": { "type": "string", "description": "[`SCHEMA`]." }, "container": { "type": "string", "description": "The container everything moves into." }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/MigrationStep" }, "description": "One step per misplaced worktree with a branch, container occupants first." }, "exceptions": { "type": "array", "items": { "$ref": "#/components/schemas/TopologyDiagnostic" }, "description": "Worktrees the migration cannot address by design: detached, missing, the primary\ncheckout off the trunk. Each says what a person does about it." }, "movable": { "type": "integer", "format": "uint", "minimum": 0, "description": "Steps that can be carried out as things stand." }, "blocked": { "type": "integer", "format": "uint", "minimum": 0, "description": "Steps that cannot." }, "moved": { "type": "integer", "format": "uint", "minimum": 0, "description": "Steps carried out and verified." }, "failed": { "type": "integer", "format": "uint", "minimum": 0, "description": "Steps attempted and not verified." }, "applied": { "type": "boolean", "description": "Whether anything was changed." }, "moved_current": { "type": [ "string", "null" ], "description": "The new path of the worktree the command was run from, when that one moved." } }, "required": [ "schema", "container", "steps", "exceptions", "movable", "blocked", "moved", "failed", "applied" ], "description": "A migration, planned or applied." }, "MigrationStep": { "type": "object", "properties": { "branch": { "type": "string", "description": "The branch it holds." }, "from": { "type": "string", "description": "Where it is." }, "to": { "type": "string", "description": "Where it belongs." }, "head": { "type": [ "string", "null" ], "description": "The commit checked out." }, "action": { "$ref": "#/components/schemas/MigrationAction", "description": "How it moves." }, "dirty": { "$ref": "#/components/schemas/DirtyState", "description": "Its uncommitted work, which moves with it." }, "blockers": { "type": "array", "items": { "$ref": "#/components/schemas/TopologyDiagnostic" }, "description": "Why it cannot move, when it cannot." }, "outcome": { "$ref": "#/components/schemas/StepOutcome", "description": "What happened." }, "message": { "type": [ "string", "null" ], "description": "What happened, in words, when it was not simply moved." }, "before": { "anyOf": [ { "$ref": "#/components/schemas/WorktreeFingerprint" }, { "type": "null" } ], "description": "The fingerprint before the move." }, "after": { "anyOf": [ { "$ref": "#/components/schemas/WorktreeFingerprint" }, { "type": "null" } ], "description": "The fingerprint after it." }, "differences": { "type": "array", "items": { "type": "string" }, "description": "What differs between the two; empty when verified." }, "envrc": { "anyOf": [ { "$ref": "#/components/schemas/EnvrcApproval" }, { "type": "null" } ], "description": "What became of its `.envrc` under direnv once it was at its new path: the primary\ncheckout's approval carried there, or why it was not. Only on a moved step." } }, "required": [ "branch", "from", "to", "action", "dirty", "blockers", "outcome", "differences" ], "description": "One worktree to bring home." }, "ModuleId": { "type": "string", "description": "A module identity: the namespace of every capability the module composes, matching\n`[a-z][a-z0-9_-]*`. Builtin modules declare theirs in `module!`; a declarative\nobject's module is its kind." }, "ModuleQuality": { "type": "object", "properties": { "modules": { "type": "integer", "format": "uint", "minimum": 0, "description": "Modules the crate exports, the crate root included." }, "documented": { "type": "integer", "format": "uint", "minimum": 0, "description": "Of those, how many carry a `//!` header." }, "exampled": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many carry an executable example in that header." }, "behaviourally_tested": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many something exercises: an in-file test, or a test that names them." } }, "required": [ "modules", "documented", "exampled", "behaviourally_tested" ], "description": "What the exported module surface looks like." }, "ModuleRef": { "type": "object", "properties": { "id": { "type": "string", "description": "The module id." }, "title": { "type": "string", "description": "The short name." }, "description": { "type": "string", "description": "One paragraph." }, "stability": { "type": [ "string", "null" ], "description": "Where the module stands, when it declared it." }, "source_path": { "type": "string", "description": "Repository-relative path of the file its descriptors were composed in." }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/CapabilityRef" }, "description": "The builtin capabilities it composes, in id order." } }, "required": [ "id", "title", "description", "source_path", "capabilities" ], "description": "One capability module the feature names." }, "MomentDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "The identity, the slug and the file name." }, "title": { "type": "string", "description": "The moment as a heading." }, "short_title": { "type": [ "string", "null" ], "description": "Two or three words for a narrow column, when the record carries one." }, "hook": { "type": "string", "description": "The first-person line an index shows." }, "summary": { "type": "string", "description": "One line: what is actually wrong." }, "status": { "type": "string", "description": "`stable`, `draft` or `deprecated`." }, "severity": { "type": "string", "description": "`low`, `medium` or `high`." }, "frequency": { "type": "string", "description": "`rare`, `occasional`, `common` or `constant`." }, "weight": { "type": "integer", "format": "uint32", "minimum": 0, "description": "Presentation order, lowest first.", "default": 0 }, "featured": { "type": "boolean", "description": "Whether the homepage shows it.", "default": false }, "audiences": { "type": "array", "items": { "type": "string" }, "description": "The audiences that recognise it." }, "areas": { "type": "array", "items": { "type": "string" }, "description": "The operational areas it falls under." }, "lifecycle": { "type": "array", "items": { "type": "string" }, "description": "The stages of work at which it shows up.", "default": [] }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free tags.", "default": [] }, "signals": { "type": "array", "items": { "$ref": "#/components/schemas/Signal" }, "description": "The observable symptoms." }, "examples": { "type": "array", "items": { "$ref": "#/components/schemas/Example" }, "description": "The concrete situations." }, "commands": { "type": "array", "items": { "type": "string" }, "description": "Commands of the tool that answer it.", "default": [] }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Capability ids of the executable that answer it.", "default": [] }, "claims": { "type": "array", "items": { "type": "string" }, "description": "Claims that say what is guaranteed here.", "default": [] }, "doctrines": { "type": "array", "items": { "type": "string" }, "description": "Rules of the effective set that govern it.", "default": [] }, "use_cases": { "type": "array", "items": { "type": "string" }, "description": "Use cases that show the way out.", "default": [] }, "related": { "type": "array", "items": { "type": "string" }, "description": "Moments explicitly related to this one. The reverse is derived.", "default": [] }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Other words a reader might search for.", "default": [] }, "route": { "type": "string", "description": "Derived: `/why//`. Never authored; the schema refuses a `route` key.", "default": "" }, "source": { "type": "string", "description": "Derived: the repository-relative file the record came from.", "default": "" }, "body": { "type": "string", "description": "The Markdown body, without its front matter." }, "responsibilities": { "type": "array", "items": { "type": "string" }, "description": "Derived: the responsibilities the claims it names belong to." }, "backlinks": { "type": "array", "items": { "type": "string" }, "description": "Derived: the moments that name this one in their `related`." }, "similar": { "type": "array", "items": { "type": "string" }, "description": "Derived: moments sharing an area or an audience with this one and not already\nnamed by it, nearest first — most shared metadata, then presentation order." }, "related_detail": { "type": "array", "items": { "$ref": "#/components/schemas/MomentSummary" }, "description": "Derived: the explicitly related moments, summarised so a page needs one call." }, "neighbours": { "type": "array", "items": { "type": "string" }, "description": "Derived: what a reader should see next, in one list and in a stated order — what\nthis moment names, then what names it, then what is nearest by shared metadata,\neach appearing once. The three lists above are the same relations kept apart for a\nreader that wants to know which is which." } }, "required": [ "id", "title", "hook", "summary", "status", "severity", "frequency", "audiences", "areas", "signals", "examples", "responsibilities", "backlinks", "similar", "related_detail", "neighbours" ], "description": "One moment in full, with everything derived that a page shows and no file states." }, "MomentRef": { "type": "object", "properties": { "id": { "type": "string", "description": "The moment id." }, "title": { "type": "string", "description": "The title." }, "hook": { "type": "string", "description": "The first-person line an index shows." }, "route": { "type": "string", "description": "`/why//`." } }, "required": [ "id", "title", "hook", "route" ], "description": "One operational moment the feature answers: derived from the moments that name any of\nthe feature's commands, capabilities, claims or rules." }, "MomentSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "The identity and the slug." }, "title": { "type": "string", "description": "The moment as a heading." }, "label": { "type": "string", "description": "The name a narrow column shows: the short title, or the title." }, "hook": { "type": "string", "description": "The first-person line an index shows." }, "summary": { "type": "string", "description": "One line: what is actually wrong." }, "status": { "type": "string", "description": "`stable`, `draft` or `deprecated`." }, "severity": { "type": "string", "description": "`low`, `medium` or `high`." }, "frequency": { "type": "string", "description": "`rare`, `occasional`, `common` or `constant`." }, "weight": { "type": "integer", "format": "uint32", "minimum": 0, "description": "Presentation order." }, "featured": { "type": "boolean", "description": "Whether the homepage shows it." }, "audiences": { "type": "array", "items": { "type": "string" }, "description": "The audiences that recognise it." }, "areas": { "type": "array", "items": { "type": "string" }, "description": "The operational areas it falls under." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free tags." }, "route": { "type": "string", "description": "Derived: `/why//`." }, "signals": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many observable symptoms it declares." }, "examples": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many concrete situations it carries." } }, "required": [ "id", "title", "label", "hook", "summary", "status", "severity", "frequency", "weight", "featured", "audiences", "areas", "tags", "route", "signals", "examples" ], "description": "One moment as a listing shows it: everything a card needs and nothing a page needs." }, "Mount": { "type": "string", "description": "An absolute mount path, without a trailing slash." }, "Node": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique within the graph." }, "kind": { "type": "string", "description": "One of the graph's declared node kinds." }, "label": { "type": "string", "description": "The short label a renderer draws." }, "summary": { "type": [ "string", "null" ], "description": "One line about the thing, when the source holds one." }, "route": { "type": [ "string", "null" ], "description": "Where the Cockpit shows this thing, when it shows it." }, "source": { "type": [ "string", "null" ], "description": "The repository-relative file the node was derived from, when one file owns it." }, "status": { "type": [ "string", "null" ], "description": "A status word the graph's own vocabulary defines (`accepted`, `active`, `query`)." }, "external": { "type": "boolean", "description": "True when the node stands for something the graph names but does not hold: a\nreference that resolves to nothing in this repository." }, "facts": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Fact" }, "description": "What the object's own kind declares about it, as its schema validated it: the\nfields of its front matter that are facts about the thing rather than the document\nitself. A rule carries its class and its statement, a skill its inputs and\noutputs, a decision its date — the vocabulary that makes each kind worth having,\nrather than the four fields every kind happens to share." } }, "required": [ "id", "kind", "label" ], "description": "One node. `id` is unique within the graph; `kind` is what the graph's `node_kinds`\ndeclares it to be; `route` is where the Cockpit shows the thing itself, when it shows\nit anywhere." }, "ObjectList": { "type": "object", "properties": { "count": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many objects matched." }, "objects": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectSummary" }, "description": "The objects, one summary each." } }, "required": [ "count", "objects" ], "description": "The answer of `objects.list`: the matching objects, summarised, in URI order." }, "ObjectProvenance": { "type": "object", "properties": { "path": { "type": "string", "description": "Repository-relative path, forward slashes, as the version-control index names it." }, "directory": { "type": "string", "description": "The directory the path sits in, repository-relative; `.` for the root. This is the\nhierarchy position a client orders by; no merge semantics are implied." }, "source_class": { "type": "string", "description": "The `sources.yaml` class that discovered the file (`rule`, `readme`, ...)." }, "section": { "type": [ "string", "null" ], "description": "The manifest section the path falls under (`rules`, `prompts`, ...), when it falls\nunder one; a root `README.md` falls under none." }, "bytes": { "type": "integer", "format": "uint64", "minimum": 0, "description": "Size of the file in bytes." }, "member": { "type": [ "string", "null" ], "description": "For an object that is one member of a collection file: the member's key path in\nthe file (`claims.3`)." } }, "required": [ "path", "directory", "source_class", "bytes" ], "description": "Where an object came from. Every field is computed from the repository, never authored." }, "ObjectStanding": { "oneOf": [ { "type": "string", "const": "current", "description": "It is what the index read." }, { "type": "string", "const": "changed", "description": "It is there and it has changed since the index was built." }, { "type": "string", "const": "missing", "description": "The file the index read is no longer there." }, { "type": "string", "const": "unreadable", "description": "It is there and could not be read." } ], "description": "How one file stands against what the index read from it." }, "ObjectSummary": { "type": "object", "properties": { "uri": { "type": "string", "description": "`majordomus:///`." }, "id": { "type": "string", "description": "The capability id, `.`." }, "kind": { "type": "string", "description": "The kind the object was read as." }, "identity": { "type": "string", "description": "The identity within the kind." }, "title": { "type": [ "string", "null" ], "description": "The title, when the kind's title rule found one." }, "description": { "type": [ "string", "null" ], "description": "The one-line description, when the kind holds one." }, "path": { "type": "string", "description": "Repository-relative source path." } }, "required": [ "uri", "id", "kind", "identity", "path" ], "description": "One object, summarised for a listing." }, "ObjectView": { "type": "object", "properties": { "uri": { "type": "string", "description": "`majordomus:///`." }, "id": { "type": "string", "description": "The capability id, `.`." }, "kind": { "type": "string", "description": "The kind the object was read as (`rule`, `prompt`, `document`, ...)." }, "identity": { "type": "string", "description": "The identity within the kind (`majordomus.scope-integrity@1`, `continue`, a path)." }, "title": { "type": [ "string", "null" ], "description": "The title the kind's title rule found, when it found one." }, "description": { "type": [ "string", "null" ], "description": "The one-line description the kind's description field held, when it held one." }, "metadata": { "description": "The parsed front matter or YAML, keys in the file's order." }, "provenance": { "$ref": "#/components/schemas/ObjectProvenance", "description": "Where the object came from: path, directory, source class, section, size, member." }, "media_type": { "type": "string", "description": "IANA media type of `content` (`text/markdown`, `application/yaml`, `application/json`, `text/plain`)." }, "content": { "type": "string", "description": "The file as read." } }, "required": [ "uri", "id", "kind", "identity", "metadata", "provenance", "media_type", "content" ], "description": "One declarative object of the repository's layer, as a client reads it." }, "Obligation": { "type": "object", "properties": { "id": { "type": "string", "description": "The token, as a task's `requires` names it." }, "title": { "type": "string", "description": "The obligation as a heading." }, "summary": { "type": "string", "description": "What a worker is being asked to have done." }, "discharged_by": { "type": "string", "description": "The command that produces the evidence. `none` for a token held by another line of\nthe contract and listed so that a report can say it rather than leave a hole." }, "inputs": { "type": "array", "items": { "type": "string" }, "description": "The pathspecs the evidence is hashed over. Empty for a token whose fact is remote,\nand empty for one bound to neither: see [`ObligationClosure::staleness`]." }, "remote": { "type": "boolean", "description": "True when the fact cannot be established from the working tree alone — a push, a\npublication, a deployment. Such evidence is bound to a commit, not to a tree." }, "note": { "type": "string", "description": "What the vocabulary says about the token beyond its summary." } }, "required": [ "id", "title", "summary", "discharged_by", "remote" ], "description": "One token a task may declare in `requires`, as the distribution ships it.\n\n`remote` and `inputs` are what decide how its evidence is judged, and they are the\nfile's decision rather than this reader's: a fact the working tree cannot establish is\nbound to the commit it was taken at, and everything else is bound to the bytes of the\nfiles its pathspecs select.\n\n```\nuse majordomus_cli::capability::builtin::obligations::Obligation;\nlet push: Obligation = serde_json::from_str(\n r#\"{\"id\":\"push\",\"title\":\"The commit reached the remote\",\n \"summary\":\"The branch's head exists on the remote it tracks.\",\n \"discharged_by\":\"git\",\"remote\":true}\"#,\n)\n.unwrap();\nassert!(push.remote);\nassert!(push.inputs.is_empty(), \"a remote fact is bound to a commit, not to a tree\");\n```" }, "ObligationClosure": { "type": "object", "properties": { "id": { "type": "string", "description": "The token, as the task's `requires` names it." }, "title": { "type": "string", "description": "From the vocabulary; the token itself when it declares none." }, "summary": { "type": "string", "description": "From the vocabulary." }, "discharged_by": { "type": "string", "description": "From the vocabulary: the command that produces the evidence." }, "remote": { "type": "boolean", "description": "From the vocabulary: whether the fact is remote." }, "inputs": { "type": "array", "items": { "type": "string" }, "description": "From the vocabulary: the pathspecs the evidence is hashed over." }, "state": { "$ref": "#/components/schemas/ObligationState", "description": "Where it stands." }, "staleness": { "anyOf": [ { "$ref": "#/components/schemas/Divergence" }, { "type": "null" } ], "description": "How far the evidence is from this checkout, in the repository's one staleness\nvocabulary. `None` when there is no evidence to label.\n\nA remote fact is labelled against the commit it was taken at, because the site that\nserves a commit goes on serving it while the tree moves underneath. A tree-bound\nfact is labelled by re-hashing: equal hashes are `exact`, and a difference takes the\ncommit's label, which is `advanced` when the working tree has merely moved on and\n`diverged` when the history it named is gone. A token that declares neither inputs\nnor a remote fact is bound to nothing and stays `exact` once recorded — that is the\nvalidator's behaviour, and it is reproduced rather than tightened here." }, "evidence": { "anyOf": [ { "$ref": "#/components/schemas/Evidence" }, { "type": "null" } ], "description": "The line that discharged it, or `None`." }, "inputs_hash_now": { "type": [ "string", "null" ], "description": "What the token's inputs hash to in this tree now — the other half of \"stale against\nwhat\". `None` for a token that declares no inputs, and `None` when git could not be\nasked which files they select." }, "inputs_files": { "type": [ "integer", "null" ], "format": "uint", "minimum": 0, "description": "How many tracked files that hash was taken over. Reported because the shell's\nselection and this one are not always the same set — see the module header — and a\ncount is the cheapest way for a reader to see it rather than be told it." }, "detail": { "type": "string", "description": "One line: what this obligation's standing actually is, in the words the validator\nuses when it refuses." }, "reproduce": { "type": "string", "description": "The command that would discharge it. Every finding here carries the way to act on\nit, as `project.finding-carries-reproduce` asks." } }, "required": [ "id", "title", "remote", "state", "detail", "reproduce" ], "description": "One obligation the task declared, joined with what the vocabulary says about it and\nwith the evidence that does or does not discharge it.\n\nThe vocabulary's fields are repeated here on purpose: a client asking what this task\nowes gets the token's title, its summary and the command that would discharge it in the\nsame answer, and needs no second call to render a report.\n\n```\nuse majordomus_cli::capability::builtin::obligations::{ObligationClosure, ObligationState};\nlet owed: ObligationClosure = serde_json::from_str(\n r#\"{\"id\":\"pages\",\"title\":\"The published site serves this commit\",\"remote\":true,\n \"state\":\"owed\",\"detail\":\"owed, and no evidence was recorded\",\n \"reproduce\":\"majordomus evidence --covers pages --command 'scripts/pages verify'\"}\"#,\n)\n.unwrap();\nassert_eq!(owed.state, ObligationState::Owed);\nassert!(owed.evidence.is_none() && owed.staleness.is_none(), \"nothing to label\");\nassert!(owed.reproduce.starts_with(\"majordomus evidence\"), \"a finding carries its repair\");\n```" }, "ObligationState": { "oneOf": [ { "type": "string", "const": "owed", "description": "Declared, and no evidence for it was ever recorded." }, { "type": "string", "const": "discharged", "description": "Evidence exists and still describes this tree, or this commit." }, { "type": "string", "const": "stale", "description": "Evidence exists and no longer describes what it proved: the inputs changed, or the\ncommit it named is not this one." }, { "type": "string", "const": "undeclared", "description": "The task requires a token the shipped vocabulary does not declare. Nothing can\ndischarge it, because nothing knows what would." } ], "description": "Where one obligation stands.\n\nThe words are the validator's verdicts, not a severity scale: `stale` is not a worse\n`owed`, it is evidence that was true and no longer describes what it proved.\n\n```\nuse majordomus_cli::capability::builtin::obligations::ObligationState;\n// only one of the four lets a task be called completed\nlet completable = |s: ObligationState| s == ObligationState::Discharged;\nassert!(completable(ObligationState::Discharged));\nassert!(!completable(ObligationState::Stale), \"evidence that no longer describes the tree\");\nassert!(!completable(ObligationState::Owed));\nassert!(!completable(ObligationState::Undeclared));\n```" }, "OpenSession": { "type": "object", "properties": { "session_id": { "type": "string", "description": "The episode's id." }, "started_at": { "type": "string", "description": "When it opened." }, "owner": { "type": "string", "description": "Who opened it." }, "worker": { "type": "string", "description": "The worker identity, when one was supplied. Never inferred." }, "provider": { "type": "string", "description": "The provider whose event opened it, when one did." }, "provider_session": { "type": "string", "description": "That provider's own session identity — the string the prompt archive stamps on the\nsame worker's records, and the name this episode is keyed by. Empty for an episode\nopened by hand, which is the one episode no provider session owns." }, "branch": { "type": "string", "description": "The branch it opened on." }, "start_head": { "type": "string", "description": "The commit it opened at." }, "foreign": { "type": "boolean", "description": "True when the open record here belongs to another checkout. Such a record is\nreported and never treated as this checkout's episode." } }, "required": [ "session_id", "started_at", "foreign" ], "description": "The open episode this checkout points at, when there is one.\n\nOne execution episode belongs to one provider session, and several can be open in one\ncheckout at once — two windows of the same provider are two workers. What is read here\nis `state/session-current.yaml`, the pointer to the episode of this checkout; a worker\nthat knows its own provider session resolves its own episode instead, which is what\n`mj_session_here_file` in `lib/common.sh` does and what stamps each ledger line." }, "OperationParity": { "type": "object", "properties": { "canonical": { "type": "integer", "format": "uint", "minimum": 0, "description": "Executable capabilities in the registry." }, "cli": { "type": "integer", "format": "uint", "minimum": 0, "description": "Of those, how many declare a command-line projection." }, "http": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many declare an HTTP route." }, "openapi": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many the OpenAPI document describes." }, "mcp": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many declare an MCP tool." }, "cli_commands": { "type": "integer", "format": "uint", "minimum": 0, "description": "Commands of the command line, leaves and runnable parents." }, "cli_from_capability": { "type": "integer", "format": "uint", "minimum": 0, "description": "Of those, how many are the projection of a capability." }, "cli_local": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many are declared to belong to the command line alone, with a reason." } }, "required": [ "canonical", "cli", "http", "openapi", "mcp", "cli_commands", "cli_from_capability", "cli_local" ], "description": "What the canonical operations look like against the transports that project them." }, "Origin": { "oneOf": [ { "type": "string", "const": "repository", "description": "The repository's own, named by the manifest's `scope` section." }, { "type": "string", "const": "distribution", "description": "The distribution's default, because the repository declares none." } ], "description": "Where the declaration was read from." }, "Os": { "oneOf": [ { "type": "string", "const": "macos", "description": "Apple's, detected as `Darwin`." }, { "type": "string", "const": "linux", "description": "Linux, detected as `Linux`, and the only one where the C library matters." }, { "type": "string", "const": "windows", "description": "Windows; representable, and not built today." } ], "description": "An operating system a target runs on." }, "Out": { "type": "object", "additionalProperties": false, "properties": { "paths": { "type": "array", "items": { "type": "string" }, "description": "Never read, by path: version control, the local half, dependencies, build outputs.", "default": [] }, "binary": { "type": "boolean", "description": "Content that is not text (a NUL byte in the first window) is out, whatever the name says.", "default": false }, "max_bytes": { "type": [ "integer", "null" ], "format": "uint64", "minimum": 0, "description": "A file over this many bytes is out, whatever it is." }, "archive": { "anyOf": [ { "$ref": "#/components/schemas/Category" }, { "type": "null" } ], "description": "Archives." }, "image": { "anyOf": [ { "$ref": "#/components/schemas/Category" }, { "type": "null" } ], "description": "Images." }, "video": { "anyOf": [ { "$ref": "#/components/schemas/Category" }, { "type": "null" } ], "description": "Video." }, "pdf": { "anyOf": [ { "$ref": "#/components/schemas/Category" }, { "type": "null" } ], "description": "PDF documents." }, "database_dump": { "anyOf": [ { "$ref": "#/components/schemas/Category" }, { "type": "null" } ], "description": "Database dumps." }, "generated": { "anyOf": [ { "$ref": "#/components/schemas/Category" }, { "type": "null" } ], "description": "Generated assets: changed by changing the source and regenerating." }, "secret": { "anyOf": [ { "$ref": "#/components/schemas/Category" }, { "type": "null" } ], "description": "Secrets: never read, never served, never quoted; a tracked one is reported." }, "fixtures": { "anyOf": [ { "$ref": "#/components/schemas/Fixtures" }, { "type": "null" } ], "description": "Fixtures are read up to a size; over it they are data, not context." } }, "description": "The `out:` mapping: every category optional, each the reason a path is out." }, "OutFile": { "type": "object", "properties": { "path": { "type": "string", "description": "Repository-relative." }, "reason": { "$ref": "#/components/schemas/Reason", "description": "Why." }, "rule": { "type": [ "string", "null" ], "description": "The rule that decided; absent for `undeclared`." } }, "required": [ "path", "reason" ], "description": "One tracked file that is out." }, "Overlap": { "type": "object", "properties": { "peer": { "$ref": "#/components/schemas/PeerId", "description": "The other peer." }, "attached": { "type": "boolean", "description": "Whether that peer is still attached. An overlap with a departed peer is a weaker\nsignal than one with a live session, and the reader is told which it is." }, "intent": { "type": "string", "description": "What it said it was doing." }, "paths": { "type": "array", "items": { "$ref": "#/components/schemas/OverlapPath" }, "description": "The claims that meet: one line per pair, `yours` and `theirs`." } }, "required": [ "peer", "attached", "intent", "paths" ], "description": "Two peers that claimed the same ground.\n\nReported when the second of them announces, so that a collision is known at the moment\nit is created rather than discovered afterwards in the history of a branch." }, "OverlapPath": { "type": "object", "properties": { "yours": { "type": "string", "description": "The path the announcing peer claimed." }, "theirs": { "type": "string", "description": "The path the other peer claimed." } }, "required": [ "yours", "theirs" ], "description": "One pair of claims that contain one another." }, "ParameterView": { "type": "object", "properties": { "name": { "type": "string", "description": "Its name." }, "description": { "type": "string", "description": "What it does." }, "required": { "type": "boolean", "description": "Whether it must be given." } }, "required": [ "name", "description", "required" ], "description": "One query parameter of the live channel." }, "Peer": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/PeerId", "description": "`p1`, `p2`, ..." }, "client": { "$ref": "#/components/schemas/ClientInfo", "description": "The client behind it." }, "transport": { "$ref": "#/components/schemas/Transport", "description": "How it is attached." }, "connected_at": { "type": "string", "description": "When it attached, RFC 3339, UTC." }, "last_seen_seconds_ago": { "type": "integer", "format": "uint64", "minimum": 0, "description": "Seconds since its last message." }, "attached": { "type": "boolean", "description": "Whether the session is still attached. A peer that announced something and then\nwent away is kept and listed with `attached: false`: what it said it was working on\noutlives the connection that said it, because the work does." }, "announcement": { "anyOf": [ { "$ref": "#/components/schemas/Announcement" }, { "type": "null" } ], "description": "Its announcement, when it made one." } }, "required": [ "id", "client", "transport", "connected_at", "last_seen_seconds_ago", "attached" ], "description": "One peer as the board lists it." }, "PeerId": { "type": "string", "description": "A peer's identity for the life of the server: `p1`, `p2`, ... in attachment order.\n`p1` is the session that started the server." }, "PeerList": { "type": "object", "properties": { "count": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many peers are attached, the caller included." }, "caller": { "anyOf": [ { "$ref": "#/components/schemas/PeerId" }, { "type": "null" } ], "description": "The caller's own peer id, when the call came through an MCP session." }, "peers": { "type": "array", "items": { "$ref": "#/components/schemas/Peer" }, "description": "The peers, in attachment order; `p1` started the server. A peer that announced\nsomething and then went away is still here, with `attached: false`." }, "overlaps": { "type": "array", "items": { "$ref": "#/components/schemas/Overlap" }, "description": "Every pair of peers whose claimed scope meets, each pair once. Empty is the\nordinary case, and a reader who sees an entry here is looking at two sessions\nabout to do the same work." } }, "required": [ "count", "peers" ], "description": "The answer of `peers.list`: every client attached to this shared server." }, "PhaseTotals": { "type": "object", "properties": { "count": { "type": "integer", "format": "uint64", "minimum": 0, "description": "How many times the phase ran." }, "total_nanos": { "type": "integer", "format": "uint64", "minimum": 0, "description": "Nanoseconds spent in it, summed." } }, "required": [ "count", "total_nanos" ], "description": "A phase's totals." }, "Plan": { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/PlanProject", "description": "The plan's header, with the active milestone derived." }, "statuses": { "$ref": "#/components/schemas/PlanVocabulary", "description": "The declared status vocabularies." }, "milestones": { "type": "array", "items": { "$ref": "#/components/schemas/PlanMilestone" }, "description": "Every milestone, in id order." }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/PlanIssue" }, "description": "Every issue, in id order." }, "waves": { "type": "array", "items": { "$ref": "#/components/schemas/PlanWave" }, "description": "The execution waves, lowest first." }, "edges": { "type": "array", "items": { "$ref": "#/components/schemas/PlanEdge" }, "description": "The issue dependency graph, sorted." }, "milestone_edges": { "type": "array", "items": { "$ref": "#/components/schemas/PlanEdge" }, "description": "The milestone dependency graph, sorted." }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/PlanFinding" }, "description": "Every finding, in derivation order." } }, "required": [ "project", "statuses", "milestones", "issues", "waves", "edges", "milestone_edges", "findings" ], "description": "The whole derived plan: what every plan capability answers out of." }, "PlanCounts": { "type": "object", "properties": { "total": { "type": "integer", "format": "uint32", "minimum": 0, "description": "Every issue naming this milestone." }, "required": { "type": "integer", "format": "uint32", "minimum": 0, "description": "The denominator the milestone's own status derivation uses: total less cancelled, so\nno surface prints \"n of total\" for a milestone the engine calls DONE." }, "by_status": { "type": "object", "additionalProperties": { "type": "integer", "format": "uint32", "minimum": 0 }, "description": "One entry per declared issue status, keyed by the vocabulary." } }, "required": [ "total", "required", "by_status" ], "description": "A milestone's issues counted: the two denominators, then one entry per declared status." }, "PlanEdge": { "type": "object", "properties": { "from": { "type": "string", "description": "The record that must be real first." }, "to": { "type": "string", "description": "The record that waits for it." } }, "required": [ "from", "to" ], "description": "One dependency edge, `from` before `to`." }, "PlanFinding": { "type": "object", "properties": { "level": { "type": "string", "description": "`FAIL` or `WARN`. A failure means the model is invalid." }, "code": { "type": "string", "description": "The stable code a reader greps for (`unknown_dependency`, `scope_conflict`, …)." }, "subject": { "type": "string", "description": "The record the finding is about, or `graph` when it is about the whole graph." }, "message": { "type": "string", "description": "What is wrong, in one line." } }, "required": [ "level", "code", "subject", "message" ], "description": "One validation finding, in the shape `project.finding-carries-reproduce` asks for." }, "PlanIssue": { "type": "object", "properties": { "id": { "type": "string", "description": "The identity, which is also the file name." }, "milestone": { "type": "string", "description": "The milestone it belongs to." }, "status": { "type": "string", "description": "The derived status. Never stored: an issue records what happened to it and the\nstatus follows from that and from the state of its dependencies." }, "wave": { "type": "integer", "format": "uint32", "minimum": 0, "description": "The execution wave: one past the longest path to it through the dependency graph." }, "priority": { "type": "string", "description": "`p0` … `p3`." }, "profile": { "type": "string", "description": "The execution profile the issue is worked under." }, "parallel_safe": { "type": "boolean", "description": "Whether it may run beside another issue of its wave." }, "title": { "type": "string", "description": "One line naming the outcome." }, "slug": { "type": "string", "description": "The slug, when the record carries one." }, "depends_on": { "type": "array", "items": { "type": "string" }, "description": "Every issue it declares a dependency on, as declared — including one that does not\nexist, which is a finding rather than a silent omission." }, "blocked_by": { "type": "array", "items": { "type": "string" }, "description": "The dependencies that are not DONE, plus `milestone:` when the milestone gate\nholds the whole outcome back." }, "dependents": { "type": "array", "items": { "type": "string" }, "description": "The issues that depend on this one." }, "scope": { "type": "array", "items": { "type": "string" }, "description": "The paths it touches; two issues of one wave that share a path are serialised." }, "objective": { "type": "string", "description": "One line: what the issue is for." }, "evidence_have": { "type": "integer", "format": "uint32", "minimum": 0, "description": "Evidence entries attached." }, "evidence_need": { "type": "integer", "format": "uint32", "minimum": 0, "description": "Evidence tokens the record requires before it may be DONE." }, "started_at": { "type": "string", "description": "When execution began, when it did." }, "verified_at": { "type": "string", "description": "When implementation was declared complete." }, "completed_at": { "type": "string", "description": "When completion was recorded." } }, "required": [ "id", "milestone", "status", "wave", "priority", "profile", "parallel_safe", "title", "slug", "depends_on", "blocked_by", "dependents", "scope", "objective", "evidence_have", "evidence_need", "started_at", "verified_at", "completed_at" ], "description": "One issue, as its record declares it and as the graph derives it." }, "PlanIssueList": { "type": "object", "properties": { "issues": { "type": "array", "items": { "$ref": "#/components/schemas/PlanIssue" }, "description": "The matching issues, in id order." }, "total": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many matched." }, "statuses": { "$ref": "#/components/schemas/PlanVocabulary", "description": "The declared status vocabularies." } }, "required": [ "issues", "total", "statuses" ], "description": "Issues matching a filter, with the vocabulary that names their statuses." }, "PlanMilestone": { "type": "object", "properties": { "id": { "type": "string", "description": "The identity, which is also the file name; a stable slug, never a version." }, "status": { "type": "string", "description": "The derived status." }, "order": { "type": "integer", "format": "int64", "description": "Tie-break inside one rank; the roadmap is ordered by rank first." }, "priority": { "type": "string", "description": "`p0` … `p3`." }, "title": { "type": "string", "description": "One line naming the outcome." }, "slug": { "type": "string", "description": "The slug, when the record carries one." }, "version": { "type": "string", "description": "The release the milestone belongs to, when it declares one." }, "rank": { "type": "integer", "format": "uint32", "minimum": 0, "description": "Its layer in the milestone graph: what orders the roadmap." }, "depends_on": { "type": "array", "items": { "type": "string" }, "description": "The milestones it requires." }, "blocked_by": { "type": "array", "items": { "type": "string" }, "description": "Those of them that are not DONE. Non-empty means the gate holds every issue of this\nmilestone back, whatever the issue graph says." }, "dependents": { "type": "array", "items": { "type": "string" }, "description": "The milestones that require it." }, "claims": { "type": "array", "items": { "type": "string" }, "description": "The claims of the repository this outcome makes true." }, "counts": { "$ref": "#/components/schemas/PlanCounts", "description": "Its issues, counted by derived status." }, "issues": { "type": "array", "items": { "type": "string" }, "description": "Its issues, in id order." }, "outcome": { "type": "string", "description": "One line: what is true once the milestone is real." } }, "required": [ "id", "status", "order", "priority", "title", "slug", "version", "rank", "depends_on", "blocked_by", "dependents", "claims", "counts", "issues", "outcome" ], "description": "One milestone, as its record declares it and as the two graphs derive it." }, "PlanMilestoneProgress": { "type": "object", "properties": { "id": { "type": "string", "description": "The identity." }, "status": { "type": "string", "description": "The derived status." }, "title": { "type": "string", "description": "One line naming the outcome." }, "counts": { "$ref": "#/components/schemas/PlanCounts", "description": "Its issues, counted by derived status." } }, "required": [ "id", "status", "title", "counts" ], "description": "One milestone's progress, without its prose." }, "PlanNextIssue": { "type": "object", "properties": { "issue": { "anyOf": [ { "$ref": "#/components/schemas/PlanIssue" }, { "type": "null" } ], "description": "The issue, when the plan has one that is executable." }, "active_milestone": { "type": "string", "description": "The milestone the search started in." }, "reason": { "type": [ "string", "null" ], "description": "Why there is none, when there is none: what to run to see what is in the way." } }, "required": [ "active_milestone" ], "description": "The one issue a worker should take now." }, "PlanProject": { "type": "object", "properties": { "name": { "type": "string", "description": "The project's name, from `project.yaml`." }, "repository": { "type": "string", "description": "The repository it belongs to, `owner/name`." }, "default_branch": { "type": "string", "description": "The branch the plan is executed on." }, "active_milestone": { "type": "string", "description": "The milestone a worker is executing now: the lowest-ranked unblocked milestone that\nis ACTIVE, else the lowest-ranked unblocked one not finished. Derived on every read,\nstored nowhere, and never authored — the plan cannot nominate a milestone whose\nprerequisites are not real." } }, "required": [ "name", "repository", "default_branch", "active_milestone" ], "description": "The plan's header: what this repository is, plus the one field nobody authors." }, "PlanRecord": { "anyOf": [ { "type": "object", "properties": { "milestone": { "$ref": "#/components/schemas/PlanMilestone", "description": "The milestone, with its counts, its rank and both directions of its graph." }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/PlanIssue" }, "description": "Its issues in full, in id order." } }, "required": [ "milestone", "issues" ], "description": "A milestone." }, { "type": "object", "properties": { "issue": { "$ref": "#/components/schemas/PlanIssue", "description": "The issue, with its status, its wave and both directions of its graph." }, "depends_on": { "type": "array", "items": { "$ref": "#/components/schemas/PlanIssue" }, "description": "The issues it waits on, in full." } }, "required": [ "issue", "depends_on" ], "description": "An issue." } ], "description": "One record of the plan, milestone or issue, with everything derived about it." }, "PlanRoadmap": { "type": "object", "properties": { "milestones": { "type": "array", "items": { "$ref": "#/components/schemas/PlanMilestone" }, "description": "The milestones ordered by rank, then order, then id. The sequence is derived from\nthe milestone graph; no list of versions is maintained anywhere." }, "now": { "type": [ "string", "null" ], "description": "The first unfinished, unblocked milestone in that sequence." }, "next": { "type": [ "string", "null" ], "description": "The one after it, blocked or not." } }, "required": [ "milestones" ], "description": "The milestones in derived order, with the one being executed and the one after it." }, "PlanStatusReport": { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/PlanProject", "description": "The plan's header, with the active milestone derived." }, "statuses": { "$ref": "#/components/schemas/PlanVocabulary", "description": "The declared status vocabularies." }, "milestones": { "type": "array", "items": { "$ref": "#/components/schemas/PlanMilestoneProgress" }, "description": "Every milestone, in id order." }, "next_ready": { "anyOf": [ { "$ref": "#/components/schemas/PlanIssue" }, { "type": "null" } ], "description": "The next ready issue, when there is one." }, "counts": { "$ref": "#/components/schemas/PlanCounts", "description": "Every issue of the plan, counted by derived status." } }, "required": [ "project", "statuses", "milestones", "counts" ], "description": "Where the plan stands: every milestone's progress, the milestone being executed, and the\none issue to take next." }, "PlanValidation": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "Whether the model is valid: no finding is a failure." }, "milestones": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many milestones the plan holds." }, "issues": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many issues." }, "failures": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many findings are failures." }, "warnings": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many are warnings." }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/PlanFinding" }, "description": "Every finding, in derivation order." } }, "required": [ "valid", "milestones", "issues", "failures", "warnings", "findings" ], "description": "The model's own validation: what the graph refuses and what it merely warns about." }, "PlanVocabulary": { "type": "object", "properties": { "issue": { "type": "array", "items": { "type": "string" }, "description": "The issue statuses, in derivation order." }, "milestone": { "type": "array", "items": { "type": "string" }, "description": "The milestone statuses, in derivation order." } }, "required": [ "issue", "milestone" ], "description": "The status vocabularies, so a reader never has to know which statuses exist." }, "PlanWave": { "type": "object", "properties": { "wave": { "type": "integer", "format": "uint32", "minimum": 0, "description": "The layer, from zero." }, "issues": { "type": "array", "items": { "type": "string" }, "description": "The issues in it, in id order." } }, "required": [ "wave", "issues" ], "description": "One execution wave: the issues the graph allows to run at the same time." }, "PlanWaveReport": { "type": "object", "properties": { "waves": { "type": "array", "items": { "$ref": "#/components/schemas/PlanWaveView" }, "description": "The waves, lowest first, with the issues of each." }, "serialised_by_scope": { "type": "array", "items": { "$ref": "#/components/schemas/PlanFinding" }, "description": "Scope overlaps between two issues of one wave. Two issues sharing a wave is a\nnecessary condition for running them at once, not a sufficient one: overlapping\nscope serialises them, and the overlap is reported here rather than left for two\nworkers to discover in a conflict." } }, "required": [ "waves", "serialised_by_scope" ], "description": "The execution waves, with the overlaps that serialise issues the graph would let run\ntogether." }, "PlanWaveView": { "type": "object", "properties": { "wave": { "type": "integer", "format": "uint32", "minimum": 0, "description": "The layer, from zero." }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/PlanIssue" }, "description": "The issues in it, in id order." } }, "required": [ "wave", "issues" ], "description": "One wave, with the issues in it." }, "Port": { "type": "integer", "format": "uint16", "minimum": 0, "maximum": 65535, "description": "A TCP port a deployed process may bind. Privileged ports are not among them: the\nprocess runs as a non-root user and could not bind one." }, "Positive": { "type": "integer", "format": "uint32", "minimum": 0, "description": "A count that is at least one: memory in megabytes, CPUs, machines. Zero is refused\nwherever zero would mean \"a deployment that cannot run\"." }, "ProductCounts": { "type": "object", "properties": { "features": { "type": "integer", "format": "uint", "minimum": 0, "description": "Stable features." }, "features_all": { "type": "integer", "format": "uint", "minimum": 0, "description": "Features of every status, drafts included." }, "featured": { "type": "integer", "format": "uint", "minimum": 0, "description": "Stable features the homepage shows." }, "providers": { "type": "integer", "format": "uint", "minimum": 0, "description": "Providers the tool has an adapter for." }, "modules": { "type": "integer", "format": "uint", "minimum": 0, "description": "Builtin modules of the executable, and how many a stable feature names." }, "modules_covered": { "type": "integer", "format": "uint", "minimum": 0, "description": "Modules a stable feature names." }, "commands": { "type": "integer", "format": "uint", "minimum": 0, "description": "Public commands of the shell tool." }, "commands_covered": { "type": "integer", "format": "uint", "minimum": 0, "description": "Commands a stable feature names." }, "kinds": { "type": "integer", "format": "uint", "minimum": 0, "description": "Kinds of the layer a feature can present." }, "kinds_covered": { "type": "integer", "format": "uint", "minimum": 0, "description": "Kinds a stable feature names." } }, "required": [ "features", "features_all", "featured", "providers", "modules", "modules_covered", "commands", "commands_covered", "kinds", "kinds_covered" ], "description": "How much the model holds. Every count anywhere is one of these." }, "ProductCoverage": { "type": "object", "properties": { "id": { "type": "string", "description": "The id." }, "title": { "type": "string", "description": "The title." }, "features": { "type": "array", "items": { "type": "string" }, "description": "The stable features that name it." } }, "required": [ "id", "title", "features" ], "description": "One thing of the product — a module, a public command, a kind — and the features that\nname it. Empty means the product page says nothing about it, which is a gap the\nvalidation reports and the matrix shows rather than hides." }, "ProductFinding": { "type": "object", "properties": { "severity": { "$ref": "#/components/schemas/Severity", "description": "`error` or `warning`." }, "code": { "type": "string", "description": "`unknown_reference`, `duplicate_identity`, `missing_content`, `uncovered`, ..." }, "path": { "type": "string", "description": "The repository-relative file the finding is in, or the registry it is about." }, "id": { "type": [ "string", "null" ], "description": "The record's identity, when one record owns the finding." }, "field": { "type": [ "string", "null" ], "description": "The front-matter key the finding is about, when one key owns it." }, "message": { "type": "string", "description": "What is wrong, in one sentence." }, "did_you_mean": { "type": [ "string", "null" ], "description": "The nearest existing name, when the value looks like a typo of one." } }, "required": [ "severity", "code", "path", "message" ], "description": "One thing wrong with the product model, named where it is, with the nearest candidate\nwhen there is one." }, "ProductProvider": { "type": "object", "properties": { "id": { "type": "string", "description": "The provider id: the template's file stem." }, "title": { "type": "string", "description": "The name a person knows it by." }, "bootstraps": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderBootstrap" }, "description": "The bootstraps this repository's policy renders through it: target, mode, whether\nevery worker loads it." }, "client_config": { "type": [ "string", "null" ], "description": "The client configuration at the repository root that starts the shared MCP server\nfor this provider, when the repository carries it." }, "hooks": { "type": "array", "items": { "type": "string" }, "description": "The enforcement entries of the policy wired by this provider's hooks." }, "scratch_roots": { "type": "array", "items": { "type": "string" }, "description": "The scratch roots this provider creates checkouts of its own under, as declared:\nthe worktree topology reports a checkout there as a session's scratch checkout and\nnever moves it (ADR 0024).", "default": [] } }, "required": [ "id", "title", "bootstraps", "hooks" ], "description": "One provider the tool has an adapter for, discovered from the templates the distribution\nships and decorated with what this repository does with it." }, "ProductValidationReport": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "True when nothing is an error. Warnings do not make it false." }, "errors": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many findings are errors." }, "warnings": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many findings are warnings." }, "counts": { "$ref": "#/components/schemas/ProductCounts", "description": "The counts the model reached." }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/ProductFinding" }, "description": "The findings, errors first, then by file." } }, "required": [ "valid", "errors", "warnings", "counts", "findings" ], "description": "What the model's own validation found." }, "ProgressView": { "type": "object", "properties": { "current": { "type": "integer", "format": "uint64", "minimum": 0, "description": "Units done." }, "total": { "type": [ "integer", "null" ], "format": "uint64", "minimum": 0, "description": "Units in total, when the handler knows how many." }, "message": { "type": [ "string", "null" ], "description": "What is being done, for a reader." } }, "required": [ "current" ], "description": "How far along an execution is." }, "ProjectIdentity": { "type": "object", "properties": { "name": { "type": "string", "description": "The product name." }, "version": { "type": "string", "description": "The version of this executable, from the crate manifest." }, "summary": { "type": "string", "description": "One sentence: what this is." }, "license": { "type": "string", "description": "The SPDX licence identifier." }, "repository": { "type": "string", "description": "The source repository." }, "target": { "type": "string", "description": "The Rust target triple this executable was built for." }, "profile": { "type": "string", "description": "The cargo profile it was built with." }, "commit": { "type": "string", "description": "The commit it was built from, or `unknown` outside a work tree." } }, "required": [ "name", "version", "summary", "license", "repository", "target", "profile", "commit" ], "description": "What the project is, from the crate manifest and the prose written once in\n[`crate::about`]. Every field here is a compile-time constant of this executable: there\nis no file to read, nothing to parse, and nothing that can disagree with the binary\nthat answers." }, "ProjectionState": { "oneOf": [ { "type": "string", "const": "current", "description": "The file matches the rendering byte for byte." }, { "type": "string", "const": "stale", "description": "The file differs: it was hand-edited, or the policy moved under it." }, { "type": "string", "const": "absent", "description": "The file is not there." }, { "type": "string", "const": "unknown", "description": "It could not be rendered, so nothing can be said." } ], "description": "Where one provider projection stands against its policy." }, "ProjectionView": { "type": "object", "properties": { "path": { "type": "string", "description": "Repository-relative path." }, "read_by": { "type": "string", "description": "What reads it." } }, "required": [ "path", "read_by" ], "description": "One generated projection of the design and what it is for." }, "ProtocolReport": { "type": "object", "properties": { "protocol_version": { "type": "string", "description": "The version of the event protocol this server speaks." }, "websocket": { "type": "string", "description": "Where the live channel is: a path on this same server, not a second daemon." }, "subscription": { "type": "array", "items": { "$ref": "#/components/schemas/ParameterView" }, "description": "How the subscription is expressed, and what a reconnect sends." }, "heartbeat_seconds": { "type": "integer", "format": "uint64", "minimum": 0, "description": "How many seconds of quiet before the server pings." }, "max_connections": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many live channels this process serves at once." }, "max_replay": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many retained events a scoped connection replays before going live." }, "event_types": { "type": "array", "items": { "type": "string" }, "description": "The event types a client may receive, from the one enum that defines them." }, "stream_types": { "type": "array", "items": { "type": "string" }, "description": "The stream's own control messages." }, "event_schema": { "description": "The JSON Schema of an event, derived from the Rust type." }, "stream_schema": { "description": "The JSON Schema of a control message, derived from the Rust type." }, "limits": { "$ref": "#/components/schemas/LimitsView", "description": "What the store keeps, so a client knows what it may ask for." } }, "required": [ "protocol_version", "websocket", "subscription", "heartbeat_seconds", "max_connections", "max_replay", "event_types", "stream_types", "event_schema", "stream_schema", "limits" ], "description": "The answer of `executions.protocol`: the live channel's whole contract, derived from\nthe types that implement it." }, "Provenance": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "registry" } }, "required": [ "source" ], "description": "Read from the capability registry: the routes the executable already declares once." }, { "type": "object", "properties": { "path": { "type": "string", "description": "The declaration file, repository-relative." }, "source": { "type": "string", "const": "producer-declaration" } }, "required": [ "source", "path" ], "description": "Read from a producer's own declaration beside its output (`surface.json`)." }, { "type": "object", "properties": { "path": { "type": "string", "description": "What was found, repository-relative." }, "source": { "type": "string", "const": "filesystem" } }, "required": [ "source", "path" ], "description": "Inferred from a file or directory being where the convention says it is." }, { "type": "object", "properties": { "path": { "type": "string", "description": "The configuration file, repository-relative." }, "source": { "type": "string", "const": "site-config" } }, "required": [ "source", "path" ], "description": "Inferred from the site generator's own configuration." }, { "type": "object", "properties": { "source": { "type": "string", "const": "default" } }, "required": [ "source" ], "description": "The model's documented default for a value nobody stated." } ], "description": "Where a resolved value came from.\n\nKept for every field a consumer can be surprised by, so that `web explain` can answer\n\"why is this mounted here?\" without anybody reading the discovery code." }, "Provider": { "type": "object", "additionalProperties": false, "properties": { "name": { "$ref": "#/components/schemas/ProviderName", "description": "Which provider." }, "fly": { "anyOf": [ { "$ref": "#/components/schemas/Fly" }, { "type": "null" } ], "description": "Fly's own block, when the provider is Fly.", "default": null } }, "required": [ "name" ], "description": "The provider and the facts that belong to it alone." }, "ProviderBootstrap": { "type": "object", "properties": { "target": { "type": "string", "description": "The target file, repository-relative." }, "mode": { "type": "string", "description": "`file` or `region`." }, "always_loaded": { "type": "boolean", "description": "Loaded by every worker without asking." } }, "required": [ "target", "mode", "always_loaded" ], "description": "One bootstrap a provider renders." }, "ProviderList": { "type": "object", "properties": { "count": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many." }, "providers": { "type": "array", "items": { "$ref": "#/components/schemas/ProductProvider" }, "description": "Each, in id order." } }, "required": [ "count", "providers" ], "description": "Every provider." }, "ProviderName": { "oneOf": [ { "type": "string", "const": "fly", "description": "Fly.io." } ], "description": "The hosting provider. One is supported; a second is an object of its own rather than an\nabstraction over this one." }, "ProviderState": { "type": "object", "properties": { "id": { "type": "string", "description": "The provider id, as the policy names it: `agents`, `claude-code`." }, "target": { "type": "string", "description": "The repository-relative file it renders to." }, "state": { "$ref": "#/components/schemas/ProjectionState", "description": "Whether the file matches what the policy renders now." }, "always_loaded": { "type": "boolean", "description": "Whether the provider loads this file into every context." } }, "required": [ "id", "target", "state", "always_loaded" ], "description": "One provider projection the policy declares, and whether the file on disk still matches\nwhat the policy renders." }, "PublicApiQuality": { "type": "object", "properties": { "items": { "type": "integer", "format": "uint", "minimum": 0, "description": "Items the crate exports, of every kind." }, "documented": { "type": "integer", "format": "uint", "minimum": 0, "description": "Of those, how many carry documentation." }, "owe_example": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many owe an executable example under the policy." }, "exampled": { "type": "integer", "format": "uint", "minimum": 0, "description": "Of those, how many have one that counts." }, "exempt": { "type": "array", "items": { "$ref": "#/components/schemas/Exemption" }, "description": "How many are exempt from the example policy for a structural reason, and why, by\nreason, so that the exemptions are visible rather than implied by a subtraction." } }, "required": [ "items", "documented", "owe_example", "exampled", "exempt" ], "description": "What the exported item surface looks like." }, "QualityAnswer": { "type": "object", "properties": { "measured": { "type": "boolean", "description": "Whether a crate was found and measured. `false` is a complete answer, not a failure:\nthe layer installs into repositories that carry no Rust crate, and a doctrine that\ncannot apply is not a violation." }, "reason": { "type": [ "string", "null" ], "description": "Why nothing was measured, when nothing was." }, "report": { "$ref": "#/components/schemas/QualityReport", "description": "The measurement. Present and empty-of-findings when `measured` is false, so that a\nconsumer reads one shape either way and `measured` is the only question it must ask." }, "passes": { "type": "boolean", "description": "Whether the report as filtered leaves nothing blocking. Answered here so that a\ncaller over any transport reads the verdict rather than deriving it, and so that the\ncommand line's exit code and this field can never disagree." }, "baselined": { "type": "integer", "format": "uint", "minimum": 0, "description": "The findings the ratchet accepts because they stood when the rule landed. A finding\noutside this count is what fails the gate." } }, "required": [ "measured", "report", "passes", "baselined" ], "description": "The answer: the measurement, or the reason there was not one." }, "QualityReport": { "type": "object", "properties": { "schema": { "type": "string", "description": "[`SCHEMA`].", "default": "" }, "target": { "type": "string", "description": "What was measured: the crate directory, repository-relative." }, "public_api": { "$ref": "#/components/schemas/PublicApiQuality", "description": "The exported item surface." }, "modules": { "$ref": "#/components/schemas/ModuleQuality", "description": "The exported module surface." }, "operations": { "$ref": "#/components/schemas/OperationParity", "description": "The canonical operations against their transports." }, "violations": { "type": "array", "items": { "$ref": "#/components/schemas/Violation" }, "description": "Every finding, errors first, then by file and line." } }, "required": [ "target", "public_api", "modules", "operations", "violations" ], "description": "One measurement of one crate, and everything found wrong in it." }, "QualitySeverity": { "oneOf": [ { "type": "string", "const": "error", "description": "The gate fails." }, { "type": "string", "const": "warning", "description": "Reported, and the gate passes." } ], "description": "How much a finding matters.\n\nThere are two levels and not five, because the only question a gate can answer is\nwhether the change may land. A warning is a finding the repository has decided not to\nblock on; nothing else is a warning." }, "Readiness": { "type": "object", "properties": { "ready": { "type": "boolean", "description": "Whether every part below is in place." }, "version": { "type": "string", "description": "This executable's version." }, "capabilities": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many capabilities the registry holds; zero would mean nothing to serve." }, "objects": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many objects the index holds. Read from the index this process built at\nstart-up: it is already in memory, and reading it walks nothing." }, "layer": { "$ref": "#/components/schemas/HealthStatus", "description": "Whether the layer read cleanly. A degraded layer is still served — the diagnostics\nare the point — so this reports rather than refuses." } }, "required": [ "ready", "version", "capabilities", "objects", "layer" ], "description": "The answer to \"can this process serve traffic\": the local initialisation a request\nwould need, and nothing beyond this process. A readiness check that grew a dependency\nprobe fails a deployment because an unrelated service is down." }, "Reason": { "oneOf": [ { "type": "string", "const": "path", "description": "Named under `out.paths`." }, { "type": "string", "const": "secret", "description": "A secret." }, { "type": "string", "const": "generated", "description": "A generated asset." }, { "type": "string", "const": "archive", "description": "An archive." }, { "type": "string", "const": "image", "description": "An image." }, { "type": "string", "const": "video", "description": "Video." }, { "type": "string", "const": "pdf", "description": "A PDF document." }, { "type": "string", "const": "database_dump", "description": "A database dump." }, { "type": "string", "const": "undeclared", "description": "Matches no `in` pathspec." }, { "type": "string", "const": "fixture_over_limit", "description": "A fixture over `out.fixtures.max_bytes`." }, { "type": "string", "const": "over_limit", "description": "Over `out.max_bytes`." }, { "type": "string", "const": "binary", "description": "Content with a NUL byte in its first [`SNIFF_BYTES`]: not text." } ], "description": "Why a path is out. The order is the order the rules decide in." }, "Recommendation": { "type": "object", "properties": { "id": { "type": "string", "description": "The thing recommended: a capability id, a command, a claim, a rule, a use case." }, "count": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many of the selected moments name it." }, "matched_because": { "type": "array", "items": { "type": "string" }, "description": "The selected moments that named it, in presentation order." } }, "required": [ "id", "count", "matched_because" ], "description": "One recommendation, with the moments that produced it. A recommendation with no\n`matched_because` is a recommendation nobody can check." }, "Record": { "type": "object", "properties": { "path": { "type": "string", "description": "Repository-relative path. The body is at the path; it is not copied here." }, "created_at": { "type": "string", "description": "When the record says it was written." }, "task_id": { "type": "string", "description": "The task it belongs to, or `none`." }, "branch": { "type": "string", "description": "The branch it was written on." }, "head": { "type": "string", "description": "The commit it was written at." }, "working_tree": { "type": "string", "description": "Whether the working tree was clean or dirty then." }, "matched": { "$ref": "#/components/schemas/Match", "description": "Which tier of the resolution rule matched." }, "divergence": { "$ref": "#/components/schemas/Divergence", "description": "How far its commit is from this one." }, "next_action": { "type": "string", "description": "The section a resuming worker acts on, when the record has one. A handover's `Next\nAction`; empty for a record that carries no sections." } }, "required": [ "path", "created_at", "task_id", "branch", "head", "working_tree", "matched", "divergence" ], "description": "One durable record of the local half, as much of it as a reader needs to decide whether\nto open the file." }, "Refusal": { "type": "object", "properties": { "file": { "type": "string", "description": "The repository-relative file the value came from." }, "key": { "type": "string", "description": "The key path within it, as the contract names it." }, "found": { "type": "string", "description": "The value observed, rendered as it was read." }, "problem": { "type": "string", "description": "What is wrong with it, in one line." }, "correction": { "type": "string", "description": "What to do instead." } }, "required": [ "file", "key", "found", "problem", "correction" ], "description": "Why a deployment object is refused: what was read, where, and what to do about it." }, "ReleaseArtifactView": { "type": "object", "properties": { "target": { "type": "string", "description": "The target's id in the model." }, "rust_target": { "type": "string", "description": "The Rust target triple." }, "tag": { "type": "string", "description": "The tag the name was derived for." }, "name": { "type": "string", "description": "The archive's file name." }, "root": { "type": "string", "description": "The directory the archive unpacks into." }, "url": { "type": "string", "description": "Where a release publishes it, when the tag is a real one." } }, "required": [ "target", "rust_target", "tag", "name", "root", "url" ], "description": "The artifact a target and a tag name, and the directory it unpacks into." }, "ReleaseChange": { "type": "object", "properties": { "kind": { "$ref": "#/components/schemas/ReleaseChangeKind", "description": "What it did." }, "scope": { "type": [ "string", "null" ], "description": "The area it did it in, when the subject named one: `commands`, `ci`, `site`." }, "subject": { "type": "string", "description": "The subject, without the type and scope that prefixed it." }, "breaking": { "type": "boolean", "description": "Whether the commit marked itself breaking, with `!` or a `BREAKING CHANGE:` trailer." }, "commit": { "type": "string", "description": "The abbreviated commit." }, "url": { "type": [ "string", "null" ], "description": "Where that commit can be read, when the repository's own URL is known. Derived from\n`about::REPOSITORY`, never written beside each entry." }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/ReleaseReference" }, "description": "The records of the layer this commit names — issues, milestones — resolved against\nwhat the layer actually holds." } }, "required": [ "kind", "subject", "breaking", "commit" ], "description": "One change, from one commit." }, "ReleaseChangeGroup": { "type": "object", "properties": { "kind": { "$ref": "#/components/schemas/ReleaseChangeKind", "description": "What the changes in it did." }, "heading": { "type": "string", "description": "The heading it is shown under." }, "rank": { "type": "integer", "format": "uint8", "minimum": 0, "maximum": 255, "description": "Where it sorts among the other groups; ascending." }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/ReleaseChange" }, "description": "The changes, in the order the commits were read." } }, "required": [ "kind", "heading", "rank", "changes" ], "description": "The changes of one kind, with the heading and the rank that decide where they are shown.\n\nThe grouping is in the document rather than in each renderer. It was in the Markdown\nrenderer alone, and the site — which cannot see a Rust function — grouped alphabetically\ninstead, so the same changelog read in two orders depending on which surface showed it.\nA presentation order stated once and carried is the only kind that survives a projection." }, "ReleaseChangeKind": { "oneOf": [ { "type": "string", "const": "feat", "description": "A capability a person did not have before." }, { "type": "string", "const": "fix", "description": "Behaviour that was wrong and is not any more." }, { "type": "string", "const": "perf", "description": "Performance, with the behaviour unchanged." }, { "type": "string", "const": "refactor", "description": "Structure, with the behaviour unchanged." }, { "type": "string", "const": "docs", "description": "Documentation." }, { "type": "string", "const": "test", "description": "Tests." }, { "type": "string", "const": "chore", "description": "The build, the pipeline, the tooling." }, { "type": "string", "const": "ci", "description": "Continuous integration." }, { "type": "string", "const": "style", "description": "Formatting, with the behaviour unchanged." }, { "type": "string", "const": "build", "description": "The build system or its dependencies." }, { "type": "string", "const": "revert", "description": "A change that undoes another." }, { "type": "string", "const": "other", "description": "A commit whose subject does not parse as a conventional commit." } ], "description": "What a conventional commit says it did.\n\nThe set is the one the repository's own commit convention uses; a commit whose subject\ndoes not parse is [`ChangeKind::Other`] and still appears, because a changelog that\nsilently drops what it cannot classify is a changelog that lies by omission." }, "ReleaseChangelog": { "type": "object", "properties": { "schema": { "type": "string", "description": "The schema this document satisfies." }, "current": { "type": "string", "description": "The version the tree currently declares." }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/ReleaseSection" }, "description": "Newest first, the unreleased section leading when there is one." }, "diagnostics": { "type": "array", "items": { "type": "string" }, "description": "What could not be read, said rather than hidden: a repository with no git history,\na release record that names no commit, a tag that is not in this clone." }, "produced_by": { "anyOf": [ { "$ref": "#/components/schemas/ReleaseProducedBy" }, { "type": "null" } ], "description": "Which capability answered, and where else the same value can be had." } }, "required": [ "schema", "current", "sections", "diagnostics" ], "description": "The whole changelog." }, "ReleaseChangelogArtifact": { "type": "object", "properties": { "target": { "type": "string", "description": "The platform triple the record names." }, "name": { "type": "string", "description": "The file name." }, "sha256": { "type": "string", "description": "Its SHA-256, as the record read it off the file." } }, "required": [ "target", "name", "sha256" ], "description": "One published artifact, from the release record's own evidence." }, "ReleaseDecision": { "type": "object", "properties": { "id": { "type": "string", "description": "`adr-0027`." }, "title": { "type": "string", "description": "The decision, in its own words." }, "status": { "type": "string", "description": "`proposed`, `accepted`, `superseded`." }, "date": { "type": "string", "description": "The date the record carries." }, "url": { "type": [ "string", "null" ], "description": "Where the decision itself can be read: the file in the repository. The site has no\nper-ADR page, so this is the honest destination rather than an invented route." }, "added": { "type": [ "string", "null" ], "description": "The commit that added the file, which is what decides the release it belongs to. The\nfront-matter date says when the decision was made; those are different questions." } }, "required": [ "id", "title", "status", "date" ], "description": "One decision, as the layer's own ADR object states it." }, "ReleaseProducedBy": { "type": "object", "properties": { "capability": { "type": "string", "description": "The capability id." }, "cli": { "type": [ "string", "null" ], "description": "The command line that renders it." }, "http": { "type": [ "string", "null" ], "description": "The HTTP route that answers with it." }, "mcp_tool": { "type": [ "string", "null" ], "description": "The MCP tool." }, "mcp_resource": { "type": [ "string", "null" ], "description": "The MCP resource URI." } }, "required": [ "capability" ], "description": "Which capability answered with this document, and where that capability is projected.\n\nThe document carries its own provenance so that a reader — a person on the site, a client\nover MCP — can find the same value elsewhere without anything having to enumerate the\nroutes. A page that listed them would be declaring them a second time, which is the\nfailure `site-check`'s `registry` and `cli` assertions exist to catch; it caught this one.\n\n```\nuse majordomus_cli::release::model::ProducedBy;\nlet by = ProducedBy {\n capability: \"release.changelog\".into(),\n cli: Some(\"majordomus release changelog\".into()),\n http: Some(\"/api/v1/changelog\".into()),\n mcp_tool: None,\n mcp_resource: Some(\"majordomus://changelog\".into()),\n};\nlet json = serde_json::to_value(&by).unwrap();\nassert_eq!(json[\"capability\"], \"release.changelog\");\n// a surface the capability is not projected on is absent, not null\nassert!(json.get(\"mcp_tool\").is_none());\nassert_eq!(ProducedBy::default().capability, \"\");\n```" }, "ReleaseReference": { "type": "object", "properties": { "kind": { "type": "string", "description": "`issue` or `milestone`." }, "id": { "type": "string", "description": "`I1305`, `M000`." }, "title": { "type": "string", "description": "What it is, from the record itself." }, "route": { "type": [ "string", "null" ], "description": "Where it is published on this site, when it has a page." } }, "required": [ "kind", "id", "title" ], "description": "A record of the layer that a commit names in its own text.\n\nInferred, never declared beside the commit: an issue id or a milestone id appearing in a\nsubject or a body is a reference, and the layer already holds the object it refers to. A\nreference to something the layer does not have is not carried — a link to a record that\ndoes not exist is worse than no link, because the reader cannot tell until they follow it.\n\n```\nuse majordomus_cli::release::model::Reference;\nlet r = Reference {\n kind: \"issue\".into(),\n id: \"I1305\".into(),\n title: \"An observed contract has a fingerprint\".into(),\n route: Some(\"/plan/i1305/\".into()),\n};\nlet json = serde_json::to_value(&r).unwrap();\nassert_eq!(json[\"id\"], \"I1305\");\nassert_eq!(json[\"route\"], \"/plan/i1305/\");\n// a reference the site has no page for carries no route rather than an invented one\nlet bare = Reference { route: None, ..r };\nassert!(serde_json::to_value(&bare).unwrap().get(\"route\").is_none());\n```" }, "ReleaseSection": { "type": "object", "properties": { "version": { "type": "string", "description": "The version, or `unreleased`." }, "tag": { "type": [ "string", "null" ], "description": "The tag, when one was published." }, "date": { "type": [ "string", "null" ], "description": "When it was published, from the record." }, "commit": { "type": [ "string", "null" ], "description": "The commit it was published from." }, "unreleased": { "type": "boolean", "description": "Whether this section is the work that has not been released." }, "notes_url": { "type": [ "string", "null" ], "description": "The release notes the record names — the published release itself." }, "compare_url": { "type": [ "string", "null" ], "description": "Every commit between the previous release and this one, as the forge renders it." }, "tree_url": { "type": [ "string", "null" ], "description": "The tree at this release." }, "decisions": { "type": "array", "items": { "$ref": "#/components/schemas/ReleaseDecision" }, "description": "The decisions dated inside this release's window." }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/ReleaseChangeGroup" }, "description": "The changes, from the commits in this release's range, grouped by what they did and\nordered by the rank each group carries. The flat list is the concatenation of the\ngroups' own; nothing holds it twice." }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/ReleaseChangelogArtifact" }, "description": "What was published, when this section is a release." } }, "required": [ "version", "unreleased", "decisions", "groups", "artifacts" ], "description": "One version's worth of changelog." }, "ReleaseVersionReport": { "type": "object", "properties": { "declared": { "type": "string", "description": "The version the crate manifest declares — the authority." }, "tool": { "type": "string", "description": "The version `bin/majordomus` prints." }, "agree": { "type": "boolean", "description": "Whether the two agree. `scripts/release-version --check` is the gate; this is the\nsame question asked by the executable, so every surface can show the answer." }, "last_release": { "type": [ "string", "null" ], "description": "The last release the layer records." }, "bump": { "type": "string", "description": "What the commits since it imply: `major`, `minor`, `patch`, or `none`." }, "next": { "type": [ "string", "null" ], "description": "The version that bump would produce." }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/ReleaseChange" }, "description": "How many commits since the last release, and of what kind — the evidence for the\nbump, so that a surprising answer can be checked rather than believed." } }, "required": [ "declared", "tool", "agree", "bump", "changes" ], "description": "What the version is, and what the commits since the last release imply it should become." }, "ReleaseView": { "type": "object", "properties": { "tag": { "type": "string", "description": "The git tag." }, "version": { "type": "string", "description": "The semantic version." }, "channel": { "$ref": "#/components/schemas/Channel", "description": "Whether an unpinned installation may resolve it." }, "published_at": { "type": "string", "description": "When it was published, UTC." }, "commit": { "type": "string", "description": "The commit it was built from." }, "yanked": { "type": "boolean", "description": "True when it has been withdrawn." }, "artifacts": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many artifacts it published." }, "metadata_url": { "type": "string", "description": "Where its public metadata is served." } }, "required": [ "tag", "version", "channel", "published_at", "commit", "yanked", "artifacts", "metadata_url" ], "description": "One release, as every projection shows it." }, "ReleasesReport": { "type": "object", "properties": { "count": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many records there are." }, "latest": { "anyOf": [ { "$ref": "#/components/schemas/ReleaseView" }, { "type": "null" } ], "description": "The release an unpinned installation resolves to, when there is one." }, "releases": { "type": "array", "items": { "$ref": "#/components/schemas/ReleaseView" }, "description": "Every record, newest first." } }, "required": [ "count", "releases" ], "description": "The releases this repository recorded, and the one an unpinned installation resolves to." }, "RepositoryEnvironment": { "type": "object", "properties": { "schema": { "type": "string", "description": "The contract this document follows, `majordomus/repository-environment/v1`." }, "generated_at": { "type": "string", "description": "When it was taken, RFC 3339 in UTC." }, "resolution": { "$ref": "#/components/schemas/Resolution", "description": "How completely it was resolved." }, "project": { "$ref": "#/components/schemas/ProjectIdentity", "description": "What the project is." }, "repository": { "$ref": "#/components/schemas/RepositoryIdentity", "description": "What the checkout is." }, "vcs": { "$ref": "#/components/schemas/VcsState", "description": "What version control says." }, "toolchains": { "type": "array", "items": { "$ref": "#/components/schemas/ToolchainState" }, "description": "The toolchains the repository declares, sorted by id." }, "layer": { "$ref": "#/components/schemas/LayerSummary", "description": "What the layer holds." }, "workflows": { "$ref": "#/components/schemas/WorkflowCatalogue", "description": "The workflows a person can run." }, "providers": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderState" }, "description": "The provider projections the policy declares, in the policy's order." }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceState" }, "description": "The local services, in the order the service table declares them." }, "diagnostics": { "type": "array", "items": { "$ref": "#/components/schemas/Diagnostic" }, "description": "Everything that went wrong or is worth knowing, in the order it was found." }, "provenance": { "type": "array", "items": { "$ref": "#/components/schemas/FieldSource" }, "description": "Where every field came from." } }, "required": [ "schema", "generated_at", "resolution", "project", "repository", "vcs", "toolchains", "layer", "workflows", "providers", "services", "diagnostics", "provenance" ], "description": "The snapshot: what this checkout is, right now.\n\nEvery surface that reports any of this renders this value. Collections are in a\ndocumented, stable order — kinds and workflows by name, services and providers in the\norder their canonical source declares them, diagnostics in the order they were found —\nso that two snapshots of the same repository serialise identically apart from\n[`RepositoryEnvironment::generated_at`]." }, "RepositoryIdentity": { "type": "object", "properties": { "name": { "type": "string", "description": "The name a person calls it: the base name of the root directory." }, "root": { "type": "string", "description": "The root, absolute. The same value `repository.info` reports." }, "layer_schema": { "type": "string", "description": "The manifest's `schema`, `ai-repository/v1`." }, "sections": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Section name to repository-relative path, as the manifest declares them." }, "local_path": { "type": "string", "description": "The checkout-local half of the layer, repository-relative. Never tracked, and\nwhere anything this checkout alone knows — the server's lease, this snapshot's\ncache — is kept." }, "linked_worktree": { "type": "boolean", "description": "Whether this checkout is a linked work tree rather than the main one." } }, "required": [ "name", "root", "layer_schema", "sections", "local_path", "linked_worktree" ], "description": "The checkout this snapshot is of." }, "RepositoryInfo": { "type": "object", "properties": { "root": { "type": "string", "description": "The repository root, absolute." }, "layer_schema": { "type": "string", "description": "The manifest's `schema`, `ai-repository/v1`." }, "sections": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Manifest section name to repository-relative path." }, "git": { "$ref": "#/components/schemas/GitState", "description": "What `git` said, or why it could not be asked." }, "discovery": { "type": "string", "description": "`vcs` or `filesystem`." }, "source_classes": { "type": "array", "items": { "type": "array", "prefixItems": [ { "type": "string" }, { "type": "string" } ], "minItems": 2, "maxItems": 2 }, "description": "Source class id to kind, in declared order." }, "kind_sources": { "type": "array", "items": { "type": "string" }, "description": "The kinds files the reader was configured from: the distribution's, then the\nrepository's own when it has one." }, "scope_origin": { "$ref": "#/components/schemas/Origin", "description": "Where the scope was read from: `repository` or `distribution`." }, "scope_path": { "type": "string", "description": "The scope file: repository-relative for the repository's own, the share path for\nthe distribution's default." } }, "required": [ "root", "layer_schema", "sections", "git", "discovery", "source_classes", "kind_sources", "scope_origin", "scope_path" ], "description": "What the index knows about the repository it was built from." }, "RepositoryRef": { "type": "object", "properties": { "name": { "type": "string", "description": "The repository's name: the last component of its root." }, "id": { "type": "string", "description": "The stable identity two processes over one checkout both compute." }, "branch": { "type": [ "string", "null" ], "description": "The branch checked out, when git can say." } }, "required": [ "name", "id" ], "description": "Which repository, and which checkout of it, an execution ran against.\n\nAn execution is never run against \"wherever this process happens to be\": the engine\nstamps the repository the index was read from, and a request that names a different one\nis refused. The path itself is not here — this value is served to whoever can reach the\nsocket, and where the checkout sits on the host is of no use to them." }, "RepositoryReport": { "type": "object", "properties": { "repository": { "$ref": "#/components/schemas/RepositoryInfo", "description": "The repository: root, layer schema, sections, git state, discovery mode, source classes, kind sources." }, "state": { "$ref": "#/components/schemas/State", "description": "`ok` when every discovered file became an object, `degraded` otherwise." }, "objects": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many objects the index holds." }, "kinds": { "type": "object", "additionalProperties": { "type": "integer", "format": "uint", "minimum": 0 }, "description": "Objects per kind." }, "diagnostics": { "type": "array", "items": { "$ref": "#/components/schemas/Diagnostic" }, "description": "Every diagnostic the index produced." }, "capabilities": { "$ref": "#/components/schemas/Summary", "description": "The capability registry, counted." } }, "required": [ "repository", "state", "objects", "kinds", "diagnostics", "capabilities" ], "description": "The repository, its layer, its git state, and the state of this process's index." }, "RepositoryTopology": { "type": "object", "properties": { "schema": { "type": "string", "description": "[`SCHEMA`]." }, "repository": { "$ref": "#/components/schemas/RepositoryView", "description": "The repository." }, "container": { "$ref": "#/components/schemas/ContainerView", "description": "The container every linked work tree belongs under." }, "trunk": { "$ref": "#/components/schemas/TrunkView", "description": "The trunk." }, "observed_from": { "type": "string", "description": "The work tree the call was answered from." }, "worktrees": { "type": "array", "items": { "$ref": "#/components/schemas/WorktreeState" }, "description": "Every registered work tree, primary first." }, "branches": { "type": "array", "items": { "$ref": "#/components/schemas/BranchState" }, "description": "Every local branch, by name." }, "diagnostics": { "type": "array", "items": { "$ref": "#/components/schemas/TopologyDiagnostic" }, "description": "Everything wrong with the topology, work trees first, then repository-wide." }, "tallies": { "$ref": "#/components/schemas/TopologyTallies", "description": "The counts." }, "valid": { "type": "boolean", "description": "No error-level diagnostic stands." } }, "required": [ "schema", "repository", "container", "trunk", "observed_from", "worktrees", "branches", "diagnostics", "tallies", "valid" ], "description": "The whole topology: what `worktree list`, the MCP resource, the HTTP route and the\nCockpit all read." }, "RepositoryView": { "type": "object", "properties": { "primary_worktree": { "type": "string", "description": "The primary checkout: what the container is named after." }, "git_common_dir": { "type": "string", "description": "The common git directory: the repository's identity." }, "name": { "type": "string", "description": "The primary checkout's directory name." } }, "required": [ "primary_worktree", "git_common_dir", "name" ], "description": "The repository's identity, as the topology reports it." }, "Resolution": { "oneOf": [ { "type": "string", "const": "fast", "description": "Only what is cheap enough for a shell prompt; the rest from the cache." }, { "type": "string", "const": "full", "description": "Everything, including the index. Writes the cache." } ], "description": "How completely a snapshot was resolved. Carried in the snapshot because a consumer must\nbe able to tell \"there is no server running\" from \"nobody looked\"." }, "Resolved": { "type": "object", "properties": { "reference": { "type": "string", "description": "The palette entry or role the declaration named." }, "css": { "type": "string", "description": "The CSS value a stylesheet gets: the literal of a palette entry, or `var(--mj-)`." }, "literal": { "type": "string", "description": "The literal after every reference is followed." } }, "required": [ "reference", "css", "literal" ], "description": "What a colour reference resolved to." }, "ResolvedRefs": { "type": "object", "properties": { "id": { "type": "string", "description": "The identity, the slug and the file name." }, "title": { "type": "string", "description": "The feature as a heading." }, "short_title": { "type": [ "string", "null" ], "description": "Two or three words for a card or a matrix row." }, "headline": { "type": "string", "description": "The promise a visitor reads first." }, "summary": { "type": "string", "description": "One line: what it does." }, "status": { "type": "string", "description": "`stable`, `draft` or `deprecated`." }, "weight": { "type": "integer", "format": "uint32", "minimum": 0, "description": "Presentation order, lowest first.", "default": 0 }, "featured": { "type": "boolean", "description": "Whether the homepage shows it as a chapter.", "default": false }, "areas": { "type": "array", "items": { "type": "string" }, "description": "The operational areas of the why catalogue it serves.", "default": [] }, "audiences": { "type": "array", "items": { "type": "string" }, "description": "The audiences of the why catalogue it is written for.", "default": [] }, "modules": { "type": "array", "items": { "type": "string" }, "description": "Capability modules of the executable it is made of.", "default": [] }, "commands": { "type": "array", "items": { "type": "string" }, "description": "Public commands of the shell tool it is made of.", "default": [] }, "kinds": { "type": "array", "items": { "type": "string" }, "description": "Object kinds of the layer it is made of.", "default": [] }, "rules": { "type": "array", "items": { "type": "string" }, "description": "Rules of the effective set that govern it, by id without the version.", "default": [] }, "docs": { "type": "array", "items": { "type": "string" }, "description": "The documents that explain it, by repository-relative path.", "default": [] }, "adrs": { "type": "array", "items": { "type": "string" }, "description": "The decisions behind it, by declared id.", "default": [] }, "claims": { "type": "array", "items": { "type": "string" }, "description": "Claims that say what is guaranteed here.", "default": [] }, "use_cases": { "type": "array", "items": { "type": "string" }, "description": "Use cases that show it in use.", "default": [] }, "cockpit": { "type": "array", "items": { "type": "string" }, "description": "Areas of the Cockpit that show it.", "default": [] }, "web": { "type": "array", "items": { "type": "string" }, "description": "Web surfaces of the topology it is offered through.", "default": [] }, "related": { "type": "array", "items": { "type": "string" }, "description": "Features explicitly related to this one. The reverse is derived.", "default": [] }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free tags.", "default": [] }, "route": { "type": "string", "description": "Derived: `/features//`. Never authored; the schema refuses a `route` key.", "default": "" }, "source": { "type": "string", "description": "Derived: the repository-relative file the record came from.", "default": "" }, "body": { "type": "string", "description": "The Markdown body, without its front matter." }, "surfaces": { "$ref": "#/components/schemas/Surfaces", "description": "Derived: the interfaces it is exposed through." }, "module_refs": { "type": "array", "items": { "$ref": "#/components/schemas/ModuleRef" }, "description": "Derived: the modules it names, each with its capabilities and their projections." }, "command_refs": { "type": "array", "items": { "$ref": "#/components/schemas/CommandRef" }, "description": "Derived: the shell commands it names, as the command registry declares them." }, "kind_refs": { "type": "array", "items": { "$ref": "#/components/schemas/KindRef" }, "description": "Derived: the kinds it names, each with its object count." }, "rule_refs": { "type": "array", "items": { "$ref": "#/components/schemas/RuleRef" }, "description": "Derived: the rules it names, each with its class and whether it is enforced." }, "doc_refs": { "type": "array", "items": { "$ref": "#/components/schemas/DocRef" }, "description": "Derived: the documents it names, with their titles." }, "adr_refs": { "type": "array", "items": { "$ref": "#/components/schemas/AdrRef" }, "description": "Derived: the decisions it names, with their status." }, "claim_refs": { "type": "array", "items": { "$ref": "#/components/schemas/ClaimRef" }, "description": "Derived: the claims it names, with their status." }, "use_case_refs": { "type": "array", "items": { "$ref": "#/components/schemas/UseCaseRef" }, "description": "Derived: the use cases it names." }, "cockpit_refs": { "type": "array", "items": { "$ref": "#/components/schemas/CockpitAreaRef" }, "description": "Derived: the Cockpit areas it names, with their routes." }, "web_refs": { "type": "array", "items": { "$ref": "#/components/schemas/SurfaceRef" }, "description": "Derived: the web surfaces it names, with their mounts." }, "moments": { "type": "array", "items": { "$ref": "#/components/schemas/MomentRef" }, "description": "Derived: the moments that name any command, capability, claim or rule of this feature." }, "backlinks": { "type": "array", "items": { "type": "string" }, "description": "Derived: the features that name this one in their `related`." }, "counts": { "$ref": "#/components/schemas/FeatureCounts", "description": "Derived: how much stands behind it." }, "evidence": { "$ref": "#/components/schemas/FeatureEvidence", "description": "Derived: what is guaranteed." } }, "required": [ "id", "title", "headline", "summary", "status", "surfaces", "module_refs", "command_refs", "kind_refs", "rule_refs", "doc_refs", "adr_refs", "claim_refs", "use_case_refs", "cockpit_refs", "web_refs", "moments", "backlinks", "counts", "evidence" ], "description": "One feature, resolved: the record as its file declares it, and everything derived." }, "ResourceView": { "oneOf": [ { "$ref": "#/components/schemas/ObjectView", "type": "object", "properties": { "source": { "type": "string", "const": "declarative" } }, "required": [ "source" ], "description": "A file of the layer, read as it is." }, { "$ref": "#/components/schemas/AnswerView", "type": "object", "properties": { "source": { "type": "string", "const": "builtin" } }, "required": [ "source" ], "description": "A query with a resource exposure, executed and rendered as a JSON document." } ], "description": "The answer of `objects.get`: what the URI resolved to, tagged by `source` the way a\ncapability's provenance is." }, "Resources": { "type": "object", "additionalProperties": false, "properties": { "cpu_kind": { "$ref": "#/components/schemas/CpuKind", "description": "Shared or dedicated." }, "cpus": { "$ref": "#/components/schemas/Positive", "description": "How many CPUs one machine has." }, "memory_mb": { "$ref": "#/components/schemas/Positive", "description": "Memory per machine, in megabytes." } }, "required": [ "cpu_kind", "cpus", "memory_mb" ], "description": "What one machine is granted." }, "Route": { "type": "string", "description": "A route a platform polls: an absolute path on this service, never a URL. The host is\nthe deployment's to know and not the object's to state." }, "Row": { "type": "object", "properties": { "id": { "type": "string", "description": "The canonical id." }, "module": { "type": "string", "description": "The module that composes it." }, "kind": { "type": "string", "description": "Query, command or resource." }, "stability": { "type": "string", "description": "Where it stands." }, "cli": { "type": [ "string", "null" ], "description": "The command line, when it declares one and clap has it." }, "http": { "type": [ "string", "null" ], "description": "The HTTP route, when it declares one." }, "mcp_tool": { "type": [ "string", "null" ], "description": "The MCP tool name, when it declares one." }, "mcp_resource": { "type": [ "string", "null" ], "description": "The MCP resource URI, when it declares one." }, "closed": { "type": "boolean", "description": "Whether every exposure this row declares is answered by its surface." }, "source": { "type": "string", "description": "Where the capability is declared; repository-relative." } }, "required": [ "id", "module", "kind", "stability", "closed", "source" ], "description": "Where one capability is projected, and where it is not.\n\nThis is the coverage matrix of the rule: a row per capability, a column per interface.\nIt is derived, never written down — a capability that reaches nothing shows as a row of\n`false`, which is exactly the \"exists but is invisible\" case worth seeing." }, "RuleRef": { "type": "object", "properties": { "id": { "type": "string", "description": "The rule id, without the version." }, "identity": { "type": "string", "description": "The identity the index holds, with the version." }, "title": { "type": "string", "description": "The title." }, "class": { "type": "string", "description": "`blocking` or `advisory`." }, "enforced": { "type": "boolean", "description": "Whether the tool enforces it: the rule carries an `x-majordomus` block." }, "path": { "type": "string", "description": "Repository-relative path." } }, "required": [ "id", "identity", "title", "class", "enforced", "path" ], "description": "One rule the feature names." }, "ScopeReport": { "type": "object", "properties": { "origin": { "$ref": "#/components/schemas/Origin", "description": "`repository` when the manifest names a scope section, `distribution` for the default." }, "path": { "type": "string", "description": "The file the declaration was read from." }, "declaration": { "$ref": "#/components/schemas/Declaration", "description": "The declaration as read." }, "tracked": { "$ref": "#/components/schemas/Tally", "description": "Every tracked file judged by name and size, counted; the out ones listed." } }, "required": [ "origin", "path", "declaration", "tracked" ], "description": "The scope: the declaration as read, its origin, and every tracked file against it." }, "SearchHit": { "type": "object", "properties": { "uri": { "type": "string", "description": "`majordomus:///`." }, "id": { "type": "string", "description": "The capability id, `.`." }, "kind": { "type": "string", "description": "The kind the object was read as." }, "identity": { "type": "string", "description": "The identity within the kind." }, "title": { "type": [ "string", "null" ], "description": "The title, when the kind's title rule found one." }, "description": { "type": [ "string", "null" ], "description": "The one-line description, when the kind holds one." }, "path": { "type": "string", "description": "Repository-relative source path." }, "snippet": { "type": [ "string", "null" ], "description": "The first line of content that matched, when one did." } }, "required": [ "uri", "id", "kind", "identity", "path" ], "description": "One search hit: the object, summarised, and the first matching line of its content." }, "SearchResult": { "type": "object", "properties": { "query": { "type": "string", "description": "The query as given." }, "count": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many hits were returned." }, "limit": { "type": "integer", "format": "uint64", "minimum": 0, "description": "The limit that applied." }, "hits": { "type": "array", "items": { "$ref": "#/components/schemas/SearchHit" }, "description": "The hits, in URI order, at most `limit` of them." } }, "required": [ "query", "count", "limit", "hits" ], "description": "The answer of `objects.search`." }, "ServerStanding": { "oneOf": [ { "type": "string", "const": "absent", "description": "No lease: nothing serves this checkout." }, { "type": "string", "const": "starting", "description": "A lease without an address, young enough that its owner is still binding." }, { "type": "string", "const": "ready", "description": "The server the lease names answers for this checkout, from the code on disk, at\nthis executable's version." }, { "type": "string", "const": "outdated", "description": "The server answers, but from older code than this executable, or from a file that\nhas been replaced since it started: everything it says is yesterday's." }, { "type": "string", "const": "stale", "description": "The lease names a server that does not answer, or is not a lease at all." } ], "description": "Where a checkout's server stands, decided from its lease, whether the server the lease\nnames answers for that checkout, and whether what answers is this executable's code.\n\n```\nuse majordomus_cli::capability::builtin::server::ServerStanding;\nlet all = [ServerStanding::Absent, ServerStanding::Starting, ServerStanding::Ready,\n ServerStanding::Outdated, ServerStanding::Stale];\nlet words: Vec<&str> = all.iter().map(|s| s.as_str()).collect();\nassert_eq!(words, [\"absent\", \"starting\", \"ready\", \"outdated\", \"stale\"]);\nassert_eq!(serde_json::from_str::(\"\\\"stale\\\"\").unwrap(), ServerStanding::Stale);\n```" }, "ServerStatus": { "type": "object", "properties": { "checkout_id": { "type": "string", "description": "This checkout's identity: what this process answers as `repository_id`." }, "git": { "anyOf": [ { "$ref": "#/components/schemas/GitIdentity" }, { "type": "null" } ], "description": "The git repository this checkout belongs to; absent where git cannot be asked." }, "desired": { "$ref": "#/components/schemas/Desired", "description": "What this executable would serve, and what `standing` is measured against." }, "this_process": { "anyOf": [ { "$ref": "#/components/schemas/LeaseView" }, { "type": "null" } ], "description": "The lease this process holds, when it is the server; absent when the question was\nanswered by a process that serves nothing." }, "standing": { "$ref": "#/components/schemas/ServerStanding", "description": "Where this checkout's server stands." }, "servers": { "type": "array", "items": { "$ref": "#/components/schemas/ServerView" }, "description": "Every checkout of the repository, the primary first, each with its server. One entry\n— this checkout — where git cannot be asked." } }, "required": [ "checkout_id", "desired", "standing", "servers" ], "description": "The shared server of this checkout and of every other checkout of the repository.\n\n```\nuse majordomus_cli::capability::builtin::server::{Desired, ServerStanding, ServerStatus};\nlet status = ServerStatus { checkout_id: \"c\".into(), git: None,\n desired: Desired { host: \"127.0.0.1\".into(), port: 8741, version: \"1.0.0\".into(), executable: None },\n this_process: None, standing: ServerStanding::Absent, servers: Vec::new() };\nlet text = serde_json::to_string(&status).unwrap();\nassert_eq!(serde_json::from_str::(&text).unwrap(), status);\n```" }, "ServerView": { "type": "object", "properties": { "worktree": { "type": "string", "description": "The checkout, absolute and canonical." }, "branch": { "type": [ "string", "null" ], "description": "The branch checked out there, when git names one." }, "checkout_id": { "type": "string", "description": "The checkout's identity: what its server answers as `repository_id`." }, "primary": { "type": "boolean", "description": "Whether this is the primary checkout rather than a linked worktree." }, "this_checkout": { "type": "boolean", "description": "Whether this is the checkout the answering process serves." }, "standing": { "$ref": "#/components/schemas/ServerStanding", "description": "Where its server stands." }, "reason": { "type": [ "string", "null" ], "description": "Why, when the standing is not `ready`: what the lease held, or what answered." }, "lease": { "anyOf": [ { "$ref": "#/components/schemas/LeaseView" }, { "type": "null" } ], "description": "The lease, when the file holds one." }, "peers": { "type": [ "integer", "null" ], "format": "uint", "minimum": 0, "description": "How many peers the server reports attached, when it answers." } }, "required": [ "worktree", "checkout_id", "primary", "this_checkout", "standing" ], "description": "One checkout of the repository, and the server its lease names.\n\n```\nuse majordomus_cli::capability::builtin::server::{ServerStanding, ServerView};\nlet view = ServerView { worktree: \"/r\".into(), branch: Some(\"master\".into()), checkout_id: \"c\".into(),\n primary: true, this_checkout: true, standing: ServerStanding::Absent, reason: None, lease: None, peers: None };\nlet v = serde_json::to_value(&view).unwrap();\nassert_eq!(v[\"standing\"], \"absent\");\nassert!(v.get(\"lease\").is_none() && v.get(\"peers\").is_none(), \"what there is not is not written\");\n```" }, "ServiceAvailability": { "oneOf": [ { "type": "string", "const": "available", "description": "The address accepted a connection." }, { "type": "string", "const": "not_running", "description": "No server holds the repository's lease, or the address refused the connection." }, { "type": "string", "const": "unknown", "description": "The probe did not finish in its budget, or this resolution did not probe." } ], "description": "Whether a service answers. `Unknown` is a real answer and never a disguised `no`: a\nprobe that timed out and a port that refused the connection lead a reader to different\nactions." }, "ServiceState": { "type": "object", "properties": { "id": { "type": "string", "description": "A stable id, `[a-z][a-z0-9-]*`." }, "title": { "type": "string", "description": "The short name a person reads." }, "path": { "type": "string", "description": "The absolute path the router serves it under." }, "url": { "type": [ "string", "null" ], "description": "The full URL, when a server is running and published its address." }, "availability": { "$ref": "#/components/schemas/ServiceAvailability", "description": "Whether anything answers there." } }, "required": [ "id", "title", "path", "availability" ], "description": "One local service of this repository: what it is, where it is, and whether anything\nanswers there. The path is the one the router serves; the URL exists only while a\nserver does." }, "Severity": { "oneOf": [ { "type": "string", "const": "info", "description": "Worth knowing; changes nothing." }, { "type": "string", "const": "warning", "description": "Something to look at; the object is still served." }, { "type": "string", "const": "error", "description": "The file is excluded and the index is degraded." } ], "description": "How bad a diagnostic is. `Error` excludes the file it concerns from the index and puts\nthe index into the degraded state; `Warning` and `Info` do neither." }, "Signal": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique within the moment; the identity a diagnosis selects by." }, "text": { "type": "string", "description": "The symptom, phrased so a reader can say whether it happened to them." } }, "required": [ "id", "text" ], "description": "One observable symptom of a moment: a question a reader can answer about their own\nweek. The questionnaire on the site and the input of `why diagnose` are these and\nnothing else." }, "Source": { "type": "object", "properties": { "path": { "type": "string", "description": "Where it was read from, as the caller named it." }, "rules": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many rules of it state a colour." } }, "required": [ "path", "rules" ], "description": "One stylesheet the pair set was derived from." }, "Stability": { "oneOf": [ { "type": "string", "const": "implemented", "description": "Implemented, and no behavioural test names it yet." }, { "type": "string", "const": "behaviorally_verified", "description": "Implemented and proved by a behavioural test." }, { "type": "string", "const": "experimental", "description": "Implemented, executable, and expected to change." }, { "type": "string", "const": "planned", "description": "Specified and not implemented: listed, never executable." }, { "type": "string", "const": "unsupported", "description": "Considered and refused: listed with the reason, never executable." } ], "description": "Where a capability stands, in the repository's own vocabulary for claims. A capability\nthat is `Planned` or `Unsupported` may be listed but is never executable through any\nprojection; the registry refuses to build otherwise." }, "Standing": { "oneOf": [ { "type": "string", "const": "primary", "description": "The primary checkout: exempt from the path rule, held to the trunk rule." }, { "type": "string", "const": "canonical", "description": "A linked work tree at exactly its branch's canonical path." }, { "type": "string", "const": "misplaced", "description": "A linked work tree somewhere else. Migration brings it home." }, { "type": "string", "const": "detached", "description": "A linked work tree with no branch. It has no canonical path and is never moved." }, { "type": "string", "const": "ephemeral", "description": "A linked work tree under the operating system's temporary directory or under the\nprimary checkout's `.claude/worktrees/`: a session's scratch checkout, owned and\nremoved by the harness that made it. Reported; migrated only on request." }, { "type": "string", "const": "missing", "description": "A registration whose directory is gone. Repair drops it." } ], "description": "Where a work tree stands against the topology." }, "StartInput": { "type": "object", "additionalProperties": false, "properties": { "capability": { "type": "string", "description": "The canonical id of the capability to run (`health.report`, `objects.verify`)." }, "input": { "description": "Its input, as its own input schema describes it; an empty object when it takes none.", "default": null } }, "required": [ "capability" ], "description": "The input of `executions.start`: which capability to run, and with what." }, "State": { "oneOf": [ { "type": "string", "const": "ok", "description": "Every discovered file became an object." }, { "type": "string", "const": "degraded", "description": "At least one file could not be read; the diagnostics say which." } ], "description": "Whether every discovered file became an object." }, "StatusReport": { "type": "object", "properties": { "schema": { "type": "string", "description": "[`SCHEMA`]." }, "repository": { "$ref": "#/components/schemas/RepositoryView", "description": "The repository." }, "container": { "$ref": "#/components/schemas/ContainerView", "description": "The container." }, "trunk": { "$ref": "#/components/schemas/TrunkView", "description": "The trunk." }, "worktree": { "$ref": "#/components/schemas/WorktreeState", "description": "The work tree the call came from, with its uncommitted work counted." }, "canonical": { "type": "boolean", "description": "Whether this work tree is where it belongs: canonical, or the primary checkout on\nthe trunk, or detached." }, "repository_errors": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many error-level diagnostics the whole topology carries." } }, "required": [ "schema", "repository", "container", "trunk", "worktree", "canonical", "repository_errors" ], "description": "The answer to \"where am I, and is that where I belong\"." }, "StepOutcome": { "oneOf": [ { "type": "string", "const": "planned", "description": "Planned and not applied." }, { "type": "string", "const": "blocked", "description": "Not carried out, with the blockers on the step." }, { "type": "string", "const": "moved", "description": "Moved, and the fingerprint after equals the one before." }, { "type": "string", "const": "failed", "description": "Attempted and not completed, or completed and not verified; the message says which." } ], "description": "What became of a step." }, "StepState": { "oneOf": [ { "type": "string", "const": "running", "description": "Entered and not finished." }, { "type": "string", "const": "completed", "description": "Finished, and what it was asked to do happened." }, { "type": "string", "const": "failed", "description": "Finished, and it did not." } ], "description": "Where a step of an execution stands." }, "StepView": { "type": "object", "properties": { "name": { "type": "string", "description": "A stable name, unique within the execution." }, "title": { "type": "string", "description": "One line for a reader." }, "state": { "$ref": "#/components/schemas/StepState", "description": "Where it stands." }, "started_at": { "type": "string", "description": "When it was entered, RFC 3339 in UTC." }, "finished_at": { "type": [ "string", "null" ], "description": "When it finished, when it has." }, "detail": { "type": [ "string", "null" ], "description": "What it said when it finished, when it said anything." } }, "required": [ "name", "title", "state", "started_at" ], "description": "One named phase of an execution, as the handler reported it." }, "Summary": { "type": "object", "properties": { "total": { "type": "integer", "format": "uint", "minimum": 0, "description": "Every capability." }, "builtin": { "type": "integer", "format": "uint", "minimum": 0, "description": "Composed in Rust." }, "declarative": { "type": "integer", "format": "uint", "minimum": 0, "description": "Read from the layer." }, "by_kind": { "type": "object", "additionalProperties": { "type": "integer", "format": "uint", "minimum": 0 }, "description": "By kind (`query`, `resource`)." }, "by_stability": { "type": "object", "additionalProperties": { "type": "integer", "format": "uint", "minimum": 0 }, "description": "By stability." }, "mcp_tools": { "type": "integer", "format": "uint", "minimum": 0, "description": "With an MCP tool exposure." }, "mcp_resources": { "type": "integer", "format": "uint", "minimum": 0, "description": "With an MCP resource exposure." }, "http_routes": { "type": "integer", "format": "uint", "minimum": 0, "description": "With an HTTP exposure." }, "cli_commands": { "type": "integer", "format": "uint", "minimum": 0, "description": "With a CLI exposure." }, "modules": { "type": "integer", "format": "uint", "minimum": 0, "description": "Modules: composed, derived, and one per declarative kind." }, "benchmark_required": { "type": "integer", "format": "uint", "minimum": 0, "description": "Executables whose benchmark policy is required." }, "benchmark_waived": { "type": "integer", "format": "uint", "minimum": 0, "description": "Executables waived from benchmarking for a typed reason." }, "cached": { "type": "integer", "format": "uint", "minimum": 0, "description": "Executables the executor caches." } }, "required": [ "total", "builtin", "declarative", "by_kind", "by_stability", "mcp_tools", "mcp_resources", "http_routes", "cli_commands", "modules", "benchmark_required", "benchmark_waived", "cached" ], "description": "The registry counted: by source, kind, stability and projection." }, "Surface": { "type": "object", "properties": { "id": { "type": "string", "description": "Identity, unique across the topology; the selector `--only` and `--exclude` use it." }, "title": { "type": "string", "description": "One line: what a reader sees in a listing." }, "category": { "$ref": "#/components/schemas/SurfaceCategory", "description": "What it is for, which is how a listing groups it." }, "visibility": { "$ref": "#/components/schemas/SurfaceVisibility", "description": "Whether a person is shown it." }, "kind": { "$ref": "#/components/schemas/SurfaceKind", "description": "How it answers." }, "mount": { "$ref": "#/components/schemas/Mount", "description": "Where it answers." }, "producer": { "type": "string", "description": "What produced it: a command, a module, or the generator that writes the directory." }, "feature": { "anyOf": [ { "$ref": "#/components/schemas/Feature" }, { "type": "null" } ], "description": "The runtime capability it needs; absent when the process always has it." }, "artifact": { "type": [ "string", "null" ], "description": "The generated directory, repository-relative, for a static surface." }, "index": { "type": [ "string", "null" ], "description": "The file served for the mount itself, when the surface has one." }, "availability": { "$ref": "#/components/schemas/SurfaceAvailability", "description": "Where the surface's files go and who answers for it." }, "built_from": { "type": [ "string", "null" ], "description": "The revision the artifact was built from, when its producer recorded one: what\nmakes a stale build a finding rather than a surprise." }, "provenance": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Provenance" }, "description": "Where each interesting value came from, by field name." } }, "required": [ "id", "title", "category", "visibility", "kind", "mount", "producer", "availability", "provenance" ], "description": "One resolved surface: everything a consumer needs, with the provenance of what it could\nbe surprised by." }, "SurfaceAvailability": { "oneOf": [ { "type": "string", "const": "both", "description": "Served by the running executable and published as files." }, { "type": "string", "const": "served-only", "description": "Answered by the running executable and never published: a route the process\ncomputes, or a build made for this server's own mount rather than for deployment." }, { "type": "string", "const": "published-only", "description": "Published as files; the running executable serves it from the same directory." } ], "description": "Whether a surface is part of the static publication, served only while a process runs,\nor both." }, "SurfaceCategory": { "oneOf": [ { "type": "string", "const": "interface", "description": "Something a person opens and looks at: the home page, the Cockpit." }, { "type": "string", "const": "documentation", "description": "Prose and reference written for a person: the site, the Swagger UI." }, { "type": "string", "const": "api", "description": "A machine-readable surface of the capability registry." }, { "type": "string", "const": "protocol", "description": "A wire protocol another program speaks." }, { "type": "string", "const": "report", "description": "Generated evidence of a run: a test report, a benchmark report." } ], "description": "What a surface is for, which is how a reader is shown it.\n\nA category is the one piece of intent that a mount cannot carry: `/openapi.json` and\n`/swagger` sit beside each other and are a document and a viewer for it. Grouping is\nderived from this field and never from a list of paths kept somewhere else." }, "SurfaceFinding": { "type": "object", "properties": { "severity": { "$ref": "#/components/schemas/SurfaceFindingSeverity", "description": "How much it matters." }, "rule": { "type": "string", "description": "The rule that produced it, stable enough to grep for." }, "surface": { "type": "string", "description": "The surface it is about." }, "message": { "type": "string", "description": "What is wrong." }, "remedy": { "type": "string", "description": "What to do about it." } }, "required": [ "severity", "rule", "surface", "message", "remedy" ], "description": "One thing wrong with a topology, said so a person can fix it without reading this file." }, "SurfaceFindingSeverity": { "oneOf": [ { "type": "string", "const": "warning", "description": "Worth reading; serving is still coherent." }, { "type": "string", "const": "error", "description": "The topology may not be served or published in this state." } ], "description": "How much a finding matters." }, "SurfaceInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "`cli`, `api`, `mcp`, `cockpit` or `docs`." }, "title": { "type": "string", "description": "The name a person reads." }, "route": { "type": "string", "description": "The route on the website where the surface is documented." }, "features": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many stable features it exposes." } }, "required": [ "id", "title", "route", "features" ], "description": "One surface of the vocabulary, as a client reads it." }, "SurfaceKind": { "oneOf": [ { "type": "string", "const": "static-directory", "description": "A generated directory, mounted under its prefix and served from disk." }, { "type": "string", "const": "native-route", "description": "A path the executable answers itself, from its own registry or handlers." }, { "type": "string", "const": "redirect", "description": "A path that answers with a redirect to another one." } ], "description": "How a surface answers a request.\n\nOnly what this repository serves: a directory of generated files, a path the executable\nanswers itself, and a redirect. A new *kind* is a new behaviour, never a new name for\nthe same behaviour with different data." }, "SurfaceRef": { "type": "object", "properties": { "id": { "type": "string", "description": "The surface id." }, "title": { "type": "string", "description": "The title." }, "mount": { "type": "string", "description": "Where it is mounted." }, "category": { "type": "string", "description": "What it is for." } }, "required": [ "id", "title", "mount", "category" ], "description": "One web surface of the topology the feature names." }, "SurfaceReport": { "type": "object", "properties": { "surfaces": { "type": "array", "items": { "$ref": "#/components/schemas/Surface" }, "description": "Every resolved surface, in route-precedence order: the order a router consults\nthem in, so the first whose mount owns a path is the one that answers it." }, "served": { "type": "array", "items": { "type": "string" }, "description": "The ids a process answers for, in the same order. A surface published and not\nserved is absent here." }, "published": { "type": "array", "items": { "type": "string" }, "description": "The ids a publication holds, in the same order." }, "public": { "type": "array", "items": { "type": "string" }, "description": "The ids offered to a person, which is what the home page lists." }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/SurfaceFinding" }, "description": "What validation says about the topology as it stands. Empty is the healthy answer;\na finding here is the same one `majordomus web validate` reports, with its remedy." } }, "required": [ "surfaces", "served", "published", "public", "findings" ], "description": "The web surfaces of this repository, as the process that answers resolved them." }, "SurfaceVisibility": { "oneOf": [ { "type": "string", "const": "public", "description": "Listed for a person: it appears on the home page." }, { "type": "string", "const": "internal", "description": "Served and introspectable, not advertised: a machine speaks to it, or another\nsurface links to it." } ], "description": "Who a surface is offered to.\n\nTwo values and no more: a surface is either offered for a person to discover, or it is\npart of the topology without being advertised. Both are always in the machine-readable\nanswer — hiding a served route from introspection would only hide it from the people\nmaintaining it." }, "Surfaces": { "type": "object", "properties": { "cli": { "type": "boolean", "description": "The command line: the executable's own, or the shell tool's." }, "api": { "type": "boolean", "description": "The HTTP routes under `/api/v1/`, and the OpenAPI document over them." }, "mcp": { "type": "boolean", "description": "MCP: a tool, or a resource." }, "cockpit": { "type": "boolean", "description": "The Cockpit." }, "docs": { "type": "boolean", "description": "The documentation." } }, "required": [ "cli", "api", "mcp", "cockpit", "docs" ], "description": "The interfaces a feature is exposed through, decided from what its references project\nand from nothing a file says. Each is a fact with a reason a reader can check: `cli` is\ntrue when a module of the feature has a capability with a command-line path or the\nfeature names a shell command; `api` when a module has an HTTP route; `mcp` when a module\nhas an MCP tool or resource, or the feature names a kind, since every object of the layer\nis an MCP resource; `cockpit` when the feature names a Cockpit area or a module, since\nevery capability has a Cockpit page; `docs` when it names a document." }, "Tally": { "type": "object", "properties": { "files": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many tracked files were judged." }, "in": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many are in." }, "out": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many are out." }, "by_reason": { "type": "object", "additionalProperties": { "type": "integer", "format": "uint", "minimum": 0 }, "description": "How many are out for each reason present." }, "out_files": { "type": "array", "items": { "$ref": "#/components/schemas/OutFile" }, "description": "Every tracked file that is out, with its reason and the rule that decided." } }, "required": [ "files", "in", "out", "by_reason", "out_files" ], "description": "Every tracked file against the scope, counted." }, "TargetStatus": { "oneOf": [ { "type": "string", "const": "supported", "description": "Built by every release, offered by the installer, listed as supported. A release\nthat is missing this artifact is not published." }, { "type": "string", "const": "experimental", "description": "Built and offered, and documented as not yet proven." }, { "type": "string", "const": "unavailable", "description": "Documented, never built, refused by the installer with its recorded reason." } ], "description": "What the project promises about a target.\n\nSee [`crate::deploy::Status`]: both are `Status` in their own module and neither is in\nthe one component namespace the schema document has." }, "TargetView": { "type": "object", "properties": { "id": { "type": "string", "description": "The target's id in the model." }, "title": { "type": "string", "description": "How it is written in prose: `Linux x86_64 musl`." }, "os": { "$ref": "#/components/schemas/Os", "description": "The operating system." }, "arch": { "$ref": "#/components/schemas/Arch", "description": "The architecture." }, "libc": { "anyOf": [ { "$ref": "#/components/schemas/Libc" }, { "type": "null" } ], "description": "The C library, on Linux." }, "rust_target": { "type": "string", "description": "The Rust target triple." }, "status": { "$ref": "#/components/schemas/TargetStatus", "description": "What the project promises about it." }, "reason": { "type": [ "string", "null" ], "description": "Why, when it is not built." }, "artifact": { "type": "string", "description": "The artifact name, with `{tag}` where a release's tag goes." } }, "required": [ "id", "title", "os", "arch", "rust_target", "status", "artifact" ], "description": "One target, as every projection shows it: what it is, what it is called in prose, and\nthe artifact name the naming function derives for a tag yet to be chosen." }, "ThemeView": { "type": "object", "properties": { "class": { "type": "string", "description": "The class on the root element that means dark." }, "storage_key": { "type": "string", "description": "The `localStorage` key the person's choice is kept under." }, "bootstrap": { "type": "string", "description": "The one pre-paint statement every surface runs." } }, "required": [ "class", "storage_key", "bootstrap" ], "description": "The theme contract as a client reads it." }, "TierState": { "oneOf": [ { "type": "string", "const": "resolved", "description": "Read from its canonical source during this resolution." }, { "type": "string", "const": "cached", "description": "Taken from the cache written by an earlier full resolution." }, { "type": "string", "const": "unavailable", "description": "Neither available; the values are absent and the reason is a diagnostic." } ], "description": "Where a tier of the snapshot came from. A tier the active resolution cannot reach is\n[`TierState::Unavailable`] with the reason, and its values are absent rather than zero." }, "Token": { "type": "object", "properties": { "name": { "type": "string", "description": "The name as declared." }, "kind": { "$ref": "#/components/schemas/TokenKind", "description": "What kind of token." }, "about": { "type": "string", "description": "What it is for, from the declaration." }, "css": { "type": "array", "items": { "type": "string" }, "description": "The custom properties and Tailwind utilities it becomes." }, "parts": { "type": "array", "items": { "$ref": "#/components/schemas/ColourPart" }, "description": "For a colour token: its parts, each resolved per theme." }, "value": { "type": [ "string", "null" ], "description": "For a scalar token: the value." }, "role": { "type": [ "string", "null" ], "description": "For a state word: the status it is filed under." }, "states": { "type": "array", "items": { "type": "string" }, "description": "For a status: the state words filed under it." }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "The Flowbite names that are synonyms of it." }, "projections": { "type": "array", "items": { "type": "string" }, "description": "The generated files the token reaches." } }, "required": [ "name", "kind", "about", "css", "projections" ], "description": "One token, explained: where it came from, what it resolves to, what reads it." }, "TokenKind": { "oneOf": [ { "type": "string", "const": "font", "description": "A type stack." }, { "type": "string", "const": "palette", "description": "A raw palette entry." }, { "type": "string", "const": "role", "description": "A semantic surface role." }, { "type": "string", "const": "status", "description": "A status meaning." }, { "type": "string", "const": "state", "description": "A state word, filed under a status." }, { "type": "string", "const": "type", "description": "A step of the type scale." }, { "type": "string", "const": "tracking", "description": "A letter-spacing." }, { "type": "string", "const": "layout", "description": "A shared layout value." }, { "type": "string", "const": "radius", "description": "A corner radius." }, { "type": "string", "const": "motion", "description": "A duration." }, { "type": "string", "const": "theme", "description": "The theme contract." } ], "description": "What kind of thing a token is." }, "TokenList": { "type": "object", "properties": { "fingerprint": { "type": "string", "description": "The fingerprint of the declaration they came from." }, "total": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many are listed." }, "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/Token" }, "description": "The tokens, in the inventory's order." } }, "required": [ "fingerprint", "total", "tokens" ], "description": "The tokens, listed." }, "TokenTallies": { "type": "object", "properties": { "palette": { "type": "integer", "format": "uint", "minimum": 0, "description": "Raw palette entries." }, "roles": { "type": "integer", "format": "uint", "minimum": 0, "description": "Semantic roles." }, "statuses": { "type": "integer", "format": "uint", "minimum": 0, "description": "Status meanings." }, "states": { "type": "integer", "format": "uint", "minimum": 0, "description": "State words filed under a status." }, "type_steps": { "type": "integer", "format": "uint", "minimum": 0, "description": "Steps of the type scale." }, "aliases": { "type": "integer", "format": "uint", "minimum": 0, "description": "Flowbite names declared as synonyms." } }, "required": [ "palette", "roles", "statuses", "states", "type_steps", "aliases" ], "description": "How many of each kind of token." }, "ToolchainAvailability": { "oneOf": [ { "type": "string", "const": "installed", "description": "Installed, and its version answered." }, { "type": "string", "const": "missing", "description": "The executable is not on the path." }, { "type": "string", "const": "unknown", "description": "Nobody asked: this resolution may not run a subprocess for it, and no cache held it." } ], "description": "Whether a declared toolchain is usable here." }, "ToolchainState": { "type": "object", "properties": { "id": { "type": "string", "description": "A stable id, `[a-z][a-z0-9-]*`: `rust`, `node`." }, "title": { "type": "string", "description": "The short name a person reads." }, "declared": { "type": [ "string", "null" ], "description": "The version the repository declares, when it declares one." }, "declared_by": { "type": "string", "description": "The repository-relative file that declares it." }, "installed": { "type": [ "string", "null" ], "description": "The version installed here, when it could be asked and the answer is not stale." }, "availability": { "$ref": "#/components/schemas/ToolchainAvailability", "description": "Where the installed version stands." } }, "required": [ "id", "title", "declared_by", "availability" ], "description": "A toolchain the repository declares, and what is installed for it. The three are kept\napart on purpose: a repository can declare a version nobody has, and a machine can have\na version no repository asked for, and reporting either as the other is how a version\nmismatch stays invisible for a week." }, "TopologyDiagnostic": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/DiagnosticCode", "description": "The stable code." }, "severity": { "$ref": "#/components/schemas/Severity", "description": "How serious it is." }, "path": { "type": [ "string", "null" ], "description": "The work tree involved." }, "branch": { "type": [ "string", "null" ], "description": "The branch involved." }, "expected": { "type": [ "string", "null" ], "description": "Where the work tree belongs." }, "message": { "type": "string", "description": "What is wrong, in one line." }, "remedy": { "type": "string", "description": "The command that addresses it." } }, "required": [ "code", "severity", "message", "remedy" ], "description": "One thing wrong with, or worth knowing about, the topology." }, "TopologyTallies": { "type": "object", "properties": { "worktrees": { "type": "integer", "format": "uint", "minimum": 0, "description": "Every registered work tree, primary included." }, "canonical": { "type": "integer", "format": "uint", "minimum": 0, "description": "Linked work trees at their canonical path." }, "misplaced": { "type": "integer", "format": "uint", "minimum": 0, "description": "Linked work trees somewhere else." }, "detached": { "type": "integer", "format": "uint", "minimum": 0, "description": "Linked work trees without a branch." }, "ephemeral": { "type": "integer", "format": "uint", "minimum": 0, "description": "Scratch checkouts of a session." }, "missing": { "type": "integer", "format": "uint", "minimum": 0, "description": "Registrations whose directory is gone." }, "locked": { "type": "integer", "format": "uint", "minimum": 0, "description": "Work trees git reports as locked." }, "dirty": { "type": "integer", "format": "uint", "minimum": 0, "description": "Work trees with uncommitted work, when it was asked for." }, "branches": { "type": "integer", "format": "uint", "minimum": 0, "description": "Local branches." }, "branches_without_worktree": { "type": "integer", "format": "uint", "minimum": 0, "description": "Local branches with no work tree." }, "cleanup_eligible": { "type": "integer", "format": "uint", "minimum": 0, "description": "Branches eligible for cleanup." }, "errors": { "type": "integer", "format": "uint", "minimum": 0, "description": "Error-level diagnostics." }, "warnings": { "type": "integer", "format": "uint", "minimum": 0, "description": "Warning-level diagnostics." } }, "required": [ "worktrees", "canonical", "misplaced", "detached", "ephemeral", "missing", "locked", "dirty", "branches", "branches_without_worktree", "cleanup_eligible", "errors", "warnings" ], "description": "How many work trees and branches are in each state." }, "TraceReport": { "type": "object", "properties": { "trunk": { "type": [ "string", "null" ], "description": "The trunk every branch and commit was measured against." }, "examined": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many trunk commits were attributed." }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/IssueTrace" }, "description": "The issues that at least one branch names, in id order." }, "without_branch": { "type": "array", "items": { "type": "string" }, "description": "The issue ids the project model declares that no ref names. Not a fault: an issue\nnobody has started has no branch yet." }, "commits": { "type": "array", "items": { "$ref": "#/components/schemas/CommitAttribution" }, "description": "The examined trunk commits, newest first." }, "tallies": { "$ref": "#/components/schemas/TraceTallies", "description": "The counts, so a caller need not add them up." } }, "required": [ "examined", "issues", "without_branch", "commits", "tallies" ], "description": "The whole traceability answer: every issue git can say something about, and every commit\nof a stretch of the trunk with the contract it served or the fact that it has none." }, "TraceTallies": { "type": "object", "properties": { "issues_declared": { "type": "integer", "format": "uint", "minimum": 0, "description": "Issue ids the project model declares." }, "issues_with_branch": { "type": "integer", "format": "uint", "minimum": 0, "description": "Of those, the ones at least one ref names." }, "branches": { "type": "integer", "format": "uint", "minimum": 0, "description": "Branches naming an issue." }, "branch_commits": { "type": "integer", "format": "uint", "minimum": 0, "description": "Distinct commits those branches claim." }, "attributed": { "type": "integer", "format": "uint", "minimum": 0, "description": "Examined trunk commits with exactly one issue." }, "unattributed": { "type": "integer", "format": "uint", "minimum": 0, "description": "Examined trunk commits no branch naming an issue contains." }, "ambiguous": { "type": "integer", "format": "uint", "minimum": 0, "description": "Examined trunk commits more than one issue claims." } }, "required": [ "issues_declared", "issues_with_branch", "branches", "branch_commits", "attributed", "unattributed", "ambiguous" ], "description": "The counts of one report." }, "Transport": { "oneOf": [ { "type": "string", "const": "stdio", "description": "The owner's own client, on the process's stdin and stdout." }, { "type": "string", "const": "http", "description": "MCP over HTTP at `/mcp`: a `majordomus mcp` bridge, or a client speaking it directly." } ], "description": "How a peer reached the server." }, "TrunkSource": { "oneOf": [ { "type": "string", "const": "remote_head", "description": "`refs/remotes//HEAD`: what the remote calls its default branch." }, { "type": "string", "const": "default_branch_config", "description": "`init.defaultBranch` in the git configuration, and that branch exists locally." }, { "type": "string", "const": "conventional_name", "description": "Exactly one of `main` and `master` exists locally." }, { "type": "string", "const": "primary_checkout", "description": "The branch the primary checkout holds, because nothing else said." }, { "type": "string", "const": "unknown", "description": "Nothing said; the trunk is unknown and every check that needs it says so." } ], "description": "Where the trunk was learned from, in the order it is looked for." }, "TrunkView": { "type": "object", "properties": { "branch": { "type": [ "string", "null" ], "description": "The branch, when known." }, "source": { "$ref": "#/components/schemas/TrunkSource", "description": "How it was decided." }, "checked_out_at": { "type": [ "string", "null" ], "description": "Where it is checked out." } }, "required": [ "source" ], "description": "The trunk, as the topology reports it." }, "UpstreamState": { "type": "object", "properties": { "name": { "type": "string", "description": "The upstream ref, short (`origin/master`)." }, "ahead": { "type": [ "integer", "null" ], "format": "uint", "minimum": 0, "description": "Commits here that the upstream lacks." }, "behind": { "type": [ "integer", "null" ], "format": "uint", "minimum": 0, "description": "Commits upstream that this branch lacks." }, "gone": { "type": "boolean", "description": "The upstream ref no longer exists." } }, "required": [ "name", "gone" ], "description": "A branch's upstream and how far the two have moved apart, from `for-each-ref` in one\nsubprocess for every branch, never a fetch." }, "UseCaseRef": { "type": "object", "properties": { "id": { "type": "string", "description": "The use case id." }, "title": { "type": "string", "description": "The title." }, "category": { "type": [ "string", "null" ], "description": "The category it is filed under." } }, "required": [ "id", "title" ], "description": "One use case the feature names." }, "ValidationReport": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "True when nothing is an error. Warnings do not make it false." }, "errors": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many findings are errors: a reference that resolves to nothing, a duplicate\nidentity, a file name that disagrees with its id." }, "warnings": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many findings are warnings: a public record that does not meet its floor." }, "counts": { "$ref": "#/components/schemas/Counts", "description": "The counts the catalogue reached." }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/Finding" }, "description": "The findings, errors first, then by file." } }, "required": [ "valid", "errors", "warnings", "counts", "findings" ], "description": "What the catalogue's own validation found." }, "VcsState": { "oneOf": [ { "$ref": "#/components/schemas/GitWorkingTree", "type": "object", "properties": { "state": { "type": "string", "const": "git" } }, "required": [ "state" ], "description": "`git` answered." }, { "type": "object", "properties": { "reason": { "type": "string", "description": "What went wrong." }, "state": { "type": "string", "const": "unavailable" } }, "required": [ "state", "reason" ], "description": "`git` could not be asked, or this is not a work tree." } ], "description": "What version control says about the checkout, or why it could not be asked." }, "Verdict": { "oneOf": [ { "type": "string", "const": "in", "description": "Read." }, { "type": "string", "const": "out", "description": "Never read; the reason says why." } ], "description": "In or out." }, "VerifyReport": { "type": "object", "properties": { "files": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many files were read." }, "current": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many of them are what the index read." }, "drifted": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many are not, of any kind of not." }, "objects": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many objects of the index those files carry." }, "compared_by_content": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many were compared byte for byte rather than by size." }, "fingerprint": { "type": "string", "description": "The index fingerprint this process is serving." }, "index_is_current": { "type": "boolean", "description": "Whether the index is still a true picture of the working tree, as far as this\ncomparison can tell." }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/DriftedObject" }, "description": "The files that are not, with what is wrong with each." } }, "required": [ "files", "current", "drifted", "objects", "compared_by_content", "fingerprint", "index_is_current", "findings" ], "description": "The answer of `objects.verify`." }, "Violation": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/ViolationCode", "description": "The stable code." }, "severity": { "$ref": "#/components/schemas/QualitySeverity", "description": "How bad it is." }, "rule": { "type": "string", "description": "The canonical id of the rule that requires this." }, "path": { "type": "string", "description": "Where it is, repository-relative; empty when the finding is not about a file." }, "line": { "type": [ "integer", "null" ], "format": "uint", "minimum": 0, "description": "The line, 1-based; `None` when the finding is not about a line." }, "symbol": { "type": "string", "description": "The item's full path, or the command, or the capability id: what the finding is about." }, "message": { "type": "string", "description": "One sentence, specific to this occurrence." }, "why": { "type": "string", "description": "Why it matters, from the code." }, "remediation": { "type": "string", "description": "What to do, from the code." } }, "required": [ "code", "severity", "rule", "path", "symbol", "message", "why", "remediation" ], "description": "One finding: what, where, why, and what to do." }, "ViolationCode": { "oneOf": [ { "type": "string", "const": "RUST_PUBLIC_MISSING_DOCS", "description": "An exported item carries no documentation at all." }, { "type": "string", "const": "RUST_PUBLIC_THIN_DOCS", "description": "An exported item's documentation says nothing its signature had not already said." }, { "type": "string", "const": "RUST_PUBLIC_MISSING_EXAMPLE", "description": "An exported item that carries behaviour has no executable example." }, { "type": "string", "const": "RUST_EXAMPLE_NOT_EXECUTABLE", "description": "Every example an item has is `ignore`d or is prose in a fenced box." }, { "type": "string", "const": "RUST_EXAMPLE_PLACEHOLDER", "description": "An example asserts nothing, or asserts something that is true of any program." }, { "type": "string", "const": "RUST_EXAMPLE_DOES_NOT_NAME_SUBJECT", "description": "An example never names the item it is documenting." }, { "type": "string", "const": "RUST_MODULE_MISSING_DOCS", "description": "An exported module carries no module-level documentation." }, { "type": "string", "const": "RUST_MODULE_MISSING_EXAMPLE", "description": "An exported module has no module-level executable example." }, { "type": "string", "const": "RUST_MODULE_MISSING_BEHAVIOURAL_TEST", "description": "No test names an exported module, and it declares none of its own." }, { "type": "string", "const": "OPERATION_CLI_UNCLASSIFIED", "description": "A command of the command line is neither a canonical capability nor classified as\nbelonging to the command line alone." }, { "type": "string", "const": "OPERATION_CLASSIFICATION_STALE", "description": "A command is classified as belonging to the command line alone, and the command\nline no longer has it." }, { "type": "string", "const": "OPERATION_CLASSIFICATION_CONFLICT", "description": "A command is classified as local *and* bound to a capability: two answers to one\nquestion." }, { "type": "string", "const": "OPERATION_MISSING_OPENAPI", "description": "A capability declares an HTTP route and the OpenAPI document does not describe it." }, { "type": "string", "const": "OPERATION_PROJECTION_MISSING", "description": "A capability declares a projection that the projection itself does not carry." }, { "type": "string", "const": "OPERATION_PROJECTION_ORPHAN", "description": "A projection carries an entry the registry does not hold." } ], "description": "What is wrong, as a stable machine-readable code.\n\nThe codes are the contract between the validator and everything downstream: CI\nannotations, Cockpit filters, documentation anchors and an agent deciding what to fix.\nA code is never renamed once it has shipped; a rule that stops existing takes its code\nwith it." }, "Vocabulary": { "type": "object", "properties": { "version": { "type": "integer", "format": "uint64", "minimum": 0, "description": "The file's own format version. `1` is the only one this reader accepts." }, "source": { "type": "string", "description": "Where it was read from, absolute: the distribution's share directory, which is not\nnecessarily inside the repository." }, "count": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many tokens there are. No number anywhere is written down." }, "obligations": { "type": "array", "items": { "$ref": "#/components/schemas/Obligation" }, "description": "Every token, in the order the file declares them." } }, "required": [ "version", "source", "count", "obligations" ], "description": "The vocabulary the distribution ships: every token there is.\n\n`count` is measured from `obligations` rather than written down, so a token added to\nthe file is counted by the same act that declares it.\n\n```\nuse majordomus_cli::capability::builtin::obligations::Vocabulary;\nlet v: Vocabulary = serde_json::from_str(\n r#\"{\"version\":1,\"source\":\"/opt/majordomus/share/obligations.yaml\",\"count\":1,\n \"obligations\":[{\"id\":\"commit\",\"title\":\"The work is committed\",\n \"summary\":\"In the branch's history, not the working tree.\",\n \"discharged_by\":\"git\",\"remote\":false}]}\"#,\n)\n.unwrap();\nassert_eq!(v.count, v.obligations.len());\nassert_eq!(v.version, 1, \"the only shape this reader accepts\");\n```" }, "WaiverReason": { "oneOf": [ { "type": "string", "const": "not_executable", "description": "A resource: read, never executed; nothing to time but `objects.get`, which is." }, { "type": "string", "const": "destructive", "description": "The capability changes something outside this process and cannot be run in a loop." }, { "type": "string", "const": "external_dependency", "description": "The capability talks to something the benchmark host cannot provide." }, { "type": "string", "const": "transient_state", "description": "The capability starts, or answers about, work that exists only while it is running.\nA benchmark host cannot stage an execution to read, and running the operation in a\nloop would measure the work rather than the operation." } ], "description": "Why an executable capability is not benchmarked. Typed, so that a waiver is a\nreviewable statement and never a convenience; `not_executable` is the registry's own\nreason for resources and is never written by hand." }, "WorkflowCatalogue": { "type": "object", "properties": { "state": { "$ref": "#/components/schemas/TierState", "description": "Where these came from." }, "source": { "type": [ "string", "null" ], "description": "The command that produced them, when one did." }, "workflows": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowDescriptor" }, "description": "Every public workflow, sorted by name." }, "entrypoints": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowEntrypoint" }, "description": "The entry point of each group, in the order the groups are declared: what a person\nnew to the repository runs first. Derived, never listed anywhere." } }, "required": [ "state" ], "description": "The workflows a person can run here, as the workflow runner itself describes them." }, "WorkflowDescriptor": { "type": "object", "properties": { "name": { "type": "string", "description": "The name a person types after `just`." }, "namespace": { "type": [ "string", "null" ], "description": "The module path, for a recipe in an imported module; empty at the root." }, "description": { "type": [ "string", "null" ], "description": "The recipe's doc comment, when it has one." }, "group": { "type": [ "string", "null" ], "description": "The `[group(...)]` it belongs to, when it declares one." }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowParameter" }, "description": "Its parameters, in declaration order." }, "dependencies": { "type": "array", "items": { "type": "string" }, "description": "The recipes it runs first, in order." }, "confirm": { "type": "boolean", "description": "Whether it asks before it runs (`[confirm]`)." } }, "required": [ "name", "confirm" ], "description": "One workflow: a recipe of the repository's `justfile`, as `just` describes it." }, "WorkflowEntrypoint": { "type": "object", "properties": { "group": { "type": "string", "description": "The group, as the justfile declares it." }, "workflow": { "type": "string", "description": "The workflow that stands for the group." }, "command": { "type": "string", "description": "The command a person types." }, "description": { "type": [ "string", "null" ], "description": "The workflow's description, when it has one." } }, "required": [ "group", "workflow", "command" ], "description": "The entry point of one group of workflows: what the group is, and the one workflow that\nstands for it." }, "WorkflowParameter": { "type": "object", "properties": { "name": { "type": "string", "description": "The name." }, "variadic": { "type": "boolean", "description": "Whether it may be repeated (`*args`, `+args`)." }, "required": { "type": "boolean", "description": "Whether it must be given." } }, "required": [ "name", "variadic", "required" ], "description": "One parameter of a workflow." }, "WorktreeFingerprint": { "type": "object", "properties": { "branch": { "type": [ "string", "null" ], "description": "The branch, or none when detached." }, "head": { "type": [ "string", "null" ], "description": "The commit." }, "index_digest": { "type": "string", "description": "A digest of the index: every tracked path with its mode, blob and stage." }, "staged_diff_digest": { "type": "string", "description": "A digest of the staged diff against HEAD." }, "unstaged_diff_digest": { "type": "string", "description": "A digest of the unstaged diff against the index." }, "untracked_manifest_digest": { "type": "string", "description": "A digest of every untracked file: path, kind, size and content." }, "untracked_files": { "type": "integer", "format": "uint", "minimum": 0, "description": "How many untracked files the manifest holds." }, "ignored_manifest_digest": { "type": "string", "description": "A digest of every ignored entry: path, kind and size, never content." }, "in_progress": { "type": [ "string", "null" ], "description": "The operation in progress, if any." }, "tree_manifest_digest": { "type": [ "string", "null" ], "description": "A digest of every entry of the directory tree, ignored included: path, kind, size\nand link target. Taken only for a move made by copying, where the rename guarantee\ndoes not hold." } }, "required": [ "index_digest", "staged_diff_digest", "unstaged_diff_digest", "untracked_manifest_digest", "untracked_files", "ignored_manifest_digest" ], "description": "What a work tree held at one moment, reduced to digests." }, "WorktreeKind": { "oneOf": [ { "type": "string", "const": "primary", "description": "The main work tree. It hosts the trunk, is never moved and is never removed." }, { "type": "string", "const": "linked", "description": "A linked work tree. Belongs at its branch's canonical path." } ], "description": "Whether a work tree is the repository's own checkout or one linked to it." }, "WorktreeState": { "type": "object", "properties": { "path": { "type": "string", "description": "Absolute, as git holds it." }, "kind": { "$ref": "#/components/schemas/WorktreeKind", "description": "Primary or linked." }, "standing": { "$ref": "#/components/schemas/Standing", "description": "Where it stands against the topology." }, "branch": { "type": [ "string", "null" ], "description": "The branch checked out here, short. Absent when detached." }, "label": { "type": "string", "description": "The name it is shown under: the branch, or `detached/`." }, "head": { "type": [ "string", "null" ], "description": "The commit checked out here." }, "detached": { "type": "boolean", "description": "HEAD is detached here." }, "expected_path": { "type": [ "string", "null" ], "description": "Where this branch's work tree belongs. Absent when detached, or for the primary\ncheckout on the trunk." }, "exists": { "type": "boolean", "description": "The directory git registered still exists on disk." }, "current": { "type": "boolean", "description": "The call came from inside this work tree." }, "locked": { "type": [ "string", "null" ], "description": "Locked, with git's reason; an empty string when it recorded none." }, "prunable": { "type": [ "string", "null" ], "description": "Prunable, with git's reason." }, "dirty": { "anyOf": [ { "$ref": "#/components/schemas/DirtyState" }, { "type": "null" } ], "description": "Uncommitted work here. Absent when it was not asked for: it costs one subprocess per\nwork tree, and a topology check does not need it." }, "upstream": { "anyOf": [ { "$ref": "#/components/schemas/UpstreamState" }, { "type": "null" } ], "description": "The branch's upstream and its distance from it." }, "issue": { "type": [ "string", "null" ], "description": "The issue this branch provably names: a path component of the branch equal to an\nissue id of `.ai/repo/project/issues/`, or beginning with it and a hyphen. Nothing\nis inferred from similarity." }, "diagnostics": { "type": "array", "items": { "$ref": "#/components/schemas/TopologyDiagnostic" }, "description": "What is wrong with this work tree, if anything." } }, "required": [ "path", "kind", "standing", "label", "detached", "exists", "current", "diagnostics" ], "description": "One work tree, as the topology sees it." } } }, "x-majordomus": { "generator": "majordomus-cli 0.5.0", "infrastructure": [ { "id": "home", "path": "/", "what": "This process, and everything it serves", "availability": "served-only" }, { "id": "api", "path": "/api/v1", "what": "The capability registry over HTTP", "availability": "served-only" }, { "id": "openapi", "path": "/openapi.json", "what": "The OpenAPI document of the capability registry", "availability": "both" }, { "id": "swagger", "path": "/swagger", "what": "Swagger UI over the OpenAPI document", "availability": "served-only" }, { "id": "mcp", "path": "/mcp", "what": "MCP over HTTP for attached clients", "availability": "served-only" }, { "id": "events", "path": "/events", "what": "The live channel: what this process's executions are doing", "availability": "served-only" }, { "id": "cockpit", "path": "/cockpit", "what": "The registry, rendered for a person", "availability": "served-only" } ], "binding": "GET binds every top-level input property as a query parameter; POST binds the input as the JSON body", "errors": [ { "status": "400", "code": "invalid_input", "reason": "The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects." }, { "status": "404", "code": "not_found", "reason": "The input names something the repository does not hold." }, { "status": "422", "code": "refused", "reason": "The command was understood and turned down for the reason the message gives." }, { "status": "500", "code": "internal", "reason": "The capability failed for a reason of its own; the message names it." } ] }, "x-majordomus-generated": "GENERATED FILE — DO NOT EDIT DIRECTLY; source: the canonical Majordomus capability registry; regenerate with `majordomus generate`", "x-majordomus-generator": "majordomus-cli 0.5.0" }