diff --git a/BACKLOG.md b/BACKLOG.md index 40836b9..91cc658 100644 --- a/BACKLOG.md +++ b/BACKLOG.md @@ -105,7 +105,7 @@ If any seat would be confused, the component fails. ### Guide (`/guide`) -- TOC / sticky nav — ○ ○ ○ +- TOC / sticky nav — ● ● ● — flat 12-item list grouped into Concepts · Onboarding · Reference buckets so first-timer sees the onboarding arc at a glance. Per-item `title=` tooltip (113–134 chars) previews each section's content (e.g. Step 3 → "Implement the canonical generate(spec, llm) -> bytes contract returning a STEP file. Two reference patterns in examples/."). Clicks now `history.replaceState` the URL hash so refresh + back-button + share-link all round-trip (deep-link refresh-proofing item). Modifier-key click (cmd/ctrl/shift/alt) honors browser default so links open in new tab. (`QuickstartGuide.tsx` L271–425) - "The three categories" section — ○ ○ ○ - "Step 1 — Set up" → "Step 5 — Submit" — ○ ○ ○ - "Whitelisted models" — ○ ○ ○ diff --git a/src/components/QuickstartGuide.tsx b/src/components/QuickstartGuide.tsx index 466c30d..a14d6fe 100644 --- a/src/components/QuickstartGuide.tsx +++ b/src/components/QuickstartGuide.tsx @@ -268,21 +268,104 @@ function MarginDecayChart() { ); } -const TOC_ITEMS = [ - { id: "categories", label: "Three categories" }, - { id: "setup", label: "Step 1 — Set up" }, - { id: "explore", label: "Step 2 — Explore" }, - { id: "write", label: "Step 3 — Write agent" }, - { id: "models", label: "Whitelisted models", indent: true }, - { id: "patterns", label: "Agent patterns", indent: true }, - { id: "fea", label: "What is FEA?", indent: true }, - { id: "eval", label: "Step 4 — Eval locally" }, - { id: "submit", label: "Step 5 — Submit" }, - { id: "api", label: "API reference" }, - { id: "rewards", label: "How rewards work" }, - { id: "anti-gaming", label: "Anti-gaming" }, +type TocItem = { id: string; label: string; indent?: boolean; preview: string }; +type TocGroup = { heading: string; items: TocItem[] }; + +const TOC_GROUPS: TocGroup[] = [ + { + heading: "Concepts", + items: [ + { + id: "categories", + label: "Three categories", + preview: + "Mass · Stiffness/Weight · Deflection — what each round optimizes, the unit it scores, and the direction (minimize/maximize) that wins.", + }, + ], + }, + { + heading: "Onboarding", + items: [ + { + id: "setup", + label: "Step 1 — Set up", + preview: + "Clone the repo, install Python 3.11+, optional Docker Desktop to run evals in the same image CI uses (forge-eval:latest).", + }, + { + id: "explore", + label: "Step 2 — Explore", + preview: + "List active specs via the API, pick an unclaimed one as your first target, and read its constraints + load + bolt pattern.", + }, + { + id: "write", + label: "Step 3 — Write agent", + preview: + "Implement the canonical generate(spec, llm) -> bytes contract returning a STEP file. Two reference patterns in examples/.", + }, + { + id: "models", + label: "Whitelisted models", + indent: true, + preview: + "18 cheap, on-par OSS models. The harness — not you — picks which one runs your agent via the FORGE_MODEL env var.", + }, + { + id: "patterns", + label: "Agent patterns", + indent: true, + preview: + "Pattern A — deterministic geometry (no LLM). Pattern B — Observe / Plan / Act using llm.chat() to drive shape decisions.", + }, + { + id: "fea", + label: "What is FEA?", + indent: true, + preview: + "Finite element analysis — how the harness physically validates your part survives the spec's applied load before scoring.", + }, + { + id: "eval", + label: "Step 4 — Eval locally", + preview: + "Run the 4-stage pipeline (image parity → agent gen → geometry → FEA, plus similarity gate for ranked submissions) before opening a PR.", + }, + { + id: "submit", + label: "Step 5 — Submit", + preview: + "Open a PR with the canonical `passed` and `optimization` labels — CI re-runs the same eval, then the leaderboard updates.", + }, + ], + }, + { + heading: "Reference", + items: [ + { + id: "api", + label: "API reference", + preview: + "21 REST endpoints grouped by intent (Rounds · Specs · SOTA · Leaderboards · Submissions · Eval · Health). Swagger try-it-out at /docs.", + }, + { + id: "rewards", + label: "How rewards work", + preview: + "Breadth-normalized percentile rank across all 3 categories. Specialists lose to generalists; new #1 must beat by a decaying margin.", + }, + { + id: "anti-gaming", + label: "Anti-gaming", + preview: + "Stage 1 image parity (same Docker image) · Stage 4 similarity gate (anti-copy) · ephemeral-TEE seam for tamper-proof inference.", + }, + ], + }, ]; +const TOC_ITEMS: TocItem[] = TOC_GROUPS.flatMap((g) => g.items); + function TableOfContents({ onItemClick }: { onItemClick?: () => void }) { const [activeId, setActiveId] = useState(""); const observerRef = useRef(null); @@ -306,25 +389,40 @@ function TableOfContents({ onItemClick }: { onItemClick?: () => void }) { }, []); return ( -