Quarto site navigation restructure — landing-page rebuild + navbar consolidation + sidebar hub-spoke nesting (narrow supersession of ADR-053 navigation contract)

Published

May 19, 2026

Superseded on one or more axes by ADR-062. The body below retains its original prose per the ADR-073 immutability rule; the corrected position lives in the superseding ADR. See the Decisions index to navigate.

ADR-061 — Quarto site navigation restructure (narrow supersession of ADR-053 navigation contract)

Status

Accepted (2026-05-19; lands in v1.1.1 patch release alongside the landing-page rebuild + hub-spoke signposting + README clarification).

Context

ADR-053 locked the v1.0.4 reading-guide architecture across 5 dimensions:

Navbar/sidebar architecture — 3 entry artifacts (EXECUTIVE_SUMMARY
- index.qmd + RESULTS) + Methodology section with hub + 8 spokes + separate Notebooks/Evidence/Reference/Decisions sections.
3-reading-paths (A1 quick-skim / A2 audit / A3 reproduce).
Headline-finding-block required on the landing page.
Interpretation pedagogy (5 patterns required on the landing page).
Pointer convention (markdown links to deep content; no PDF).

User feedback 2026-05-19 surfaced a real discoverability issue at dimension 1. The 9-item navbar fragments the entry points; “Methodology (TOC)” + “Spokes” peer items confuse the hub-spoke relationship; index.qmd is too dense (137 lines covering results + 5 interpretations + 3 reading paths + headline ADRs + repo map + submission anchors + status). The 5-pattern interpretation pedagogy is technically prose-heavy and not “plain language” by user expectation.

Dimensions 2-5 of ADR-053 are unchanged. Dimension 1 needs revision.

Decision

Narrow supersession of ADR-053 dimension 1 (navbar/sidebar/landing-page architecture). All other dimensions of ADR-053 preserved.

Subsection A — Navbar simplification (9 items → 5)

_quarto.yml navbar:left changes:

# OLD (9 items): EXECUTIVE_SUMMARY / index.qmd / RESULTS / WRITEUP.md /
# Spokes dropdown / Notebooks dropdown / EVIDENCE.md / Reference dropdown
# / Decisions dropdown.

# NEW (5 items):
navbar:
  left:
    - href: RESULTS.md
      text: Results
    - text: Methodology
      menu:
        - text: "Cover narrative (hub)"
          href: WRITEUP.md
        - text: "Reading guide"
          href: READING_GUIDE.md
        - href: WRITEUP/data-decisions.md
        - href: WRITEUP/model-rungs.md
        - href: WRITEUP/eval-design.md
        - href: WRITEUP/threshold-policy.md
        - href: WRITEUP/reference-scorer-audit.md
        - href: WRITEUP/methodology-guarantees.md
        - href: WRITEUP/limitations-and-future-work.md
        - href: WRITEUP/reproducibility.md
    - text: Decisions
      href: decisions/README.md
    - text: Reference
      menu:
        - EXECUTIVE_SUMMARY.md
        - EVIDENCE.md
        - SPEC_SHEET.md
        - SUBMISSION_AUDIT.md
        - NEXT_STEPS.md
        - assumptions.md
        - notebooks/01_canonical_results.ipynb
        - notebooks/02_frozen_vs_lora.ipynb
        - notebooks/03_calibration.ipynb
        - notebooks/04_ood_slate.ipynb
    - text: Repo
      href: https://github.com/brandon-behring/behring/prompt-injection-detection-prototype
      target: _blank

The single Methodology dropdown becomes the obvious entry to the hub + 8 spokes + the new READING_GUIDE.md page. Notebooks collapse into Reference (they’re auxiliary artifacts, not primary methodology). EVIDENCE.md moves to Reference (it’s an audit-trail artifact, not a methodology entry point). Repo is a direct GitHub link for users who want to browse source.

Subsection B — Sidebar hub-spoke nesting

_quarto.yml sidebar.contents Methodology section:

# OLD: 9 peer items (WRITEUP.md + 8 spokes at same indent level).
# NEW: 2-level nesting.
- section: "Methodology"
  contents:
    - text: "Cover narrative (hub)"
      href: WRITEUP.md
    - text: "Reading guide"
      href: READING_GUIDE.md
    - section: "Detailed spokes (8 topics)"
      contents:
        - WRITEUP/data-decisions.md
        - WRITEUP/model-rungs.md
        - WRITEUP/eval-design.md
        - WRITEUP/threshold-policy.md
        - WRITEUP/reference-scorer-audit.md
        - WRITEUP/methodology-guarantees.md
        - WRITEUP/limitations-and-future-work.md
        - WRITEUP/reproducibility.md

The “Detailed spokes (8 topics)” sub-section is visually indented under WRITEUP.md. A reader scanning the sidebar sees the hub-spoke relationship at-a-glance — no longer 9 peer items.

