---
name: radiance-flag-truth-from-pinned-source
description: "Before writing a radiance flag, value, or metric name into a runbook, prove it against the pinned image's source and the engine's own boot ledger — catches invented option names and stale defaults."
---

# Radiance flag truth from the pinned source

Use when a radiance (`codeberg.org/StillDeadcode/radiance`) flag, its admitted values, a resolved
default, or a `/metrics` name is about to go into a vault page, env comment, or arm proposal — or when
a claim about one is being repeated from memory. Docs and old vault pages go stale; the pinned tree and
the boot ledger do not.

## Procedure

1. **Get the tree at the running version, not at master.** Read the pin:
   `grep -E 'FRANK_ARCHON_IMAGE' scripts/frank-archon.env` (digest), then
   `ssh dank@192.168.0.235 'podman images --no-trunc | grep radiance'`.
   `git clone --branch <ver>` (or checkout the tag) into `/tmp/rad-<ver>`. A `--depth 1` clone makes
   every `git log -S` report its own tip — never date a flag's introduction from a shallow clone.
2. **Flag table is the admitted set.** `core/config.cpp` holds the help strings (each option's legal
   names/units live in the value column) and the validator branch refuses anything else at boot, e.g.
   `--checkpoint-policy` → `geometric-backoff | tip-only | keep-all`. `core/rad_core.h` carries the
   struct with the compiled-in defaults. `tests/config_test.cpp` asserts the admitted set — it is the
   fastest oracle for "is `lru` a policy?".
3. **Live argv beats the repo env.** `sudo tr '\0' '\n' < /proc/$(pidof radiance)/cmdline` — proves the
   knob actually reached the engine (an env var typo is invisible from the repo).
4. **Boot ledger is the referee for every resolved number.** The engine prints its own arithmetic:
   `ssh dank@192.168.0.235 'podman logs frank-archon 2>&1 | grep -iE "checkpoint|chunk geometry|pools|arena|stager"'`
   (root unit, but podman storage is dank's — **no sudo**, sudo reads empty root storage). Lines like
   *"checkpoint slots: auto: 20 … geometric-backoff keeps 9 for a 200000-token session at a 2048-token
   interval"* are exact; quote them.
5. **Reproduce the engine's arithmetic to check you understood it.** Reimplement the policy/geometry
   function in a throwaway Python eval (`select()` / `held()` in `core/mem/prefix.cpp`, `plan_chunk` in
   `core/sched/scheduler.cpp`) and confirm the numbers match the ledger line from step 4. Agreement
   means the rule is understood; disagreement means the read is wrong. Delete the scratch after.
6. **Metric names: query the live target, not the guide.** Latency histograms and preemption live under
   the **`vllm:`** compatibility prefix, cadence under **`radiance:`**; preemption is the counter
   `vllm:num_preemptions_total` while `radiance:num_requests_preempted` is an instant gauge. Enumerate
   with `curl -s localhost:7770/metrics | grep '^# HELP'` on Dankserver, or
   Prometheus `/api/v1/label/__name__/values?match[]={job="frank-archon"}`.

## Traps that produced real errors here

- A policy name invented from prose (`--checkpoint-policy floor`) would be a boot refusal; a stale
  resolved default (`auto` = 512) had been copied between pages. Both survived only in the vault.
- `--checkpoint-policy` governs **retention only**; snapshots are written at every interval regardless
  (only `--prefill-span` skips writes). Read the call site (`retain()` in `core/mem/prefix.cpp`), not
  the flag help.
- Guide/`GUIDE.md` inside an image can be newer or older than the binary; `/diagnostics`
  `configuration` and the ledger print the running truth.
- Facts belong to the vault page that owns the endpoint (`serverAppConfigs-docs/LLM/frank-archon.md`) —
  this skill owns the *procedure*, not the numbers.