@capagents/forgeqe 1.1.2 → 1.1.4

package/src/capabilities/guide.ts

@@ -15,6 +15,9 @@ import { describeRequirement } from "./status.ts"
 const root = path.resolve(import.meta.dir, "..", "..")
 export const GUIDE_FILE = path.join(root, "docs", "user-guide.html")
 const THEME_SOURCE = path.join(root, "docs", "security-data-flow.html")
+const GUIDE_LOGO_LIGHT_FILE = path.join(root, "assets", "forgeqe-logo.png")
+const GUIDE_LOGO_DARK_FILE = path.join(root, "assets", "forgeqe-logo-white.png")
+const PARTNER_LOGO_FILE = path.join(root, "assets", "capgemini-logo.svg")
 
 /** Chapters that are not a capability area: which HOW_TO_USE sections they hold, in order. */
 const START: DocRef[] = ["What you need to run", "Quick start", "1. Install", "2. Scaffold config"].map((heading) => ({ doc: "HOW_TO_USE.md", heading }))
@@ -44,9 +47,11 @@ function sharedLook() {
   const page = readFileSync(THEME_SOURCE, "utf8")
   const tokens = page.match(/\/\* =+ tokens =+ \*\/[\s\S]*?(?=\/\* =+ base =+ \*\/)/)?.[0]
   const favicon = page.match(/<link rel="icon"[^>]*>/)?.[0]
-  const logo = page.match(/const MARK = h\("img", \{ src: "(data:image\/png;base64,[A-Za-z0-9+/=]+)"/)?.[1]
-  if (!tokens || !favicon || !logo) throw new Error(`${THEME_SOURCE} no longer has its tokens block, favicon, or MARK logo where the guide reads them.`)
-  return { tokens: tokens.trim(), favicon, logo }
+  const logo = `data:image/png;base64,${readFileSync(GUIDE_LOGO_LIGHT_FILE).toString("base64")}`
+  const logoDark = `data:image/png;base64,${readFileSync(GUIDE_LOGO_DARK_FILE).toString("base64")}`
+  const partnerLogo = `data:image/svg+xml;base64,${Buffer.from(readFileSync(PARTNER_LOGO_FILE, "utf8")).toString("base64")}`
+  if (!tokens || !favicon) throw new Error(`${THEME_SOURCE} no longer has its tokens block or favicon where the guide reads them.`)
+  return { tokens: tokens.trim(), favicon, logo, logoDark, partnerLogo }
 }
 
 /** Which section renders where: the first place that names it; later places link to it. */
@@ -175,8 +180,25 @@ export function renderGuide(): string {
     { id: "reference", title: "Reference", note: "MCP, tuning, logs, environment variables, and every command", body: ids(REFERENCE).map((id) => docBlock(id, sections, placement, 3)).join("\n") },
   ]
 
-  const rail = chapters
-    .map((c, i) => `<li><a href="#${c.id}"><span class="n">${String(i + 1).padStart(2, "0")}</span><span class="t">${esc(c.title)}</span><span class="d">${esc(c.note)}</span></a></li>`)
+  const railGroups = [
+    { label: "Guide", items: chapters.filter((c) => ["overview", "get-started", "using"].includes(c.id)) },
+    { label: "Capability areas", items: chapters.filter((c) => c.id.startsWith("area-")) },
+    { label: "Reference", items: chapters.filter((c) => c.id === "reference") },
+  ]
+    .filter((g) => g.items.length > 0)
+    .map((g) => [
+      `<section class="rail-group">`,
+      `<h2 class="rail-title mono">${esc(g.label)}</h2>`,
+      `<ol class="chapters">`,
+      g.items
+        .map((c) => {
+          const n = String(chapters.indexOf(c) + 1).padStart(2, "0")
+          return `<li><a href="#${c.id}"><span class="n">${n}</span><span class="t">${esc(c.title)}</span><span class="d">${esc(c.note)}</span></a></li>`
+        })
+        .join("\n"),
+      `</ol>`,
+      `</section>`,
+    ].join("\n"))
     .join("\n")
 
   return `<!DOCTYPE html>
@@ -191,7 +213,7 @@ export function renderGuide(): string {
 ${look.favicon}
 <link rel="preconnect" href="https://fonts.googleapis.com">
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500&family=Montserrat:ital,wght@0,400;0,500;0,600;0,700;0,800;1,700;1,800&display=swap" rel="stylesheet">
+<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500&family=Plus+Jakarta+Sans:wght@400;500;600;700;800&display=swap" rel="stylesheet">
 <style>
 ${look.tokens}
 ${GUIDE_CSS}
@@ -200,23 +222,39 @@ ${GUIDE_CSS}
 <body>
 <a class="skip" href="#panel">Skip to the guide</a>
 <div id="app">
-<header class="mast">
-<div class="mark"><img src="${look.logo}" alt=""><b>ForgeQE</b></div>
-<span class="sep" aria-hidden="true"></span>
-<div class="ttl"><h1>User guide</h1><span class="sub">How to use ForgeQE, and every feature in detail</span></div>
-<div class="right"><button class="theme" type="button" aria-label="Switch theme" title="Switch theme">${SUN}${MOON}</button></div>
-</header>
+<div class="shell">
 <nav class="rail" aria-label="Chapters">
-<div class="cap mono">Contents</div>
-<ol class="chapters">
-${rail}
-</ol>
+<div class="rail-inner">
+<div class="side-brand">
+<div class="mark"><img class="logo light" src="${look.logo}" alt="ForgeQE AI"><img class="logo dark" src="${look.logoDark}" alt="" aria-hidden="true"></div>
+<label class="search-wrap" for="rail-search"><span class="search-icon" aria-hidden="true">⌕</span><input id="rail-search" class="rail-search" type="search" placeholder="Search sections" aria-label="Search sections"></label>
+</div>
+${railGroups}
+</div>
 </nav>
+<header class="mast">
+<nav class="tabs" aria-label="Guide views"><span class="tab is-active" aria-current="page">Docs</span><button class="tab" type="button" disabled>Changelog</button></nav>
+<div class="right"><img class="partner-logo" src="${look.partnerLogo}" alt="Capgemini"><button class="theme" type="button" aria-label="Switch theme" title="Switch theme">${SUN}${MOON}</button></div>
+</header>
 <main class="panel" id="panel" tabindex="-1">
 <div class="page">
+<header class="pagehead">
+<nav class="crumbs" aria-label="Breadcrumb"><a href="#overview">Docs</a><span aria-hidden="true">/</span><span aria-current="page">User guide</span></nav>
+<span class="kicker mono">ForgeQE guide</span>
+<h1>User guide</h1>
+<p>Install ForgeQE, learn the shell, and find every capability with its requirements, prompts, and limits in one place.</p>
+</header>
 ${chapters.map((c, i) => chapter(i + 1, c)).join("\n")}
 </div>
 </main>
+<aside class="toc" aria-label="On this page">
+<div class="toc-box">
+<span class="toc-kicker mono">On this page</span>
+<p class="toc-current" id="toc-current">Overview</p>
+<ol class="toc-links" id="toc-links"></ol>
+</div>
+</aside>
+</div>
 </div>
 <script>
 ${GUIDE_JS}
@@ -229,175 +267,248 @@ ${GUIDE_JS}
 const SUN = `<svg class="sun" viewBox="0 0 16 16" aria-hidden="true"><circle cx="8" cy="8" r="3" fill="none" stroke="currentColor" stroke-width="1.4"/><path d="M8 1v2M8 13v2M1 8h2M13 8h2M3 3l1.4 1.4M11.6 11.6 13 13M3 13l1.4-1.4M11.6 4.4 13 3" stroke="currentColor" stroke-width="1.4"/></svg>`
 const MOON = `<svg class="moon" viewBox="0 0 16 16" aria-hidden="true"><path d="M13 10.2A5.5 5.5 0 0 1 5.8 3a5.5 5.5 0 1 0 7.2 7.2Z" fill="none" stroke="currentColor" stroke-width="1.4"/></svg>`
 
-/** The shared shell (masthead, rail, panel, chapter head, card) as docs/security-data-flow.html writes it, plus the guide's reading styles. */
+/** A docs-style shell for the generated guide, using the shared documentation tokens and logo. */
 const GUIDE_CSS = `
 /* ============ base ============ */
 *{box-sizing:border-box}
 html,body{height:100%}
 html{-webkit-text-size-adjust:100%}
-body{margin:0;background:var(--bg);color:var(--ink);font-family:var(--sans);font-size:12.75px;line-height:1.5;-webkit-font-smoothing:antialiased}
+:root{
+  --sans:'Plus Jakarta Sans',ui-sans-serif,'Segoe UI',Arial,sans-serif;
+  --display:'Plus Jakarta Sans',ui-sans-serif,'Segoe UI',Arial,sans-serif;
+  --mono:'Plus Jakarta Sans',ui-sans-serif,'Segoe UI',Arial,sans-serif;
+  --guide-bg:#F8FAFC;
+  --guide-panel:#FFFFFF;
+  --guide-panel-2:#FCFDFE;
+  --guide-line:#E2E8F0;
+  --guide-text:#020617;
+  --guide-muted:#475569;
+  --guide-soft:#F1F5F9;
+  --guide-accent:#0369A1;
+}
+:root[data-theme="dark"]{
+  --guide-bg:#08111F;
+  --guide-panel:#0E1726;
+  --guide-panel-2:#101B2C;
+  --guide-line:#22324A;
+  --guide-text:#E8EEF8;
+  --guide-muted:#9FB0C7;
+  --guide-soft:#132034;
+  --guide-accent:#60A5FA;
+}
+@media (prefers-color-scheme:dark){
+  :root:not([data-theme="light"]){
+    --guide-bg:#08111F;
+    --guide-panel:#0E1726;
+    --guide-panel-2:#101B2C;
+    --guide-line:#22324A;
+    --guide-text:#E8EEF8;
+    --guide-muted:#9FB0C7;
+    --guide-soft:#132034;
+    --guide-accent:#60A5FA;
+  }
+}
+body{margin:0;background:var(--guide-bg);color:var(--guide-text);font-family:var(--sans);font-size:13.5px;line-height:1.65;-webkit-font-smoothing:antialiased}
 button{font:inherit;color:inherit}
-:focus-visible{outline:2px solid var(--focus);outline-offset:2px}
-code{font-family:var(--codefont);font-size:.88em;background:var(--code);padding:0 4px;border:1px solid var(--hair);border-radius:2px;white-space:nowrap}
+:focus-visible{outline:2px solid var(--guide-accent);outline-offset:2px}
+code{font-family:var(--codefont);font-size:.92em;font-weight:500;background:var(--guide-panel);color:var(--guide-text);padding:2px 7px;border:1px solid var(--guide-line);border-radius:8px;white-space:nowrap}
 p{margin:0}
-h2,h3{margin:0}
-a{color:var(--ink);text-decoration:underline;text-decoration-color:var(--rule);text-underline-offset:2px}
-a:hover{text-decoration-color:var(--ink)}
-.muted{color:var(--muted)}
-.mono{font-family:var(--mono);font-size:10px;letter-spacing:.09em;text-transform:uppercase;font-weight:500}
-.skip{position:absolute;left:-9999px;top:8px;z-index:20;background:var(--card);color:var(--ink);padding:6px 10px;border:1px solid var(--ink)}
+h1,h2,h3{margin:0}
+a{color:var(--guide-accent);text-decoration:underline;text-decoration-color:color-mix(in srgb,var(--guide-accent) 35%,transparent);text-underline-offset:2px}
+a:hover{text-decoration-color:var(--guide-accent)}
+.muted{color:var(--guide-muted)}
+.mono{font-family:var(--mono);font-size:10px;letter-spacing:.09em;text-transform:uppercase;font-weight:700}
+.skip{position:absolute;left:-9999px;top:8px;z-index:20;background:var(--guide-panel);color:var(--guide-text);padding:6px 10px;border:1px solid var(--guide-line)}
 .skip:focus{left:8px}
 
 /* ============ shell ============ */
-#app{height:100vh;height:100dvh;display:grid;grid-template-columns:216px minmax(0,1fr);grid-template-rows:auto minmax(0,1fr)}
-.mast{grid-column:1/-1;display:flex;align-items:center;gap:16px;height:52px;padding:0 20px;background:var(--brand);color:var(--brand-ink)}
-.mark{display:flex;align-items:center;gap:9px;flex:none}
-.mark img{display:block;width:30px;height:30px;padding:2px;background:var(--brand-ink);border-radius:7px}
-.mark b{font-family:var(--sans);font-weight:700;font-size:14px;letter-spacing:-.01em}
-.mast .sep{width:1px;height:22px;background:color-mix(in srgb,var(--brand-ink) 40%,transparent);flex:none}
-.mast .ttl{display:flex;align-items:baseline;gap:12px;min-width:0}
-.mast h1{font-family:var(--display);font-weight:700;font-size:16px;line-height:1;margin:0;white-space:nowrap;letter-spacing:-.005em}
-.mast .sub{color:var(--brand-soft);font-size:11.5px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+#app{height:100vh;height:100dvh}
+.mast{grid-column:2 / 4;grid-row:1;display:flex;align-items:center;justify-content:space-between;gap:18px;height:52px;padding:0 24px;background:var(--guide-panel);border-bottom:1px solid var(--guide-line)}
+.mark{display:flex;align-items:center;flex:none}
+.mark .logo{display:block;height:36px;width:auto;max-width:196px}
+.mark .logo.dark{display:none}
+.tabs{display:flex;align-items:center;gap:16px}
+.tab{border:0;background:transparent;color:var(--guide-muted);padding:0 0 12px;border-radius:0;font-size:12px;font-weight:600;line-height:1;cursor:default;border-bottom:1px solid transparent}
+.tab.is-active{color:var(--guide-text);box-shadow:none;border-bottom-color:var(--guide-accent)}
+.tab:disabled{opacity:.7}
 .mast .right{margin-left:auto;display:flex;align-items:center;gap:14px;flex:none}
-.theme{display:grid;place-items:center;width:30px;height:30px;border:1px solid color-mix(in srgb,var(--brand-ink) 50%,transparent);background:transparent;cursor:pointer;border-radius:0;color:var(--brand-ink)}
-.theme:hover{background:var(--brand-ink);color:var(--brand);border-color:var(--brand-ink)}
-.mast :focus-visible{outline-color:var(--brand-ink)}
+.partner-logo{display:block;height:20px;width:auto;opacity:.98}
+.theme{display:grid;place-items:center;width:34px;height:34px;border:1px solid var(--guide-line);background:var(--guide-panel);cursor:pointer;border-radius:12px;color:var(--guide-text)}
+.theme:hover{border-color:color-mix(in srgb,var(--guide-accent) 35%,var(--guide-line));background:var(--guide-soft)}
 .theme svg{width:14px;height:14px}
 .theme .sun{display:none}
+:root[data-theme="dark"] .mark .logo.light{display:none}
+:root[data-theme="dark"] .mark .logo.dark{display:block}
 :root[data-theme="dark"] .theme .sun{display:block}
 :root[data-theme="dark"] .theme .moon{display:none}
 @media (prefers-color-scheme:dark){
+  :root:not([data-theme="light"]) .mark .logo.light{display:none}
+  :root:not([data-theme="light"]) .mark .logo.dark{display:block}
   :root:not([data-theme="light"]) .theme .sun{display:block}
   :root:not([data-theme="light"]) .theme .moon{display:none}
 }
-
-/* chapter rail */
-.rail{grid-row:2;border-right:1px solid var(--hair);background:var(--band);display:flex;flex-direction:column;min-height:0;overflow:auto}
-.rail .cap{padding:16px 18px 8px;color:var(--muted)}
-.chapters{list-style:none;margin:0;display:flex;flex-direction:column;padding:0 0 12px}
-.chapters a{position:relative;display:grid;grid-template-columns:28px minmax(0,1fr);gap:0 6px;text-decoration:none;border-top:1px solid var(--hair);padding:11px 16px 11px 18px;color:var(--muted)}
-.chapters li:last-child a{border-bottom:1px solid var(--hair)}
-.chapters .n{font-family:var(--mono);font-size:10.5px;font-weight:600;padding-top:2px;color:var(--muted)}
-.chapters .t{font-weight:600;font-size:12.5px;color:var(--ink2);line-height:1.3}
-.chapters .d{grid-column:2;font-size:11px;line-height:1.4;margin-top:2px}
-.chapters a::before{content:"";position:absolute;left:0;top:-1px;bottom:-1px;width:3px;background:var(--ink);transform:scaleY(0);transform-origin:top;transition:transform .25s ease}
-.chapters a:hover{background:var(--card)}
-.chapters a:hover .t{color:var(--ink)}
-.chapters a[aria-current]{background:var(--card);color:var(--ink2)}
-.chapters a[aria-current] .t,.chapters a[aria-current] .n{color:var(--ink)}
+.shell{height:100%;min-height:0;display:grid;grid-template-columns:214px minmax(0,1fr) 188px;grid-template-rows:auto minmax(0,1fr);gap:0}
+
+/* left rail */
+.rail,.toc{min-height:0;overflow:auto}
+.rail{grid-column:1;grid-row:1 / 3;background:var(--guide-panel);border-right:1px solid var(--guide-line)}
+.rail-inner{padding:14px 14px 28px}
+.side-brand{display:flex;flex-direction:column;gap:18px;margin-bottom:18px;padding:8px 6px 4px}
+.side-brand-copy .eyebrow{color:var(--guide-accent)}
+.search-wrap{display:flex;align-items:center;gap:8px;height:36px;padding:0 10px;background:var(--guide-panel);border:1px solid var(--guide-line);border-radius:10px}
+.search-icon{font-size:14px;line-height:1;color:#94A3B8}
+.rail-search{width:100%;border:0;background:transparent;padding:0;font:inherit;color:var(--guide-text)}
+.rail-search::placeholder{color:#94A3B8}
+.rail-search:focus{outline:0}
+.rail-group+.rail-group{margin-top:20px}
+.rail-title{margin:0 0 10px;color:var(--guide-muted);font-size:9.5px}
+.chapters{list-style:none;margin:0;padding:0;display:flex;flex-direction:column}
+.chapters li+li{margin-top:2px}
+.chapters a{position:relative;display:grid;grid-template-columns:22px minmax(0,1fr);gap:0 8px;padding:6px 8px 6px 12px;border-radius:8px;text-decoration:none;color:var(--guide-muted);transition:background-color .18s ease}
+.chapters .n{font-family:var(--mono);font-size:10px;padding-top:2px;color:#94A3B8}
+.chapters .t{font-weight:500;font-size:12px;line-height:1.35;color:var(--guide-muted)}
+.chapters .d{display:none}
+.chapters a::before{content:"";position:absolute;left:0;top:7px;bottom:7px;width:2px;border-radius:999px;background:var(--guide-accent);transform:scaleY(0);transform-origin:top;transition:transform .18s ease}
+.chapters a:hover{background:var(--guide-panel-2)}
+.chapters a:hover .t{color:var(--guide-text)}
+.chapters a[aria-current]{background:transparent;box-shadow:none}
+.chapters a[aria-current] .t,.chapters a[aria-current] .n{color:var(--guide-text);font-weight:600}
 .chapters a[aria-current]::before{transform:scaleY(1)}
-.chapters a:focus-visible{outline-offset:-2px}
+
+/* right toc */
+.toc{grid-column:3;grid-row:2;padding:14px 16px 20px;background:transparent;border-left:1px solid var(--guide-line)}
+.toc-box{position:sticky;top:0;display:flex;flex-direction:column;gap:10px;padding:6px 0 0;background:transparent;border:0;border-radius:0;box-shadow:none}
+.toc-kicker{color:var(--guide-muted)}
+.toc-current{font-weight:700;font-size:13px;line-height:1.35;color:var(--guide-text)}
+.toc-links{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:2px}
+.toc-links a{display:block;padding:4px 0 4px 10px;border-left:2px solid transparent;font-size:11.5px;line-height:1.45;color:var(--guide-muted);text-decoration:none}
+.toc-links a:hover{color:var(--guide-text)}
+.toc-links a[aria-current]{border-left-color:var(--guide-accent);color:var(--guide-text);font-weight:600}
 
 /* content */
-.panel{grid-row:2;min-width:0;min-height:0;overflow:auto;padding:14px 22px 18px;scroll-behavior:smooth}
-.page{max-width:920px;margin:0 auto;display:flex;flex-direction:column;gap:36px;padding-bottom:40vh}
-.chapter{display:flex;flex-direction:column;gap:16px;scroll-margin-top:8px}
-.chead{display:flex;align-items:baseline;gap:12px;flex-wrap:wrap;padding-bottom:9px;border-bottom:1px solid var(--hair)}
-.chead .mono{color:var(--muted)}
-.chead h2{font-family:var(--display);font-weight:700;font-size:20px;line-height:1.1;letter-spacing:-.01em}
-.chead p{color:var(--muted);font-size:12px;flex:1 1 280px}
+.panel{grid-column:2;grid-row:2;min-width:0;min-height:0;overflow:auto;padding:0 16px 40px;scroll-behavior:smooth}
+.page{max-width:980px;margin:0 auto;display:flex;flex-direction:column;gap:56px;padding:28px 24px 28vh;background:transparent;border:0;border-radius:0;box-shadow:none}
+.pagehead{display:flex;flex-direction:column;gap:12px;padding:2px 0 4px}
+.crumbs{display:flex;align-items:center;gap:8px;font-size:12px;color:var(--guide-muted)}
+.crumbs a{text-decoration:none;color:var(--guide-accent);font-weight:600}
+.crumbs span[aria-current="page"]{color:var(--guide-muted)}
+.pagehead .kicker{color:var(--guide-accent)}
+.pagehead h1{font-family:var(--display);font-weight:800;font-size:clamp(34px,3.2vw,46px);line-height:1;letter-spacing:-.035em;color:var(--guide-text)}
+.pagehead p{max-width:60ch;color:var(--guide-muted);font-size:15px;line-height:1.72}
+.chapter{display:flex;flex-direction:column;gap:28px;scroll-margin-top:20px}
+.chead{display:flex;flex-direction:column;gap:7px;padding-bottom:16px;border-bottom:1px solid var(--guide-line)}
+.chead .mono{color:var(--guide-accent)}
+.chead h2{font-family:var(--display);font-weight:750;font-size:30px;line-height:1.06;letter-spacing:-.03em;color:var(--guide-text)}
+.chead p{color:var(--guide-muted);font-size:14.5px;max-width:58ch}
 
 /* overview */
-.lead{font-size:13.5px;line-height:1.6;color:var(--ink2)}
-.band-title{font-family:var(--display);font-weight:700;font-size:15.5px;line-height:1.15;margin-top:6px}
-.area{display:grid;grid-template-columns:140px minmax(0,1fr);gap:8px 16px;border-top:1px solid var(--hair);padding-top:10px}
-.area-name{text-decoration:none;color:var(--org);padding-top:2px}
+.lead{font-size:14.75px;line-height:1.78;color:var(--guide-muted)}
+.band-title{font-family:var(--display);font-weight:700;font-size:19px;line-height:1.15;margin-top:12px;color:var(--guide-text)}
+.area{display:grid;grid-template-columns:150px minmax(0,1fr);gap:12px 18px;border-top:1px solid var(--guide-line);padding-top:16px}
+.area-name{text-decoration:none;color:#0F766E;padding-top:4px}
 .area-name:hover{text-decoration:underline;text-underline-offset:3px}
-.tiles{list-style:none;margin:0;padding:0;display:grid;grid-template-columns:repeat(auto-fill,minmax(220px,1fr));gap:8px}
-.tile{display:flex;flex-direction:column;gap:2px;height:100%;background:var(--card);border:1px solid var(--hair);padding:8px 10px;text-decoration:none;color:var(--ink)}
-.tile b{font-size:12.5px;font-weight:600}
-.tile span{color:var(--muted);font-size:11.5px}
-.tile:hover{border-color:var(--ink)}
-
-/* feature card */
-.spec{background:var(--card);border:1px solid var(--hair);display:flex;flex-direction:column;scroll-margin-top:8px}
-.spec>.hd{display:flex;align-items:baseline;gap:10px;padding:10px 14px 8px;border-bottom:1px solid var(--hair)}
-.spec>.hd .mono{color:var(--org)}
-.spec>.hd h3{font-family:var(--display);font-weight:700;font-size:15.5px;line-height:1.15}
-.spec>.ds{padding:8px 14px 10px;color:var(--muted);font-size:12px}
-.facts{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:12px 22px;padding:10px 14px 12px;border-top:1px solid var(--hair);background:var(--canvas)}
+.tiles{list-style:none;margin:0;padding:0;display:grid;grid-template-columns:repeat(auto-fill,minmax(220px,1fr));gap:10px}
+.tile{display:flex;flex-direction:column;gap:4px;height:100%;background:var(--guide-panel);border:1px solid var(--guide-line);border-radius:16px;padding:14px 15px;text-decoration:none;color:var(--guide-text);box-shadow:0 10px 26px rgba(15,23,42,.04)}
+.tile b{font-size:13px;font-weight:700}
+.tile span{color:var(--guide-muted);font-size:12px;line-height:1.45}
+.tile:hover{border-color:color-mix(in srgb,var(--guide-accent) 22%,var(--guide-line));background:var(--guide-panel-2)}
+
+/* feature cards */
+.spec{background:var(--guide-panel);border:1px solid var(--guide-line);border-radius:18px;display:flex;flex-direction:column;scroll-margin-top:16px;overflow:hidden;box-shadow:0 12px 32px rgba(15,23,42,.05)}
+.spec>.hd{display:flex;align-items:center;gap:10px;padding:16px 20px 12px;border-bottom:1px solid var(--guide-line)}
+.spec>.hd .mono{color:#0F766E}
+.spec>.hd h3{font-family:var(--display);font-weight:700;font-size:18px;line-height:1.15;color:var(--guide-text)}
+.spec>.ds{padding:12px 22px 16px;color:var(--guide-muted);font-size:14px;line-height:1.7}
+.facts{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:20px 28px;padding:18px 22px 20px;border-top:1px solid var(--guide-line);background:var(--guide-panel-2)}
 .fact{display:flex;flex-direction:column;gap:6px;min-width:0}
-.fact>.mono{color:var(--muted)}
+.fact>.mono{color:var(--guide-muted);font-size:9.5px}
 .asks,.needs,.plainlist{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:6px}
-.asks li{border-left:3px solid var(--ink);padding:2px 0 2px 8px;font-size:12.5px;color:var(--ink)}
-.needs li{display:grid;grid-template-columns:86px minmax(0,1fr);gap:8px;align-items:baseline;font-size:12.25px}
-.need{justify-self:start;display:inline-flex;align-items:center;gap:5px;font-family:var(--mono);font-size:9.5px;font-weight:600;letter-spacing:.07em;text-transform:uppercase;padding:1px 6px 1px 5px;border:1px solid currentColor;border-radius:2px;line-height:1.5;white-space:nowrap;color:var(--ink2);background:var(--card)}
+.asks li{border-left:2px solid var(--guide-accent);padding:4px 0 4px 10px;font-size:13px;color:var(--guide-text);line-height:1.6}
+.needs li{display:grid;grid-template-columns:92px minmax(0,1fr);gap:10px;align-items:baseline;font-size:12.75px;line-height:1.6}
+.need{justify-self:start;display:inline-flex;align-items:center;gap:5px;font-family:var(--mono);font-size:9.5px;font-weight:600;letter-spacing:.07em;text-transform:uppercase;padding:1px 7px 1px 6px;border:1px solid currentColor;border-radius:999px;line-height:1.5;white-space:nowrap;color:var(--guide-muted);background:var(--guide-panel)}
 .need::before{content:"";width:5px;height:5px;background:currentColor;flex:none}
-.need.opt{border-style:dashed;color:var(--muted)}
+.need.opt{border-style:dashed;color:var(--guide-muted)}
 .need.opt::before{background:none;border:1px solid currentColor;width:4px;height:4px}
-.need.input{color:var(--muted);background:var(--band)}
-.plainlist li{font-size:12.25px}
+.need.input{color:var(--guide-muted);background:var(--guide-soft)}
+.plainlist li{font-size:12.4px}
 .tools{display:flex;flex-wrap:wrap;gap:6px}
-.detail{padding:12px 14px 14px;border-top:1px solid var(--hair);display:flex;flex-direction:column;gap:14px}
-.detail>.mono{color:var(--muted)}
-
-/* documentation text */
-.doc{display:flex;flex-direction:column;gap:8px;scroll-margin-top:8px}
-.doc>:is(h3,h4){font-family:var(--display);font-weight:700;font-size:15.5px;line-height:1.15;margin:0}
-.doc.sub{margin-top:8px;padding-top:10px;border-top:1px dashed var(--hair)}
-.doc.sub>:is(h4,h5){font-family:var(--display);font-weight:700;font-size:13.5px;margin:0}
-.chapter>.doc+.doc{padding-top:18px;border-top:1px solid var(--hair)}
-.see{color:var(--muted);font-size:12.25px}
-.prose{font-size:13.5px;line-height:1.6;color:var(--ink2)}
+.detail{padding:20px 22px 22px;border-top:1px solid var(--guide-line);display:flex;flex-direction:column;gap:20px}
+.detail>.mono{color:var(--guide-muted)}
+
+/* prose */
+.doc{display:flex;flex-direction:column;gap:12px;scroll-margin-top:16px}
+.doc>:is(h3,h4){font-family:var(--display);font-weight:700;font-size:21px;line-height:1.15;margin:0;letter-spacing:-.02em;color:var(--guide-text)}
+.doc.sub{margin-top:8px;padding-top:12px;border-top:1px dashed var(--guide-line)}
+.doc.sub>:is(h4,h5){font-family:var(--display);font-weight:700;font-size:16px;margin:0;color:var(--guide-text)}
+.chapter>.doc+.doc{padding-top:28px;border-top:1px solid var(--guide-line)}
+.see{color:var(--guide-muted);font-size:12.25px}
+.prose{font-size:15px;line-height:1.9;color:var(--guide-muted)}
 .prose :where(p,ul,ol,pre,blockquote){margin:0}
-.prose>*+*{margin-top:10px}
-.prose ul,.prose ol{padding-left:20px}
-.prose li+li{margin-top:4px}
-.prose strong{color:var(--ink)}
-.prose h5,.prose h6{font-family:var(--display);font-weight:700;font-size:13.5px;color:var(--ink);margin:16px 0 0}
+.prose>*+*{margin-top:16px}
+.prose ul,.prose ol{padding-left:22px}
+.prose li+li{margin-top:8px}
+.prose strong{color:var(--guide-text)}
+.prose h5,.prose h6{font-family:var(--display);font-weight:700;font-size:15px;color:var(--guide-text);margin:18px 0 0}
 .prose code{white-space:normal;overflow-wrap:anywhere}
-.prose pre{margin:0;padding:10px 12px;overflow-x:auto;background:var(--code);border:1px solid var(--hair);font-family:var(--codefont);font-size:11.5px;line-height:1.6}
-.prose pre code{background:none;border:0;padding:0;font-size:inherit;white-space:pre;overflow-wrap:normal}
-.prose hr{border:0;border-top:1px solid var(--hair)}
-.prose blockquote{margin:0;padding-left:12px;border-left:3px solid var(--rule);color:var(--muted)}
-.tbl{overflow-x:auto;border:1px solid var(--hair)}
-.tbl table{border-collapse:collapse;width:100%;font-size:12.25px;line-height:1.5}
-.tbl th,.tbl td{text-align:left;vertical-align:top;padding:6px 10px;border-bottom:1px solid var(--hair)}
-.tbl th{background:var(--band);color:var(--ink);font-weight:600}
-.tbl tr:last-child td{border-bottom:0}
-
-/* ============ responsive shell ============ */
-@media (max-width:1023px){
-  #app{grid-template-columns:minmax(0,1fr);grid-template-rows:auto auto minmax(0,1fr)}
-  .rail{grid-row:2;border-right:0;border-bottom:1px solid var(--hair);overflow:visible}
-  .rail .cap{display:none}
+.prose pre{margin:0;padding:16px 18px;overflow-x:auto;background:linear-gradient(180deg,#152033,#0C1422);color:#F8FBFF;border:1px solid #22314A;border-radius:16px;font-family:var(--codefont);font-size:13px;line-height:1.75;box-shadow:inset 0 1px 0 color-mix(in srgb,#fff 10%,transparent),0 1px 0 rgba(15,23,42,.12);tab-size:2}
+.prose pre code{display:block;background:none;border:0;padding:0;font-size:inherit;white-space:pre;overflow-wrap:normal;color:inherit}
+.prose hr{border:0;border-top:1px solid var(--guide-line)}
+.prose blockquote{margin:0;padding-left:14px;border-left:3px solid var(--guide-accent);color:var(--guide-muted)}
+.tbl{overflow-x:auto;border:1px solid var(--guide-line);border-radius:16px;background:var(--guide-panel);box-shadow:0 10px 28px rgba(15,23,42,.04)}
+.tbl table{border-collapse:separate;border-spacing:0;width:100%;font-size:13px;line-height:1.65}
+.tbl th,.tbl td{text-align:left;vertical-align:top;padding:12px 16px;border-bottom:1px solid var(--guide-line)}
+.tbl th{background:var(--guide-soft);color:var(--guide-muted);font-weight:700;font-size:10px;letter-spacing:.08em;text-transform:uppercase}
+.tbl tbody tr:nth-child(even) td{background:var(--guide-panel-2)}
+.tbl tbody tr:hover td{background:color-mix(in srgb,var(--guide-panel-2) 78%,var(--guide-soft))}
+.tbl td code{font-size:.85em}
+
+/* responsive */
+@media (max-width:1180px){
+  .shell{grid-template-columns:214px minmax(0,1fr);grid-template-rows:auto minmax(0,1fr)}
+  .mast{grid-column:2;grid-row:1}
+  .toc{display:none}
+}
+@media (max-width:900px){
+  .shell{grid-template-columns:minmax(0,1fr);grid-template-rows:auto minmax(0,1fr);gap:14px;padding:0}
+  .rail{grid-column:1;grid-row:1;overflow:visible;border-right:0;border-bottom:1px solid var(--guide-line)}
+  .mast{grid-column:1;grid-row:2}
+  .rail-inner{padding:12px 14px}
+  .rail-group+.rail-group{margin-top:14px}
   .chapters{flex-direction:row;overflow-x:auto;scrollbar-width:none;padding:0}
   .chapters::-webkit-scrollbar{display:none}
   .chapters li{flex:none}
-  .chapters a{grid-template-columns:auto auto;gap:6px;border-top:0;border-right:1px solid var(--hair);padding:10px 14px}
-  .chapters li:last-child a{border-bottom:0}
-  .chapters .d{display:none}
-  .chapters a::before{left:0;right:0;top:auto;bottom:0;width:auto;height:3px;transform:scaleX(0);transform-origin:left}
+  .chapters a{grid-template-columns:auto auto;gap:6px;padding:9px 12px}
+  .chapters .n{padding-top:1px}
+  .chapters a::before{left:10px;right:10px;top:auto;bottom:0;width:auto;height:2px;transform:scaleX(0);transform-origin:left}
   .chapters a[aria-current]::before{transform:scaleX(1)}
-  .panel{grid-row:3;padding:12px 16px 18px}
-  .mast .sub{display:none}
+  .panel{grid-column:1;grid-row:3;padding:0 14px 32px}
+  .page{padding:24px 10px 24vh;border-radius:0}
+  .tabs{margin-left:auto}
   .facts{grid-template-columns:minmax(0,1fr)}
   .area{grid-template-columns:minmax(0,1fr)}
 }
 @media (max-width:640px){
-  .mast{padding:0 12px;gap:10px;height:48px}
-  .mast .sep,.mark b{display:none}
-  .mast h1{font-size:18px}
-  .panel{padding:12px 16px 18px}
-  .chead h2{font-size:21px}
+  .mast{padding:12px 14px;height:auto;flex-wrap:wrap}
+  .tabs{order:3;margin-left:0}
+  .page{padding:22px 4px 22vh;border-radius:0}
+  .pagehead h1,.chead h2{font-size:24px}
 }
 @media (prefers-reduced-motion:reduce){.panel{scroll-behavior:auto}.chapters a::before{transition:none}}
 
-/* ============ print ============ */
+/* print */
 @media print{
   #app{display:block;height:auto}
-  .rail,.theme,.skip{display:none}
+  .rail,.toc,.theme,.tabs,.skip{display:none}
   .panel{overflow:visible;padding:0}
-  .page{max-width:none;padding-bottom:0}
-  .mast{background:none;color:var(--ink);border-bottom:1px solid var(--ink)}
-  .mast .sub{color:var(--muted)}
+  .page{max-width:none;padding:0;border:0;box-shadow:none;background:none}
+  .mast{padding:0 0 12px;background:none;color:var(--guide-text);border-bottom:1px solid var(--guide-text);backdrop-filter:none}
   .spec,.doc{break-inside:auto}
   .chapter{break-before:page}
   .chapter:first-child{break-before:auto}
 }
 `
 
-/** The theme switch (stored as the other documentation pages store it) and the rail following the chapter in view. */
+/** Theme switching, active left rail, and a docs-style "On this page" outline for the current chapter. */
 const GUIDE_JS = `(function () {
   var root = document.documentElement;
   var dark = function () {
@@ -417,26 +528,91 @@ const GUIDE_JS = `(function () {
 
   var panel = document.getElementById("panel");
   var links = Array.prototype.slice.call(document.querySelectorAll(".chapters a"));
+  var railSearch = document.getElementById("rail-search");
+  var railGroups = Array.prototype.slice.call(document.querySelectorAll(".rail-group"));
+  var tocCurrent = document.getElementById("toc-current");
+  var tocLinks = document.getElementById("toc-links");
   var byId = {};
   links.forEach(function (a) { byId[a.getAttribute("href").slice(1)] = a; });
-  var mark = function (id) {
-    links.forEach(function (a) { if (a === byId[id]) a.setAttribute("aria-current", "location"); else a.removeAttribute("aria-current"); });
-    var a = byId[id];
-    if (a && a.scrollIntoView && window.matchMedia("(max-width:1023px)").matches) a.scrollIntoView({ block: "nearest", inline: "nearest" });
+  var filterRail = function (term) {
+    railGroups.forEach(function (group) {
+      var items = Array.prototype.slice.call(group.querySelectorAll(".chapters li"));
+      var shown = 0;
+      items.forEach(function (item) {
+        var a = item.querySelector("a");
+        var label = a ? a.textContent.toLowerCase() : "";
+        var on = !term || label.indexOf(term) !== -1;
+        item.style.display = on ? "" : "none";
+        if (on) shown += 1;
+      });
+      group.style.display = shown ? "" : "none";
+    });
   };
   var chapters = Array.prototype.slice.call(document.querySelectorAll(".chapter"));
+  var itemText = function (node) {
+    var heading = node.querySelector("h3,h4,h5");
+    return heading ? heading.textContent.trim() : "";
+  };
+  var tocItems = function (chapter) {
+    return Array.prototype.slice.call(chapter.querySelectorAll("[id^='cap-'],[id^='doc-']")).filter(function (node) { return !!itemText(node); });
+  };
   var current = function () {
-    var top = panel.getBoundingClientRect().top + 24, id = chapters[0].id;
+    var top = panel.getBoundingClientRect().top + 72, id = chapters[0].id;
     chapters.forEach(function (c) { if (c.getBoundingClientRect().top <= top) id = c.id; });
     return id;
   };
+  var currentItem = function (nodes) {
+    if (!nodes.length) return null;
+    var top = panel.getBoundingClientRect().top + 116, id = nodes[0].id;
+    nodes.forEach(function (node) { if (node.getBoundingClientRect().top <= top) id = node.id; });
+    return id;
+  };
+  var renderToc = function (chapterId) {
+    var chapter = document.getElementById(chapterId);
+    if (!chapter || !tocLinks || !tocCurrent) return;
+    var title = chapter.querySelector(".chead h2");
+    tocCurrent.textContent = title ? title.textContent.trim() : "On this page";
+    var nodes = tocItems(chapter);
+    tocLinks.innerHTML = "";
+    nodes.forEach(function (node) {
+      var li = document.createElement("li");
+      var a = document.createElement("a");
+      a.setAttribute("href", "#" + node.id);
+      a.textContent = itemText(node);
+      li.appendChild(a);
+      tocLinks.appendChild(li);
+    });
+    var itemId = currentItem(nodes);
+    Array.prototype.forEach.call(tocLinks.querySelectorAll("a"), function (a) {
+      if (itemId && a.getAttribute("href") === "#" + itemId) a.setAttribute("aria-current", "location");
+      else a.removeAttribute("aria-current");
+    });
+  };
+  var mark = function (id) {
+    links.forEach(function (a) { if (a === byId[id]) a.setAttribute("aria-current", "location"); else a.removeAttribute("aria-current"); });
+    var a = byId[id];
+    if (a && a.scrollIntoView && window.matchMedia("(max-width:900px)").matches) a.scrollIntoView({ block: "nearest", inline: "nearest" });
+    renderToc(id);
+  };
+  var locateChapter = function (id) {
+    for (var i = 0; i < chapters.length; i++) {
+      var chapter = chapters[i];
+      if (chapter.id === id) return chapter.id;
+      var safe = window.CSS && CSS.escape ? CSS.escape(id) : id.replace(/[^a-zA-Z0-9_-]/g, "\\$&");
+      if (chapter.querySelector("#" + safe)) return chapter.id;
+    }
+    return current();
+  };
   var ticking = false;
   panel.addEventListener("scroll", function () {
     if (ticking) return;
     ticking = true;
     requestAnimationFrame(function () { ticking = false; mark(current()); });
   }, { passive: true });
-  mark(location.hash && byId[location.hash.slice(1)] ? location.hash.slice(1) : current());
+  if (railSearch) railSearch.addEventListener("input", function () { filterRail(railSearch.value.trim().toLowerCase()); });
+  filterRail("");
+  mark(location.hash && document.getElementById(location.hash.slice(1)) ? locateChapter(location.hash.slice(1)) : current());
+
   // The browser jumps to a link's section before the fonts arrive, and the text reflows when they do: jump again
   // after each font loads and once the page has, until the reader scrolls themselves.
   var target = location.hash && document.getElementById(location.hash.slice(1));
@@ -447,9 +623,15 @@ const GUIDE_JS = `(function () {
     var settle = function () {
       if (moved) return;
       target.scrollIntoView({ block: "start", behavior: "instant" });
-      mark(current());
+      mark(locateChapter(target.id));
     };
     window.addEventListener("load", settle);
     if (document.fonts) document.fonts.addEventListener("loadingdone", settle);
   }
+  window.addEventListener("hashchange", function () {
+    var id = location.hash.slice(1);
+    if (!id) return mark(current());
+    mark(locateChapter(id));
+  });
 })();`
+