Skip to content

How this site was verified

Every page on this site makes claims about two Avalonia apps. This page describes how those claims were produced, checked, and how you can re-check them yourself after the code moves.

Source-of-truth order

When sources disagree, this site resolves conflicts in a fixed order:

  1. Code — what is compiled and shipped under src/.
  2. Beads and ADRs — stated intent; what the code should be.
  3. Docs — narrative descriptions under docs/; useful context, lowest authority.
  4. Inference — anything we concluded without a direct statement; always marked INFERENCE on the page where it appears.

The rule is short: code wins. A doc that contradicts the code is a stale doc, not a hidden feature. Two real cases from this site's own build:

Case 1 — tooltip keys that do not exist. An early draft of an interaction page listed tooltip hotkeys T, S, C, and W for viewport toggles. A grep for Key.T, Key.S, Key.C, Key.W across src/SimulatorApp, src/SlicerApp, and src/Nps.Shell returns nothing. The actual hotkey set is implemented in ShellKeybindings.Handle at src/Nps.Shell/Controls/ShellKeybindings.cs:84-110: Key.P (play/pause), Ctrl+Key.L (inspector toggle), Key.Right and Key.Left (playback step). The draft keys were invented; the verifier removed them. HOW IT IS: only the four keys dispatched in ShellKeybindings.cs exist — both apps' OnKeyDown handlers delegate to it and add no keys of their own.

Case 2 — auto-pause marked as a stub. docs/ui-shell-and-viewport.md:103 states: "Auto-pause on findings near the current move is a stub comment only." The code disagrees. src/SimulatorApp/MainWindow.axaml.cs:645-657 contains the working check — playback pauses when advancing within two moves of a pinned finding — wired to the panel at MainWindow.axaml.cs:127 and defaulted on at MainWindow.axaml.cs:136. The Simulator interaction page documents auto-pause as implemented, because it is. The older doc is stale.

Note

Both errors survived a first pass and were caught only because every claim was re-checked against code. This is why the code-wins rule is a rule and not a preference.

Process

The site was built in two waves.

Wave 1 — scouts. Parallel read-only scout agents mapped the UI. Each scout owned one slice of the problem: app structure, element inventories, event wiring, sharing between the two apps, and roadmap signals from beads and ADRs. Scouts produced draft pages with a file:line citation on every factual claim.

Wave 2 — adversarial verifiers. A second wave of agents re-checked every file:line citation against the actual code, reading the cited file at the cited line. False claims were fixed in place; claims that could not be verified were deleted or re-marked as INFERENCE. Both invented-examples above were caught in this wave.

Duplication percentages. The numbers on the duplication audit page come from a block-by-block comparison of the two app entry points: src/SlicerApp/MainWindow.axaml.cs (671 lines) and src/SimulatorApp/MainWindow.axaml.cs (860 lines). Blocks were matched by shape — same method structure, same logic, differing identifiers — not by exact text.

Model routing

Scout and verifier agents ran on kimi-k3. Web research (for the tooling decision page) was done against official sources only: PyPI for package facts, zensical.org for the Zensical documentation, and the squidfunk blog for Material for MkDocs direction. No forum posts, no aggregators.

How to re-verify

The site drifts the moment the code changes. To check a page after a UI change:

1. Dump the current element inventory. The UI-map skill ships a script that lists elements from the AXAML source:

.claude/skills/nps-apps-site/scripts/list-ui-elements.sh

2. Grep the claim. Every element, handler, and hotkey claim on this site resolves to a symbol you can find:

# Does this handler still exist?
rg "OnScrubberChanged" src/SimulatorApp

# Does this hotkey exist?
rg "Key\.P" src/Nps.Shell/Controls/ShellKeybindings.cs

# Is this panel still in the AXAML?
rg "PanelFindings" src/ --glob "*.axaml"

3. Build the site. Zensical catches broken links and syntax errors:

cd docs/guide && zensical build

The refresh rule: any PR that changes UI structure — a panel added or renamed, a handler rewired, a hotkey changed — must refresh the affected page in the same PR. A page whose citations no longer resolve is worse than no page.

Warning

Line numbers are point-in-time. MainWindow.axaml.cs:645 is correct as of the last verification pass; after the next commit it may be off by a few lines. Trust the symbol, not the line number, and re-rg before quoting.

Known limits

  • Duplication percentages are estimates. They come from matching method-shaped clones — blocks with the same structure and logic but different names — not from token-identical diffs. Two reviewers running the same comparison would land within a few points of each other, not on the same number.
  • Line numbers drift. Citations were exact when verified. Code changes shift them; the symbol name is the durable part of every citation.
  • HOW IT SHOULD BE is stated intent, not a promise. Roadmap claims cite beads and ADRs. Beads get re-scoped; ADRs get superseded. A cited bead describes what was decided, not what will ship.
  • INFERENCE is marked, not eliminated. Where the code and docs are both silent, pages say INFERENCE in bold rather than guess silently. Treat those claims as hypotheses until someone confirms them against the engine.

See also