{
  "markdown": "# dotrepo\n\n[![CI](https://github.com/maxwellsantoro/dotrepo/actions/workflows/ci.yml/badge.svg)](https://github.com/maxwellsantoro/dotrepo/actions/workflows/ci.yml)\n[![Latest Release](https://img.shields.io/github/v/release/maxwellsantoro/dotrepo)](https://github.com/maxwellsantoro/dotrepo/releases/latest)\n[![License: MIT](https://img.shields.io/badge/license-MIT-0f766e.svg)](LICENSE)\n\n**dotrepo** is an open metadata protocol and shared semantic cache for software\nrepositories. It makes repository understanding reusable instead of forcing\nevery human and agent to fetch, parse, and infer the same basic facts again.\n\nIt packages that into three aligned surfaces:\n- **maintainers** get one structured source of truth and tools that keep supported repository surfaces from drifting\n- **users** get consistent, evidence-linked project orientation and an increasingly useful research index\n- **agents and tools** get compact, trust-aware repository facts before resorting to cloning or scraping\n\nRepositories that have not adopted dotrepo can still receive autonomously\ngenerated overlays. The pipeline uses deterministic parsers first, escalates\nonly unresolved fields through progressively stronger model tiers, validates\nall output against evidence, and publishes uncertainty instead of inventing\ncertainty. Maintainers can later publish a native `.repo` and become the\ncanonical authority.\n\nThe goal is not to replace project documentation or character. It is to pay the\ncost of basic repository understanding when a project changes, then reuse that\nunderstanding across future tools, users, and research tasks.\n\nProject site and hosted public surface:\n[dotrepo.org](https://dotrepo.org/)\n\n## See it in 60 seconds\n\nThis repository now ships its own native [`.repo`](.repo). A minimal slice of\nthat record looks like:\n\n```toml\nschema = \"dotrepo/v0.1\"\n\n[record]\nmode = \"native\"\nstatus = \"canonical\"\n\n[record.trust]\nconfidence = \"high\"\nprovenance = [\"declared\", \"verified\"]\nnotes = \"Maintainer-controlled source of truth.\"\n\n[repo]\nname = \"dotrepo\"\ndescription = \"Open metadata protocol for software repositories\"\nbuild = \"cargo build --workspace\"\ntest = \"cargo test --workspace\"\n\n[repo.toolchain]\nmin = \"1.90.0\"\necosystem = \"Rust\"\n```\n\nWhat the CLI gives you once `dotrepo` is on your `PATH`:\n\n```bash\ndotrepo --root examples/native-minimal validate\ndotrepo --root examples/native-minimal query repo.build --raw\ndotrepo --root examples/native-minimal trust\n```\n\n```text\nmanifest valid\ncargo build\nselected: .repo (Native, Canonical)\nselection reason: only matching record\nsource: none\nconfidence: high\nprovenance: declared, verified\nnotes: Maintainer-controlled source of truth.\n```\n\nThat is the wedge: dotrepo does not just answer a repository question, it tells\nyou why that answer should be trusted.\n\n## Quick start\n\n1. Install `dotrepo` from the latest **stable** GitHub release bundle (`1.0.x`),\n   or with `cargo install dotrepo-cli` (pin a `1.0.x` version for production).\n   The `main` branch tracks a `2.0.0-alpha` development line with public API\n   changes. See [`docs/install.md`](docs/install.md) for platform bundles and\n   the VS Code extension package.\n2. Start a record in your repository:\n\n```bash\ndotrepo --root <repo> init\n# or bootstrap from existing README.md / CODEOWNERS / SECURITY.md:\ndotrepo --root <repo> import\n```\n\n3. Run the canonical maintainer loop:\n\n```bash\ndotrepo --root <repo> validate\ndotrepo --root <repo> query repo.build --raw\ndotrepo --root <repo> trust\ndotrepo --root <repo> generate --check\n```\n\nFor the full maintainer flow, see\n[`docs/maintainer-happy-path.md`](docs/maintainer-happy-path.md).\n\nIf you want to contribute to the protocol, toolchain, or public index, start with\n[`CONTRIBUTING.md`](CONTRIBUTING.md).\n\n## What dotrepo is\n\ndotrepo has three inseparable parts:\n\n1. **A protocol**\n   A versioned `.repo` schema for essential repository metadata, provenance, trust, and synchronization hints.\n2. **A reference toolchain**\n   A Rust CLI, stdio MCP server, and related integrations for importing, validating, querying, syncing, and generating compatible repository surfaces.\n3. **An index**\n   A public, Git-backed collection of evidence-backed overlays, trust context,\n   and maintainer handoffs that makes repositories mechanically visible before\n   native adoption.\n\nThe current index is generated and refreshed through an autonomous conveyor.\nRoutine generated records do not require per-record human review. Humans set\npolicy, improve gates and parsers, monitor aggregate health, and handle\nmaintainer authority claims.\n\n## Why it matters for agents\n\n`dotrepo-mcp` is a thin stdio MCP server that exposes the same trust-aware core\nused by the CLI. It gives agent clients structured tools instead of forcing them\nto scrape README prose.\n\nCurrent MCP tools:\n- `dotrepo.validate`\n- `dotrepo.query`\n- `dotrepo.trust`\n- `dotrepo.adoption_status`\n- `dotrepo.lookup`\n- `dotrepo.claim_inspect`\n- `dotrepo.generate_check`\n- `dotrepo.import_preview`\n- `dotrepo.import_write`\n\nTool execution errors are returned as MCP tool results with\n`isError: true` and machine-readable `structuredContent`. Protocol-level\nmistakes, such as calling an unknown tool name, still use normal JSON-RPC\nerrors.\n\nExample local MCP tool call:\n\n```json\n{\n  \"name\": \"dotrepo.query\",\n  \"arguments\": {\n    \"root\": \"examples/native-minimal\",\n    \"path\": \"repo.build\"\n  }\n}\n```\n\nThat returns the selected value together with record status, provenance, and\nconflict context.\n\n`dotrepo validate` intentionally checks only the root `.repo` or root\n`record.toml` for the selected repository. Use `dotrepo validate-index` for\ndescendant `index/repos/**/record.toml` overlays; `query` and `trust` still\nload matching descendant candidates when resolving conflict-aware answers.\n\nExample hosted lookup call:\n\n```json\n{\n  \"name\": \"dotrepo.lookup\",\n  \"arguments\": {\n    \"repositoryUrl\": \"https://github.com/BurntSushi/ripgrep\",\n    \"path\": \"repo.description\"\n  }\n}\n```\n\nThat resolves the repository against `https://dotrepo.org/`, returns the hosted\nsummary, profile, trust, and query entrypoints, and optionally includes the live\nquery result for the requested dot-path. See\n[`rfcs/0006-mcp-server-contract.md`](rfcs/0006-mcp-server-contract.md) for the\ntool contract.\n\nFor repeated known-repository access, the reference CLI and hosted public\nsurface also expose batch profile/field lookup, structured profile search,\nfactual profile comparison, and relationship traversal as cacheable GET\nroutes:\n\n```bash\ncargo run -p dotrepo-cli -- public batch-profiles --repo github.com/sharkdp/fd\ncurl -s \"https://dotrepo.org/v0/batch/profiles?repo=github.com/sharkdp/fd\"\n```\n\nSee [`docs/public-export-examples.md`](docs/public-export-examples.md) for the\nfull set of batch, search, compare, relations, lookup-efficiency, and coverage\nexamples, and for the operator-facing measurement scripts.\n\nThe repository also includes a falsifiable\n[head-to-head benchmark harness](benchmarks/head-to-head/) that compares\ndotrepo lookups against a GitHub API + README baseline on accuracy, abstention,\nconfidently-wrong answers, latency, and bytes over the wire. It is intentionally\nallowed to make dotrepo lose; that is the measurement point.\n\n## Why now\n\nRepository metadata is fragmented. Some facts live in README files. Some live in `CODEOWNERS`, `SECURITY.md`, CI config, or platform settings. Some are nowhere except tribal knowledge.\n\nThat is annoying for maintainers, confusing for users, and expensive for coding agents. Today, basic questions like these often require heuristics or LLM interpretation:\n- What is this repo?\n- Who owns it?\n- How do I build and test it?\n- Where are the real docs?\n- What policies or constraints apply?\n\nA structured `.repo` record does not replace code or good documentation. It\nprovides a stable layer of essential facts that humans can maintain and machines\ncan query directly. The public index extends that stable shape to repositories\nthat have not adopted the protocol yet.\n\n## Core principles\n\n- **Protocol first**: dotrepo is a shared metadata protocol, not just a CLI.\n- **Trust matters**: all records should communicate provenance and trust level clearly.\n- **Respect the source**: overlays must distinguish declared facts, imported facts, and inferred facts.\n- **Useful before adoption**: the index and overlay model make dotrepo valuable even for repos that do not use it natively.\n- **Deterministic first**: parsers and evidence checks do the common work; model intelligence escalates only when needed.\n- **Honest automation**: generated overlays publish confidence, provenance, conflicts, and explicit unknowns without a routine human review queue.\n- **Practical, not doctrinaire**: dotrepo should work with existing files and conventions, not demand an all-or-nothing migration.\n- **Machine-readable, human-legible**: the protocol should help agents and tools without making projects feel sterile.\n\n## Current protocol decisions\n\n- **Canonical in-repo v0.1 form**: a single root `.repo` file in TOML format\n- **Bundle mode**: reserved for a future version\n- **Overlay records**: separate TOML records in the index, with explicit provenance and trust metadata\n- **Query support**: first-class CLI support for querying structured fields\n- **Mode-aware validation**: native records and overlays validate differently\n- **Generated outputs**: supported, but not the sole editing surface\n- **Extension namespace**: `x.*` is reserved for non-core extensions\n- **Repository relations**: explicit directed links carry their own trust;\n  workspace-specific relation kinds remain reserved for future work\n\n## Versioning note\n\nThe project release, manifest schema, claim schema, MCP protocol, and hosted API\nhave independent version lines. Read tool versions from GitHub releases,\nmanifest versions from the manifest itself, and the hosted API version from\n[`meta.json`](https://dotrepo.org/v0/meta.json) instead of copying them into\nadditional status documents.\n\nThose are separate version lines on purpose:\n- the release version tracks the shipped reference toolchain\n- the schema version tracks the `.repo` document contract\n- the public API version tracks the hosted JSON response surface\n\n## What the repo includes today\n\n- a Rust workspace with `dotrepo-schema`, `dotrepo-core`, `dotrepo-cli`, `dotrepo-mcp`, `dotrepo-lsp`, and the shared internal `dotrepo-transport`\n- a thin VS Code extension shell under [`editors/vscode/`](editors/vscode/)\n- a thin import path for bootstrapping records from `README.md`, `CODEOWNERS`, and `SECURITY.md`\n- a thin stdio MCP server exposing trust-aware validate/query/trust/generate-check/import tools\n- an autonomous crawler with deterministic verification, field scoring,\n  progressive adjudication providers, optional bounded synthesis sidecars,\n  promotion, refresh planning, and batch telemetry\n- updated RFCs that reflect the protocol + toolchain + index model\n- example native and overlay records\n- a seeded `index/` tree with real overlay layout and validation rules\n- GitHub Actions workflows for workspace CI, operator-gate claim checks,\n  release-gate packaging, and Cloudflare deployment\n- public-facing docs with a balanced tone around ambition, safety, and practicality\n\n## What dotrepo does not claim yet\n\nThis repo ships the current dotrepo protocol and reference toolchain surface.\nThe crates implement import, validation, querying, generated-surface checks,\nindex validation, claims, public export, and an MCP server.\n\nThe current public site includes exact lookup, ranked repository search,\nfactual profile comparison, relationship lookup, and optional bounded research\nsynthesis. What remains intentionally deferred is production-scale ranking\ncalibration, public mutation APIs, bundle mode, first-class workspace semantics,\nbroad editor automation, and arbitrary prose round-tripping.\n\n## Read next\n\nFor strategy and active execution:\n- [`ROADMAP.md`](ROADMAP.md)\n- [`docs/README.md`](docs/README.md)\n\nIf you are adopting dotrepo in a repository:\n- [`docs/install.md`](docs/install.md)\n- [`docs/maintainer-happy-path.md`](docs/maintainer-happy-path.md)\n- [`docs/sync-boundaries.md`](docs/sync-boundaries.md)\n\nIf you are consuming the hosted public surface or building agent tooling:\n- [`docs/public-export-examples.md`](docs/public-export-examples.md)\n- [`docs/public-surface.md`](docs/public-surface.md)\n- [`docs/ai-tool-interviews.md`](docs/ai-tool-interviews.md)\n- [`rfcs/0006-mcp-server-contract.md`](rfcs/0006-mcp-server-contract.md)\n\nIf you want the protocol and trust model:\n- [`docs/trust-model.md`](docs/trust-model.md)\n- [`rfcs/0001-protocol-and-ecosystem.md`](rfcs/0001-protocol-and-ecosystem.md)\n- [`rfcs/0004-index-and-trust-model.md`](rfcs/0004-index-and-trust-model.md)\n\nIf you want to contribute:\n- [`CONTRIBUTING.md`](CONTRIBUTING.md)\n- [`index/README.md`](index/README.md)\n- [`index/review-checklist.md`](index/review-checklist.md)\n\nRepository Python tooling is managed exclusively with `uv`: run `uv venv`,\n`uv sync --dev --locked`, then invoke scripts and tests through `uv run`.\n",
  "bytes": 13100,
  "sha": "cf1c4420bc85cdbf1c4b49587739034e7a70657a50baba1314b9a885306f88d0",
  "repo_slug": "maxwellsantoro/dotrepo",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_maxwellsantoro_dotrepo_a103c7c4/readme"
}