dotrepo

dotrepo gives maintainers, users, tools, and coding agents a shared metadata layer for understanding repositories without flattening them into scraped sludge.

It combines three aligned surfaces:

a versioned protocol centered on a canonical root .repo file
a Rust reference toolchain for validation, query, trust inspection, import, and public export
a hosted public index with trust-aware overlays for repositories that have not adopted the protocol natively

What it is

Repository metadata is fragmented almost by default.

Some facts live in README.md. Some live in CODEOWNERS, SECURITY.md, CI configuration, editor settings, or package metadata. Some are nowhere except tribal knowledge. That is annoying for maintainers, confusing for users, and expensive for agents.

If you ask basic questions like “what is this repo?”, “who owns it?”, “how do I build it?”, or “what trust level should I assign to this record?”, the answer is usually spread across several files and a lot of implied context.

dotrepo is an attempt to turn that loose pile of conventions into a real coordination layer: something maintainers can author, tools can query, and users can inspect with trust and provenance still attached.

What ships today

The current public release is already a real surface, not just an architecture sketch.

Today the project includes:

a canonical root .repo format plus overlay records for index use
shared Rust core semantics for validation, query, trust, import, export, and authority/conflict reporting
a reference CLI with commands for init, import, validate, query, generate, doctor, trust, claim workflows, and public export
a stdio MCP server and thin stdio LSP server built on the same core semantics
a thin VS Code shell around the same validation and language-server surface
managed sync for supported Markdown surfaces through explicit managed regions
a hosted read-only public/v0/ JSON surface for repository summary, trust, inventory, freshness, and query responses
a seed public index for ripgrep, cli/cli, bat, fd, and ries-rs
release-artifact packaging for dotrepo, dotrepo-lsp, and dotrepo-mcp

The release bundles cover macOS and Linux. The point is that the protocol, toolchain, and hosted public surface now exist together.

The trust model is the point

The core idea is not merely “put repo metadata in TOML.”

What matters is that a record carries its authority and provenance with it. dotrepo distinguishes draft, imported, inferred, reviewed, verified, and canonical states, and it keeps declared, imported, inferred, and verified provenance visible instead of pretending every answer is maintainer-declared truth.

That is why the index matters. The project is designed to be useful even before broad adoption. A repository can become mechanically visible through carefully labeled overlays, and maintainers can later claim, correct, or replace that representation with canonical records.

Live public surface

dotrepo.org already exposes the public model directly.

Stable entry points include:

/v0/meta.json for snapshot freshness and digest metadata
/v0/repos/index.json for repository inventory and navigation
/v0/repos/<host>/<owner>/<repo>/index.json for per-repository summary
/v0/repos/<host>/<owner>/<repo>/trust.json for selection, provenance, and claim context
/v0/repos/<host>/<owner>/<repo>/query?path=... for same-origin trust-aware field queries

Snapshot freshness and digest metadata are part of that surface, so the public responses are not just readable; they are inspectable as reviewed exports.

Use dotrepo now

If you want the fastest way to understand the project, start with the public surface directly:

Those three doors are enough to make the shape of the system legible: inventory, trust context, and query responses all come from the same reviewed export family.

A concrete trust example

The first stable release includes a live accepted maintainer claim for github.com/maxwellsantoro/ries-rs.

That is the kind of detail that matters more than the schema alone. The interesting question is not just whether the public surface can answer “what is this repository?” The interesting question is whether it can show which record won, why it won, and whether the answer comes from canonical maintainer-controlled data, a reviewed overlay, or some other provenance path.

trust.json and trust-aware query responses carry that context forward instead of stripping it away.

What it does not claim yet

The current release is the protocol, the toolchain, and the hosted public index.

It is not trying to solve every downstream product surface yet. Richer search and ranking UX, mutation APIs, bundle mode, broader editor automation, and relation-heavy discovery are still intentionally out of scope.

Why it matters

A lot of software infrastructure only becomes useful after broad adoption. dotrepo is designed to be useful earlier than that.

Repositories can become visible through carefully labeled overlays now, and maintainers can later claim, correct, or replace those records with canonical in-repo metadata. That makes the project simultaneously a protocol, a toolchain, and an ecosystem design for trust-aware repository metadata.

Where to start

If you want to see the idea live, start with the public surface on dotrepo.org.

If you want the full implementation, the repository is the source of truth: schema, CLI, trust model, release bundles, and hosted-surface code all live there.