Valinor - Self-enforcing engineering discipline.

governance.config.yml is the single file that tells Valinor how to govern your repo. valinor init scaffolds one for your profile; you tune it as your repo matures. It declares four things: your repo's nature (profile + stack), how much autonomy a green PR has, how strict the gates run (the adoption dial), and which gates and surfaces apply — plus the GitHub repo settings Valinor gates as code.

Every field is optional unless marked required, and each has a sensible profile-aware default, so a minimal config is just profile and stack. The onboard wizard walks you through the opt-in dials interactively.

Every field at a glance

This inventory is a projection of the source of truth — it is generated directly from the GovernanceConfig schema in src/config/schema.ts, so it lists every top-level field with its type, allowed values, and default, and can never silently fall behind the code. (The site-freshness gate fails the build if this table drifts from the schema.)

Generated — do not hand-edit

The table below is regenerated by npm run gen:config-reference. Edit a field's summary in src/siteGen/configReference.ts (its single authoritative home), not here.

Field	Type	Allowed values	Default	What it does
`adoption`	object	—	`{"maturity":"greenfield","mode":"strict"}`	The strictness/scope dial — how strict the gates are and whether they run whole-tree or new-code only.
`agent-dispatch`	object	—	—	The scheduled agent-dispatch workflow — `{ enabled, model?, cron? }`; `enabled: true` scaffolds a cron'd headless Claude-Code run that ACTS on overdue standing obligations (AUTO-ACT → opens a PR, RECOMMEND → opens an issue; never pushes to main, merges, or escalates to admin). DEFAULT-OFF + opt-in: it requires an `ANTHROPIC_API_KEY` secret and incurs recurring per-run cost, so an absent block (the default) scaffolds nothing.
`api`	object	—	—	The API spec-contract declaration — keeps an OpenAPI/GraphQL/protobuf spec in sync with the implementation; fires only when `enabled: true` (an absent block is a no-op), tool-selected per stack with `UNVERIFIABLE` (never a silent green) when a tool is absent.
`autonomy`	object	—	`{"docs":"hitl","code_merge":"hitl"}`	The merge-automation dial — how much a green PR can land unattended (docs vs code merge).
`compliance`	object	—	—	The universal legal-doc floor this repo's nature requires (privacy-policy · terms-of-service), profile-defaulted — ADVISORY: flags a missing/incomplete legal doc, never certifies legal sufficiency.
`deploy`	object	—	—	The deploy target the scaffolded CI gates a deploy job against — `{ target, environment? }`; `target: none` (or an absent block) omits the deploy job.
`gates`	record	—	`{}`	Per-concern gate config — a boolean on/off shorthand, or an object carrying a `severity` dial and gate-specific keys.
`merge-gate`	object	—	—	The draft-until-green merge gate — holds a PR draft until the pre-review quality gates pass green, then auto-marks it ready (so Greptile reviews a clean, gates-green PR once). `pre-review-checks` overrides the default gate-set (all required checks minus the Greptile + deploy checks); `exclude-checks` extends the default exclusions.
`profile` (required)	enum	`technical-app` · `marketing-site` · `bizdev-proposal` · `library`	—	The repo's nature — selects profile-aware defaults (which surfaces it warrants, which gates apply).
`publish`	object	—	—	The publish leg of the scaffolded release workflow — `{ enabled }`; `enabled: true` wires the per-stack inline publish + post-publish smoke into the release cut (an absent block, the default, omits it — the cut still tags the release). The registry/access are derived from `stack` and documented inline in the generated workflow.
`repo_settings`	object	—	`{}`	GitHub repo settings Valinor gates as code (e.g. merge options), each verifiable or an explicit opt-out.
`stack` (required)	string	—	—	The repo's tech stack (e.g. `nextjs`) — shapes stack-aware checks like `.gitignore` completeness.
`surfaces`	object	—	—	The client-facing web surfaces this repo's nature warrants (help-center · changelog · api-docs), profile-defaulted.
`telemetry`	object	—	—	The strictly-advisory telemetry dial — `{ crash-reporting?, gate-events?, host? }`; both channels default ON but can never alter an exit code (crash reporting is inert until the baked DSN is provisioned; gate events are inert without a `POSTHOG_API_KEY`). The `DO_NOT_TRACK`/`VALINOR_NO_TELEMETRY` env opt-outs override both dials; `host` overrides the PostHog ingestion host (e.g. EU residency).

How the dials compose

A few of these fields are objects with their own nested dials — the ones you reach for most as your repo matures:

adoption.mode — strict blocks on the whole tree from commit one; new-code grandfathers existing findings against a baseline file and blocks only on new code; advisory warns without blocking while you establish the baseline. This is the dial you loosen to adopt Valinor on a legacy repo without drowning in pre-existing findings.
autonomy.code_merge — hitl requires a human review (auto-merge off); auto-staging / auto-main let a green PR land unattended (zero required reviews, auto-merge on). Orthogonal to adoption: one governs strictness, the other governs who lands the PR.
gates.<concern> — a boolean turns a concern's gate on or off; the object form carries a severity dial (error · warn · off) plus gate-specific keys. Integrity-class gates (like release-integrity and claims-verify) are floored to error in code and can't be dialed down.
surfaces — declares which client-facing sites your repo should stand up (help-center · changelog · api-docs). Omit it to take the profile default; set a key false to deliberately mark a surface absent (the api-docs-without-an-API guard).

For the per-concern gate dials and what each gate checks, see the CLI reference and the governance overview.