# CodeVetter docs

> The local-first knowledge system for the CodeVetter repository.

Canonical: https://codevetter.com/docs/

This is the canonical knowledge system for the CodeVetter repository. The
committed Markdown here is the source of truth; [Blume](https://useblume.dev/)
is only the presentation and search layer.

- **Short current view**: [`STATUS.md`](https://github.com/Codevetter/codevetter/blob/main/STATUS.md)
- **Deep timeline + feature log**: [`PROJECT_STATUS.md`](https://github.com/Codevetter/codevetter/blob/main/PROJECT_STATUS.md)
- **Agent bootloader**: [`AGENTS.md`](https://github.com/Codevetter/codevetter/blob/main/AGENTS.md)
- **Product readme**: [`README.md`](https://github.com/Codevetter/codevetter/blob/main/README.md)

## Product

- [overview.md](https://codevetter.com/docs/product/overview/) — what CodeVetter is, durable scope, capability matrix, strategy.
- [capabilities.md](https://codevetter.com/docs/product/capabilities/) — UI, CLI, MCP, underlying-tool, and future-capability glossary.
- [mcp-setup.md](https://codevetter.com/docs/product/mcp-setup/) — verified CLI installation and repository-scoped MCP onboarding.
- [surfaces.md](https://codevetter.com/docs/product/surfaces/) — nav tabs, URL-only routes, removed surfaces.
- [synthetic-user-qa.md](https://codevetter.com/docs/product/synthetic-user-qa/) — runtime proof layer for agent-written code.
- [trex-change-preview.md](https://codevetter.com/docs/product/trex-change-preview/) — exact PR or commit-range verification against an existing preview.

## Architecture

- **Start here:** [how-it-works.md](https://codevetter.com/docs/architecture/how-it-works/) — end-to-end pedagogical overview of the whole system (components, review flow, key decisions).
- [overview.md](https://codevetter.com/docs/architecture/overview/) — layers, critical invariants, what was removed.
- [ipc-and-commands.md](https://codevetter.com/docs/architecture/ipc-and-commands/) — the IPC bridge and command map.
- [data-model.md](https://codevetter.com/docs/architecture/data-model/) — SQLite tables and persistence boundaries.
- [review-pipeline.md](https://codevetter.com/docs/architecture/review-pipeline/) — review → fix → re-review → proof.
- [graph-and-history.md](https://codevetter.com/docs/architecture/graph-and-history/) — canonical structural graph + release history workbench.
- [repo-unpacked.md](https://codevetter.com/docs/architecture/repo-unpacked/) — evidence-backed repo briefs.
- [mcp-sidecar.md](https://codevetter.com/docs/architecture/mcp-sidecar/) — opt-in local MCP server.
- [trex-mcp-projection.md](https://codevetter.com/docs/architecture/trex-mcp-projection/) — future
  agent-triggered verification boundary without weakening the read-only MCP.
- [history-evidence-import.md](https://codevetter.com/docs/architecture/history-evidence-import/) — importing provider-side outcomes.
- [verification-workbench.md](https://codevetter.com/docs/architecture/verification-workbench/) — additive evidence identities, retention, managed-run, intent, and performance records.
- [native-migration-matrix.md](https://codevetter.com/docs/architecture/native-migration-matrix/) —
  no-regression map and release gates for the sole native macOS app.
- [native-rust-boundary.md](https://codevetter.com/docs/architecture/native-rust-boundary/) — measured
  hybrid ownership split between in-process reads and supervised execution.

### Decisions

- [mcp-sdk.md](https://codevetter.com/docs/architecture/decisions/mcp-sdk/) — chose `rmcp` 2.2.0 for the MCP sidecar.
- [oss-integration.md](https://codevetter.com/docs/architecture/decisions/oss-integration/) — OSS integration evaluation.
- [structural-graph-contract.md](https://codevetter.com/docs/architecture/decisions/structural-graph-contract/) — first-party code-graph capability and release contract.

## Development

- [setup.md](https://codevetter.com/docs/development/setup/) — prerequisites, install, run.
- [testing.md](https://codevetter.com/docs/development/testing/) — native, Rust, CLI/MCP, package, and code-health gates.
- [performance.md](https://codevetter.com/docs/development/performance/) — native, Rust, MCP, and exact-package performance gates.
- [native-macos.md](https://codevetter.com/docs/development/native-macos/) — native Evidence Workbench
  toolchain, ownership, and qualification boundaries.
- [benchmark.md](https://codevetter.com/docs/development/benchmark/) — catch-rate benchmark.
- [agent-task-corpus.md](https://codevetter.com/docs/development/agent-task-corpus/) — immutable
  coding-agent task packages and fail-closed readiness.
- [verification-receipts.md](https://codevetter.com/docs/development/verification-receipts/) — ingest
  project-runner evidence, compare regressions, and explain test blast radius.
- [configuration.md](https://codevetter.com/docs/development/configuration/) — native identity, settings, data, and updater configuration.
- [docs.md](https://codevetter.com/docs/development/docs/) — how to write, validate, and render docs.

## Operations

- [automation-contract.md](https://codevetter.com/docs/operations/automation-contract/) — privacy-safe product, release, reliability, and Foundry evidence contracts.
- [release-pipeline.md](https://codevetter.com/docs/operations/release-pipeline/) — desktop release chain.
- [signing-and-updates.md](https://codevetter.com/docs/operations/signing-and-updates/) — Developer ID signing, notarization, and Sparkle auto-update inputs.
- [landing-deploy.md](https://codevetter.com/docs/operations/landing-deploy/) — Cloudflare Pages deploy.
- [ci.md](https://codevetter.com/docs/operations/ci/) — CI workflow and order.

### Jobs

- [weekly-quality.md](https://codevetter.com/docs/operations/jobs/weekly-quality/) — Monday cron canary.

### Runbooks

- [cut-a-release.md](https://codevetter.com/docs/operations/runbooks/cut-a-release/) — ship a new desktop version.
- [deploy-landing.md](https://codevetter.com/docs/operations/runbooks/deploy-landing/) — deploy the Astro site.

## Knowledge

- [failed-approaches.md](https://codevetter.com/docs/knowledge/failed-approaches/) — things that broke and the constraints they left.
- [competitive-landscape.md](https://codevetter.com/docs/knowledge/competitive-landscape/) — AI code review competitive landscape.
- [performance-lab-publication.md](https://codevetter.com/docs/knowledge/performance-lab-publication/) —
  published optimization experiments, external PRs, and evidence boundaries.
- [tooling-decisions.md](https://codevetter.com/docs/knowledge/tooling-decisions/) — what CodeVetter
  embeds instead of building, what it refuses, and why. Hub for the five
  evaluations below.
- [tooling-secrets-and-supply-chain.md](https://codevetter.com/docs/knowledge/tooling-secrets-and-supply-chain/)
  — secret scanners and dependency/vulnerability scanners.
- [tooling-coverage.md](https://codevetter.com/docs/knowledge/tooling-coverage/) — coverage collection
  across Rust/TS/Python, the LCOV transport decision, diff-coverage traps.
- [tooling-agent-benchmarks.md](https://codevetter.com/docs/knowledge/tooling-agent-benchmarks/) —
  public agent benchmark corpora, graded on determinism and licensing.
- [tooling-documentation.md](https://codevetter.com/docs/knowledge/tooling-documentation/) — the
  DeepWiki reject and what would fit instead.
- [tooling-sandboxing.md](https://codevetter.com/docs/knowledge/tooling-sandboxing/) — isolation for
  running untrusted agent code, determinism controls, SARIF analyzers.
- [codebase-context-tools-landscape.md](https://codevetter.com/docs/knowledge/codebase-context-tools-landscape/)
  — April 2026 survey of codebase indexing and context tooling.

### Learnings

- [README.md](https://codevetter.com/docs/knowledge/learnings/README/) — learning roadmap and coverage map.
- [new-things.md](https://codevetter.com/docs/knowledge/learnings/new-things/) — platform + stack concepts.
- [telemetry-and-indexing.md](https://codevetter.com/docs/knowledge/learnings/telemetry-and-indexing/) — the usage pipeline.
- [verification-and-judgment.md](https://codevetter.com/docs/knowledge/learnings/verification-and-judgment/) — the verification stack.

## Archive

Superseded docs kept for git history. **Do not treat as current.** These are
excluded from the rendered Blume site (see `blume.config.ts`), so the links
below point at the files in the repo on GitHub.

- [DECISIONS.md](https://github.com/Codevetter/codevetter/blob/main/docs/archive/DECISIONS.md) — older decision log.
- [LESSONS.md](https://github.com/Codevetter/codevetter/blob/main/docs/archive/LESSONS.md) — older lessons.
- [PRD-*.md](https://github.com/Codevetter/codevetter/tree/main/docs/archive) — scoped PRDs for shipped slices.
- [stale-competitive-landscape-2026-03.md](https://github.com/Codevetter/codevetter/blob/main/docs/archive/stale-competitive-landscape-2026-03.md) — full March competitor survey + April OSS GTM plan.
- [stale-architecture-2026-04.md](https://github.com/Codevetter/codevetter/blob/main/docs/archive/stale-architecture-2026-04.md) — pre-desloppification architecture (removed `packages/`/`workers/`).
- [stale-development-2026-04.md](https://github.com/Codevetter/codevetter/blob/main/docs/archive/stale-development-2026-04.md)
- [stale-configuration-2026-04.md](https://github.com/Codevetter/codevetter/blob/main/docs/archive/stale-configuration-2026-04.md)
- [stale-testing-2026-04.md](https://github.com/Codevetter/codevetter/blob/main/docs/archive/stale-testing-2026-04.md)
- [stale-performance-harness-2026-09.md](https://github.com/Codevetter/codevetter/blob/main/docs/archive/stale-performance-harness-2026-09.md) — retired React/Tauri performance harness and historical measurements.
- [stale-native-agent-island-2026-09.md](https://github.com/Codevetter/codevetter/blob/main/docs/archive/stale-native-agent-island-2026-09.md) — retired helper prototype; any future status island is a side quest.
- [stale-repo-unpacked-2026-09.md](https://github.com/Codevetter/codevetter/blob/main/docs/archive/stale-repo-unpacked-2026-09.md) — retired React/Tauri implementation notes.
- [planning-codebase/](https://github.com/Codevetter/codevetter/tree/main/docs/archive/planning-codebase) — pre-desloppification `.planning/codebase/` docs.

## Open questions

Tracked in [`STATUS.md`](https://github.com/Codevetter/codevetter/blob/main/STATUS.md) under "Unresolved questions".
Do not invent answers in docs; mark gaps explicitly.

## Agent workflows

- [Agent workflow skills](https://codevetter.com/docs/development/agent-skills/) — review, testing, performance and value evaluation.
