Valinor - Self-enforcing engineering discipline.

This guide walks you through adopting Valinor on a repository — installing it, scaffolding the gates, and verifying your repo against the quality bar it declares.

Prerequisites

Before you start, make sure you have:

Node 24 or newer. Valinor is ESM TypeScript and requires Node 24+.
npm, bundled with Node.
A repository to govern, with access to install from Camber's package registry.
The Valinor GitHub App installed on the repo's org, with packages: read (it authenticates the registry pull in CI).
A Greptile account + the Greptile App, with the repo connected in Greptile's dashboard — the LLM-review rubrics only run once it's connected.
VALINOR_APP_ID (Actions variable) + VALINOR_APP_PRIVATE_KEY (Actions secret) provisioned at the org level.

Valinor is Camber-internal today

The App, Greptile account, and @cmbrcreative/valinor registry are already provisioned inside Camber's GitHub org (cmbrcreative), so for a Camber maintainer the items above are "confirm," not "set up." The full setup contract — what each item is, and the CI-workflow mechanics — is on the Prerequisites page.

Authenticating to the package registry locally

valinor init configures registry auth automatically. If you hit a 401 or 403, see Package registry errors in Prerequisites.

1. Run Valinor via npx — no install step

For every repo, whatever its stack — Node, Rails, Python, Swift, Kotlin, PHP — run Valinor via npx with the full package name and a version. There is nothing to install into your repo:

npx --yes @cmbrcreative/valinor@latest init .

Run every subsequent command the same way, and pin the version your repo standardizes on where reproducibility matters (the scaffolded CI workflows already pin @^X.Y.Z).

Use the full package name, and configure ~/.npmrc first

The short form npx valinor … only resolves from a local node_modules — without one it fails with could not determine executable to run. And npx has to resolve the package from the private registry before init ever runs, so your ~/.npmrc must map the @cmbrcreative scope before the first npx run — set it up once per machine via Package registry errors. Node 24+ is required on the machine running the CLI.

Advanced: npm i -D only if ALL your surfaces have registry auth

A package.json dependency on @cmbrcreative/valinor makes every surface that installs your dependencies need private-registry auth — your other CI jobs' npm ci and your deploy builds (e.g. Vercel) fail with a 401 because those surfaces carry no token. Add it as a dev dependency only when every CI and deploy surface is auth-configured; you then also get the short npx valinor form. CI never needs this: the scaffolded workflows authenticate with a workflow-minted Valinor-App token.

2. Adopt the doctrine and scaffold the gates

Run init from your repo root. It propagates Valinor's versioned canonical doctrine into your AGENTS.md ≡ CLAUDE.md and scaffolds the minimum to run the gates:

npx --yes @cmbrcreative/valinor@latest init .

It detects your repo's stack and default branch (from origin/HEAD — a master-default repo's workflows trigger on master) and prints what it detected.

This writes (only where absent — it never clobbers existing files):

governance.config.yml — your adoption profile, maturity, and per-gate severity dials.
claims.yml — a starter claims registry (the doctrine-block claim plus a presence baseline).
README.md — a starter README, if you don't have one.
.greptile/config.json — the canonical Greptile review-rubric rules (the same rubric Valinor runs on itself).
.github/workflows/valinor-gates.yml — a CI workflow that runs each gate.

Want to see the plan first? Add --dry-run to print what would happen without writing anything:

npx --yes @cmbrcreative/valinor@latest init . --dry-run

You can also set your adoption profile up front with flags — --profile, --maturity, --mode, and --stack. See the CLI reference for the full list.

Adopting a whole folder of repos? Use `init-workspace`

If your project is a non-git parent directory holding several related repos (an app, a backend, a marketing site under one client folder), run init-workspace on the parent instead of init on each repo:

npx @cmbrcreative/valinor@latest init-workspace .

It discovers every git checkout beneath the folder (deduping duplicate clones and linked worktrees with visible skip rows), writes the authoritative valinor-workspace.yml manifest plus lean workspace-level AGENTS.md ≡ CLAUDE.md (the doctrine block and a generated table of the governed repos), and runs the standard init in every governed repo — the same flags pass through, and --dry-run previews everything (a dry rediscovery reports what it would add; nothing is written). Afterwards, valinor doctrine-check-all and valinor audit-all sweep every governed repo with one row per repo and an honest non-zero exit when any repo fails or is not yet initialized — and you can run them from the workspace root or any directory beneath it (they walk up to the nearest valinor-workspace.yml). See the CLI reference for the full flag set.

Two expectations worth knowing up front:

The discovery boundary. The scan never enters dot-directories (.claude/, .worktrees/, …) or follows symlinked directories, and skips node_modules/vendor — so a checkout living under a dot-directory (for example an agent harness's worktree) is invisible to discovery by design. Govern the primary checkout instead.
audit-all starts all-red — that's expected. A freshly-inited workspace reports every repo no-grade: init-workspace scaffolds governance but records no audit grade. Each repo earns its row by running the audit flow once (valinor audit, then valinor audit-record after the graded run) — the sweep then turns green repo by repo.

3. Run your first gate

Verify your repo satisfies every claim it declares:

npx --yes @cmbrcreative/valinor@latest claims-verify

A passing run prints one ✓ line per claim and ends with claims-verify: N claims true. If a claim has drifted, the run exits non-zero and prints a ✗ <id> line naming exactly what was expected — fix the repo (or update the claim, if the claim itself is now wrong) and re-run.

You can run the other local checks the same way (each via npx --yes @cmbrcreative/valinor@latest …):

npx --yes @cmbrcreative/valinor@latest doctrine-check          # verify the AGENTS.md doctrine block is present + current
npx --yes @cmbrcreative/valinor@latest check-doc-freshness     # scan your docs for dead links, refs, and commands
npx --yes @cmbrcreative/valinor@latest branch-protection-check # diff branch-protection.json against the live GitHub ruleset

GitHub checks need a token

branch-protection-check and repo-settings-check call the GitHub API and read GITHUB_TOKEN from the environment. The built-in Actions token covers most reads; a couple of admin-only fields need a broader token. See the token tiers in the CLI reference.

4. Wire it into CI

The simplest CI adoption is the scaffolded valinor-gates workflow that init writes for you — it runs the deterministic gate suite on every pull request. Commit the scaffolded files, push, and open a PR to see the gates run.

Adopting Valinor on an existing repository with pre-existing debt? Valinor ships two adoption dials — a baseline (grandfather current findings, block only on new) and per-gate severity (error / warn / off) — so the gates don't red-CI your repo on day one. The Valinor repository's developer guide covers the legacy-adoption path in depth.

Next steps

Look up any command in the CLI reference.
Understand the layers in the Governance overview.
Hit a snag? See FAQ & troubleshooting.