Skip to content

Vendors and models are declared once in share/models.yaml, and the CLI, HTTP, OpenAPI, MCP and Cockpit render that one declaration with no model name of their own

Which models exist, what each can do, how large its context is, and which name is an

declared statusdeclared status: guaranteed Declared deterministic and blocking, implemented, and naming the behavioural test that is to prove it. Whether a recorded run supports it is the evidence verdict, shown beside it.

recorded evidencerecorded evidence: not run Declared guaranteed, and not supported by a recorded run: the test is named, and no passing run of the current inputs is recorded. how evidence is recorded

models.list and models.route are capability declarations, so every surface is a projection; the catalogue's own diagnostics report a duplicate alias or an undeclared vendor at first read. Declaration order is routing's preference order, verifiable by reading the file.

What it means

Which models exist, what each can do, how large its context is, and which name is an alias of which are facts stated exactly once, in share/models.yaml. majordomus models list, GET /api/v1/models, the majordomus_models MCP tool, the majordomus://models resource, the OpenAPI document and the Cockpit's Models page are projections of that file — none carries a model name of its own, so adding or retiring a model is one edit and every surface follows. The catalogue's own findings — a duplicate alias, a model naming an undeclared vendor — ride along in every listing, reported at first read rather than discovered downstream.

How it works

models.list and models.route are capability! declarations (apps/majordomus-cli/src/capability/builtin/models.rs), so every transport projection is derived (ADR 0004); the catalogue type and its loader live in apps/majordomus-cli/src/models/mod.rs, reading the share directory through the same resolution everything else uses. Declaration order is routing's preference order, a property a person verifies by reading the file. test/cases/131_models.sh proves the operator path — one declaration rendered, presence-only credentials, an empty catalogue as an answer. ADR 0049 records the decision and why the word "provider" stays spent.

How to see it

majordomus models list                   # the whole catalogue, one declaration
curl http://127.0.0.1:8741/api/v1/models
grep -c "id:" share/models.yaml          # the same count the surfaces show
bash test/run.sh 131_models

What it does not cover

The catalogue does not verify that a declared model still exists at its vendor — it is reviewed data with stated provenance, not a live probe (ADR 0032 keeps network clients out of the crate). Staleness is visible in the file's provenance header, where it can be judged.

Why it exists

Model names scattered through prompts, configs and workers' heads are a hand-maintained truth per consumer — the exact shape this repository refuses everywhere else. One declared file, projected everywhere, makes adding or retiring a model one reviewable edit (ADR 0049).

Detail rendered from docs/claims/models-one-declaration.md.

From the statement to the proof

  1. 1 · the public statement

    Vendors and models are declared once in share/models.yaml, and the CLI, HTTP, OpenAPI, MCP and Cockpit render that one declaration with no model name of their own

    Made on Models.

  2. 2 · the canonical claim

    models-one-declarationdeclared status: guaranteed in docs/CLAIMS.yaml

    Defined in read it on this site · docs/MODELS.md

  3. 3 · the implementation

    apps/majordomus-cli/src/models/mod.rs

  4. 4 · the test and the scenarios

    Test: test/cases/131_models.sh

  5. 5 · the recorded runs

    recorded evidence: not run how evidence is recorded

Verify it yourself

The test runs in a disposable temporary repository and asserts the behaviour, not a string in the source.

from a clone of the repository 
bash test/run.sh 131_models

Related claims same implementation

Searches the titles and descriptions of every page this site publishes.