Contributor hub

This page is the reader-facing entry point for contributor documentation.

If you are evaluating Vox as a language or product, start with the site landing page, the FAQ, and the tutorials. If you are changing this repository, start here.

Start here

• AGENTS.md - required contributor and agent policy entry point, with Clavis as the secret-management SSOT.
• Agent instruction architecture - instruction layering model (AGENTS.md, tool overlays, continuation prompts, CI gates).
• Coding Agents Guide - heuristics and rules for agents, including god object constraints and stale docs guidelines.
• Documentation governance - where docs live, which surface owns what, status vocabulary, and review cadence.
• CI runner contract - canonical vox ci guidance, runner labels, and line-ending policy.
• Doc inventory verifier - machine-readable doc inventory workflow and drift expectations.
• Architectural governance (TOESTUB) - repository governance, organization rules, and quality policy.

Contributor map

Use these surfaces intentionally:

Fast local policy rerun for this lane:

• vox ci policy-smoke runs cargo check -p vox-orchestrator, then command-compliance and the same rust ecosystem parity test used by vox ci rust-ecosystem-policy in one command.

Pre-push: local CI parity

CI on main / PRs is defined in .github/workflows/ci.yml. The job does not rely on a lone cargo check -p vox-cli; it runs cargo clippy --workspace --all-targets, cargo doc --workspace --no-deps (with warnings denied), cargo llvm-cov nextest --workspace, and many vox ci * guards. Before pushing, run a high-signal subset so failures match CI instead of showing up only on the runner.

Suggested commands (from repo root; use full cargo path on Windows agents if PATH is minimal — see AGENTS.md):

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo run -p vox-cli --quiet -- ci ssot-drift

Then run tests for crates you changed (faster than a full workspace test pass):

cargo test -p vox-db --test schema_contract_tests   # example; pick your crates

TOESTUB on changed directories (requires the stub-check feature on vox-cli):

cargo run -p vox-cli --features stub-check --quiet -- stub-check crates/vox-mcp

Use a single positional path per invocation (repeat for each directory). See Architectural governance (TOESTUB).

vox_db::legacy_schema warnings during stub-check: if stderr mentions schema_version chain is not the current baseline, the harness opened the canonical Codex store resolved from your environment (usually the platform default vox.db when VOX_DB_PATH is unset). Fix by either completing Stage 1 in the VoxDB cutover runbook for that file, or — when you do not need to keep data — point VOX_DB_PATH at a fresh scratch .db per the runbook section Contributors / local tooling — fresh canonical DB (connect_default does not use :memory: when env is empty). Do not lower BASELINE_VERSION to silence the log.

Codex + docs SSOT: vox ci check-codex-ssot and vox ci check-docs-ssot are merge-blocking in CI (see .github/workflows/ci.yml). Run check-codex-ssot locally after changing contracts/db/baseline-version-policy.yaml or crates/vox-db/src/schema/manifest.rs. Run check-docs-ssot when you change doc inventories, canonical maps, or migration-facing docs.

Contributor expectations

• Prefer updating the canonical surface instead of copying prose into a second location.
• When code changes alter public behavior, update the corresponding docs in the same PR.
• Treat contracts/ as machine SSOT, docs/src/reference/ as human lookup, docs/src/architecture/ as design and rationale, and docs/agents/ as contributor and automation support.
• Use vox ci guards where they exist instead of replacing them with one-off shell checks.