Which repository instructions should I believe?

To work in an unfamiliar repository, I need a few basic facts: what it does, how to build and test it, who maintains it, and where to find the documentation. Answering those questions can mean reading across several files and deciding which one to believe.

Different sources carry different authority

Build instructions may live in a README, a Justfile, CI workflows, or a package manifest. Ownership may live partly in CODEOWNERS, partly in org settings, and partly in habits no file captures at all. Security expectations might be declared in SECURITY.md, implied by automation, or nowhere obvious.

An explicit maintainer declaration, an imported value, and a guess from surrounding files carry different kinds of evidence. A tool that returns only the value loses those distinctions.

dotrepo records the source and status alongside repository facts. Here are two illustrative answers to repo.build for different repositories. These simplified examples show the distinction; they are not the API’s complete response format.

{
  "path": "repo.build",
  "value": "cargo build --release",
  "status": "canonical",
  "provenance": "declared",
  "source": ".repo",
  "claimed_by": "maintainer"
}

{
  "path": "repo.build",
  "value": "make",
  "status": "inferred",
  "provenance": "inferred",
  "source": "Makefile (heuristic)",
  "claimed_by": null
}

The first command was declared by the maintainer; the second was inferred from a Makefile. That distinction helps a consumer assess the answer. Whether to execute either command depends on the environment and the permissions granted to the agent. Even a maintainer-declared command can be stale or unsuitable for the task.

The same care applies to status labels. In dotrepo, verified can come from automated checks rather than maintainer approval; the query essay explains what the label does and doesn’t establish.

Records for repositories that haven’t adopted dotrepo

An index limited to repositories whose maintainers have installed dotrepo would have little to offer its first users. Overlays let it provide records earlier: they are separate records generated or contributed from available repository sources.

An overlay can later be corrected or superseded through a maintainer claim. Its sources and status need to stay visible throughout that process so consumers can distinguish an inferred answer from one the maintainer controls.

Repeating the same discovery work

An agent asked to explain a repository or run its checks has to read documentation, inspect configuration files, and infer intent from conventions. The same orientation work is repeated each time a new agent encounters the project.

dotrepo’s MCP server gives coding agents a way to query those facts and inspect their sources. The intended benefit is less repeated discovery work. Whether an answer is useful still depends on its age, supporting evidence, and relevance to the task; source inspection remains necessary when those checks fail.

The parts of dotrepo

The project has three parts:

• a versioned .repo protocol for essential repository metadata
• Rust tools for validation, queries, source and conflict inspection, import, and publication
• a hosted index and API for repository records, including generated overlays

Maintainers use the local tools to check their records. Consumers query either local metadata or the hosted index and follow the evidence back to repository files when needed.

For a worked example, see Where did that build command come from?. For local setup, see Set up repository metadata with dotrepo.