Help

FAQ & troubleshooting

Answers to the questions people ask most when adopting Valinor, and fixes for the errors you're most likely to see. Every error entry below is a real, deliberate behavior of the tool — Valinor fails closed and tells you exactly what's wrong.

Frequently asked questions

What is Valinor, in one sentence?

A CI-native quality-governance product: you declare the quality bar your repository must meet — verifiable claims, branch-protection rules, an LLM-review rubric suite, and a whole-repo audit — and Valinor enforces that bar in CI, deterministically and fail-closed.

Is Valinor publicly available?

Not yet. Valinor is a Camber-internal product today — the Valinor GitHub App, the Greptile account, and the @cmbrcreative/valinor package are provisioned inside Camber's GitHub org (cmbrcreative). The Prerequisites page lists exactly what an org needs provisioned to run the gates, written so a future external adopter can see what they'd set up.

Which languages and stacks does it work with?

The doctrine, claims registry, GitHub config-as-code, documentation gates, and rubric reviews are stack-agnostic — they govern any repository. A few gates are JS/TS-specific (for example, the empty-catch lint) and ship as advisory no-ops on other stacks — they report only where your stack gives them something to scan, so a non-JS repo is never flagged. See Supported platforms for the per-language, per-ecosystem, and per-deploy-target support status.

Do I need to send my code anywhere?

No. The deterministic checks (file / grep / token / files-identical claims and the documentation gates) run entirely offline. Only the GitHub configuration checks call the GitHub API, and the optional LLM rubric review runs through Greptile on your pull requests — which requires Greptile connected (a Greptile account, the App, and the repo dashboard-connected; see Prerequisites). Without it, the deterministic gates still run; only the review rubrics go un-evaluated.

Will adopting Valinor break my existing repo's CI on day one?

No, if you use the adoption dials. A baseline grandfathers your current findings so gates block only on new debt, and per-gate severity (error / warn / off) lets you soften a noisy gate while you drain it. Start in advisory or new-code mode and ratchet up.

Is valinor init safe to re-run?

Yes. It re-inlines the current doctrine in place and writes scaffold files only where they're absent, so re-running to pull a doctrine update never clobbers your custom claims.yml, governance.config.yml, or .greptile rules.

How do I update to a new version of Valinor?

There is no dependency to bump — the consumer path is npx-only, and npx --yes @cmbrcreative/valinor@latest init . always resolves the newest published version (re-run it to pull any doctrine update). If you pinned a version in your own scripts, bump the pin. Because the audit skills are bundled in the package version-locked, upgrading Valinor upgrades your audit skills too — no per-repo drift.

Do I need a package.json to adopt Valinor?

No. The consumer path is the same for every repo (Rails, Python, Swift, Kotlin, PHP, Node, …): run every command via npx with the full package name — npx --yes @cmbrcreative/valinor@latest init . — with no install step. Node 24+ must be on the machine running the CLI, and ~/.npmrc must map the @cmbrcreative scope first (see Package registry errors). Avoid adding @cmbrcreative/valinor to your package.json unless every CI and deploy surface that runs npm ci has private-registry auth — a dependency on the private registry 401-breaks the ones that don't (see Installation).

Troubleshooting

Package registry 401/403 errors {#package-registry-errors}

If an npx --yes @cmbrcreative/valinor run (or an advanced-path npm install) fails with a 401 or 403 from npm.pkg.github.com, the @cmbrcreative scope-to-registry mapping or its authentication token is missing from your ~/.npmrc. On a fresh machine this is the expected starting state; it can also happen when init's auth pre-flight couldn't complete (for example, gh wasn't installed at the time).

Add the following to your global ~/.npmrc (create it if it doesn't exist):

@cmbrcreative:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=<your-gh-token>

Get the token:

gh auth login -h github.com -s read:packages

Why not gh auth refresh? gh auth refresh -s read:packages looks like it should add the scope, but it silently fails to apply read:packages in most configurations. Always use gh auth login when you need this scope.

Once logged in, run gh auth token to get the gho_… value and paste it as <your-gh-token> in ~/.npmrc, then re-run the failed command.

This setup is a true prerequisite, not a fallback: the npx --yes @cmbrcreative/valinor@latest form has to resolve the package from GitHub Packages before valinor init (and its auth pre-flight) can ever run.

npx valinor fails with "could not determine executable to run"

npm error could not determine executable to run

The short form npx valinor … resolves the binary from a local install — it only works in a repo where @cmbrcreative/valinor is already in node_modules (the advanced dev-dependency path). On any other repo — the normal case — use the full package name:

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

Every command works the same way (npx --yes @cmbrcreative/valinor@latest claims-verify, …).

A gate prints "dist/ not built"

check-…: dist/ not built — run `npm run build` first

This appears when running Valinor's gate scripts from a source checkout before building. When you use the published package via npx valinor …, the build is already done — this message is only relevant to contributors working inside the Valinor repository.

claims-verify exits non-zero ("N/M drifted")

A claim no longer holds. Each failing claim prints a ✗ <id> — <detail> line naming what was expected. Open claims.yml, find the claim by id, and either fix the repo so the claim is true again (the usual case — a claim is a spec) or, if the claim itself is now wrong, update it. claims-verify fails closed: any drift is a non-zero exit.

repo-settings-check reports ⚠ UNVERIFIABLE

⚠ allow_auto_merge: UNVERIFIABLE — the current token cannot read this field.

Two repo merge-setting booleans (allow_auto_merge, delete_branch_on_merge) are only readable by a classic repo-scoped token; the built-in Actions token returns them as null. The check fails closed rather than reporting a phantom drift. To resolve, either provide a token tier that can read the field (see the CLI reference) or set verify: false on that field in governance.config.yml (with a reason) to stop gating it.

A GitHub command fails to read the ruleset or settings

branch-protection-check, branch-protection-sync, repo-settings-check, and repo-settings-sync call the GitHub API and read GITHUB_TOKEN plus GITHUB_REPOSITORY (owner/repo) from the environment. A read failure exits non-zero with the underlying error. Confirm GITHUB_TOKEN is set with sufficient scope and that GITHUB_REPOSITORY is present (Actions sets it automatically; set it yourself when running locally).

valinor baseline refuses to write

⚠ baseline would grow … refusing to write — fix the new finding(s) first

When a committed baseline already exists, baseline refuses to regenerate if doing so would inflate any finding count — otherwise it would be a one-command bypass of the block-on-new guarantee. Fix the new findings instead. To deliberately re-snapshot from scratch, delete the committed baseline first, then re-run.

check-doc-freshness flags dead internal links, dead config references, and dead valinor / npm run command references; check-docs-coverage flags orphan docs (no governing manifest entry) and stub docs (near-empty placeholders). The error names the offending path — fix the reference, govern the doc, or remove it.

Still stuck?

Previous
Supported platforms