@capagents/forgeqe 0.0.0-stage → 1.0.1

package/src/capabilities/guide.ts

@@ -0,0 +1,455 @@
+import { readFileSync } from "node:fs"
+import path from "node:path"
+
+import { docSections, resolveDoc, type DocSection } from "./docs.ts"
+import { CAPABILITIES, OUT_OF_SCOPE, type Area, type Capability, type DocRef } from "./registry.ts"
+import { describeRequirement } from "./status.ts"
+
+/**
+ * docs/user-guide.html: how to use ForgeQE and every capability in detail, generated from the capability registry and
+ * HOW_TO_USE.md so it never drifts from either. Its look (theme tokens, logo, masthead, rail) is the one
+ * docs/security-data-flow.html sets; the tokens and logo are read from that page, so both share one theme.
+ * Regenerate with bun scripts/gen-guide.ts; tests/guide.test.ts fails while the file is stale.
+ */
+
+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")
+
+/** 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 }))
+const USING: DocRef[] = ["3. Shell", "4. Without the shell"].map((heading) => ({ doc: "HOW_TO_USE.md", heading }))
+const REFERENCE: DocRef[] = ["10. MCP", "12. Engine tuning", "13. Logs for debugging", "14. Env overrides", "15. Commands cheat sheet"].map((heading) => ({ doc: "HOW_TO_USE.md", heading }))
+/** Left out on purpose: the Agent map is the registry's own table, which the Overview chapter replaces. */
+export const GUIDE_EXCLUDED = ["HOW_TO_USE.md#agent-map"]
+
+const AREA_NOTE: Record<Area, string> = {
+  Browser: "Goals carried out in a real browser, and the logins they use",
+  "Test cases": "Run, check, write, and explore manual test cases",
+  "Automated tests": "Write, heal, find, run, and stabilise tests in your repository",
+  "Pull requests": "Reviews, impact, and the tests a change can break",
+  API: "Contracts and end-to-end scenarios, without a browser",
+  Quality: "Accessibility, page performance, and visual changes",
+  Release: "Requirement coverage and a release verdict",
+  Operations: "Monitoring and CI pipelines",
+  Systems: "Azure DevOps, Jira, and Confluence",
+  Setup: "Configuration, skills, and help",
+}
+
+const esc = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;")
+const slug = (s: string) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "")
+
+/** The theme and logo the documentation pages share, from the page that defines them. */
+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 }
+}
+
+/** Which section renders where: the first place that names it; later places link to it. */
+type Placement = { rendered: Set<string>; claimed: Set<string> }
+
+function ids(refs: DocRef[]): string[] {
+  return refs.map((r) => {
+    const s = resolveDoc(r)
+    if (!s) throw new Error(`The guide names "${r.heading}" in ${r.doc}, which has no such heading.`)
+    return s.id
+  })
+}
+
+const sectionAnchor = (s: Pick<DocSection, "id">) => `doc-${s.id.replace(/\.md#/, "-").toLowerCase()}`
+
+/** HOW_TO_USE Markdown as HTML: headings one level down, wide tables scrollable, links pointed at this guide or the docs. */
+function markdown(text: string, sections: DocSection[], placement: Placement): string {
+  let html = Bun.markdown.html(text)
+  html = html.replace(/<(\/?)h([1-5])>/g, (_, close, n) => `<${close}h${Math.min(6, Number(n) + 1)}>`)
+  html = html.replace(/<table>/g, '<div class="tbl"><table>').replace(/<\/table>/g, "</table></div>")
+  return html.replace(/href="([^"]+)"/g, (whole, href: string) => {
+    if (/^(https?:|mailto:)/.test(href)) return `href="${href}" rel="noopener"`
+    const [file, hash] = href.startsWith("#") ? ["HOW_TO_USE.md", href.slice(1)] : href.split("#")
+    const target = sections.find((s) => s.id === `${file}#${hash}`)
+    if (target && placement.claimed.has(target.id)) return `href="#${sectionAnchor(target)}"`
+    // Anything else is a file in the package: links are relative to its root, this page is in docs/.
+    return `href="../${esc(href)}"`
+  })
+}
+
+/** One HOW_TO_USE section with its text, then the subsections no chapter or capability shows elsewhere. */
+function docBlock(id: string, sections: DocSection[], placement: Placement, level: 3 | 4): string {
+  const s = sections.find((x) => x.id === id)!
+  if (placement.rendered.has(id)) {
+    return `<p class="see">See <a href="#${sectionAnchor(s)}">${esc(s.heading)}</a>${s.doc === "README.md" ? " (from the README)" : ""}.</p>`
+  }
+  placement.rendered.add(id)
+  const children = sections.filter((c) => c.parent === id && !placement.claimed.has(c.id) && !GUIDE_EXCLUDED.includes(c.id))
+  for (const c of children) placement.rendered.add(c.id)
+  return [
+    `<section class="doc" id="${sectionAnchor(s)}">`,
+    `<h${level}>${esc(s.heading.replace(/^\d+\.\s+/, ""))}</h${level}>`,
+    `<div class="prose">${markdown(s.text, sections, placement)}</div>`,
+    ...children.map((c) => `<section class="doc sub" id="${sectionAnchor(c)}"><h${level + 1}>${esc(c.heading)}</h${level + 1}><div class="prose">${markdown(c.text, sections, placement)}</div></section>`),
+    `</section>`,
+  ].join("\n")
+}
+
+function feature(c: Capability, sections: DocSection[], placement: Placement): string {
+  const needs = c.requires.map((r) => {
+    const optional = "optional" in r && r.optional
+    const kind = r.kind === "input" ? "input" : optional ? "opt" : "req"
+    const label = r.kind === "input" ? "You give" : optional ? "Optional" : "Required"
+    return `<li><span class="need ${kind}">${label}</span><span>${esc(describeRequirement(r).replace(/^From your request: /, ""))}</span></li>`
+  })
+  return [
+    `<article class="spec feat" id="cap-${c.id}">`,
+    `<div class="hd"><span class="mono">${esc(c.area)}</span><h3>${esc(c.title)}</h3></div>`,
+    `<p class="ds">${esc(c.summary)}</p>`,
+    `<div class="facts">`,
+    `<div class="fact"><span class="mono">Ask it</span><ul class="asks">${c.examples.map((e) => `<li>${esc(e)}</li>`).join("")}</ul></div>`,
+    `<div class="fact"><span class="mono">What it needs</span>${needs.length ? `<ul class="needs">${needs.join("")}</ul>` : `<p class="muted">Nothing beyond ForgeQE itself.</p>`}</div>`,
+    c.limits?.length ? `<div class="fact"><span class="mono">Limits</span><ul class="plainlist">${c.limits.map((l) => `<li>${esc(l)}</li>`).join("")}</ul></div>` : "",
+    `<div class="fact"><span class="mono">Tools</span><p class="tools">${c.tools.map((t) => `<code>${esc(t)}</code>`).join(" ")}</p></div>`,
+    `</div>`,
+    `<div class="detail"><span class="mono">In detail</span>`,
+    ...ids(c.docs).map((id) => docBlock(id, sections, placement, 4)),
+    `</div>`,
+    `</article>`,
+  ]
+    .filter(Boolean)
+    .join("\n")
+}
+
+type Chapter = { id: string; title: string; note: string; body: string }
+
+function chapter(n: number, c: Chapter): string {
+  return [
+    `<section class="chapter" id="${c.id}" aria-labelledby="${c.id}-h">`,
+    `<header class="chead"><span class="mono">${String(n).padStart(2, "0")}</span><h2 id="${c.id}-h">${esc(c.title)}</h2><p>${esc(c.note)}</p></header>`,
+    c.body,
+    `</section>`,
+  ].join("\n")
+}
+
+function intro(): string {
+  const text = readFileSync(path.join(root, "HOW_TO_USE.md"), "utf8")
+  const start = text.indexOf("\n", text.indexOf("# How to use ForgeQE")) + 1
+  return text.slice(start, text.indexOf("\n## ", start)).replace(/\n---\s*$/, "").trim()
+}
+
+export function renderGuide(): string {
+  const look = sharedLook()
+  const sections = docSections()
+  const areas = [...new Set(CAPABILITIES.map((c) => c.area))]
+  const placement: Placement = {
+    rendered: new Set(),
+    claimed: new Set([...ids(START), ...ids(USING), ...ids(REFERENCE), ...CAPABILITIES.flatMap((c) => ids(c.docs))]),
+  }
+
+  const overview = [
+    `<div class="lead prose">${markdown(intro(), sections, placement)}</div>`,
+    `<h3 class="band-title">Every feature</h3>`,
+    ...areas.map((a) => {
+      const caps = CAPABILITIES.filter((c) => c.area === a)
+      return `<div class="area"><a class="area-name" href="#area-${slug(a)}"><span class="mono">${esc(a)}</span></a><ul class="tiles">${caps
+        .map((c) => `<li><a class="tile" href="#cap-${c.id}"><b>${esc(c.title)}</b><span>${esc(c.examples[0]!)}</span></a></li>`)
+        .join("")}</ul></div>`
+    }),
+    `<h3 class="band-title">Not supported</h3>`,
+    `<ul class="plainlist">${OUT_OF_SCOPE.map((o) => `<li><b>${esc(o.what)}</b>${o.instead ? `. Instead: ${esc(o.instead)}.` : ""}</li>`).join("")}</ul>`,
+  ].join("\n")
+
+  const chapters: Chapter[] = [
+    { id: "overview", title: "Overview", note: "What ForgeQE is, and everything it can do", body: overview },
+    { id: "get-started", title: "Get started", note: "Install, configure a model, and sign in to your tools", body: ids(START).map((id) => docBlock(id, sections, placement, 3)).join("\n") },
+    { id: "using", title: "Using ForgeQE", note: "The shell, its commands, and running without it", body: ids(USING).map((id) => docBlock(id, sections, placement, 3)).join("\n") },
+    ...areas.map((a) => ({
+      id: `area-${slug(a)}`,
+      title: a,
+      note: AREA_NOTE[a],
+      body: CAPABILITIES.filter((c) => c.area === a)
+        .map((c) => feature(c, sections, placement))
+        .join("\n"),
+    })),
+    { 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>`)
+    .join("\n")
+
+  return `<!DOCTYPE html>
+<!-- Generated by scripts/gen-guide.ts from src/capabilities/registry.ts and HOW_TO_USE.md. Do not edit: change those and run bun scripts/gen-guide.ts. -->
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>ForgeQE user guide</title>
+<script>try{var t=localStorage.getItem("wp-theme");if(t==="light"||t==="dark")document.documentElement.setAttribute("data-theme",t)}catch(e){}</script>
+<meta name="description" content="How to use ForgeQE: install, configure, and every feature in detail, with what it needs and how to ask for it.">
+${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">
+<style>
+${look.tokens}
+${GUIDE_CSS}
+</style>
+</head>
+<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>
+<nav class="rail" aria-label="Chapters">
+<div class="cap mono">Contents</div>
+<ol class="chapters">
+${rail}
+</ol>
+</nav>
+<main class="panel" id="panel" tabindex="-1">
+<div class="page">
+${chapters.map((c, i) => chapter(i + 1, c)).join("\n")}
+</div>
+</main>
+</div>
+<script>
+${GUIDE_JS}
+</script>
+</body>
+</html>
+`
+}
+
+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. */
+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}
+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}
+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)}
+.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}
+.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)}
+.theme svg{width:14px;height:14px}
+.theme .sun{display:none}
+: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"]) .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)}
+.chapters a[aria-current]::before{transform:scaleY(1)}
+.chapters a:focus-visible{outline-offset:-2px}
+
+/* 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}
+
+/* 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}
+.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)}
+.fact{display:flex;flex-direction:column;gap:6px;min-width:0}
+.fact>.mono{color:var(--muted)}
+.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)}
+.need::before{content:"";width:5px;height:5px;background:currentColor;flex:none}
+.need.opt{border-style:dashed;color:var(--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}
+.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)}
+.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 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}
+  .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[aria-current]::before{transform:scaleX(1)}
+  .panel{grid-row:3;padding:12px 16px 18px}
+  .mast .sub{display:none}
+  .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}
+}
+@media (prefers-reduced-motion:reduce){.panel{scroll-behavior:auto}.chapters a::before{transition:none}}
+
+/* ============ print ============ */
+@media print{
+  #app{display:block;height:auto}
+  .rail,.theme,.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)}
+  .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. */
+const GUIDE_JS = `(function () {
+  var root = document.documentElement;
+  var dark = function () {
+    var t = root.getAttribute("data-theme");
+    if (t) return t === "dark";
+    return window.matchMedia && matchMedia("(prefers-color-scheme: dark)").matches;
+  };
+  var button = document.querySelector(".theme");
+  var label = function () { var l = dark() ? "Switch to light theme" : "Switch to dark theme"; button.setAttribute("aria-label", l); button.title = l; };
+  label();
+  button.addEventListener("click", function () {
+    var next = dark() ? "light" : "dark";
+    root.setAttribute("data-theme", next);
+    try { localStorage.setItem("wp-theme", next); } catch (e) {}
+    label();
+  });
+
+  var panel = document.getElementById("panel");
+  var links = Array.prototype.slice.call(document.querySelectorAll(".chapters a"));
+  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 chapters = Array.prototype.slice.call(document.querySelectorAll(".chapter"));
+  var current = function () {
+    var top = panel.getBoundingClientRect().top + 24, id = chapters[0].id;
+    chapters.forEach(function (c) { if (c.getBoundingClientRect().top <= top) id = c.id; });
+    return id;
+  };
+  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());
+  // 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));
+  if (target) {
+    var moved = false;
+    var stop = function () { moved = true; };
+    ["wheel", "touchstart", "keydown", "mousedown"].forEach(function (e) { window.addEventListener(e, stop, { once: true, passive: true }); });
+    var settle = function () {
+      if (moved) return;
+      target.scrollIntoView({ block: "start", behavior: "instant" });
+      mark(current());
+    };
+    window.addEventListener("load", settle);
+    if (document.fonts) document.fonts.addEventListener("loadingdone", settle);
+  }
+})();`