Docs › site-design-v2

Site design v2 — what this site is working towards

Written 2026-08-11 in answer to the operator’s review: the structure is fair but the site is accreting around daily workflow instead of being designed toward a purpose; metrics jumble configs together; prose goes stale as the field grows; personal/household items leaked into public pages. This doc states the destination first, then derives structure, then lists the small set of decisions that are genuinely taste.

1. North star

The reference lab for local AI on Strix Halo-class hardware: what to run, how to configure it, and what it truly costs — every number wall-measured, provenance-graded, and corrected in public.

The audiences, in priority order:

  1. Practitioners on this hardware class (the r/StrixHalo, r/LocalLLaMA reader with a 128 GB unified-memory box) deciding what to run and how.
  2. Upstream developers (llama.cpp, model vendors) who need a citable, methodical result — our KV-dequant and BF16 threads already live in that conversation.
  3. Ourselves, later — the lab’s own memory, which is why evidence must stay primary.

What we publish that nobody else does, which is the entire brand: wall-socket energy per useful result; time-to-correct and turns as first-class metrics; provenance and confidence on every number; retractions kept visible with the reasoning that fixed them.

Out of scope, permanently: personal task lists, household infrastructure, anything about the humans rather than the lab. The site describes the lab, not the week.

2. The four surfaces

ANSWERS — the authority layer, organised by the question a visitor arrives with.

  • /models/<id> — one page per model (template in §3).
  • /compare — the field table: every benched model’s best-config numbers side by side, sortable. The single most-linked page, eventually.
  • /questions/<slug> — short, self-contained answers to the questions people actually search (“Does KV quantisation cost quality?”, “Vulkan or ROCm on Strix Halo?”, “Is thinking mode worth it?”). Each is a 300-word synthesis over claim links — cheap to write once the claims exist, and they capture search traffic the raw records never will.

EVIDENCE — claims, runs, configs, energy, candidates, incidents: what exists today, kept citable and anchored. Unchanged except presentation polish.

METHOD — protocol, methodology-lessons, the essays. This is the trust layer; it gets a front-door link, not a buried listing. Retractions and the correction machinery are featured here, because they are the credibility argument.

LOG — the public lab notebook: dated, impersonal entries derived from the record (claims landed, gates changed, series started/finished). Replaces the public half of the Now page. The private half — the actual work queue, who’s waiting on what — moves to an unrendered WORKQUEUE.md in the repo: same information for us, invisible to the site.

3. The model page template (fixes the config jumble and staleness)

Ordering principle: a model page leads with its best configuration, fully specified; every other configuration is a delta against it. No interleaving, no footnote hunts.

  1. Header — identity: params, arch, licence, quants held, gate status badge, dates.
  2. Verdict — 5-8 authored sentences. Editorial rules that prevent staleness: self-contained absolutes only — no field-relative phrasing (“the fastest of the five”), no counts of other models, no “currently”. A verdict may cite claims and dated facts; if the field growing would falsify a sentence, the sentence is wrong.
  3. Best configuration — the recommended flags block (engine, build hash, quant, KV, FA, thinking, speculation), then ITS metric card: decode/prefill at standard depths, agentic score + median turns-to-correct, Wh and pence per correct answer, guard 4/4. Generated from the records at build time — the config ref joins to its runs and energy records; no hand-typed numbers anywhere in this section.
  4. Other configurations tested — one row per config variant, each showing its delta vs best (decode Δ, turns Δ, Wh Δ) and a one-line note. Also generated. A reader who wants “what does q8 KV cost on this model” finds one row, not five footnotes.
  5. Open questions — maintained per-model list, honest and short.
  6. Provenance footer — build hashes, meter, dates, links to every underlying record. Generated.

Staleness is solved structurally: numbers regenerate from the record on every build; only §2 and §5 are authored, and §2’s editorial rules make it durable by construction.

4. Dynamic vs static: decided

Fully static, data-driven. Astro generates every Answers page from the YAML collections at build time — the record is the CMS. No server, no database, no client framework. Two deliberate exceptions:

  • The /compare table gets a small progressive-enhancement script for sort/filter (works without it; enhances with it).
  • Charts are build-time SVG rendered from run data — throughput-vs-depth curves, Wh-per-correct bars — consistent axes and palette, no chart library shipped to the client.

The site updates when the record updates, which is the correct coupling: a page can never disagree with the data because it is the data, rendered.

5. Visual language (the actual taste decisions)

Recommendation, as one coherent package rather than a menu:

  • Dark-first lab aesthetic with a light mode; near-black surface, high-contrast text, a single restrained accent (suggest the oscilloscope green/amber family) used ONLY for data emphasis and links — never decoration.
  • Type: a clean sans for prose (self-hosted; Inter or system stack) and a monospace for every number, flag and identifier (JetBrains Mono) — tabular numerals so columns align. The mono-for-data habit alone will kill most of the “jumble” feel.
  • Badges as the signature component: provenance (measured-here / community / vendor-claim), confidence, gate state, guard state — colour-coded, identical everywhere. Provenance-as-UI is our differentiator made visible.
  • Layout: persistent left nav (Models · Compare · Questions · Evidence · Method · Log), 72ch prose measure, data tables allowed full width. No hero images, no marketing furniture.

6. Migration plan

  1. Scope pass (done 2026-08-11): personal/household content removed from public pages; work queue heading out of the rendered site.
  2. Data plumbing: config→runs→energy joins as build-time utilities; the metric card and config-delta table as components; field table for /compare.
  3. One model page rebuilt to this template (the 122B) + the visual language applied site-wide (tokens: colours, type, badges). The operator reviews the sample.
  4. Remaining model pages generate; /compare ships; Log replaces public-Now.
  5. First three /questions/ pages (KV quality; Vulkan-vs-ROCm; thinking) distilled from existing claims; essays linked from Method.
  6. Charts pass.

Each phase ships independently; the record and current pages stay live throughout.

7. Editorial rules (additions to the existing plan)

  • The plain-language lede is mandatory on every essay and question page: three headlines — Problem / Claim / Conclusion — worded so a non-specialist takes the point in thirty seconds, before any jargon. The conclusion carries the real numbers, linked to claims. (The operator’s pattern, 2026-08-11; the KV essay is the reference example.)

  • First use of a term of art in any Answers-layer page gets a plain gloss in-line.

  • No person’s name appears on a public page. Attribution is “the lab”.

  • No content about infrastructure that isn’t the measurement programme.

  • Prose must be self-contained: no field-relative counts, no “currently”, no “recent”. Dates are absolute; comparisons name their subjects.

  • A number outside a generated component is a bug.