dotrepo

dotrepo is an attempt to make repositories easier to understand, trust, and work with by turning metadata into a real shared layer instead of a loose pile of conventions.

It is not just a CLI, and it is not just a schema. The project has three parts that only really make sense together:

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

Why build this?

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 meant to provide a machine-readable repository layer without flattening projects into sterile metadata sludge. The source materials stay primary. The protocol is the coordination layer around them.

What ships today

The current workspace is already a working implementation, not just an architecture sketch.

It includes:

• a canonical root .repo format plus overlay records for index use
• shared Rust core semantics for validation, query, trust, import, generate-check, 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 seed index/ tree with evidence rules, maintainer-claim artifacts, and review workflows
• a hosted read-only public JSON tree architecture for repository summary and trust responses
• release-artifact packaging for dotrepo, dotrepo-lsp, and dotrepo-mcp

The local workspace test suite passes across the CLI, core library, MCP server, LSP server, public export fixtures, and claim/public-contract suites.

The trust model is the point

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

What matters is that records communicate provenance and authority clearly. dotrepo distinguishes canonical, imported, inferred, reviewed, and verified states, and it treats overlays as first-class public records rather than pretending inferred data is equivalent to 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.

Toolchain shape

The Rust workspace currently includes:

• dotrepo-schema
• dotrepo-core
• dotrepo-cli
• dotrepo-mcp
• dotrepo-lsp
• dotrepo-transport

The intended release binaries are:

dotrepo
dotrepo-lsp
dotrepo-mcp

And the reference CLI surface already includes commands like:

dotrepo init
dotrepo import
dotrepo validate
dotrepo query
dotrepo trust
dotrepo public

Public-surface direction

One part of the project I especially like is the public export model.

Instead of inventing a separate hosted application truth model, dotrepo exports a read-only JSON tree that can be deployed through static hosting. That public surface carries repository identity, trust context, and claim-aware selection in a form that both humans and agents can inspect directly.

That keeps the hosted view downstream of the same exported data used for local review and CI, which is much cleaner than bolting a separate web runtime onto the side and hoping the semantics match.

Release posture

As of March 2026, dotrepo is in release-shaping mode rather than blank-slate invention mode.

The workspace, seed index, maintainer-claim flow, public export contracts, and release packaging are all real. What remains is release hardening, public rollout, and pushing the broader ecosystem story into a form other people can actually adopt.

The next step is opening the repository publicly and shipping the first release around that surface.

Why it belongs on this site

dotrepo sits close to the center of what I care about:

• protocols that need to be precise without becoming joyless
• tools that work for humans and agents at the same time
• trust and provenance as first-class product concerns
• infrastructure that becomes useful before universal adoption

It is one of the clearest examples on this site of a project that is simultaneously systems work, interface design, and ecosystem design.