feat(docs): standalone docs site chrome + category/subcategory navigation

Docs pages no longer embed the app Header (whose hx-post login form silently
degraded to a native GET, leaking credentials into the URL — this page never
loaded htmx). New docs-owned topbar: search, theme picker, Open App; anonymous
visitors get a plain /login link. Optional-auth middleware (hand-rolled —
echojwt's ErrorHandler return ends the chain, producing empty 200s) populates
the user for signed-in visitors.

Navigation rebuilt from the docs directory tree: 6 sections, subcategory
groups, server-rendered expansion and active states. Search results are a
templ partial (/docs/search/partial); code highlighting is server-side chroma
(previously dead hljs CSS); prose is theme-aware via typography DEFAULT vars
(prose-invert painted unreadable text under light themes). /docs renders the
index directly; standalone 404 without the tailwind CDN.

Tests: navigation routing/expansion (internal/docs), render pins asserting no
login form/password field/app sidebar ever return on docs pages.
lint-rendering: exempt *.test.ts fixtures (jsdom DOM building); docs.ts
baseline 5 -> 1.

web/src/docs.ts

@@ -1,42 +1,42 @@
 import { Alpine } from "./alpine";
 
+// Documentation site behavior. Rendering ownership (AGENTS.md): the server
+// renders what things look like — nav markup, search results — and this
+// module only orchestrates client-local state (open/closed panels, the
+// search dropdown) and swaps in the server-rendered search partial.
+
 function toggleSidebar(): void {
   const sidebar = document.getElementById("docs-sidebar");
   const overlay = document.getElementById("docs-overlay");
+  if (!sidebar || !overlay) return;
 
-  if (sidebar && overlay) {
-    sidebar.classList.toggle("translate-x-0");
-    sidebar.classList.toggle("-translate-x-full");
-    overlay.classList.toggle("hidden");
-  }
+  sidebar.classList.toggle("translate-x-0");
+  sidebar.classList.toggle("-translate-x-full");
+  overlay.classList.toggle("hidden");
 }
 
-function toggleSection(el: HTMLElement): void {
-  const items = el.nextElementSibling as HTMLElement;
-  const arrow = el.querySelector(".section-arrow") as HTMLElement;
-  if (!items || !arrow) return;
+function toggleCollapsible(header: HTMLElement): void {
+  const items = header.nextElementSibling as HTMLElement | null;
+  const arrow = header.querySelector<HTMLElement>(".section-arrow");
+  if (!items) return;
 
   const isCollapsed = items.getAttribute("data-collapsed") === "true";
 
-  if (isCollapsed) {
-    items.classList.remove("hidden");
-    items.setAttribute("data-collapsed", "false");
-    arrow.style.transform = "rotate(0deg)";
-  } else {
-    items.classList.add("hidden");
-    items.setAttribute("data-collapsed", "true");
-    arrow.style.transform = "rotate(-90deg)";
+  items.classList.toggle("hidden", !isCollapsed);
+  items.setAttribute("data-collapsed", isCollapsed ? "false" : "true");
+  if (arrow) {
+    arrow.style.transform = isCollapsed ? "rotate(0deg)" : "rotate(-90deg)";
   }
 }
 
+let docsSearchTimeout: ReturnType<typeof setTimeout> | null = null;
+let docsSearchAbort: AbortController | null = null;
+
 function initializeDocsSearch(): void {
-  const searchInput = document.getElementById("docs-search") as HTMLInputElement;
+  const searchInput = document.getElementById("docs-search") as HTMLInputElement | null;
   const searchResults = document.getElementById("docs-search-results");
-
   if (!searchInput || !searchResults) return;
 
-  let docsSearchTimeout: ReturnType<typeof setTimeout> | null = null;
-
   searchInput.addEventListener("input", () => {
     const query = searchInput.value.trim();
 
@@ -45,118 +45,77 @@ function initializeDocsSearch(): void {
     }
 
     if (query.length < 2) {
-      searchResults.innerHTML = "";
-      searchResults.classList.add("hidden");
+      hideDocsSearchResults();
       return;
     }
 
     docsSearchTimeout = setTimeout(() => {
-      performDocsSearch(query);
-    }, 300);
+      void performDocsSearch(query);
+    }, 250);
   });
 }
 
-function performDocsSearch(query: string): void {
+function hideDocsSearchResults(): void {
+  const searchResults = document.getElementById("docs-search-results");
+  if (!searchResults) return;
+  searchResults.replaceChildren();
+  searchResults.classList.add("hidden");
+}
+
+// performDocsSearch fetches the server-rendered results partial and swaps it
+// in verbatim. The partial is templ-rendered (DocsSearchResults); this module
+// never builds result markup itself.
+async function performDocsSearch(query: string): Promise<void> {
   const searchResults = document.getElementById("docs-search-results");
   if (!searchResults) return;
 
-  if (!(window as any).lunr) {
-    console.warn("Lunr.js not loaded");
-    return;
-  }
+  docsSearchAbort?.abort();
+  docsSearchAbort = new AbortController();
 
   try {
-    const idx = (window as any).lunrIndex;
-    if (!idx) {
-      searchResults.innerHTML =
-        '<p class="p-2 text-sm" style="color: var(--text-secondary)">Search index not loaded</p>';
-      searchResults.classList.remove("hidden");
-      return;
+    const response = await fetch(`/docs/search/partial?q=${encodeURIComponent(query)}`, {
+      signal: docsSearchAbort.signal,
+    });
+    if (!response.ok) {
+      throw new Error(`search failed: ${response.status}`);
     }
-
-    const results = idx.search(query);
-
-    if (results.length === 0) {
-      searchResults.innerHTML =
-        '<p class="p-2 text-sm" style="color: var(--text-secondary)">No results found</p>';
-    } else {
-      searchResults.innerHTML = results
-        .slice(0, 10)
-        .map((result: { ref: string }) => {
-          const doc = (window as any).docsData?.[result.ref];
-          if (!doc) return "";
-
-          return `
-                    <a href="${result.ref}" class="block p-2 hover:bg-opacity-50 transition-colors" style="background-color: var(--bg-secondary)">
-                        <p class="font-medium text-sm" style="color: var(--text-primary)">${doc.title || result.ref}</p>
-                        ${doc.section ? `<p class="text-xs" style="color: var(--text-secondary)">${doc.section}</p>` : ""}
-                    </a>
-                `;
-        })
-        .join("");
-    }
-
+    searchResults.innerHTML = await response.text();
     searchResults.classList.remove("hidden");
   } catch (error) {
-    console.error("Search error:", error);
-    searchResults.innerHTML =
-      '<p class="p-2 text-sm" style="color: var(--text-secondary)">Search error</p>';
+    if (error instanceof DOMException && error.name === "AbortError") return;
+    console.error("Docs search error:", error);
+    searchResults.textContent = "Search failed — try again.";
+    searchResults.classList.add("px-4", "py-3", "text-sm");
+    searchResults.style.color = "var(--text-secondary)";
     searchResults.classList.remove("hidden");
   }
 }
 
-function highlightCurrentPage(): void {
-  const currentPath = window.location.pathname;
-  document.querySelectorAll(".nav-item").forEach((item) => {
-    if (item.getAttribute("href") === currentPath) {
-      item.classList.add("text-accent", "bg-accent/10", "border-r-2", "border-accent");
-    }
-  });
-}
-
 function initializeCodeCopyButtons(): void {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const hljs = (window as any).hljs;
-  if (hljs) {
-    hljs.highlightAll();
+  document.querySelectorAll(".prose pre").forEach((pre) => {
+    const wrapper = document.createElement("div");
+    wrapper.className = "relative group";
+    pre.parentNode?.insertBefore(wrapper, pre);
+    wrapper.appendChild(pre);
 
-    document.querySelectorAll("pre code").forEach((block) => {
-      const pre = block.parentElement;
-      if (!pre) return;
-
-      const wrapper = document.createElement("div");
-      wrapper.className = "relative group";
-      pre.parentNode.insertBefore(wrapper, pre);
-      wrapper.appendChild(pre);
-
-      const button = document.createElement("button");
-      button.className =
-        "absolute top-2 right-2 bg-background-secondary text-text-secondary px-2 py-1 rounded text-xs opacity-0 group-hover:opacity-100 transition-opacity border border-border hover:text-accent";
-      button.textContent = "Copy";
-      button.onclick = async () => {
-        await navigator.clipboard.writeText(block.textContent || "");
-        button.textContent = "Copied!";
-        setTimeout(() => {
-          button.textContent = "Copy";
-        }, 2000);
-      };
-      wrapper.appendChild(button);
+    const button = document.createElement("button");
+    button.className =
+      "absolute top-2 right-2 btn px-2 py-1 rounded-lg text-xs opacity-0 group-hover:opacity-100 transition-opacity";
+    button.textContent = "Copy";
+    button.addEventListener("click", async () => {
+      await navigator.clipboard.writeText(pre.textContent || "");
+      button.textContent = "Copied!";
+      setTimeout(() => {
+        button.textContent = "Copy";
+      }, 2000);
     });
-  }
+    wrapper.appendChild(button);
+  });
 }
 
 Alpine.data("docs", () => ({
   toggleSidebar,
-  toggleSection,
+  toggleCollapsible,
   initializeSearch: initializeDocsSearch,
-  highlightCurrentPage,
   initializeCodeCopyButtons,
 }));
-
-export {
-  toggleSidebar,
-  toggleSection,
-  initializeDocsSearch,
-  highlightCurrentPage,
-  initializeCodeCopyButtons,
-};

web/src/rendering-allowlist.txt

@@ -12,7 +12,7 @@ web/src/collection-rules.ts:6
 web/src/collections.ts:5
 web/src/custom-section-builder.ts:10
 web/src/device-management.ts:4
-web/src/docs.ts:5
+web/src/docs.ts:1
 web/src/dashboard.ts:2
 web/src/linking.ts:3
 web/src/markdown.ts:1

web/static/style.css

@@ -1,2 +1,2 @@
 *,:after,:before{--tw-border-spacing-x:0;--tw-border-spacing-y:0;--tw-translate-x:0;--tw-translate-y:0;--tw-rotate:0;--tw-skew-x:0;--tw-skew-y:0;--tw-scale-x:1;--tw-scale-y:1;--tw-pan-x: ;--tw-pan-y: ;--tw-pinch-zoom: ;--tw-scroll-snap-strictness:proximity;--tw-gradient-from-position: ;--tw-gradient-via-position: ;--tw-gradient-to-position: ;--tw-ordinal: ;--tw-slashed-zero: ;--tw-numeric-figure: ;--tw-numeric-spacing: ;--tw-numeric-fraction: ;--tw-ring-inset: ;--tw-ring-offset-width:0px;--tw-ring-offset-color:#fff;--tw-ring-color:rgba(59,130,246,.5);--tw-ring-offset-shadow:0 0 #0000;--tw-ring-shadow:0 0 #0000;--tw-shadow:0 0 #0000;--tw-shadow-colored:0 0 #0000;--tw-blur: ;--tw-brightness: ;--tw-contrast: ;--tw-grayscale: ;--tw-hue-rotate: ;--tw-invert: ;--tw-saturate: ;--tw-sepia: ;--tw-drop-shadow: ;--tw-backdrop-blur: ;--tw-backdrop-brightness: ;--tw-backdrop-contrast: ;--tw-backdrop-grayscale: ;--tw-backdrop-hue-rotate: ;--tw-backdrop-invert: ;--tw-backdrop-opacity: ;--tw-backdrop-saturate: ;--tw-backdrop-sepia: ;--tw-contain-size: ;--tw-contain-layout: ;--tw-contain-paint: ;--tw-contain-style: }::backdrop{--tw-border-spacing-x:0;--tw-border-spacing-y:0;--tw-translate-x:0;--tw-translate-y:0;--tw-rotate:0;--tw-skew-x:0;--tw-skew-y:0;--tw-scale-x:1;--tw-scale-y:1;--tw-pan-x: ;--tw-pan-y: ;--tw-pinch-zoom: ;--tw-scroll-snap-strictness:proximity;--tw-gradient-from-position: ;--tw-gradient-via-position: ;--tw-gradient-to-position: ;--tw-ordinal: ;--tw-slashed-zero: ;--tw-numeric-figure: ;--tw-numeric-spacing: ;--tw-numeric-fraction: ;--tw-ring-inset: ;--tw-ring-offset-width:0px;--tw-ring-offset-color:#fff;--tw-ring-color:rgba(59,130,246,.5);--tw-ring-offset-shadow:0 0 #0000;--tw-ring-shadow:0 0 #0000;--tw-shadow:0 0 #0000;--tw-shadow-colored:0 0 #0000;--tw-blur: ;--tw-brightness: ;--tw-contrast: ;--tw-grayscale: ;--tw-hue-rotate: ;--tw-invert: ;--tw-saturate: ;--tw-sepia: ;--tw-drop-shadow: ;--tw-backdrop-blur: ;--tw-backdrop-brightness: ;--tw-backdrop-contrast: ;--tw-backdrop-grayscale: ;--tw-backdrop-hue-rotate: ;--tw-backdrop-invert: ;--tw-backdrop-opacity: ;--tw-backdrop-saturate: ;--tw-backdrop-sepia: ;--tw-contain-size: ;--tw-contain-layout: ;--tw-contain-paint: ;--tw-contain-style: }
-/*! tailwindcss v3.4.19 | MIT License | https://tailwindcss.com*/*,:after,:before{box-sizing:border-box;border:0 solid #e5e7eb}:after,:before{--tw-content:""}:host,html{line-height:1.5;-webkit-text-size-adjust:100%;-moz-tab-size:4;-o-tab-size:4;tab-size:4;font-family:ui-sans-serif,system-ui,sans-serif,Noto Sans SC,Noto Sans TC,Noto Sans JP,Noto Sans KR,PingFang SC,Microsoft YaHei,Hiragino Sans,Apple SD Gothic Neo,Apple Color Emoji,Segoe UI Emoji,Segoe UI Symbol,Noto Color Emoji;font-feature-settings:normal;font-variation-settings:normal;-webkit-tap-highlight-color:transparent}body{margin:0;line-height:inherit}hr{height:0;color:inherit;border-top-width:1px}abbr:where([title]){-webkit-text-decoration:underline dotted;text-decoration:underline dotted}h1,h2,h3,h4,h5,h6{font-size:inherit;font-weight:inherit}a{color:inherit;text-decoration:inherit}b,strong{font-weight:bolder}code,kbd,pre,samp{font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,monospace;font-feature-settings:normal;font-variation-settings:normal;font-size:1em}small{font-size:80%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sub{bottom:-.25em}sup{top:-.5em}table{text-indent:0;border-color:inherit;border-collapse:collapse}button,input,optgroup,select,textarea{font-family:inherit;font-feature-settings:inherit;font-variation-settings:inherit;font-size:100%;font-weight:inherit;line-height:inherit;letter-spacing:inherit;color:inherit;margin:0;padding:0}button,select{text-transform:none}button,input:where([type=button]),input:where([type=reset]),input:where([type=submit]){-webkit-appearance:button;background-color:transparent;background-image:none}:-moz-focusring{outline:auto}:-moz-ui-invalid{box-shadow:none}progress{vertical-align:baseline}::-webkit-inner-spin-button,::-webkit-outer-spin-button{height:auto}[type=search]{-webkit-appearance:textfield;outline-offset:-2px}::-webkit-search-decoration{-webkit-appearance:none}::-webkit-file-upload-button{-webkit-appearance:button;font:inherit}summary{display:list-item}blockquote,dd,dl,figure,h1,h2,h3,h4,h5,h6,hr,p,pre{margin:0}fieldset{margin:0}fieldset,legend{padding:0}menu,ol,ul{list-style:none;margin:0;padding:0}dialog{padding:0}textarea{resize:vertical}input::-moz-placeholder,textarea::-moz-placeholder{opacity:1;color:#9ca3af}input::placeholder,textarea::placeholder{opacity:1;color:#9ca3af}[role=button],button{cursor:pointer}:disabled{cursor:default}audio,canvas,embed,iframe,img,object,svg,video{display:block;vertical-align:middle}img,video{max-width:100%;height:auto}[hidden]:where(:not([hidden=until-found])){display:none}input:where(:not([type])),input:where([type=date]),input:where([type=datetime-local]),input:where([type=email]),input:where([type=month]),input:where([type=number]),input:where([type=password]),input:where([type=search]),input:where([type=tel]),input:where([type=text]),input:where([type=time]),input:where([type=url]),input:where([type=week]),select,select:where([multiple]),textarea{-webkit-appearance:none;-moz-appearance:none;appearance:none;background-color:#fff;border-color:#6b7280;border-width:1px;border-radius:0;padding:.5rem .75rem;font-size:1rem;line-height:1.5rem;--tw-shadow:0 0 #0000}input:where(:not([type])):focus,input:where([type=date]):focus,input:where([type=datetime-local]):focus,input:where([type=email]):focus,input:where([type=month]):focus,input:where([type=number]):focus,input:where([type=password]):focus,input:where([type=search]):focus,input:where([type=tel]):focus,input:where([type=text]):focus,input:where([type=time]):focus,input:where([type=url]):focus,input:where([type=week]):focus,select:focus,select:where([multiple]):focus,textarea:focus{outline:2px solid transparent;outline-offset:2px;--tw-ring-inset:var(--tw-empty,/*!*/ /*!*/);--tw-ring-offset-width:0px;--tw-ring-offset-color:#fff;--tw-ring-color:#2563eb;--tw-ring-offset-shadow:var(--tw-ring-inset) 0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color);--tw-ring-shadow:var(--tw-ring-inset) 0 0 0 calc(1px + var(--tw-ring-offset-width)) var(--tw-ring-color);box-shadow:var(--tw-ring-offset-shadow),var(--tw-ring-shadow),var(--tw-shadow);border-color:#2563eb}input::-moz-placeholder,textarea::-moz-placeholder{color:#6b7280;opacity:1}input::placeholder,textarea::placeholder{color:#6b7280;opacity:1}::-webkit-datetime-edit-fields-wrapper{padding:0}::-webkit-date-and-time-value{min-height:1.5em;text-align:inherit}::-webkit-datetime-edit{display:inline-flex}::-webkit-datetime-edit,::-webkit-datetime-edit-day-field,::-webkit-datetime-edit-hour-field,::-webkit-datetime-edit-meridiem-field,::-webkit-datetime-edit-millisecond-field,::-webkit-datetime-edit-minute-field,::-webkit-datetime-edit-month-field,::-webkit-datetime-edit-second-field,::-webkit-datetime-edit-year-field{padding-top:0;padding-bottom:0}select{background-image:url("data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='none' viewBox='0 0 20 20'%3E%3Cpath Line truncated
+/*! tailwindcss v3.4.19 | MIT License | https://tailwindcss.com*/*,:after,:before{box-sizing:border-box;border:0 solid #e5e7eb}:after,:before{--tw-content:""}:host,html{line-height:1.5;-webkit-text-size-adjust:100%;-moz-tab-size:4;-o-tab-size:4;tab-size:4;font-family:ui-sans-serif,system-ui,sans-serif,Noto Sans SC,Noto Sans TC,Noto Sans JP,Noto Sans KR,PingFang SC,Microsoft YaHei,Hiragino Sans,Apple SD Gothic Neo,Apple Color Emoji,Segoe UI Emoji,Segoe UI Symbol,Noto Color Emoji;font-feature-settings:normal;font-variation-settings:normal;-webkit-tap-highlight-color:transparent}body{margin:0;line-height:inherit}hr{height:0;color:inherit;border-top-width:1px}abbr:where([title]){-webkit-text-decoration:underline dotted;text-decoration:underline dotted}h1,h2,h3,h4,h5,h6{font-size:inherit;font-weight:inherit}a{color:inherit;text-decoration:inherit}b,strong{font-weight:bolder}code,kbd,pre,samp{font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,monospace;font-feature-settings:normal;font-variation-settings:normal;font-size:1em}small{font-size:80%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sub{bottom:-.25em}sup{top:-.5em}table{text-indent:0;border-color:inherit;border-collapse:collapse}button,input,optgroup,select,textarea{font-family:inherit;font-feature-settings:inherit;font-variation-settings:inherit;font-size:100%;font-weight:inherit;line-height:inherit;letter-spacing:inherit;color:inherit;margin:0;padding:0}button,select{text-transform:none}button,input:where([type=button]),input:where([type=reset]),input:where([type=submit]){-webkit-appearance:button;background-color:transparent;background-image:none}:-moz-focusring{outline:auto}:-moz-ui-invalid{box-shadow:none}progress{vertical-align:baseline}::-webkit-inner-spin-button,::-webkit-outer-spin-button{height:auto}[type=search]{-webkit-appearance:textfield;outline-offset:-2px}::-webkit-search-decoration{-webkit-appearance:none}::-webkit-file-upload-button{-webkit-appearance:button;font:inherit}summary{display:list-item}blockquote,dd,dl,figure,h1,h2,h3,h4,h5,h6,hr,p,pre{margin:0}fieldset{margin:0}fieldset,legend{padding:0}menu,ol,ul{list-style:none;margin:0;padding:0}dialog{padding:0}textarea{resize:vertical}input::-moz-placeholder,textarea::-moz-placeholder{opacity:1;color:#9ca3af}input::placeholder,textarea::placeholder{opacity:1;color:#9ca3af}[role=button],button{cursor:pointer}:disabled{cursor:default}audio,canvas,embed,iframe,img,object,svg,video{display:block;vertical-align:middle}img,video{max-width:100%;height:auto}[hidden]:where(:not([hidden=until-found])){display:none}input:where(:not([type])),input:where([type=date]),input:where([type=datetime-local]),input:where([type=email]),input:where([type=month]),input:where([type=number]),input:where([type=password]),input:where([type=search]),input:where([type=tel]),input:where([type=text]),input:where([type=time]),input:where([type=url]),input:where([type=week]),select,select:where([multiple]),textarea{-webkit-appearance:none;-moz-appearance:none;appearance:none;background-color:#fff;border-color:#6b7280;border-width:1px;border-radius:0;padding:.5rem .75rem;font-size:1rem;line-height:1.5rem;--tw-shadow:0 0 #0000}input:where(:not([type])):focus,input:where([type=date]):focus,input:where([type=datetime-local]):focus,input:where([type=email]):focus,input:where([type=month]):focus,input:where([type=number]):focus,input:where([type=password]):focus,input:where([type=search]):focus,input:where([type=tel]):focus,input:where([type=text]):focus,input:where([type=time]):focus,input:where([type=url]):focus,input:where([type=week]):focus,select:focus,select:where([multiple]):focus,textarea:focus{outline:2px solid transparent;outline-offset:2px;--tw-ring-inset:var(--tw-empty,/*!*/ /*!*/);--tw-ring-offset-width:0px;--tw-ring-offset-color:#fff;--tw-ring-color:#2563eb;--tw-ring-offset-shadow:var(--tw-ring-inset) 0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color);--tw-ring-shadow:var(--tw-ring-inset) 0 0 0 calc(1px + var(--tw-ring-offset-width)) var(--tw-ring-color);box-shadow:var(--tw-ring-offset-shadow),var(--tw-ring-shadow),var(--tw-shadow);border-color:#2563eb}input::-moz-placeholder,textarea::-moz-placeholder{color:#6b7280;opacity:1}input::placeholder,textarea::placeholder{color:#6b7280;opacity:1}::-webkit-datetime-edit-fields-wrapper{padding:0}::-webkit-date-and-time-value{min-height:1.5em;text-align:inherit}::-webkit-datetime-edit{display:inline-flex}::-webkit-datetime-edit,::-webkit-datetime-edit-day-field,::-webkit-datetime-edit-hour-field,::-webkit-datetime-edit-meridiem-field,::-webkit-datetime-edit-millisecond-field,::-webkit-datetime-edit-minute-field,::-webkit-datetime-edit-month-field,::-webkit-datetime-edit-second-field,::-webkit-datetime-edit-year-field{padding-top:0;padding-bottom:0}select{background-image:url("data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='none' viewBox='0 0 20 20'%3E%3Cpath Line truncated