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 project README, 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 vox-secrets as the secret-management SSOT.
Agent instruction architecture - instruction layering model (AGENTS.md, tool overlays, continuation prompts, CI gates).
Coding Agent Instructions - 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.
Documentation Reality Audit Program - doc/code/contract triage backlog, scoring, and vox ci docs-reality-audit.
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.
docs/agents/ — full agent-facing support docs (orchestrator behavior, handoff protocol, editor contracts, time awareness).

I want to…

Quick routing by goal. All links resolve from this directory.

Goal	Start here
Fix a TOESTUB / stub-check CI failure	TOESTUB contributor guide
Fix a `god_object` or `sprawl` violation	TOESTUB contributor guide (god-object rules)
Understand why my code affects model quality	Contribution loop
Add a golden `.vox` example	Examples corpus how-to
Write or update documentation	Documentation governance
Contribute to the compiler / parser	How-To: parser and HIR
Contribute to MENS training pipeline	How-To: Mens native training
Add a CLI command	CLI reference + Command compliance
Work with secrets or credentials	Secrets SSOT
Understand the agentic quality model	Coding agent instructions + Governance (TOESTUB)
Read architecture or research context	Research index

Contributor map

Use these surfaces intentionally:

Need	Start with
Cursor IDE rules and per-glob patterns	`.cursor/rules/`
Secrets, credentials, env parity	AGENTS.md, Secrets SSOT
Agent behavior consistency across long sessions and IDEs	Agent instruction architecture, Continuation prompt engineering
Antigravity-specific overrides	GEMINI.md, Agent instruction architecture
Terminal shell discipline, exec-policy, `vox shell check`	AGENTS.md, CLI reference (`vox shell`), `contracts/terminal/exec-policy.v1.yaml`
CLI or command-surface changes	CLI reference, Command compliance
Documentation updates or new docs	Documentation governance
Telemetry, metrics, privacy boundaries	Telemetry trust SSOT, Telemetry metric contract
Architecture or roadmap context	Where things live, Research index
Contracts and schema-backed behavior	contracts/README.md, related reference pages under `docs/src/reference/`
MCP, HTTP, Populi mesh, SSE, WebSockets	Communication protocols, protocol catalog; research Protocol convergence research 2026
CI, workflow, or policy guardrails	CI runner contract, Dependency policy, Pre-push local CI parity (below), Architectural governance (TOESTUB)
VS Code / Cursor extension, MCP tool calls from the editor, Oratio speech UX	`apps/editor/vox-vscode/README.md`, VS Code ↔ MCP compatibility, Speech capture architecture

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

Default git push hook: vox ci pre-push runs the fast profile (scoped docs + critical guards). Use vox ci pre-push --complete for the full static gate before risky merges; CI still runs the heavy docs-quality sweep. Install once via vox ci install-hooks. See local CI parity for --full, heartbeats, --no-verify policy, and tuning VOX_PREPUSH_BASE.

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.