command-center/agent/managed-skills/radiance-flag-truth-from-pinned-source/SKILL.md

name, description

name	description
radiance-flag-truth-from-pinned-source	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.