Introduction

Installation

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.

Authenticating to the package registry

@cmbrcreative/valinor is published to GitHub Packages. Your environment needs an .npmrc that authenticates the @cmbrcreative scope against npm.pkg.github.com. In CI, the scaffolded workflow wires this up for you via a short-lived GitHub App token; locally, configure a token with read:packages.

1. Install Valinor

Install it as a dev dependency:

npm i -D @cmbrcreative/valinor

The valinor command is now available via npx valinor (or directly if you add it to a script).

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 valinor init .

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 valinor 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.

3. Run your first gate

Verify your repo satisfies every claim it declares:

npx valinor 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:

npx valinor doctrine-check          # verify the AGENTS.md doctrine block is present + current
npx valinor check-doc-freshness     # scan your docs for dead links, refs, and commands
npx valinor 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

Previous
Getting started
Next
CLI reference