npm - @zigrivers/scaffold - Versions diffs - 3.28.0 → 3.30.0 - Mend

@zigrivers/scaffold 3.28.0 → 3.30.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (721) hide show

package/content/guides/dashboard/index.html ADDED Viewed

@@ -0,0 +1,1560 @@
+<!DOCTYPE html>
+<html lang="en" data-chrome-version="1">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Dashboard &amp; Design System</title>
+<!-- scaffold:chrome v1 -->
+<style>/* Scaffold Dashboard Theme
+ * All CSS for the generated pipeline dashboard.
+ * Embedded into HTML by scripts/generate-dashboard.sh.
+ * Design system reference: docs/design-system.md
+ *
+ * Aesthetic: "Precision Industrial" — Swiss-typographic control room.
+ * Deep navy dark mode with indigo accents, clean cool-white light mode.
+ */
+/* ─── Design Tokens (Light Mode) ──────────────── */
+:root {
+    /* Surface */
+    --bg:           #f5f6fa;
+    --bg-card:      #ffffff;
+    --bg-hover:     #eef0f6;
+    --bg-inset:     #e8eaf2;
+    /* Text */
+    --text:         #1a1d2e;
+    --text-muted:   #6b7294;
+    --text-faint:   #9ba1c0;
+    /* Borders & Structure */
+    --border:       #dde0ed;
+    --border-light: #eceef5;
+    --radius:       10px;
+    --radius-sm:    6px;
+    /* Accent */
+    --accent:       #4f46e5;
+    --accent-hover: #4338ca;
+    --accent-glow:  rgba(79, 70, 229, 0.10);
+    /* Semantic: Status */
+    --green:        #059669;
+    --green-bg:     #ecfdf5;
+    --green-border: #a7f3d0;
+    --blue:         #2563eb;
+    --blue-bg:      #eff6ff;
+    --blue-border:  #bfdbfe;
+    --yellow:       #d97706;
+    --yellow-bg:    #fffbeb;
+    --yellow-border:#fde68a;
+    --gray:         #9ca3af;
+    --gray-bg:      #f3f4f6;
+    --gray-border:  #e5e7eb;
+    /* Semantic: Next Banner */
+    --next-bg:      #eef2ff;
+    --next-border:  #4f46e5;
+    --next-glow:    rgba(79, 70, 229, 0.06);
+    /* Semantic: Progress */
+    --progress-bg:  #e5e7eb;
+    --progress-h:   10px;
+    /* Depth */
+    --shadow-sm:    0 1px 2px rgba(30, 34, 60, 0.04);
+    --shadow:       0 1px 3px rgba(30, 34, 60, 0.07), 0 1px 2px rgba(30, 34, 60, 0.04);
+    --shadow-md:    0 4px 12px rgba(30, 34, 60, 0.08), 0 1px 3px rgba(30, 34, 60, 0.05);
+    --shadow-lg:    0 8px 24px rgba(30, 34, 60, 0.10), 0 2px 6px rgba(30, 34, 60, 0.04);
+    /* Spacing scale (4px base) */
+    --sp-1: 4px;
+    --sp-2: 8px;
+    --sp-3: 12px;
+    --sp-4: 16px;
+    --sp-5: 20px;
+    --sp-6: 24px;
+    --sp-8: 32px;
+    --sp-10: 40px;
+    /* Typography */
+    --font-sans:  -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
+    --font-mono:  "SF Mono", "Cascadia Code", "Fira Code", "JetBrains Mono", Menlo, Consolas, monospace;
+    --text-xs:    0.75rem;
+    --text-sm:    0.8125rem;
+    --text-base:  0.9375rem;
+    --text-lg:    1.125rem;
+    --text-xl:    1.375rem;
+    --text-2xl:   1.75rem;
+    --lh-tight:   1.25;
+    --lh-normal:  1.5;
+    --lh-relaxed: 1.625;
+    --ls-tight:   -0.01em;
+    --ls-wide:    0.025em;
+    --fw-normal:  400;
+    --fw-medium:  500;
+    --fw-semi:    600;
+    --fw-bold:    700;
+    /* Layout */
+    --max-w:      960px;
+    --page-pad:   24px;
+}
+/* ─── Design Tokens (Dark Mode) ───────────────── */
+[data-theme="dark"] {
+    /* Surface */
+    --bg:           #0f1117;
+    --bg-card:      #1a1d2e;
+    --bg-hover:     #252940;
+    --bg-inset:     #141724;
+    /* Text */
+    --text:         #e2e5f0;
+    --text-muted:   #7c82a8;
+    --text-faint:   #555c80;
+    /* Borders & Structure */
+    --border:       #2a2f45;
+    --border-light: #21253a;
+    /* Accent */
+    --accent:       #818cf8;
+    --accent-hover: #a5b4fc;
+    --accent-glow:  rgba(129, 140, 248, 0.12);
+    /* Semantic: Status */
+    --green:        #34d399;
+    --green-bg:     rgba(6, 78, 59, 0.25);
+    --green-border: rgba(52, 211, 153, 0.25);
+    --blue:         #60a5fa;
+    --blue-bg:      rgba(30, 58, 95, 0.30);
+    --blue-border:  rgba(96, 165, 250, 0.25);
+    --yellow:       #fbbf24;
+    --yellow-bg:    rgba(120, 53, 15, 0.25);
+    --yellow-border:rgba(251, 191, 36, 0.20);
+    --gray:         #6b7294;
+    --gray-bg:      #252940;
+    --gray-border:  #363c58;
+    /* Semantic: Next Banner */
+    --next-bg:      rgba(30, 27, 75, 0.50);
+    --next-border:  #818cf8;
+    --next-glow:    rgba(129, 140, 248, 0.08);
+    /* Semantic: Progress */
+    --progress-bg:  #1f2337;
+    /* Depth */
+    --shadow-sm:    0 1px 2px rgba(0, 0, 0, 0.20);
+    --shadow:       0 1px 3px rgba(0, 0, 0, 0.30), 0 1px 2px rgba(0, 0, 0, 0.15);
+    --shadow-md:    0 4px 12px rgba(0, 0, 0, 0.35), 0 1px 3px rgba(0, 0, 0, 0.20);
+    --shadow-lg:    0 8px 24px rgba(0, 0, 0, 0.40), 0 2px 6px rgba(0, 0, 0, 0.20);
+}
+/* ─── Theme Toggle ───────────────────────────── */
+.theme-toggle {
+    background: var(--bg-inset);
+    border: 1px solid var(--border);
+    border-radius: var(--radius-sm);
+    padding: var(--sp-1) var(--sp-2);
+    cursor: pointer;
+    font-size: var(--text-base);
+    line-height: 1;
+    color: var(--text-muted);
+    transition: border-color 0.15s ease, color 0.15s ease, background 0.15s ease;
+    display: flex;
+    align-items: center;
+    margin-left: auto;
+}
+.theme-toggle:hover {
+    border-color: var(--accent);
+    color: var(--accent);
+    background: var(--accent-glow);
+}
+/* ─── Base ────────────────────────────────────── */
+*, *::before, *::after {
+    margin: 0;
+    padding: 0;
+    box-sizing: border-box;
+}
+body {
+    font-family: var(--font-sans);
+    font-size: var(--text-base);
+    line-height: var(--lh-normal);
+    color: var(--text);
+    background: var(--bg);
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+}
+/* ─── Layout ──────────────────────────────────── */
+.wrap {
+    max-width: var(--max-w);
+    margin: 0 auto;
+    padding: var(--sp-8) var(--page-pad);
+}
+/* ─── Header ──────────────────────────────────── */
+.header {
+    display: flex;
+    align-items: baseline;
+    gap: var(--sp-3);
+    margin-bottom: var(--sp-2);
+    flex-wrap: wrap;
+}
+h1 {
+    font-size: var(--text-2xl);
+    font-weight: var(--fw-bold);
+    letter-spacing: var(--ls-tight);
+    line-height: var(--lh-tight);
+}
+h2 {
+    font-size: var(--text-lg);
+    font-weight: var(--fw-semi);
+    letter-spacing: var(--ls-tight);
+    line-height: var(--lh-tight);
+    margin-bottom: var(--sp-3);
+}
+.header-meta {
+    font-size: var(--text-xs);
+    color: var(--text-faint);
+    margin-bottom: var(--sp-6);
+    letter-spacing: var(--ls-wide);
+    text-transform: uppercase;
+}
+/* ─── Badge ───────────────────────────────────── */
+.badge {
+    display: inline-block;
+    padding: 2px var(--sp-2);
+    border-radius: 99px;
+    font-size: var(--text-xs);
+    font-weight: var(--fw-semi);
+    letter-spacing: var(--ls-wide);
+    background: var(--accent);
+    color: #fff;
+    text-transform: uppercase;
+}
+.badge-optional {
+    background: var(--yellow-bg);
+    color: var(--yellow);
+    border: 1px solid var(--yellow-border);
+}
+/* ─── Progress Bar ────────────────────────────── */
+.progress-bar {
+    width: 100%;
+    height: var(--progress-h);
+    background: var(--progress-bg);
+    border-radius: 99px;
+    overflow: hidden;
+    margin-bottom: var(--sp-6);
+    display: flex;
+    box-shadow: inset 0 1px 2px rgba(0, 0, 0, 0.06);
+}
+.progress-bar .seg-done {
+    background: linear-gradient(135deg, var(--green), #10b981);
+    box-shadow: 0 0 8px rgba(5, 150, 105, 0.3);
+}
+.progress-bar .seg-likely {
+    background: linear-gradient(135deg, var(--blue), #3b82f6);
+    box-shadow: 0 0 8px rgba(37, 99, 235, 0.25);
+}
+.progress-bar .seg-skip {
+    background: var(--gray);
+    opacity: 0.7;
+}
+/* ─── Summary Cards ───────────────────────────── */
+.cards {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(130px, 1fr));
+    gap: var(--sp-3);
+    margin-bottom: var(--sp-6);
+}
+.card {
+    background: var(--bg-card);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    padding: var(--sp-4) var(--sp-5);
+    box-shadow: var(--shadow);
+    transition: box-shadow 0.15s ease, transform 0.15s ease;
+}
+.card:hover {
+    box-shadow: var(--shadow-md);
+    transform: translateY(-1px);
+}
+.card-num {
+    font-size: var(--text-2xl);
+    font-weight: var(--fw-bold);
+    font-family: var(--font-mono);
+    letter-spacing: var(--ls-tight);
+    line-height: 1;
+}
+.card-lbl {
+    font-size: var(--text-xs);
+    color: var(--text-muted);
+    margin-top: var(--sp-1);
+    letter-spacing: var(--ls-wide);
+    text-transform: uppercase;
+    font-weight: var(--fw-medium);
+}
+/* ─── What's Next Banner ──────────────────────── */
+.next-banner {
+    background: var(--next-bg);
+    border: 1px solid var(--next-border);
+    border-left: 4px solid var(--next-border);
+    border-radius: var(--radius);
+    padding: var(--sp-5) var(--sp-6);
+    margin-bottom: var(--sp-6);
+    box-shadow: 0 0 0 1px var(--next-glow), var(--shadow);
+    position: relative;
+    overflow: hidden;
+}
+.next-banner::before {
+    content: "";
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 4px;
+    height: 100%;
+    background: var(--next-border);
+    animation: pulse-border 2.5s ease-in-out infinite;
+}
+@keyframes pulse-border {
+    0%, 100% { opacity: 1; }
+    50%      { opacity: 0.5; }
+}
+.next-banner h2 {
+    color: var(--accent);
+    margin-bottom: var(--sp-1);
+    font-size: var(--text-base);
+    font-weight: var(--fw-semi);
+    letter-spacing: var(--ls-wide);
+    text-transform: uppercase;
+}
+.next-banner p {
+    color: var(--text);
+    font-size: var(--text-base);
+}
+.next-cmd {
+    font-family: var(--font-mono);
+    background: var(--bg-card);
+    padding: var(--sp-1) var(--sp-3);
+    border-radius: var(--radius-sm);
+    font-size: var(--text-sm);
+    display: inline-flex;
+    align-items: center;
+    gap: var(--sp-2);
+    margin-top: var(--sp-3);
+    border: 1px solid var(--border);
+}
+/* ─── Phase Headers (Collapsible) ─────────────── */
+.phase {
+    margin-bottom: var(--sp-6);
+}
+.phase-hdr {
+    display: flex;
+    align-items: center;
+    gap: var(--sp-2);
+    cursor: pointer;
+    padding: var(--sp-2) 0;
+    user-select: none;
+    border-bottom: 2px solid var(--border);
+    margin-bottom: var(--sp-3);
+    transition: border-color 0.15s ease;
+}
+.phase-hdr:hover {
+    border-bottom-color: var(--accent);
+}
+.phase-hdr:hover h2 {
+    color: var(--accent);
+}
+.phase-hdr h2 {
+    transition: color 0.15s ease;
+}
+.phase-hdr .arr {
+    transition: transform 0.2s ease;
+    font-size: var(--text-xs);
+    color: var(--text-muted);
+}
+.phase-hdr.closed .arr {
+    transform: rotate(-90deg);
+}
+.phase-cnt {
+    font-size: var(--text-xs);
+    font-family: var(--font-mono);
+    color: var(--text-faint);
+    margin-left: auto;
+    letter-spacing: var(--ls-wide);
+}
+/* ─── Prompt List ─────────────────────────────── */
+.plist {
+    display: flex;
+    flex-direction: column;
+    gap: var(--sp-2);
+}
+/* ─── Prompt Cards ────────────────────────────── */
+.pcard {
+    background: var(--bg-card);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    padding: var(--sp-3) var(--sp-4);
+    box-shadow: var(--shadow-sm);
+    display: grid;
+    grid-template-columns: auto 1fr auto;
+    gap: var(--sp-2) var(--sp-3);
+    align-items: start;
+    transition: box-shadow 0.15s ease, transform 0.15s ease, border-color 0.15s ease;
+}
+.pcard:hover {
+    box-shadow: var(--shadow);
+    transform: translateY(-1px);
+    border-color: var(--accent-glow);
+}
+/* ─── Status Badges ──────────────────────────── */
+.status-badge {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--sp-1);
+    font-size: var(--text-xs);
+    font-weight: var(--fw-medium);
+    padding: 2px var(--sp-2);
+    border-radius: 99px;
+    white-space: nowrap;
+    flex-shrink: 0;
+    letter-spacing: var(--ls-wide);
+    line-height: var(--lh-tight);
+}
+.st-completed {
+    background: var(--green-bg);
+    color: var(--green);
+    border: 1px solid var(--green-border);
+}
+.st-likely-completed {
+    background: var(--blue-bg);
+    color: var(--blue);
+    border: 1px solid var(--blue-border);
+}
+.st-skipped {
+    background: var(--gray-bg);
+    color: var(--gray);
+    border: 1px solid var(--gray-border);
+}
+.st-pending {
+    background: var(--bg-inset);
+    color: var(--text-faint);
+    border: 1px solid var(--border);
+}
+/* ─── Status Legend ──────────────────────────── */
+.status-legend {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--sp-2);
+    margin-bottom: var(--sp-4);
+    padding: var(--sp-2) 0;
+}
+.status-legend .status-badge {
+    cursor: default;
+}
+/* ─── Prompt Card Inner ───────────────────────── */
+.pinfo {
+    min-width: 0;
+}
+.pname {
+    font-weight: var(--fw-semi);
+    font-size: var(--text-base);
+}
+.pstep {
+    font-size: var(--text-xs);
+    font-family: var(--font-mono);
+    color: var(--text-faint);
+    letter-spacing: var(--ls-wide);
+}
+.pdesc {
+    font-size: var(--text-sm);
+    color: var(--text-muted);
+    margin-top: 2px;
+    line-height: var(--lh-relaxed);
+}
+.pdesc-long {
+    font-size: var(--text-xs);
+    color: var(--text-faint);
+    margin-top: 2px;
+}
+.pdeps {
+    font-size: var(--text-xs);
+    color: var(--yellow);
+    margin-top: var(--sp-1);
+    font-weight: var(--fw-medium);
+}
+/* ─── Copy Command Button ─────────────────────── */
+.pcmd {
+    font-family: var(--font-mono);
+    font-size: var(--text-xs);
+    background: var(--bg-inset);
+    padding: 3px var(--sp-2);
+    border-radius: var(--radius-sm);
+    cursor: pointer;
+    border: 1px solid var(--border);
+    white-space: nowrap;
+    align-self: center;
+    color: var(--text-muted);
+    transition: border-color 0.15s ease, color 0.15s ease, background 0.15s ease;
+    letter-spacing: var(--ls-wide);
+}
+.pcmd:hover {
+    border-color: var(--accent);
+    color: var(--accent);
+    background: var(--accent-glow);
+}
+.pcmd.copied {
+    border-color: var(--green);
+    color: var(--green);
+    background: var(--green-bg);
+}
+/* ─── Prompt Modal ────────────────────────────── */
+.modal-overlay {
+    position: fixed;
+    inset: 0;
+    background: rgba(0, 0, 0, 0.6);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    z-index: 1000;
+    padding: var(--sp-4);
+}
+.modal {
+    background: var(--bg-card);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    box-shadow: var(--shadow-lg);
+    max-width: 720px;
+    width: 100%;
+    max-height: 85vh;
+    display: flex;
+    flex-direction: column;
+}
+.modal-header {
+    display: flex;
+    align-items: center;
+    gap: var(--sp-3);
+    padding: var(--sp-4) var(--sp-5);
+    border-bottom: 1px solid var(--border);
+    flex-shrink: 0;
+}
+.modal-header h3 {
+    font-size: var(--text-lg);
+    font-weight: var(--fw-semi);
+    flex: 1;
+    min-width: 0;
+}
+.modal-close {
+    background: var(--bg-inset);
+    border: 1px solid var(--border);
+    border-radius: var(--radius-sm);
+    padding: var(--sp-1) var(--sp-2);
+    cursor: pointer;
+    font-size: var(--text-base);
+    color: var(--text-muted);
+    line-height: 1;
+    transition: border-color 0.15s ease, color 0.15s ease;
+}
+.modal-close:hover {
+    border-color: var(--accent);
+    color: var(--accent);
+}
+.modal-body {
+    padding: var(--sp-5);
+    overflow-y: auto;
+    flex: 1;
+}
+.modal-body pre {
+    font-family: var(--font-mono);
+    font-size: var(--text-sm);
+    line-height: var(--lh-relaxed);
+    white-space: pre-wrap;
+    word-break: break-word;
+    color: var(--text);
+}
+.modal-body pre .md-heading {
+    font-weight: var(--fw-bold);
+    color: var(--accent);
+}
+.modal-body pre .md-code {
+    background: var(--bg-inset);
+    padding: 1px 4px;
+    border-radius: 3px;
+    font-size: var(--text-xs);
+}
+.modal-footer {
+    display: flex;
+    gap: var(--sp-2);
+    padding: var(--sp-3) var(--sp-5);
+    border-top: 1px solid var(--border);
+    flex-shrink: 0;
+}
+.modal-copy-btn {
+    background: var(--accent);
+    color: #fff;
+    border: none;
+    border-radius: var(--radius-sm);
+    padding: var(--sp-2) var(--sp-4);
+    font-size: var(--text-sm);
+    font-weight: var(--fw-medium);
+    cursor: pointer;
+    transition: background 0.15s ease;
+}
+.modal-copy-btn:hover {
+    background: var(--accent-hover);
+}
+.modal-copy-btn.copied {
+    background: var(--green);
+}
+/* ─── Beads Task Section ─────────────────────── */
+.beads-section {
+    margin-top: var(--sp-8);
+    margin-bottom: var(--sp-6);
+}
+.beads-filters {
+    display: flex;
+    gap: var(--sp-2);
+    margin-bottom: var(--sp-3);
+}
+.beads-filter {
+    background: var(--bg-inset);
+    border: 1px solid var(--border);
+    border-radius: 99px;
+    padding: var(--sp-1) var(--sp-3);
+    font-size: var(--text-xs);
+    font-weight: var(--fw-medium);
+    color: var(--text-muted);
+    cursor: pointer;
+    transition: border-color 0.15s ease, color 0.15s ease, background 0.15s ease;
+    letter-spacing: var(--ls-wide);
+}
+.beads-filter:hover {
+    border-color: var(--accent);
+    color: var(--accent);
+}
+.beads-filter.active {
+    background: var(--accent);
+    color: #fff;
+    border-color: var(--accent);
+}
+/* ─── Beads Status Badges ────────────────────── */
+.st-bead-open {
+    background: var(--accent-glow);
+    color: var(--accent);
+    border: 1px solid var(--accent);
+}
+.st-bead-progress {
+    background: var(--blue-bg);
+    color: var(--blue);
+    border: 1px solid var(--blue-border);
+}
+.st-bead-blocked {
+    background: var(--yellow-bg);
+    color: var(--yellow);
+    border: 1px solid var(--yellow-border);
+}
+.st-bead-deferred {
+    background: var(--gray-bg);
+    color: var(--gray);
+    border: 1px solid var(--gray-border);
+}
+.st-bead-closed {
+    background: var(--green-bg);
+    color: var(--green);
+    border: 1px solid var(--green-border);
+}
+/* ─── Beads Filter Separator ─────────────────── */
+.beads-filter-sep {
+    width: 1px;
+    background: var(--border);
+    align-self: stretch;
+    margin: 0 var(--sp-1);
+}
+/* ─── Beads Priority Filter ──────────────────── */
+.beads-prio-filter {
+    background: var(--bg-inset);
+    border: 1px solid var(--border);
+    border-radius: 99px;
+    padding: var(--sp-1) var(--sp-3);
+    font-size: var(--text-xs);
+    font-weight: var(--fw-medium);
+    color: var(--text-muted);
+    cursor: pointer;
+    transition: border-color 0.15s ease, color 0.15s ease, background 0.15s ease;
+    letter-spacing: var(--ls-wide);
+}
+.beads-prio-filter:hover {
+    border-color: var(--accent);
+    color: var(--accent);
+}
+.beads-prio-filter.active {
+    background: var(--accent);
+    color: #fff;
+    border-color: var(--accent);
+}
+/* ─── Beads Task Detail Modal ────────────────── */
+.bead-meta-grid {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: var(--sp-3);
+    padding: var(--sp-4) 0;
+    border-bottom: 1px solid var(--border-light);
+}
+.bead-meta-item {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+}
+.bead-meta-label {
+    font-size: var(--text-xs);
+    color: var(--text-faint);
+    text-transform: uppercase;
+    letter-spacing: var(--ls-wide);
+    font-weight: var(--fw-medium);
+}
+.bead-meta-value {
+    font-size: var(--text-sm);
+    font-weight: var(--fw-medium);
+    color: var(--text);
+}
+.bead-description {
+    padding: var(--sp-4) 0;
+    border-bottom: 1px solid var(--border-light);
+    white-space: pre-wrap;
+    font-size: var(--text-sm);
+    line-height: var(--lh-relaxed);
+    color: var(--text-muted);
+}
+.bead-deps {
+    padding: var(--sp-4) 0;
+    border-bottom: 1px solid var(--border-light);
+}
+.bead-dep-group {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--sp-2);
+    margin-bottom: var(--sp-2);
+}
+.bead-dep-group:last-child {
+    margin-bottom: 0;
+}
+.bead-dep-label {
+    font-size: var(--text-xs);
+    color: var(--text-faint);
+    text-transform: uppercase;
+    letter-spacing: var(--ls-wide);
+    font-weight: var(--fw-medium);
+    min-width: 80px;
+}
+.bead-dep-link {
+    display: inline-block;
+    font-family: var(--font-mono);
+    font-size: var(--text-xs);
+    padding: 2px var(--sp-2);
+    border-radius: 99px;
+    background: var(--accent-glow);
+    color: var(--accent);
+    border: 1px solid var(--accent);
+    cursor: pointer;
+    transition: background 0.15s ease, color 0.15s ease;
+    text-decoration: none;
+}
+.bead-dep-link:hover {
+    background: var(--accent);
+    color: #fff;
+}
+.bead-timestamps {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--sp-4);
+    padding: var(--sp-4) 0;
+}
+.bead-ts-item {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+}
+.bead-ts-label {
+    font-size: var(--text-xs);
+    color: var(--text-faint);
+    text-transform: uppercase;
+    letter-spacing: var(--ls-wide);
+    font-weight: var(--fw-medium);
+}
+.bead-ts-value {
+    font-size: var(--text-sm);
+    color: var(--text-muted);
+}
+.bead-ts-value[title] {
+    border-bottom: 1px dotted var(--text-faint);
+    cursor: help;
+}
+/* ─── Standalone Commands Section ─────────────── */
+.ongoing {
+    margin-top: var(--sp-10);
+}
+.ongoing h2 {
+    letter-spacing: var(--ls-wide);
+    text-transform: uppercase;
+    font-size: var(--text-sm);
+    color: var(--text-muted);
+    margin-bottom: var(--sp-4);
+    border-bottom: 2px solid var(--border);
+    padding-bottom: var(--sp-2);
+}
+/* ─── Footer ──────────────────────────────────── */
+.footer {
+    text-align: center;
+    font-size: var(--text-xs);
+    color: var(--text-faint);
+    margin-top: var(--sp-10);
+    padding-top: var(--sp-4);
+    border-top: 1px solid var(--border-light);
+    letter-spacing: var(--ls-wide);
+}
+/* ─── Utilities ───────────────────────────────── */
+.hidden {
+    display: none;
+}
+/* Build-observability severity + verdict tokens (Plan 4) */
+:root {
+  --sev-p0: #dc2626;        /* red 600 */
+  --sev-p1: #ea580c;        /* orange 600 */
+  --sev-p2: #ca8a04;        /* yellow 600 */
+  --sev-p3: #2563eb;        /* blue 600 */
+  --sev-pass: #16a34a;      /* green 600 */
+}
+[data-theme="dark"] {
+  --sev-p0: #f87171;
+  --sev-p1: #fb923c;
+  --sev-p2: #facc15;
+  --sev-p3: #60a5fa;
+  --sev-pass: #4ade80;
+}
+/* Build-observability panel layout */
+.panel {
+    background: var(--bg-card);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    padding: var(--sp-4) var(--sp-6);
+    margin-bottom: var(--sp-6);
+}
+.panel > header {
+    display: flex;
+    align-items: center;
+    gap: var(--sp-3);
+    margin-bottom: var(--sp-4);
+    flex-wrap: wrap;
+}
+.panel > header h2 {
+    margin: 0;
+    font-size: var(--text-base);
+    font-weight: var(--fw-semi);
+}
+.panel .meta {
+    color: var(--text-muted);
+    font-size: var(--text-sm);
+}
+.grid { display: grid; gap: var(--sp-4); }
+.grid-2 { grid-template-columns: repeat(2, 1fr); }
+@media (max-width: 640px) { .grid-2 { grid-template-columns: 1fr; } }
+/* Finding filters */
+.finding-filters {
+    display: flex;
+    gap: var(--sp-2);
+    flex-wrap: wrap;
+    margin-bottom: var(--sp-4);
+}
+.finding-filters button {
+    padding: var(--sp-1) var(--sp-3);
+    border: 1px solid var(--border);
+    border-radius: var(--radius-sm);
+    background: var(--bg-inset);
+    color: var(--text);
+    font-size: var(--text-sm);
+    cursor: pointer;
+}
+.finding-filters button:hover,
+.finding-filters button.active {
+    background: var(--accent);
+    border-color: var(--accent);
+    color: #fff;
+}
+/* Findings list */
+.findings {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+    display: flex;
+    flex-direction: column;
+    gap: var(--sp-3);
+}
+.finding {
+    background: var(--bg-inset);
+    border: 1px solid var(--border-light);
+    border-radius: var(--radius-sm);
+    padding: var(--sp-3) var(--sp-4);
+}
+.finding header {
+    display: flex;
+    align-items: center;
+    gap: var(--sp-2);
+    flex-wrap: wrap;
+    margin-bottom: var(--sp-2);
+}
+.finding-id {
+    font-family: var(--font-mono, monospace);
+    font-size: var(--text-xs);
+    color: var(--text-muted);
+    background: var(--bg-card);
+    border: 1px solid var(--border);
+    border-radius: 4px;
+    padding: 1px var(--sp-1);
+}
+.finding .lens {
+    font-size: var(--text-xs);
+    color: var(--text-muted);
+}
+.finding .title {
+    font-size: var(--text-sm);
+    font-weight: var(--fw-semi);
+    flex: 1;
+}
+.finding p { margin: 0; font-size: var(--text-sm); color: var(--text-muted); }
+.empty { color: var(--text-muted); font-size: var(--text-sm); text-align: center; padding: var(--sp-4); }
+/* ── Mermaid diagrams ─────────────────────────────────────────────────────────
+   The build renders mermaid to inline SVG via mmdc, then sanitizeSvg() +
+   rehype-sanitize strip the SVG's own <script>, <foreignObject>, AND <style>
+   for security. Stripping <style> means the diagram arrives unstyled (nodes
+   default to a black fill). These theme-token rules restyle the SVG so nodes,
+   edges, arrowheads, and labels render correctly — and follow light/dark mode.
+   Authors must render with htmlLabels:false (the generator forces this) so node
+   labels are native <text>/<tspan> rather than stripped <foreignObject> HTML. */
+figure.mermaid { margin: var(--sp-5) 0; text-align: center; }
+figure.mermaid svg { max-width: 100%; height: auto; }
+/* Node shapes */
+figure.mermaid svg .node rect,
+figure.mermaid svg .node circle,
+figure.mermaid svg .node ellipse,
+figure.mermaid svg .node polygon,
+figure.mermaid svg .node path {
+    fill: var(--bg-inset);
+    stroke: var(--border);
+    stroke-width: 1px;
+}
+/* Background helper rects mermaid emits behind labels */
+figure.mermaid svg .node .label-container { fill: var(--bg-inset); stroke: var(--border); }
+figure.mermaid svg rect.background { fill: none; stroke: none; }
+/* Labels (rendered as <text>/<tspan> when htmlLabels:false) */
+figure.mermaid svg .nodeLabel,
+figure.mermaid svg .node text,
+figure.mermaid svg text.nodeLabel,
+figure.mermaid svg .label text,
+figure.mermaid svg span.nodeLabel {
+    fill: var(--text);
+    color: var(--text);
+    font-family: var(--font-sans);
+}
+/* Edges: thin strokes, not filled blobs */
+figure.mermaid svg .edgePath path,
+figure.mermaid svg path.flowchart-link,
+figure.mermaid svg .flowchart-link {
+    fill: none;
+    stroke: var(--text-faint);
+    stroke-width: 1.5px;
+}
+/* Arrowheads */
+figure.mermaid svg marker path,
+figure.mermaid svg .marker {
+    fill: var(--text-faint);
+    stroke: var(--text-faint);
+}
+figure.mermaid svg .edgeLabel,
+figure.mermaid svg .edgeLabel text { fill: var(--text-muted); color: var(--text-muted); }
+</style>
+<script>(function(){try{var t=localStorage.getItem('guide-theme');if(!t&&window.matchMedia&&matchMedia('(prefers-color-scheme: dark)').matches)t='dark';if(t)document.documentElement.setAttribute('data-theme',t);}catch(e){}})();</script>
+</head>
+<body>
+<header class="topbar">
+  <button data-action="nav" class="nav-toggle" aria-label="Toggle navigation">☰</button>
+  <h1>Dashboard &amp; Design System</h1>
+  <button data-action="theme" class="theme-toggle" aria-label="Toggle theme">◐</button>
+</header>
+<div class="layout">
+  <aside class="rail"><nav class="toc" aria-label="Table of contents"><ul><li class="toc-2"><a href="#what-the-dashboard-is">What the dashboard is</a></li><li class="toc-2"><a href="#reading-the-dashboard">Reading the dashboard</a></li><li class="toc-3"><a href="#the-build-observability-panels">The Build-Observability panels</a></li><li class="toc-3"><a href="#filters-and-modals-the-inline-js">Filters and modals (the inline JS)</a></li><li class="toc-2"><a href="#the-design-token-system">The design-token system</a></li><li class="toc-3"><a href="#colors-light-dark-parity">Colors — light + dark parity</a></li><li class="toc-3"><a href="#spacing-the---sp--scale">Spacing — the --sp-* scale</a></li><li class="toc-3"><a href="#typography-radius-layout">Typography, radius &amp; layout</a></li><li class="toc-2"><a href="#customizing-the-dashboard-safely">Customizing the dashboard safely</a></li><li class="toc-2"><a href="#visual-testing">Visual testing</a></li></ul></nav></aside>
+  <main class="content"><h2 id="what-the-dashboard-is">What the dashboard is</h2>
+<p>Each dashboard is a single, self-contained HTML file that visualizes where a
+Scaffold build stands: which pipeline steps are done and what to run next.
+Everything is inlined (CSS, JS, data); there are no CDN fonts, stylesheets, or
+scripts, so the file works offline and renders identically wherever you open it.</p>
+<div class="callout callout-warning"><p><strong>Two different producers — this guide documents the bash generator.</strong> Scaffold
+has two distinct dashboard surfaces that do <strong>not</strong> share markup, CSS, or
+features:</p><ul>
+<li><strong><code>scaffold dashboard</code></strong> (the user-facing CLI) renders HTML from
+<code>src/dashboard/template.ts</code> + <code>generator.ts</code>. It has its own inline <code>&#x3C;style></code>
+block (classes like <code>.container</code>, <code>.phase-header</code>, <code>.summary-cards</code>), a
+<strong>Decision Log</strong> section, and standalone-command cards. It does <strong>not</strong> read
+<code>lib/dashboard-theme.css</code>, has <strong>no</strong> Beads task section, and does <strong>not</strong>
+inject the Build-Observability panels. The CLI writes the HTML to a temp file
+(or <code>--output &#x3C;path></code>) and opens it via <code>open</code> / <code>xdg-open</code> / <code>start</code>
+(<span class="fp" data-path="src/cli/commands/dashboard.ts:64-66">src/cli/commands/dashboard.ts:64-66</span>).</li>
+<li><strong><code>scripts/generate-dashboard.sh</code></strong> is the visual-test fixture that
+<code>make dashboard-test</code> runs. It embeds <code>lib/dashboard-theme.css</code>, renders a
+Beads task section, and injects the two Build-Observability panels. Its
+classes (<code>.phase-hdr</code>, <code>.pcard</code>, <code>.beads-section</code>) and design tokens are
+exclusive to this surface.</li>
+</ul><p>The rest of this guide documents the <strong><code>scripts/generate-dashboard.sh</code></strong>
+surface — the one used for visual verification and the one that carries the
+<code>lib/dashboard-theme.css</code> token system. The panels, classes, design tokens, and
+inline JS described below belong to that generator, <strong>not</strong> to the
+<code>scaffold dashboard</code> CLI command.</p></div>
+<h2 id="reading-the-dashboard">Reading the dashboard</h2>
+<p>The page is built top-to-bottom by the inline renderer in the generator. From
+the header down:</p>
+<table><thead><tr><th>Region</th><th>Classes</th><th>What it shows</th></tr></thead><tbody><tr><td>Header</td><td><code>.header</code>, <code>.header-meta</code>, <code>.theme-toggle</code></td><td>Title, profile badge, project name + timestamp, light/dark toggle</td></tr><tr><td>Status legend</td><td><code>.status-legend</code></td><td>The four pipeline status badges (Done / Likely Done / Skipped / Pending)</td></tr><tr><td>Progress bar</td><td><code>.progress-bar</code>, <code>.seg-done</code>, <code>.seg-likely</code>, <code>.seg-skip</code></td><td>Proportional completion rail</td></tr><tr><td>Summary cards</td><td><code>.cards</code>, <code>.card</code>, <code>.card-num</code></td><td>Counts: completed, likely, skipped, pending, total, Beads-open</td></tr><tr><td>What's Next</td><td><code>.next-banner</code>, <code>.next-cmd</code></td><td>The recommended next command, with a copy button</td></tr><tr><td>Phases</td><td><code>.phase</code>, <code>.phase-hdr</code>, <code>.pcard</code></td><td>Collapsible phase sections, one prompt card per step</td></tr><tr><td>Beads Tasks</td><td><code>.beads-section</code>, <code>.beads-filters</code> (container), <code>.beads-filter</code> (buttons)</td><td>Filterable task list (status + priority), cards open a detail modal</td></tr><tr><td>Build Progress / Audit</td><td><code>#build-progress</code>, <code>#build-audit</code></td><td>The two Build-Observability panels (only when populated)</td></tr></tbody></table>
+<p>The header, legend, progress bar, summary cards, and What's Next banner are all
+emitted in sequence by the renderer (<span class="fp" data-path="scripts/generate-dashboard.sh:505-544">scripts/generate-dashboard.sh:505-544</span>).</p>
+<h3 id="the-build-observability-panels">The Build-Observability panels</h3>
+<p>After the pipeline content, the generator shells out to Build Observability and
+splices its HTML fragments into the page between named HTML comment markers
+(<code>&#x3C;!-- observe:progress --></code> … <code>&#x3C;!-- /observe:progress --></code> and the audit pair),
+preferring a local <code>dist/index.js</code> build and falling back to a global <code>scaffold</code>
+binary (<span class="fp" data-path="scripts/generate-dashboard.sh:872-887">scripts/generate-dashboard.sh:872-887</span>):</p>
+<pre><code class="language-bash">scaffold observe progress --render=dashboard-fragment       # → #build-progress panel
+scaffold observe audit   --render=dashboard-fragment-audit  # → #build-audit panel
+</code></pre>
+<p>Each renders as a <code>&#x3C;section class="panel"></code> — <code>#build-progress</code> for the live
+timeline and <code>#build-audit</code> (carrying <code>data-verdict</code> and <code>data-threshold</code>) for
+audit findings. If neither a local build nor a global <code>scaffold</code> is available the
+markers stay empty and the panels simply don't appear. See the
+<a href="../observability/index.md">Build Observability guide</a>{mode=advisory} for what
+those panels report.</p>
+<h3 id="filters-and-modals-the-inline-js">Filters and modals (the inline JS)</h3>
+<p>The dashboard is interactive without any framework — a handful of vanilla
+functions are inlined at the foot of the generated HTML:</p>
+<ul>
+<li><strong>Collapse a phase</strong> — clicking a <code>.phase-hdr</code> calls <code>togglePhase()</code>, which
+toggles <code>.closed</code> on the header (rotating its arrow) and <code>.hidden</code> on the next
+sibling list (<span class="fp" data-path="scripts/generate-dashboard.sh:825-828">scripts/generate-dashboard.sh:825-828</span>).</li>
+<li><strong>Copy a command</strong> — clicking a <code>.pcmd</code> calls <code>copyCmd()</code>, which writes the
+<code>data-cmd</code> value to the clipboard and flashes the <code>.copied</code> state for 1.5 s
+(<span class="fp" data-path="scripts/generate-dashboard.sh:829-838">scripts/generate-dashboard.sh:829-838</span>).</li>
+<li><strong>Filter Beads</strong> — <code>filterBeads()</code> switches the active status filter and
+<code>filterBeadsPrio()</code> toggles priority filters; cards carry <code>data-bead-status</code>
+and <code>data-bead-priority</code> so the filters can show/hide them
+(<span class="fp" data-path="scripts/generate-dashboard.sh:733-741">scripts/generate-dashboard.sh:733-741</span>).</li>
+<li><strong>Beads task detail modal</strong> — <code>openBeadModal(id)</code> builds a <code>.modal-overlay</code>
+detail view for a Beads task (status, priority, deps, timestamps); close via
+the X, Escape, or a backdrop click
+(<span class="fp" data-path="scripts/generate-dashboard.sh:756-816">scripts/generate-dashboard.sh:756-816</span>).</li>
+<li><strong>Prompt detail modal</strong> — clicking a prompt card calls <code>openModal(slug)</code>,
+which renders the full prompt content for that pipeline step in the same
+<code>.modal-overlay</code> shell (<span class="fp" data-path="scripts/generate-dashboard.sh:693-710">scripts/generate-dashboard.sh:693-710</span>).</li>
+<li><strong>Audit finding filters</strong> — on load, <code>initAuditFilters()</code> finds the
+<code>#build-audit</code> section, reads its <code>data-threshold</code>, and wires the
+<code>[data-filter]</code> buttons to show/hide <code>.finding</code> rows by severity rank
+(<span class="fp" data-path="scripts/generate-dashboard.sh:839-863">scripts/generate-dashboard.sh:839-863</span>).</li>
+</ul>
+<h2 id="the-design-token-system">The design-token system</h2>
+<p><code>lib/dashboard-theme.css</code> defines a shared set of CSS custom properties for
+colors, spacing, sizes, and radii. Component styles should prefer these tokens
+via <code>var(--token)</code> — that is what keeps light and dark mode in lockstep and the
+surface coherent. The contract is "prefer tokens," not "tokens only": the file
+still contains some component-level raw values (e.g. <code>#fff</code>, gradient stop hex
+colors, <code>rgba(...)</code>, and a few one-off pixel values like <code>99px</code>, <code>720px</code>, and
+<code>130px</code>). Promote a raw value to a token when it needs light/dark parity or
+reuse; leave genuinely one-off structural values inline rather than minting a
+single-use token.</p>
+<h3 id="colors-light-dark-parity">Colors — light + dark parity</h3>
+<p>The light palette is declared on <code>:root</code> (<span class="fp" data-path="lib/dashboard-theme.css:11-35">lib/dashboard-theme.css:11-35</span>),
+and every color token has a matching override under <code>[data-theme="dark"]</code>
+(<span class="fp" data-path="lib/dashboard-theme.css:98-120">lib/dashboard-theme.css:98-120</span>). Dark mode is not a filter — backgrounds
+go dramatically darker, text lightens but stays slightly warm, and accents shift
+lighter for contrast on dark surfaces.</p>
+<div class="filter-table"><input type="text" class="filter-input" placeholder="Filter…" aria-label="Filter table rows" disabled>
+<table><thead><tr><th>token</th><th>light</th><th>dark</th><th>role</th></tr></thead><tbody><tr><td><code>--bg</code></td><td><code>#f5f6fa</code></td><td><code>#0f1117</code></td><td>Page background</td></tr><tr><td><code>--bg-card</code></td><td><code>#ffffff</code></td><td><code>#1a1d2e</code></td><td>Card / panel surface</td></tr><tr><td><code>--bg-inset</code></td><td><code>#e8eaf2</code></td><td><code>#141724</code></td><td>Recessed elements (copy buttons, inputs)</td></tr><tr><td><code>--text</code></td><td><code>#1a1d2e</code></td><td><code>#e2e5f0</code></td><td>Primary text</td></tr><tr><td><code>--text-muted</code></td><td><code>#6b7294</code></td><td><code>#7c82a8</code></td><td>Secondary text</td></tr><tr><td><code>--border</code></td><td><code>#dde0ed</code></td><td><code>#2a2f45</code></td><td>Default borders</td></tr><tr><td><code>--accent</code></td><td><code>#4f46e5</code></td><td><code>#818cf8</code></td><td>Primary interactive color</td></tr><tr><td><code>--green</code></td><td><code>#059669</code></td><td><code>#34d399</code></td><td>Completed status</td></tr><tr><td><code>--blue</code></td><td><code>#2563eb</code></td><td><code>#60a5fa</code></td><td>Likely-completed status</td></tr><tr><td><code>--yellow</code></td><td><code>#d97706</code></td><td><code>#fbbf24</code></td><td>Warnings / blocked</td></tr><tr><td><code>--gray</code></td><td><code>#9ca3af</code></td><td><code>#6b7294</code></td><td>Skipped status</td></tr></tbody></table></div>
+<p>Each status color (<code>--green</code>, <code>--blue</code>, <code>--yellow</code>, <code>--gray</code>) also has <code>-bg</code> and
+<code>-border</code> companions used by badges and status dots, so a status reads correctly
+on both card and inset surfaces.</p>
+<div class="callout callout-note"><p>The table above is a high-level subset of the most visible status and surface
+tokens — not the complete set. <code>lib/dashboard-theme.css</code> (and
+<code>docs/design-system.md</code> §2) also define many component-specific semantic tokens
+such as <code>--bg-hover</code>, <code>--text-faint</code>, the <code>--next-*</code>, <code>--progress-*</code>,
+<code>--shadow-*</code>, <code>--accent-hover</code> / <code>--accent-glow</code>, and <code>--border-light</code>. Consult
+the CSS file and §2 for the full system.</p></div>
+<h3 id="spacing-the---sp--scale">Spacing — the <code>--sp-*</code> scale</h3>
+<p>All spacing comes from an 8-step scale on a 4px base
+(<span class="fp" data-path="lib/dashboard-theme.css:63-71">lib/dashboard-theme.css:63-71</span>). There are no ad-hoc margins or paddings;
+layout is composed entirely from these:</p>
+<table><thead><tr><th>token</th><th>value</th><th>typical use</th></tr></thead><tbody><tr><td><code>--sp-1</code></td><td><code>4px</code></td><td>minimal gaps (dot margin)</td></tr><tr><td><code>--sp-2</code></td><td><code>8px</code></td><td>tight gaps (badge padding)</td></tr><tr><td><code>--sp-3</code></td><td><code>12px</code></td><td>card gap, prompt-card padding</td></tr><tr><td><code>--sp-4</code></td><td><code>16px</code></td><td>card inner padding, section gap</td></tr><tr><td><code>--sp-5</code></td><td><code>20px</code></td><td>banner padding</td></tr><tr><td><code>--sp-6</code></td><td><code>24px</code></td><td>section margin, page side padding</td></tr><tr><td><code>--sp-8</code></td><td><code>32px</code></td><td>page top/bottom padding</td></tr><tr><td><code>--sp-10</code></td><td><code>40px</code></td><td>major section separation, footer</td></tr></tbody></table>
+<h3 id="typography-radius-layout">Typography, radius &#x26; layout</h3>
+<p>The font stacks are system-only (no web fonts): <code>--font-sans</code> for body and
+headings, <code>--font-mono</code> for commands, counts, and step numbers
+(<span class="fp" data-path="lib/dashboard-theme.css:74-75">lib/dashboard-theme.css:74-75</span>). Sizes run on a <code>--text-xs</code> … <code>--text-2xl</code>
+scale (<span class="fp" data-path="lib/dashboard-theme.css:76-81">lib/dashboard-theme.css:76-81</span>), paired with <code>--lh-*</code> line heights,
+<code>--fw-*</code> weights, and <code>--ls-*</code> letter-spacing tokens. Surfaces use <code>--radius</code>
+(10px) for cards/panels and <code>--radius-sm</code> (6px) for buttons and code blocks
+(<span class="fp" data-path="lib/dashboard-theme.css:26">lib/dashboard-theme.css:26</span>); content is centered within <code>--max-w</code> (960px)
+(<span class="fp" data-path="lib/dashboard-theme.css:93">lib/dashboard-theme.css:93</span>). Depth comes from a four-step shadow scale,
+with <code>--shadow-lg</code> reserved for modals and overlays
+(<span class="fp" data-path="lib/dashboard-theme.css:61">lib/dashboard-theme.css:61</span>).</p>
+<h2 id="customizing-the-dashboard-safely">Customizing the dashboard safely</h2>
+<p>The dashboard's coherence is enforced by convention, not by a build step — so the
+rules in <code>docs/design-system.md</code> are load-bearing (with the §6.1 caveat noted
+below). Follow the add-a-token / add-a-component flow and stay inside the token
+system.</p>
+<div class="callout callout-warning"><p><strong>Two rules that are never optional.</strong> (1) <strong>Prefer tokens for anything that
+needs light/dark parity</strong> — never hardcode a color, theme-dependent value, or
+font name in a component style; if you need a value that doesn't exist, add a
+<em>token</em> first. (Purely structural one-offs may stay inline — see the token
+section above.) (2) <strong>Always ship both modes</strong> —
+every new color token needs a <code>:root</code> value <em>and</em> a <code>[data-theme="dark"]</code>
+override, and every change must be checked in light <em>and</em> dark. Skipping the dark
+override leaves the token undefined in dark mode and breaks the surface.</p></div>
+<p>To add a token: declare it on <code>:root</code> in the light section of
+<code>lib/dashboard-theme.css</code>, add the dark override under <code>[data-theme="dark"]</code>,
+then reference it as <code>var(--token)</code>. Note that <code>docs/design-system.md</code> §6.1 is
+stale here — it still says to add the dark override to a
+<code>@media (prefers-color-scheme: dark)</code> block, but no such block exists in
+<code>lib/dashboard-theme.css</code>; the dark tokens live only under the <code>[data-theme="dark"]</code>
+attribute selector. Follow the code, not §6.1. To add a component: add its styles to the right section of the
+theme file, reuse existing tokens (add new ones first if needed), wire its markup
+into the generator JS, and document it in §3. New components should reuse
+established patterns — for example, collapsible sections reuse the same
+<code>.phase-hdr</code> + <code>togglePhase()</code> mechanism as pipeline phases, and detail views
+reuse <code>.modal-overlay</code>.</p>
+<p>Also avoid: <code>!important</code> (restructure selectors instead), any second theme
+mechanism (the <code>[data-theme]</code> toggle is the only one), and external resource
+references — the generated HTML must stay self-contained. Dark mode is driven by
+the inline bootstrap that reads <code>localStorage.getItem('scaffold-theme')</code>, falling
+back to <code>prefers-color-scheme</code> on first visit
+(<span class="fp" data-path="scripts/generate-dashboard.sh:438">scripts/generate-dashboard.sh:438</span>), and the <code>.theme-toggle</code> button flips
+the <code>[data-theme]</code> attribute and persists the choice via
+<code>localStorage.setItem('scaffold-theme', …)</code>
+(<span class="fp" data-path="scripts/generate-dashboard.sh:817-823">scripts/generate-dashboard.sh:817-823</span>).</p>
+<h2 id="visual-testing">Visual testing</h2>
+<p>Reference guides are verified manually with a screenshot, and the dashboard
+itself is verified the same way: after any change to
+<code>scripts/generate-dashboard.sh</code>, <code>lib/dashboard-theme.css</code>, or a dashboard test,
+render it and look at it in a browser. There is no pixel-diff gate — a human (or
+an agent driving Playwright MCP) confirms the rendering.</p>
+<pre><code class="language-bash">make dashboard-test   # writes tests/screenshots/dashboard-test.html
+</code></pre>
+<p>Then drive Playwright MCP over the generated file: <code>browser_navigate</code> to its
+<code>file://</code> path, <code>browser_resize</code> to 1280×800 then 375×812, take a
+<code>browser_take_screenshot</code> at each. For dark mode, don't rely on emulating
+<code>prefers-color-scheme</code> after the page has loaded — the inline bootstrap reads it
+only once, so the page stays on whatever <code>[data-theme]</code> is already set. Instead,
+either set <code>localStorage('scaffold-theme', 'dark')</code> and reload, or click the
+<code>.theme-toggle</code> button; then confirm
+<code>document.documentElement.dataset.theme === 'dark'</code> <strong>before</strong> capturing the
+dark screenshots (and clear/set the key back for light shots). Also exercise the
+interactive bits (expand/collapse a phase, a Beads filter, a modal), and
+<code>browser_snapshot</code> to sanity-check accessibility.</p>
+<p>The minimum coverage for any dashboard change is desktop + mobile in both light
+and dark mode, plus the interactive elements, compared against the committed
+baselines.</p>
+<table><thead><tr><th>Path</th><th>Role</th></tr></thead><tbody><tr><td><code>tests/screenshots/dashboard-test.html</code></td><td>Generated test fixture (from <code>make dashboard-test</code>)</td></tr><tr><td><code>tests/screenshots/baseline/</code></td><td>Committed baselines</td></tr><tr><td><code>tests/screenshots/current/</code></td><td>New screenshots (gitignored); name <code>{feature}_{viewport}_{state}.png</code></td></tr></tbody></table>
+<p>Update a baseline only for an intentional visual change — copy the new shot from
+<code>current/</code> to <code>baseline/</code> and commit it. Full workflow and naming live in
+<code>docs/tdd-standards.md</code> §7 and the design rules in <code>docs/design-system.md</code>.</p></main>
+</div>
+<script>(function(){
+  var LS_KEY = 'guide-theme';
+  function applyTheme(t) {
+    document.documentElement.setAttribute('data-theme', t);
+  }
+  document.addEventListener('DOMContentLoaded', function() {
+    // ─── Theme toggle ────────────────────────────────────────────────────────
+    document.querySelectorAll('[data-action="theme"]').forEach(function(btn) {
+      btn.addEventListener('click', function() {
+        var current = document.documentElement.getAttribute('data-theme');
+        var next = current === 'dark' ? 'light' : 'dark';
+        applyTheme(next);
+        try { localStorage.setItem(LS_KEY, next); } catch(e) {}
+      });
+    });
+    // ─── Mobile nav ──────────────────────────────────────────────────────────
+    document.querySelectorAll('[data-action="nav"]').forEach(function(btn) {
+      btn.addEventListener('click', function() {
+        var rail = document.querySelector('.rail');
+        if (rail) rail.classList.toggle('open');
+      });
+    });
+    // ─── Copy buttons ─────────────────────────────────────────────────────────
+    document.querySelectorAll('pre').forEach(function(pre) {
+      if (!pre.parentNode) return;
+      var wrapper = document.createElement('div');
+      wrapper.className = 'code';
+      pre.parentNode.insertBefore(wrapper, pre);
+      wrapper.appendChild(pre);
+      var btn = document.createElement('button');
+      btn.className = 'copy-btn';
+      btn.textContent = 'Copy';
+      btn.addEventListener('click', function() {
+        var text = pre.textContent || '';
+        if (navigator.clipboard && navigator.clipboard.writeText) {
+          navigator.clipboard.writeText(text).then(function() {
+            btn.textContent = 'Copied';
+            setTimeout(function() { btn.textContent = 'Copy'; }, 1200);
+          }, function() {
+            btn.textContent = 'Copy';
+          });
+        }
+      });
+      wrapper.insertBefore(btn, pre);
+    });
+    // ─── Tabs ─────────────────────────────────────────────────────────────────
+    document.querySelectorAll('.tabs').forEach(function(group) {
+      group.querySelectorAll('.tab-btn').forEach(function(btn) {
+        btn.addEventListener('click', function() {
+          var idx = btn.getAttribute('data-tab');
+          group.querySelectorAll('.tab-btn').forEach(function(b) {
+            b.classList.toggle('active', b === btn);
+          });
+          group.querySelectorAll('.tabpane').forEach(function(pane) {
+            pane.classList.toggle('active', pane.getAttribute('data-tab') === idx);
+          });
+        });
+      });
+    });
+    // ─── Filter tables ────────────────────────────────────────────────────────
+    document.querySelectorAll('.filter-input').forEach(function(input) {
+      input.addEventListener('input', function() {
+        var q = input.value.toLowerCase();
+        var container = input.closest('.filter-table');
+        if (!container) return;
+        container.querySelectorAll('tbody tr').forEach(function(row) {
+          var text = (row.textContent || '').toLowerCase();
+          row.style.display = text.includes(q) ? '' : 'none';
+        });
+      });
+    });
+    // ─── Scrollspy ────────────────────────────────────────────────────────────
+    if (typeof IntersectionObserver === 'undefined') return;
+    var headings = document.querySelectorAll('h2[id],h3[id]');
+    if (!headings.length) return;
+    var observer = new IntersectionObserver(function(entries) {
+      entries.forEach(function(entry) {
+        if (!entry.isIntersecting) return;
+        var id = entry.target.getAttribute('id');
+        document.querySelectorAll('.toc a').forEach(function(a) {
+          a.classList.toggle('active', a.getAttribute('href') === '#' + id);
+        });
+      });
+    }, { rootMargin: '0px 0px -70% 0px', threshold: 0 });
+    headings.forEach(function(h) { observer.observe(h); });
+  });
+})();</script>
+</body>
+</html>