docs: document the settings that only existed in source

[AKogut]

Closing the two threads the audit left open, rather than letting "everything is fixed" stand on three findings when I had stopped short on two others.

Thread one: dead code — clean

The sweep I abandoned as inconclusive, done properly at module level. Five files nothing imports: the CLI binary, a type declaration, and three Next route handlers. All entry points. No dead modules.

Thread two: undocumented settings — eight

Everything below works today and was discoverable only by reading source.

The AI block is the one that matters. The configuration reference documented ai.rca and ai.dailyTokenBudget — how to switch root-cause analysis on, and how to bound its spend — and never mentioned the provider, the key, the model or the endpoint. Those live only in docker-compose.yml, the Helm templates and .env.example.

So an operator reading the reference to enable AI RCA sets FLAKEMETRY_AI_RCA=true, gets a feature that stays silent, and has nothing to tell them why: the worker has no provider to ask. The reference now has its own section saying exactly that.

Also written down for the first time:

FLAKEMETRY_QUEUE_VISIBILITY_MS	with the warning that setting it below the slowest job causes the same run to be processed twice
FLAKEMETRY_COMMIT_SHA / _BRANCH	for CI that detection does not recognise — a run without a commit lands on 0000000, where every such run looks like the same commit to the scorer, which is the strongest flakiness signal there is
FLAKEMETRY_SHARD_INDEX / _TOTAL	for sharding schemes detection does not recognise

The guard

apps/api/src/__tests__/env-documented.test.ts walks the source for FLAKEMETRY_ variables and fails when one appears in neither the configuration reference nor an action definition.

Three are excluded by name with a reason each — the token and endpoint are the credential and the URL rather than knobs, and FLAKEMETRY_SEED_FORCE is internal to a seed whose documented interface is pnpm demo. Silence should be chosen, not fall out.

Proved non-vacuous by removing one entry from the reference and watching it fail:

× finds each one in the documentation or an action definition
+   "FLAKEMETRY_QUEUE_VISIBILITY_MS",

It lives in apps/api beside api-surface.test.ts — the same genre of check — because packages/contracts deliberately has no @types/node and adding it to host a filesystem walk would spoil a package that is pure schemas.

62/62 turbo tasks.