repository.info
The repository root, layer sections, git state, discovery mode, kinds present, every diagnostic, and the capability registry counted.
The repository root, layer sections, git state, discovery mode, kinds present, every diagnostic, and the capability registry counted.
- query
- behaviorally_verified
- module repository
- #repository
- #introspection
Exposure
Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.
| surface | as |
|---|---|
| MCP | tool majordomus_repository resource majordomus://repository |
| HTTP | GET /api/v1/repository operationId repository.info |
| command line | — |
Schemas
The canonical input and output, from the Rust types; the MCP tool schema and the OpenAPI parameters and responses are derived from these.
input · Empty
No input.
No properties: the capability takes no input.
JSON Schema
{
"additionalProperties": false,
"description": "No input.",
"title": "Empty",
"type": "object"
}output · RepositoryReport
The repository, its layer, its git state, and the state of this process's index.
| property | type | required | description |
|---|---|---|---|
| capabilities | reference | yes | The capability registry, counted. |
| diagnostics | array | yes | Every diagnostic the index produced. |
| kinds | object | yes | Objects per kind. |
| objects | integer | yes | How many objects the index holds. |
| repository | reference | yes | The repository: root, layer schema, sections, git state, discovery mode, source classes, kind sources. |
| state | reference | yes | ok when every discovered file became an object, degraded otherwise. |
JSON Schema
{
"$defs": {
"AnswerObservation": {
"description": "When the state behind an answer was read: the freshness contract of a capability answer.\n\nDeclared once and carried in the output type of every answer that is a picture of\nstate, so that the output schema, OpenAPI, the MCP tool schemas and the command line's\nJSON all carry it without a transport of their own. It is set where the state is read —\nthe index build, the git read — never by the executor, which knows when a handler ran\nand not when the state it read was taken.\n\n```\nuse std::time::{Duration, UNIX_EPOCH};\nuse majordomus_cli::index::AnswerObservation;\nlet at = UNIX_EPOCH + Duration::from_secs(1_788_000_000);\nlet o = AnswerObservation::taken(\"git read\", at, Some(Duration::from_secs(120)));\nassert_eq!(o.observed_at, \"2026-08-29T10:40:00Z\");\nassert_eq!(o.stale_after.as_deref(), Some(\"2026-08-29T10:42:00Z\"));\nassert!(!o.is_stale_at(at + Duration::from_secs(120)));\nassert!(o.is_stale_at(at + Duration::from_secs(121)));\n```",
"properties": {
"observed_at": {
"description": "RFC 3339 UTC, whole seconds: when the state behind the answer was read. Empty only\nin an answer from an index that was never built (a hand-made one in a test).",
"type": "string"
},
"source": {
"description": "What was read at that time: `index build` or `git read`.",
"type": "string"
},
"stale_after": {
"description": "RFC 3339 UTC: after this the answer is not to be trusted as current even though\nnothing announced a change. Absent when there is no known blind spot.",
"type": [
"string",
"null"
]
}
},
"required": [
"observed_at",
"source"
],
"type": "object"
},
"Diagnostic": {
"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.",
"properties": {
"code": {
"description": "A stable machine-readable code, e.g. `unknown_key`, `duplicate_identity`.",
"type": "string"
},
"message": {
"description": "What is wrong, for a person; the code is for a program.",
"type": "string"
},
"path": {
"description": "Repository-relative path of the file concerned, when there is one.",
"type": [
"string",
"null"
]
},
"severity": {
"$ref": "#/$defs/Severity",
"description": "How bad."
}
},
"required": [
"severity",
"code",
"message"
],
"type": "object"
},
"GitInfo": {
"description": "What `git` said about the repository.",
"properties": {
"branch": {
"description": "Branch name, or `None` when detached or unborn.",
"type": [
"string",
"null"
]
},
"head": {
"description": "Full commit id of HEAD, or `None` in an unborn repository.",
"type": [
"string",
"null"
]
},
"toplevel": {
"description": "Absolute path of the work tree top level.",
"type": "string"
},
"working_tree": {
"description": "`clean` or `dirty`, from `git status --porcelain`.",
"type": "string"
}
},
"required": [
"toplevel",
"working_tree"
],
"type": "object"
},
"GitState": {
"description": "What git says about the repository, or why it could not be asked.",
"oneOf": [
{
"$ref": "#/$defs/GitInfo",
"description": "`git` answered; the facts follow.",
"properties": {
"state": {
"const": "available",
"type": "string"
}
},
"required": [
"state"
],
"type": "object"
},
{
"description": "`git` could not be asked, or the root is not a work tree; the reason says which.",
"properties": {
"reason": {
"description": "What `git` said, or why it could not be run.",
"type": "string"
},
"state": {
"const": "unavailable",
"type": "string"
}
},
"required": [
"state",
"reason"
],
"type": "object"
}
]
},
"Origin": {
"description": "Where the declaration was read from.",
"oneOf": [
{
"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.",
"type": "string"
}
]
},
"RepositoryInfo": {
"description": "What the index knows about the repository it was built from.",
"properties": {
"discovery": {
"description": "`vcs` or `filesystem`.",
"type": "string"
},
"git": {
"$ref": "#/$defs/GitState",
"description": "What `git` said, or why it could not be asked."
},
"kind_sources": {
"description": "The kinds files the reader was configured from: the distribution's, then the\nrepository's own when it has one.",
"items": {
"type": "string"
},
"type": "array"
},
"layer_schema": {
"description": "The manifest's `schema`, `ai-repository/v1`.",
"type": "string"
},
"observed": {
"$ref": "#/$defs/RepositoryObservations",
"default": {
"git": {
"observed_at": "",
"source": ""
},
"index": {
"observed_at": "",
"source": ""
}
},
"description": "When the index and the git state it carries were read. Defaults to empty so that a\nrecord written before the freshness contract still reads."
},
"root": {
"description": "The repository root, absolute.",
"type": "string"
},
"scope_origin": {
"$ref": "#/$defs/Origin",
"description": "Where the scope was read from: `repository` or `distribution`."
},
"scope_path": {
"description": "The scope file: repository-relative for the repository's own, the share path for\nthe distribution's default.",
"type": "string"
},
"sections": {
"additionalProperties": {
"type": "string"
},
"description": "Manifest section name to repository-relative path.",
"type": "object"
},
"source_classes": {
"description": "Source class id to kind, in declared order.",
"items": {
"maxItems": 2,
"minItems": 2,
"prefixItems": [
{
"type": "string"
},
{
"type": "string"
}
],
"type": "array"
},
"type": "array"
}
},
"required": [
"root",
"layer_schema",
"sections",
"git",
"discovery",
"source_classes",
"kind_sources",
"scope_origin",
"scope_path"
],
"type": "object"
},
"RepositoryObservations": {
"description": "The two pictures a process takes of the repository, each with when it was taken.\n\nA picture without a window is never stale, and its window is not serialized.\n\n```\nuse std::time::{Duration, UNIX_EPOCH};\nuse majordomus_cli::index::{AnswerObservation, RepositoryObservations};\nlet now = RepositoryObservations {\n index: AnswerObservation::taken(\"index build\", UNIX_EPOCH, None),\n git: AnswerObservation::taken(\"git read\", UNIX_EPOCH, Some(Duration::from_secs(120))),\n};\nlet json = serde_json::to_value(&now).unwrap();\nassert_eq!(json[\"git\"][\"stale_after\"], \"1970-01-01T00:02:00Z\");\nassert!(json[\"index\"].get(\"stale_after\").is_none());\nlet back: RepositoryObservations = serde_json::from_value(json).unwrap();\nassert_eq!(back, now);\n```",
"properties": {
"git": {
"$ref": "#/$defs/AnswerObservation",
"description": "When git was asked: the branch, the head, the working tree."
},
"index": {
"$ref": "#/$defs/AnswerObservation",
"description": "When the index was built: the objects, the kinds, the diagnostics."
}
},
"required": [
"index",
"git"
],
"type": "object"
},
"Severity": {
"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.",
"oneOf": [
{
"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.",
"type": "string"
}
]
},
"State": {
"description": "Whether every discovered file became an object.",
"oneOf": [
{
"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.",
"type": "string"
}
]
},
"Summary": {
"description": "The registry counted: by source, kind, stability and projection.",
"properties": {
"benchmark_required": {
"description": "Executables whose benchmark policy is required.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"benchmark_waived": {
"description": "Executables waived from benchmarking for a typed reason.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"builtin": {
"description": "Composed in Rust.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"by_kind": {
"additionalProperties": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"description": "By kind (`query`, `resource`).",
"type": "object"
},
"by_stability": {
"additionalProperties": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"description": "By stability.",
"type": "object"
},
"cached": {
"description": "Executables the executor caches.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"cli_commands": {
"description": "With a CLI exposure.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"declarative": {
"description": "Read from the layer.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"http_routes": {
"description": "With an HTTP exposure.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"mcp_resources": {
"description": "With an MCP resource exposure.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"mcp_tools": {
"description": "With an MCP tool exposure.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"modules": {
"description": "Modules: composed, derived, and one per declarative kind.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"total": {
"description": "Every capability.",
"format": "uint",
"minimum": 0,
"type": "integer"
}
},
"required": [
"total",
"builtin",
"declarative",
"by_kind",
"by_stability",
"mcp_tools",
"mcp_resources",
"http_routes",
"cli_commands",
"modules",
"benchmark_required",
"benchmark_waived",
"cached"
],
"type": "object"
}
},
"description": "The repository, its layer, its git state, and the state of this process's index.",
"properties": {
"capabilities": {
"$ref": "#/$defs/Summary",
"description": "The capability registry, counted."
},
"diagnostics": {
"description": "Every diagnostic the index produced.",
"items": {
"$ref": "#/$defs/Diagnostic"
},
"type": "array"
},
"kinds": {
"additionalProperties": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"description": "Objects per kind.",
"type": "object"
},
"objects": {
"description": "How many objects the index holds.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"repository": {
"$ref": "#/$defs/RepositoryInfo",
"description": "The repository: root, layer schema, sections, git state, discovery mode, source classes, kind sources."
},
"state": {
"$ref": "#/$defs/State",
"description": "`ok` when every discovered file became an object, `degraded` otherwise."
}
},
"required": [
"repository",
"state",
"objects",
"kinds",
"diagnostics",
"capabilities"
],
"title": "RepositoryReport",
"type": "object"
}Policies
- benchmark
- required — a target on every transport the exposure declares; the cases are the input type's
- cache
- generation — up to 1 entries in the process, scoped by the registry fingerprint and the context's reading of the repository
Benchmark targets
Derived from the registry for this repository: one requirement per transport, and the cases the input type provides. The whole matrix is on the benchmarks page.
The moments this answers
- opened CLAUDE.md and AGENTS.md and found two different rulebooks for one repository Each provider reads its own hand-edited file, nothing relates them, and which contract applies depends on which tool is open.
- found a task "in progress" that nobody had touched for three weeks A status that was authored rather than computed is true at the moment of writing and decays silently from then on.
- watched the always-loaded instruction file grow past a thousand lines Everything important gets appended to the always-loaded file, so every session pays for every rule and reads none of them carefully.
- found five worktrees and could not say which of them still mattered Isolation is cheap to create and expensive to reason about: nothing records what a worktree was for or whether its work landed.
- changed a policy in one place and found the old one still in force in three others A decision is updated at its source and the generated copies keep serving the previous version, with nothing reporting the difference.
- had a green pipeline over generated files that no longer matched their sources Tests exercise the code and say nothing about the committed outputs derived from it, so the build is green and the artifacts are wrong.
- could not say why one provider was used for that work and another for this Provider and model selection is made implicitly, per session, and recorded nowhere, so it cannot be reviewed or repeated.
- spent the first hour in an unfamiliar repository working out what was normal here What is conventional in a codebase is knowledge held by its regulars, so every arrival — human or machine — pays for it again.