Subsection C — index.qmd landing page rebuild

index.qmd (137 lines → ~30 lines):

1-paragraph thesis.
Headline finding table (the §1 AUPRC trio from RESULTS — unchanged content).
5-bullet “What this means in plain language” — 1 sentence per interpretation pattern (distilled from the current ADR-053 dimension-4 5-patterns; the deeper technical version is one click away via a “Full interpretation” link).
Three obvious drill-down links: “Full results + figures” (RESULTS.md), “Full methodology” (WRITEUP.md), “How to read this site” (READING_GUIDE.md).

The reading-guide content displaced from index.qmd (3 reading paths + headline ADRs list + repo map + submission anchors + status) moves to the new READING_GUIDE.md page. Per no-orphaned-code invariant: the content is NOT duplicated — index.qmd is rewritten and READING_GUIDE.md is the new home for the moved sections.

Subsection D — WRITEUP.md hub-spoke primer

Insert 2-paragraph primer at WRITEUP.md immediately after the title (before the current “Reading guide” table):

This is the hub of the methodology — a cover narrative + headline results. The detailed methodology lives in 8 spoke pages linked below; each spoke is a focused deep-dive on one topic (data design, rung ladder, evaluation, thresholds, calibration, reference-scorer audit, limitations, reproducibility).

Reading on the live Quarto site: drill into each spoke from the Methodology dropdown in the navbar or the sidebar. Reading on GitHub: click each spoke link in the table below — the GitHub blob view of this file alone is the cover narrative; the full methodology requires all 8 spokes.

The primer reframes WRITEUP.md as INTENTIONAL — not as an incomplete document.

Subsection E — Spoke→hub back-link (8 files)

Each of WRITEUP/data-decisions.md, model-rungs.md, eval-design.md, threshold-policy.md, reference-scorer-audit.md, methodology-guarantees.md, limitations-and-future-work.md, reproducibility.md gains a 1-line back-link at the very top (before any other content):

Part of the WRITEUP methodology — see the hub for the cover narrative + reading guide.

Signposts the spoke as a child of the hub for any reader who deep-links into a spoke (search, external link, sidebar click) without seeing the hub first.

Subsection F — README.md “How to read” clarified

README’s reading-path section gains explicit Quarto-vs-GitHub guidance:

Quick read (5 min): live Quarto site → landing page (results + plain-language interpretation).
Full methodology (60 min): live Quarto site → Methodology dropdown → cover narrative + 8 spokes.
GitHub-only readers: WRITEUP.md is only the cover narrative; the 8 WRITEUP/*.md spokes carry the detailed methodology — meant to be read together. Reading WRITEUP.md alone is executive-summary depth. Click the spoke links in the table at the top of WRITEUP.md to drill in.

Removes the user’s mental-model inversion (GitHub-blob feels like the full methodology when it’s actually a subset).

Consequences

Discoverability: landing page now satisfies the user’s “immediately clear where to find results + plain-language meaning” bar. Results above the fold; 5-bullet meaning right below; 3 obvious drill-down links.
Hub-spoke visual hierarchy: navbar Methodology dropdown + sidebar 2-level nesting + WRITEUP.md primer + spoke back-links reinforce the same mental model from 4 angles.
ADR-053 narrow supersession: only navigation dimension changes; 3-reading-paths (now moved to READING_GUIDE.md but unchanged), headline-finding-block (preserved on index.qmd), interpretation pedagogy (5 patterns preserved; landing page gets distilled 1-line bullets + “Full interpretation” link to the technical version), pointer convention (markdown links unchanged) — all preserved.
No methodology drift: zero changes to WRITEUP.md hub or 8 spoke contents (text body). Only navigation + signposting.
Reviewer URL pin unchanged: per ADR-033, tree/v1.0.0 stays; live Quarto site reflects the v1.1.1 restructure.
CHANGELOG.md [1.1.1] documents the change; SUBMISSION_AUDIT.md regenerates with 61 CLAIM rows.

Linked ADRs

Superseded (narrow, navigation dimension only): ADR-053 (the reading-guide governance ADR; dimensions 2-5 preserved).
Referenced: ADR-030 (Quarto static-site renderer; rendering recipe unchanged); ADR-054 (RESULTS as 3rd entry artifact; preserved as the default landing-page target); ADR-033 (release strategy; v1.1.1 = patch release per the post-submission patch convention).
Source: user feedback 2026-05-19 “the quatro documents they seem really confusing and hard to follow” + Explore-agent audit + plan file [PLAN_REF redacted; per ADR-068 Class B aspirational-upstream path] Phase 2.

Transcript

Decisions surfaced during the 2026-05-19 v1.1.1 Quarto-clarity restructure planning session; transcript at transcripts/2026-05-19__v1-1-1-quarto-clarity-restructure.md.