dotrepo AGENTS.md

AGENTS.md

This file provides guidance to coding agents when working with code in this repository.

What This Is

dotrepo is an open metadata protocol for software repositories. It has three interlinked deliverables:

1. A .repo schema — versioned TOML manifests that encode provenance, trust, owners, docs, and build/test metadata
2. A reference toolchain — Rust CLI, stdio MCP server, and LSP for importing, validating, querying, syncing, and generating compatible surfaces
3. A public index — a Git-backed collection of evidence-backed overlays and maintainer authority context at index/repos/<host>/<owner>/<repo>/ that makes public repos mechanically visible whether or not maintainers have adopted dotrepo natively

The public overlay index is generated and refreshed through an autonomous, evidence-constrained conveyor. Deterministic parsers run first; unresolved fields may escalate through progressively stronger model tiers; routine generated records do not wait for human review.

Documentation Authority

• README.md — project overview and shipped capabilities
• ROADMAP.md — strategy, active execution order, and milestone gates
• CHANGELOG.md — release history
• docs/README.md — documentation map
• RFCs — design records and accepted contracts, not live task lists

When documentation conflicts, prefer current code and contracts, then README.md for shipped behavior and ROADMAP.md for direction.

Commands

All Python tooling in this repository uses uv. Create the repository environment with uv venv, then run Python commands, scripts, and tests with uv run. Never invoke python, python3, pip, or pytest directly, and preserve this convention in documentation, automation, subprocesses, and examples.

uv venv                              # Create the repository Python environment
uv sync --dev                       # Install locked Python development dependencies
cargo fmt --all -- --check          # Format check (CI enforced)
cargo test --workspace              # Run all tests
cargo build -p <crate-name>        # Build specific crate
uv run python scripts/check_release_version.py  # Release-version parity

# CLI
cargo run -p dotrepo-cli -- --root <path> validate
cargo run -p dotrepo-cli -- --root <path> query repo.name
cargo run -p dotrepo-cli -- --root <path> import --mode native
cargo run -p dotrepo-cli -- --root <path> generate --check
cargo run -p dotrepo-cli -- --root <path> trust
cargo run -p dotrepo-cli -- --root <path> doctor
cargo run -p dotrepo-cli -- validate-index
cargo run -p dotrepo-cli -- public export --index-root index --out-dir public --generated-at <time> --stale-after <time>

# MCP server (stdio JSON-RPC)
cargo run -p dotrepo-mcp

# LSP server (stdio JSON-RPC)
cargo run -p dotrepo-lsp

# Public export packaging
uv run python scripts/package_public_export.py --input public --output-dir dist

# Autonomous index batch (local, explicit opt-in)
uv run python scripts/run_autonomous_index_batch.py --skip-automation-enabled-check --output-dir /tmp/dotrepo-autonomous-batch

# Canonical public release gate
uv run python scripts/check_release_gate.py --output-root /tmp/dotrepo-release-gate --skip-vsix

# Python tests
uv run pytest