@nexpress/theme-docs 0.2.2 → 0.3.1

package/dist/index.js

@@ -2,7 +2,8 @@
 import { defineTheme } from "@nexpress/theme";
 
 // src/header.tsx
-import { NavMenu } from "@nexpress/next";
+import { NavMenu, getCachedSite } from "@nexpress/next";
+import { SearchKeyboardShortcut } from "./components/search-keyboard-shortcut.js";
 
 // src/settings-helpers.ts
 import { getCachedThemeSettings } from "@nexpress/next";
@@ -31,42 +32,83 @@ async function resolveDocsSettings() {
 
 // src/header.tsx
 import { jsx, jsxs } from "react/jsx-runtime";
+var FALLBACK_SITE_NAME = "NexPress";
 async function DocsHeader() {
-  const settings = await resolveDocsSettings();
+  const [settings, site] = await Promise.all([
+    resolveDocsSettings(),
+    getCachedSite()
+  ]);
+  const siteName = site?.name?.trim() || FALLBACK_SITE_NAME;
   return /* @__PURE__ */ jsx("header", { className: "np-docs-header", children: /* @__PURE__ */ jsxs("div", { className: "np-docs-header-inner", children: [
     /* @__PURE__ */ jsxs("a", { href: "/", className: "np-docs-brand", children: [
-      /* @__PURE__ */ jsx("span", { className: "np-docs-brand-name", children: "Docs" }),
+      /* @__PURE__ */ jsx("span", { className: "np-docs-brand-mark", "aria-hidden": "true" }),
+      /* @__PURE__ */ jsx("span", { className: "np-docs-brand-name", children: siteName }),
       /* @__PURE__ */ jsx("span", { className: "np-docs-brand-version", children: settings.version })
     ] }),
-    /* @__PURE__ */ jsx(
+    /* @__PURE__ */ jsxs(
       "form",
       {
         action: "/docs/search",
         method: "get",
         className: "np-docs-search-form",
         role: "search",
-        children: /* @__PURE__ */ jsx(
-          "input",
-          {
-            type: "search",
-            name: "q",
-            placeholder: settings.searchPlaceholder,
-            className: "np-docs-search-input",
-            "aria-label": "Search the docs"
-          }
-        )
+        children: [
+          /* @__PURE__ */ jsxs(
+            "svg",
+            {
+              width: "14",
+              height: "14",
+              viewBox: "0 0 24 24",
+              fill: "none",
+              stroke: "currentColor",
+              strokeWidth: "2",
+              "aria-hidden": "true",
+              children: [
+                /* @__PURE__ */ jsx("circle", { cx: "11", cy: "11", r: "7" }),
+                /* @__PURE__ */ jsx("path", { d: "m21 21-4.3-4.3" })
+              ]
+            }
+          ),
+          /* @__PURE__ */ jsx("label", { className: "sr-only", htmlFor: "np-docs-search-input", children: "Search the docs" }),
+          /* @__PURE__ */ jsx(
+            "input",
+            {
+              id: "np-docs-search-input",
+              type: "search",
+              name: "q",
+              placeholder: settings.searchPlaceholder,
+              className: "np-docs-search-input"
+            }
+          ),
+          /* @__PURE__ */ jsx("kbd", { className: "np-docs-search-kbd", children: "\u2318K" })
+        ]
       }
     ),
+    /* @__PURE__ */ jsx(SearchKeyboardShortcut, { targetId: "np-docs-search-input" }),
     /* @__PURE__ */ jsxs("nav", { className: "np-docs-nav", "aria-label": "Primary", children: [
       /* @__PURE__ */ jsx(NavMenu, { location: "primary", className: "np-docs-primary-nav" }),
-      settings.githubRepo ? /* @__PURE__ */ jsx(
+      settings.githubRepo ? /* @__PURE__ */ jsxs(
         "a",
         {
           href: settings.githubRepo,
-          className: "np-docs-github-link",
+          className: "np-docs-github",
           target: "_blank",
           rel: "noreferrer",
-          children: "GitHub"
+          "aria-label": "GitHub repository",
+          children: [
+            /* @__PURE__ */ jsx(
+              "svg",
+              {
+                width: "14",
+                height: "14",
+                viewBox: "0 0 24 24",
+                fill: "currentColor",
+                "aria-hidden": "true",
+                children: /* @__PURE__ */ jsx("path", { d: "M12 .5a12 12 0 0 0-3.8 23.39c.6.11.82-.26.82-.58v-2c-3.34.73-4.04-1.61-4.04-1.61-.55-1.39-1.34-1.76-1.34-1.76-1.1-.75.08-.74.08-.74 1.21.09 1.85 1.24 1.85 1.24 1.07 1.84 2.81 1.31 3.5 1 .11-.78.42-1.31.76-1.61-2.66-.3-5.47-1.33-5.47-5.93 0-1.31.47-2.38 1.24-3.22-.12-.3-.54-1.52.12-3.17 0 0 1-.32 3.3 1.23a11.5 11.5 0 0 1 6 0c2.28-1.55 3.29-1.23 3.29-1.23.66 1.65.25 2.87.12 3.17.77.84 1.24 1.91 1.24 3.22 0 4.61-2.81 5.62-5.49 5.92.43.37.81 1.1.81 2.22v3.29c0 .32.22.7.83.58A12 12 0 0 0 12 .5Z" })
+              }
+            ),
+            "GitHub"
+          ]
         }
       ) : null
     ] })
@@ -219,52 +261,179 @@ import { findDocuments as findDocuments2 } from "@nexpress/core";
 import { notFound } from "next/navigation";
 
 // src/templates/doc-page.tsx
+import * as React from "react";
 import { findDocuments } from "@nexpress/core";
-import { jsx as jsx5, jsxs as jsxs5 } from "react/jsx-runtime";
+import { extractHeadingToc, renderRichText } from "@nexpress/editor/server";
+
+// src/toc-scrollspy-bridge.ts
+import { TocScrollspy } from "./components/toc-scrollspy.js";
+
+// src/templates/doc-page.tsx
+import { Fragment as Fragment2, jsx as jsx5, jsxs as jsxs5 } from "react/jsx-runtime";
 async function DocPageTemplate({
   doc: rawDoc
 }) {
   const doc = rawDoc;
   const settings = await resolveDocsSettings();
+  const breadcrumbs = await loadBreadcrumbs(doc);
   const navInfo = await loadPrevNext(doc);
-  return /* @__PURE__ */ jsxs5("article", { className: "np-docs-page", children: [
-    /* @__PURE__ */ jsx5("header", { children: /* @__PURE__ */ jsx5("h1", { children: doc.title }) }),
-    /* @__PURE__ */ jsx5("div", { className: "np-docs-body", children: /* @__PURE__ */ jsx5("pre", { style: { whiteSpace: "pre-wrap", fontFamily: "inherit" }, children: typeof doc.body === "string" ? doc.body : "Doc body unavailable." }) }),
-    settings.githubRepo ? /* @__PURE__ */ jsx5("p", { style: { marginTop: "2rem" }, children: /* @__PURE__ */ jsx5(
-      "a",
-      {
-        href: `${settings.githubRepo}/edit/main/docs/${doc.slug}.md`,
-        target: "_blank",
-        rel: "noreferrer",
-        style: {
-          fontSize: "0.875rem",
-          color: "var(--np-color-muted-foreground)"
-        },
-        children: "\u270F\uFE0F Edit on GitHub"
-      }
-    ) }) : null,
-    /* @__PURE__ */ jsxs5("nav", { className: "np-docs-prev-next", "aria-label": "Pagination", children: [
-      navInfo.prev ? /* @__PURE__ */ jsxs5("a", { href: `/docs/${navInfo.prev.slug}`, children: [
-        /* @__PURE__ */ jsx5("span", { className: "np-docs-prev-next-label", children: "\u2190 Previous" }),
-        navInfo.prev.title
-      ] }) : /* @__PURE__ */ jsx5("span", {}),
-      navInfo.next ? /* @__PURE__ */ jsxs5(
-        "a",
+  const updatedLabel = formatUpdated(doc.updatedAt ?? doc.publishedAt);
+  const readingLabel = readingMinutesLabel(doc.readingTime);
+  const editHref = settings.githubRepo ? `${settings.githubRepo}/edit/main/docs/${doc.slug}.md` : null;
+  const toc = extractHeadingToc(doc.body);
+  const reportIssueHref = settings.githubRepo ? `${settings.githubRepo}/issues/new` : null;
+  return /* @__PURE__ */ jsxs5(Fragment2, { children: [
+    /* @__PURE__ */ jsxs5("article", { className: "np-docs-page", children: [
+      /* @__PURE__ */ jsx5("nav", { className: "np-docs-breadcrumbs", "aria-label": "Breadcrumb", children: breadcrumbs.map((crumb, index) => {
+        const isLast = index === breadcrumbs.length - 1;
+        return /* @__PURE__ */ jsxs5(React.Fragment, { children: [
+          index > 0 ? /* @__PURE__ */ jsx5("span", { className: "np-docs-breadcrumbs-sep", "aria-hidden": "true", children: "/" }) : null,
+          isLast || !crumb.slug ? /* @__PURE__ */ jsx5("span", { children: crumb.title }) : /* @__PURE__ */ jsx5("a", { href: `/docs/${crumb.slug}`, children: crumb.title })
+        ] }, `crumb-${index.toString()}-${crumb.slug ?? "root"}`);
+      }) }),
+      /* @__PURE__ */ jsx5("h1", { children: doc.title }),
+      doc.lede ? /* @__PURE__ */ jsx5("p", { className: "np-docs-page-lede", children: doc.lede }) : null,
+      doc.stableSince || readingLabel || updatedLabel || editHref ? /* @__PURE__ */ jsxs5("div", { className: "np-docs-page-meta", children: [
+        doc.stableSince ? /* @__PURE__ */ jsxs5("span", { className: "np-docs-page-meta-pill status", children: [
+          "Stable since ",
+          doc.stableSince
+        ] }) : null,
+        readingLabel ? /* @__PURE__ */ jsx5("span", { className: "np-docs-page-meta-pill", children: readingLabel }) : null,
+        updatedLabel ? /* @__PURE__ */ jsxs5(Fragment2, { children: [
+          /* @__PURE__ */ jsx5("span", { className: "np-docs-page-meta-sep", "aria-hidden": "true", children: "\xB7" }),
+          /* @__PURE__ */ jsxs5("span", { children: [
+            "Updated ",
+            updatedLabel
+          ] })
+        ] }) : null,
+        editHref ? /* @__PURE__ */ jsx5("a", { href: editHref, target: "_blank", rel: "noreferrer", children: "Edit this page \u2192" }) : null
+      ] }) : null,
+      /* @__PURE__ */ jsx5("div", { className: "np-docs-page-body", children: doc.body ? (
+        // Core types `NpRichTextContent` as the opaque
+        // `Record<string, unknown>`; the editor's renderer
+        // refines it to `{ root: ... }`. Structural cast at
+        // the boundary — both sides go through the same
+        // Lexical serializer.
+        renderRichText(doc.body)
+      ) : /* @__PURE__ */ jsx5("p", { style: { color: "var(--np-color-muted-foreground)" }, children: "No body content yet." }) }),
+      /* @__PURE__ */ jsxs5("div", { className: "np-docs-feedback", children: [
+        /* @__PURE__ */ jsxs5("div", { children: [
+          /* @__PURE__ */ jsx5("div", { className: "np-docs-feedback-title", children: "Was this page helpful?" }),
+          /* @__PURE__ */ jsx5("div", { className: "np-docs-feedback-helper", children: "Operators wire the feedback endpoint via a plugin or a custom client island \u2014 the form is intentionally inert in v0.1." })
+        ] }),
+        /* @__PURE__ */ jsxs5("div", { className: "np-docs-feedback-buttons", children: [
+          /* @__PURE__ */ jsx5("button", { type: "button", children: "Yes" }),
+          /* @__PURE__ */ jsx5("button", { type: "button", children: "Could be better" })
+        ] })
+      ] }),
+      /* @__PURE__ */ jsxs5("nav", { className: "np-docs-prev-next", "aria-label": "Pagination", children: [
+        navInfo.prev ? /* @__PURE__ */ jsxs5(
+          "a",
+          {
+            href: `/docs/${navInfo.prev.slug}`,
+            className: "np-docs-prev-next-prev",
+            children: [
+              /* @__PURE__ */ jsx5("div", { className: "np-docs-prev-next-dir", children: "\u2190 Previous" }),
+              /* @__PURE__ */ jsx5("div", { className: "np-docs-prev-next-title", children: navInfo.prev.title })
+            ]
+          }
+        ) : /* @__PURE__ */ jsx5("span", {}),
+        navInfo.next ? /* @__PURE__ */ jsxs5(
+          "a",
+          {
+            href: `/docs/${navInfo.next.slug}`,
+            className: "np-docs-prev-next-next",
+            children: [
+              /* @__PURE__ */ jsx5("div", { className: "np-docs-prev-next-dir", children: "Next \u2192" }),
+              /* @__PURE__ */ jsx5("div", { className: "np-docs-prev-next-title", children: navInfo.next.title })
+            ]
+          }
+        ) : /* @__PURE__ */ jsx5("span", {})
+      ] })
+    ] }),
+    toc.length > 0 ? /* @__PURE__ */ jsxs5("aside", { className: "np-docs-toc", "aria-label": "On this page", children: [
+      /* @__PURE__ */ jsx5("p", { className: "np-docs-toc-eyebrow", children: "On this page" }),
+      /* @__PURE__ */ jsx5("ul", { children: toc.map((entry) => /* @__PURE__ */ jsx5(
+        "li",
         {
-          href: `/docs/${navInfo.next.slug}`,
-          style: { textAlign: "right" },
-          children: [
-            /* @__PURE__ */ jsx5("span", { className: "np-docs-prev-next-label", children: "Next \u2192" }),
-            navInfo.next.title
-          ]
-        }
-      ) : /* @__PURE__ */ jsx5("span", {})
-    ] })
+          style: entry.level === 3 ? { marginLeft: "0.85rem" } : void 0,
+          children: /* @__PURE__ */ jsx5("a", { href: `#${entry.id}`, children: entry.text })
+        },
+        `toc-${entry.id}`
+      )) }),
+      /* @__PURE__ */ jsx5(TocScrollspy, { ids: toc.map((entry) => entry.id) }),
+      editHref || reportIssueHref ? /* @__PURE__ */ jsxs5("div", { className: "np-docs-toc-secondary", children: [
+        editHref ? /* @__PURE__ */ jsxs5("a", { href: editHref, target: "_blank", rel: "noreferrer", children: [
+          /* @__PURE__ */ jsxs5(
+            "svg",
+            {
+              width: "12",
+              height: "12",
+              viewBox: "0 0 24 24",
+              fill: "none",
+              stroke: "currentColor",
+              strokeWidth: "2",
+              "aria-hidden": "true",
+              children: [
+                /* @__PURE__ */ jsx5("path", { d: "M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7" }),
+                /* @__PURE__ */ jsx5("path", { d: "m18.5 2.5 3 3L12 15l-4 1 1-4 9.5-9.5z" })
+              ]
+            }
+          ),
+          "Edit on GitHub"
+        ] }) : null,
+        reportIssueHref ? /* @__PURE__ */ jsxs5("a", { href: reportIssueHref, target: "_blank", rel: "noreferrer", children: [
+          /* @__PURE__ */ jsxs5(
+            "svg",
+            {
+              width: "12",
+              height: "12",
+              viewBox: "0 0 24 24",
+              fill: "none",
+              stroke: "currentColor",
+              strokeWidth: "2",
+              "aria-hidden": "true",
+              children: [
+                /* @__PURE__ */ jsx5("circle", { cx: "12", cy: "12", r: "10" }),
+                /* @__PURE__ */ jsx5("path", { d: "M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3" }),
+                /* @__PURE__ */ jsx5("line", { x1: "12", y1: "17", x2: "12.01", y2: "17" })
+              ]
+            }
+          ),
+          "Report an issue"
+        ] }) : null
+      ] }) : null
+    ] }) : null
   ] });
 }
+async function loadBreadcrumbs(current) {
+  const root = { slug: null, title: "Docs" };
+  if (!current.parent) {
+    return [root, { slug: null, title: current.title }];
+  }
+  const result = await findDocuments("posts", {
+    where: { status: "published", kind: "doc" },
+    sort: "order",
+    limit: 500
+  });
+  const byId = /* @__PURE__ */ new Map();
+  for (const r of result.docs) {
+    if (r.id) byId.set(r.id, r);
+  }
+  const chain = [];
+  let cursor = current.parent;
+  let safety = 6;
+  while (cursor && safety-- > 0) {
+    const node = byId.get(cursor);
+    if (!node) break;
+    chain.unshift({ slug: node.slug, title: node.title });
+    cursor = node.parent ?? null;
+  }
+  return [root, ...chain, { slug: null, title: current.title }];
+}
 async function loadPrevNext(current) {
-  const result = await findDocuments("docs", {
-    where: { status: "published" },
+  const result = await findDocuments("posts", {
+    where: { status: "published", kind: "doc" },
     sort: "order",
     limit: 500
   });
@@ -276,6 +445,25 @@ async function loadPrevNext(current) {
     next: idx < docs.length - 1 ? docs[idx + 1] ?? null : null
   };
 }
+function formatUpdated(value) {
+  if (!value) return null;
+  try {
+    const d = typeof value === "string" ? new Date(value) : value;
+    if (Number.isNaN(d.getTime())) return null;
+    return d.toLocaleDateString(void 0, {
+      year: "numeric",
+      month: "short",
+      day: "numeric"
+    });
+  } catch {
+    return null;
+  }
+}
+function readingMinutesLabel(value) {
+  if (!value && value !== 0) return null;
+  if (typeof value === "number") return `${value.toString()} min read`;
+  return value;
+}
 
 // src/routes/doc-detail.tsx
 import { jsx as jsx6 } from "react/jsx-runtime";
@@ -285,8 +473,8 @@ async function DocsDetailRoute({
 }) {
   const slug = typeof params.slug === "string" ? params.slug : "";
   if (!slug) notFound();
-  const result = await findDocuments2("docs", {
-    where: { slug, status: "published" },
+  const result = await findDocuments2("posts", {
+    where: { slug, status: "published", kind: "doc" },
     limit: 1
   });
   const doc = result.docs[0];
@@ -395,16 +583,52 @@ import { findDocuments as findDocuments3 } from "@nexpress/core";
 import { jsx as jsx9, jsxs as jsxs7 } from "react/jsx-runtime";
 async function DocsSidebar() {
   const settings = await resolveDocsSettings();
-  const result = await findDocuments3("docs", {
-    where: { status: "published" },
+  const currentSlug = await currentPathSlug();
+  const result = await findDocuments3("posts", {
+    where: { status: "published", kind: "doc" },
     sort: "order",
     limit: 500
   });
   const tree = buildTree(result.docs);
-  return /* @__PURE__ */ jsxs7("aside", { className: "np-docs-sidebar", "aria-label": "Docs navigation", children: [
-    /* @__PURE__ */ jsx9("h2", { children: settings.sidebarHeading }),
-    /* @__PURE__ */ jsx9(NavTree, { nodes: tree })
-  ] });
+  if (tree.length === 0) {
+    return /* @__PURE__ */ jsx9("aside", { className: "np-docs-sidebar", "aria-label": "Docs navigation", children: /* @__PURE__ */ jsxs7("div", { className: "np-docs-sidebar-group", children: [
+      /* @__PURE__ */ jsxs7("h2", { className: "np-docs-sidebar-eyebrow", children: [
+        /* @__PURE__ */ jsx9("span", { className: "np-docs-sidebar-eyebrow-dot", "aria-hidden": "true" }),
+        settings.sidebarHeading
+      ] }),
+      /* @__PURE__ */ jsx9(
+        "p",
+        {
+          style: {
+            padding: "0.34rem 0.6rem",
+            fontSize: "0.875rem",
+            color: "var(--np-color-muted-foreground)",
+            margin: 0
+          },
+          children: "No docs yet."
+        }
+      )
+    ] }) });
+  }
+  return /* @__PURE__ */ jsx9("aside", { className: "np-docs-sidebar", "aria-label": "Docs navigation", children: tree.map((group) => /* @__PURE__ */ jsxs7("div", { className: "np-docs-sidebar-group", children: [
+    /* @__PURE__ */ jsxs7("h2", { className: "np-docs-sidebar-eyebrow", children: [
+      /* @__PURE__ */ jsx9("span", { className: "np-docs-sidebar-eyebrow-dot", "aria-hidden": "true" }),
+      group.title
+    ] }),
+    group.children.length > 0 ? /* @__PURE__ */ jsx9(NavTree, { nodes: group.children, currentSlug }) : /* @__PURE__ */ jsx9("ul", { children: /* @__PURE__ */ jsx9(SidebarLink, { node: group, currentSlug }) })
+  ] }, group.id)) });
+}
+async function currentPathSlug() {
+  try {
+    const { headers } = await import("next/headers");
+    const list = await headers();
+    const pathname = list.get("x-np-pathname");
+    if (!pathname) return null;
+    const m = /^\/docs\/(.+?)\/?$/.exec(pathname);
+    return m ? m[1] ?? null : null;
+  } catch {
+    return null;
+  }
 }
 function buildTree(rawDocs) {
   const docs = rawDocs;
@@ -418,6 +642,7 @@ function buildTree(rawDocs) {
       title: typeof d.title === "string" ? d.title : d.slug,
       parent: typeof d.parent === "string" ? d.parent : null,
       order: typeof d.order === "number" ? d.order : 0,
+      badge: typeof d.badge === "string" ? d.badge : null,
       children: []
     });
   }
@@ -436,12 +661,34 @@ function buildTree(rawDocs) {
   sortRec(roots);
   return roots;
 }
-function NavTree({ nodes }) {
+function NavTree({
+  nodes,
+  currentSlug
+}) {
   return /* @__PURE__ */ jsx9("ul", { children: nodes.map((n) => /* @__PURE__ */ jsxs7("li", { children: [
-    /* @__PURE__ */ jsx9("a", { href: `/docs/${n.slug}`, children: n.title }),
-    n.children.length > 0 ? /* @__PURE__ */ jsx9(NavTree, { nodes: n.children }) : null
+    /* @__PURE__ */ jsx9(SidebarLink, { node: n, currentSlug }),
+    n.children.length > 0 ? /* @__PURE__ */ jsx9(NavTree, { nodes: n.children, currentSlug }) : null
   ] }, n.id)) });
 }
+function SidebarLink({
+  node,
+  currentSlug
+}) {
+  const isCurrent = currentSlug !== null && currentSlug === node.slug;
+  const badgeClass = node.badge ? `np-docs-sidebar-badge ${node.badge.toLowerCase()}` : null;
+  return /* @__PURE__ */ jsxs7(
+    "a",
+    {
+      href: `/docs/${node.slug}`,
+      "data-current": isCurrent ? "true" : void 0,
+      "aria-current": isCurrent ? "page" : void 0,
+      children: [
+        node.title,
+        badgeClass ? /* @__PURE__ */ jsx9("span", { className: badgeClass, children: node.badge.toUpperCase() }) : null
+      ]
+    }
+  );
+}
 
 // src/styles.ts
 var docsCss = `
@@ -451,257 +698,896 @@ var docsCss = `
   min-height: 100vh;
   background: var(--np-color-background);
   color: var(--np-color-foreground);
-  font-family: var(--np-font-body, system-ui, sans-serif);
+  font-family: var(--np-font-body, "Geist", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif);
+  line-height: 1.6;
+  -webkit-font-smoothing: antialiased;
+}
+.np-docs-shell a { color: inherit; }
+.np-docs-shell code,
+.np-docs-shell pre,
+.np-docs-shell kbd {
+  font-family: var(--np-font-mono, "Geist Mono", ui-monospace, SFMono-Regular, Menlo, monospace);
 }
 
+/* ============================================================
+ * Header \u2014 sticky bar with brand + version pill, \u2318K search in
+ * the center, primary nav + GitHub link on the right. Grid
+ * keeps everything anchored regardless of viewport width.
+ * ============================================================ */
 .np-docs-header {
   position: sticky;
   top: 0;
-  z-index: 50;
-  background: var(--np-color-background);
+  z-index: 30;
+  background: color-mix(in oklab, var(--np-color-background) 80%, transparent);
+  backdrop-filter: saturate(140%) blur(14px);
+  -webkit-backdrop-filter: saturate(140%) blur(14px);
   border-bottom: 1px solid var(--np-color-border);
-  backdrop-filter: blur(8px);
 }
-
 .np-docs-header-inner {
-  max-width: 1200px;
+  max-width: 1380px;
   margin: 0 auto;
-  padding: 0.75rem 1.5rem;
+  padding: 0.7rem 1.5rem;
   display: grid;
-  grid-template-columns: auto 1fr auto;
+  grid-template-columns: minmax(220px, 1fr) minmax(0, 2fr) auto;
   gap: 1.5rem;
   align-items: center;
 }
-
 .np-docs-brand {
-  display: flex;
-  align-items: baseline;
-  gap: 0.5rem;
-  font-weight: 600;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.55rem;
+  font-weight: 700;
+  font-size: 1.0625rem;
+  letter-spacing: -0.02em;
   text-decoration: none;
-  color: var(--np-color-foreground);
 }
-
+.np-docs-brand-mark {
+  width: 1.55rem;
+  height: 1.55rem;
+  border-radius: 6px;
+  background: linear-gradient(135deg, var(--np-color-primary, #2563eb), #0ea5e9);
+  position: relative;
+  flex: none;
+}
+.np-docs-brand-mark::after {
+  content: "";
+  position: absolute;
+  inset: 5px;
+  border-radius: 2px;
+  background: var(--np-color-background, #fff);
+  opacity: 0.95;
+  clip-path: polygon(0 0, 100% 0, 100% 100%, 60% 100%, 0 35%);
+}
+.np-docs-brand-name { font-weight: 700; }
 .np-docs-brand-version {
-  font-size: 0.75rem;
-  font-family: ui-monospace, "SF Mono", Menlo, monospace;
-  color: var(--np-color-muted-foreground);
-  background: var(--np-color-muted);
-  padding: 0.125rem 0.375rem;
-  border-radius: 0.25rem;
+  font-family: var(--np-font-mono);
+  font-size: 0.72rem;
+  font-weight: 500;
+  color: var(--np-color-primary);
+  background: color-mix(in oklab, var(--np-color-primary) 14%, var(--np-color-card));
+  padding: 0.15rem 0.45rem;
+  border-radius: 5px;
 }
 
 .np-docs-search-form {
-  flex: 1;
+  max-width: 520px;
+  width: 100%;
+  position: relative;
+  justify-self: center;
+}
+.np-docs-search-form svg {
+  position: absolute;
+  top: 50%;
+  left: 0.85rem;
+  transform: translateY(-50%);
+  color: var(--np-color-muted-foreground);
 }
-
 .np-docs-search-input {
   width: 100%;
-  padding: 0.4rem 0.75rem;
-  border: 1px solid var(--np-color-border);
-  border-radius: 0.375rem;
-  background: var(--np-color-card);
-  color: var(--np-color-foreground);
+  padding: 0.55rem 0.85rem 0.55rem 2.4rem;
+  font: inherit;
   font-size: 0.875rem;
+  color: var(--np-color-foreground);
+  background: var(--np-color-card);
+  border: 1px solid var(--np-color-border);
+  border-radius: 9px;
+}
+.np-docs-search-input::placeholder {
+  color: var(--np-color-muted-foreground);
 }
-
 .np-docs-search-input:focus {
-  outline: 2px solid var(--np-color-primary);
-  outline-offset: -2px;
-  border-color: transparent;
+  outline: none;
+  border-color: var(--np-color-primary);
+  box-shadow: 0 0 0 3px color-mix(in oklab, var(--np-color-primary) 22%, transparent);
+}
+.np-docs-search-kbd {
+  position: absolute;
+  right: 0.6rem;
+  top: 50%;
+  transform: translateY(-50%);
+  font-size: 0.7rem;
+  padding: 0.1rem 0.4rem;
+  color: var(--np-color-muted-foreground);
+  border: 1px solid var(--np-color-border);
+  border-radius: 4px;
 }
 
 .np-docs-nav {
   display: flex;
   align-items: center;
-  gap: 1rem;
+  gap: 1.25rem;
 }
-
 .np-docs-primary-nav {
   display: flex;
   list-style: none;
+  gap: 1.25rem;
   margin: 0;
   padding: 0;
-  gap: 1rem;
 }
-
 .np-docs-primary-nav a {
   color: var(--np-color-muted-foreground);
-  text-decoration: none;
   font-size: 0.875rem;
+  font-weight: 500;
+  text-decoration: none;
 }
-
-.np-docs-primary-nav a:hover {
+.np-docs-primary-nav a:hover,
+.np-docs-primary-nav a[aria-current="page"] {
   color: var(--np-color-foreground);
 }
-
+.np-docs-github,
 .np-docs-github-link {
-  font-size: 0.875rem;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.45rem;
+  padding: 0.4rem 0.7rem;
+  font-size: 0.8125rem;
   color: var(--np-color-muted-foreground);
+  background: var(--np-color-muted);
+  border: 1px solid var(--np-color-border);
+  border-radius: 7px;
   text-decoration: none;
 }
+.np-docs-github:hover,
+.np-docs-github-link:hover {
+  color: var(--np-color-foreground);
+}
 
-.np-docs-grid {
-  flex: 1;
-  display: grid;
-  grid-template-columns: 240px minmax(0, 1fr);
-  max-width: 1200px;
+@media (max-width: 800px) {
+  .np-docs-header-inner {
+    grid-template-columns: auto 1fr auto;
+    gap: 0.75rem;
+  }
+  .np-docs-search-form { display: none; }
+  .np-docs-primary-nav { display: none; }
+}
+
+/* ============================================================
+ * 3-column layout: sidebar + article + on-page TOC.
+ * ============================================================ */
+.np-docs-grid,
+.np-docs-body {
+  max-width: 1380px;
   margin: 0 auto;
   width: 100%;
-  gap: 2.5rem;
-  padding: 2rem 1.5rem;
+  display: grid;
+  grid-template-columns: 260px minmax(0, 1fr) 220px;
+  gap: 3rem;
+  padding: 2.25rem 1.5rem 4rem;
 }
-
-@media (max-width: 768px) {
-  .np-docs-grid {
-    grid-template-columns: 1fr;
+@media (max-width: 1100px) {
+  .np-docs-grid,
+  .np-docs-body {
+    grid-template-columns: 240px minmax(0, 1fr);
   }
-  .np-docs-sidebar {
-    display: none;
+  .np-docs-toc { display: none; }
+}
+@media (max-width: 800px) {
+  .np-docs-grid,
+  .np-docs-body {
+    grid-template-columns: 1fr;
   }
+  .np-docs-sidebar { display: none; }
 }
 
+/* ============================================================
+ * Sidebar \u2014 grouped link list with bullet eyebrow + badges.
+ * ============================================================ */
 .np-docs-sidebar {
   position: sticky;
-  top: 4rem;
+  top: 4.25rem;
   align-self: start;
   max-height: calc(100vh - 5rem);
   overflow-y: auto;
+  padding-right: 0.5rem;
 }
-
-.np-docs-sidebar h2 {
-  font-size: 0.75rem;
+.np-docs-sidebar-group { margin-bottom: 1.5rem; }
+.np-docs-sidebar-eyebrow {
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+  font-family: var(--np-font-mono);
+  font-size: 0.7rem;
   text-transform: uppercase;
   letter-spacing: 0.08em;
   color: var(--np-color-muted-foreground);
-  margin: 0 0 0.75rem;
+  margin: 0 0 0.65rem;
+  font-weight: 600;
+}
+.np-docs-sidebar-eyebrow-dot {
+  width: 0.4rem;
+  height: 0.4rem;
+  border-radius: 50%;
+  background: var(--np-color-primary);
 }
-
 .np-docs-sidebar ul {
   list-style: none;
   padding: 0;
   margin: 0;
 }
-
-.np-docs-sidebar li {
-  margin: 0.125rem 0;
-}
-
+.np-docs-sidebar li { margin: 0.05rem 0; }
 .np-docs-sidebar a {
   display: block;
-  padding: 0.25rem 0.5rem;
-  border-radius: 0.25rem;
+  padding: 0.34rem 0.6rem;
+  font-size: 0.875rem;
   color: var(--np-color-muted-foreground);
   text-decoration: none;
-  font-size: 0.875rem;
+  border-radius: 6px;
+  line-height: 1.35;
 }
-
 .np-docs-sidebar a:hover {
   background: var(--np-color-muted);
   color: var(--np-color-foreground);
 }
-
-.np-docs-sidebar a[data-current="true"] {
-  background: color-mix(in oklch, var(--np-color-primary) 12%, transparent);
+.np-docs-sidebar a[data-current="true"],
+.np-docs-sidebar a[aria-current="page"] {
   color: var(--np-color-primary);
+  background: color-mix(in oklab, var(--np-color-primary) 14%, var(--np-color-card));
   font-weight: 500;
 }
-
 .np-docs-sidebar ul ul {
-  margin-left: 0.75rem;
+  margin-left: 0.5rem;
+  padding-left: 0.85rem;
   border-left: 1px solid var(--np-color-border);
-  padding-left: 0.5rem;
+}
+.np-docs-sidebar-badge {
+  display: inline-block;
+  font-family: var(--np-font-mono);
+  font-size: 0.62rem;
+  padding: 0.02rem 0.34rem;
+  margin-left: 0.4rem;
+  vertical-align: 1px;
+  border-radius: 4px;
+  background: var(--np-color-muted);
+  color: var(--np-color-muted-foreground);
+  font-weight: 500;
+}
+.np-docs-sidebar-badge.new { background: #dcfce7; color: #166534; }
+.np-docs-sidebar-badge.beta { background: #fef3c7; color: #92400e; }
+.np-docs-sidebar-badge.api {
+  background: color-mix(in oklab, var(--np-color-primary) 16%, var(--np-color-card));
+  color: var(--np-color-primary);
 }
 
+/* ============================================================
+ * Doc page \u2014 article column. h1 + lede + meta row + sections
+ * with hovered anchor link icon.
+ * ============================================================ */
 .np-docs-page {
-  max-width: 720px;
+  max-width: 760px;
+  min-width: 0;
+}
+.np-docs-breadcrumbs {
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+  font-size: 0.8125rem;
+  color: var(--np-color-muted-foreground);
+  margin-bottom: 1rem;
 }
+.np-docs-breadcrumbs a {
+  color: inherit;
+  text-decoration: none;
+}
+.np-docs-breadcrumbs a:hover { color: var(--np-color-foreground); }
+.np-docs-breadcrumbs-sep { opacity: 0.5; }
 
 .np-docs-page h1 {
-  font-size: 2rem;
+  font-size: clamp(2rem, 3.6vw, 2.5rem);
+  font-weight: 700;
+  letter-spacing: -0.03em;
+  line-height: 1.1;
   margin: 0 0 0.5rem;
+  text-wrap: balance;
+}
+.np-docs-page-lede {
+  font-size: 1.125rem;
+  color: var(--np-color-muted-foreground);
+  line-height: 1.55;
+  margin: 0 0 2rem;
+  max-width: 38rem;
+  text-wrap: pretty;
+}
+.np-docs-page-meta {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  align-items: center;
+  font-size: 0.8125rem;
+  color: var(--np-color-muted-foreground);
+  padding: 0.85rem 0;
+  margin-bottom: 2rem;
+  border-top: 1px solid var(--np-color-border);
+  border-bottom: 1px solid var(--np-color-border);
+}
+.np-docs-page-meta-pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+  padding: 0.15rem 0.55rem;
+  font-family: var(--np-font-mono);
+  font-size: 0.72rem;
+  border: 1px solid var(--np-color-border);
+  border-radius: 999px;
+  background: var(--np-color-card);
+}
+.np-docs-page-meta-pill.status {
+  color: #047857;
+  border-color: #bbf7d0;
+  background: #f0fdf4;
+}
+.np-docs-page-meta-pill.status::before {
+  content: "";
+  width: 0.4rem;
+  height: 0.4rem;
+  border-radius: 50%;
+  background: #047857;
+}
+.np-docs-page-meta-sep { opacity: 0.4; }
+.np-docs-page-meta a {
+  color: var(--np-color-primary);
+  text-decoration: none;
+  margin-left: auto;
+}
+.np-docs-page-meta a:hover { text-decoration: underline; }
+
+.np-docs-page h2 {
+  font-size: 1.5rem;
+  font-weight: 600;
+  letter-spacing: -0.02em;
+  line-height: 1.25;
+  margin: 3rem 0 0.85rem;
+  scroll-margin-top: 5rem;
+  position: relative;
+}
+.np-docs-page h2:first-of-type { margin-top: 2.5rem; }
+.np-docs-page h3 {
+  font-size: 1.1rem;
+  font-weight: 600;
+  letter-spacing: -0.01em;
+  margin: 2.25rem 0 0.7rem;
+  scroll-margin-top: 5rem;
+  position: relative;
+}
+.np-docs-page p { margin: 0 0 1rem; }
+.np-docs-page p code,
+.np-docs-page li code {
+  font-size: 0.875em;
+  padding: 0.1em 0.35em;
+  background: var(--np-color-muted);
+  border: 1px solid var(--np-color-border);
+  border-radius: 4px;
+}
+.np-docs-page strong { font-weight: 600; }
+.np-docs-page ul,
+.np-docs-page ol {
+  margin: 0 0 1rem;
+  padding-left: 1.4rem;
+}
+.np-docs-page li { margin: 0.35rem 0; }
+.np-docs-page a:not(.np-docs-prev-next a):not(.np-docs-anchor) {
+  color: var(--np-color-primary);
+  text-decoration: underline;
+  text-underline-offset: 3px;
+  text-decoration-thickness: 1px;
+  text-decoration-color: color-mix(in oklab, var(--np-color-primary) 45%, transparent);
+}
+.np-docs-page a:not(.np-docs-prev-next a):not(.np-docs-anchor):hover {
+  text-decoration-color: currentColor;
+}
+
+/* Anchor icon \u2014 visible only on heading hover. */
+.np-docs-anchor {
+  position: absolute;
+  left: -1.3rem;
+  top: 50%;
+  transform: translateY(-50%);
+  color: var(--np-color-muted-foreground);
+  opacity: 0;
+  text-decoration: none !important;
+  font-weight: 400;
+}
+.np-docs-page h2:hover .np-docs-anchor,
+.np-docs-page h3:hover .np-docs-anchor { opacity: 1; }
+
+/* ============================================================
+ * Callouts \u2014 info (default) / note (indigo) / warn (amber) /
+ * danger (red). 3px left rule carries the variant color.
+ * ============================================================ */
+.np-docs-callout {
+  display: grid;
+  grid-template-columns: auto 1fr;
+  gap: 0.85rem;
+  padding: 1rem 1.15rem;
+  border: 1px solid var(--np-color-border);
+  border-left: 3px solid var(--np-color-primary);
+  border-radius: 8px;
+  background: var(--np-color-card);
+  margin: 1.25rem 0;
+  font-size: 0.95rem;
+  line-height: 1.55;
+}
+.np-docs-callout > svg,
+.np-docs-callout-icon {
+  width: 1.25rem;
+  height: 1.25rem;
+  flex-shrink: 0;
+  color: var(--np-color-primary);
+  margin-top: 0.1rem;
+}
+.np-docs-callout p { margin: 0; }
+.np-docs-callout-title {
+  font-weight: 600;
+  margin-bottom: 0.15rem;
+  color: var(--np-color-foreground);
+}
+.np-docs-callout--warn {
+  border-left-color: #b45309;
+  background: #fffbeb;
+  border-color: #fde68a;
+}
+.np-docs-callout--warn .np-docs-callout-icon,
+.np-docs-callout--warn > svg { color: #b45309; }
+.np-docs-callout--note {
+  border-left-color: #6366f1;
+  background: #eef2ff;
+  border-color: #c7d2fe;
+}
+.np-docs-callout--note .np-docs-callout-icon,
+.np-docs-callout--note > svg { color: #4338ca; }
+.np-docs-callout--danger {
+  border-left-color: #b91c1c;
+  background: #fef2f2;
+  border-color: #fecaca;
+}
+.np-docs-callout--danger .np-docs-callout-icon,
+.np-docs-callout--danger > svg { color: #b91c1c; }
+
+/* ============================================================
+ * Code blocks \u2014 dark surface with a file-named header and a
+ * copy button. Syntax tokens (.tk-*) cover the common slots
+ * (keyword / string / function / number / type / punctuation /
+ * comment) using a muted neutral-paired palette so the block
+ * reads at the same contrast as the page chrome.
+ * ============================================================ */
+.np-docs-code {
+  margin: 1.25rem 0;
+  border-radius: 10px;
+  background: #0b1220;
+  color: #e6edf6;
+  overflow: hidden;
+  border: 1px solid #1e2939;
+}
+.np-docs-code-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0.55rem 0.85rem;
+  background: #0f1a2b;
+  border-bottom: 1px solid #1e293b;
+}
+.np-docs-code-file {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-family: var(--np-font-mono);
+  font-size: 0.78rem;
+  color: #94a3b8;
+}
+.np-docs-code-file svg { color: #64748b; }
+.np-docs-code-copy {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+  padding: 0.25rem 0.55rem;
+  font-size: 0.72rem;
+  font-family: var(--np-font-mono);
+  color: #94a3b8;
+  background: transparent;
+  border: 1px solid #1e293b;
+  border-radius: 5px;
+  cursor: pointer;
+}
+.np-docs-code-copy:hover {
+  color: #e2e8f0;
+  border-color: #334155;
+}
+.np-docs-code pre {
+  margin: 0;
+  padding: 1rem 1.1rem;
+  font-size: 0.825rem;
+  line-height: 1.65;
+  overflow-x: auto;
+}
+.np-docs-code pre code {
+  display: block;
+  font-family: inherit;
+  background: transparent;
+  border: 0;
+  padding: 0;
+  color: inherit;
+}
+.tk-c { color: #64748b; font-style: italic; }
+.tk-k { color: #c084fc; }
+.tk-s { color: #86efac; }
+.tk-f { color: #93c5fd; }
+.tk-t { color: #fcd34d; }
+.tk-n { color: #f9a8d4; }
+.tk-p { color: #e2e8f0; }
+
+/* Inline shell snippet \u2014 for terse \`pnpm dev\` style commands.
+ * Named \`cmdline\` (not \`shell\`) so it doesn't collide with the
+ * route shell container at \`.np-docs-shell\`. */
+.np-docs-cmdline {
+  display: grid;
+  grid-template-columns: auto 1fr auto;
+  gap: 0.7rem;
+  align-items: center;
+  padding: 0.75rem 1rem;
+  margin: 1.25rem 0;
+  background: #0b1220;
+  color: #e6edf6;
+  border-radius: 9px;
+  font-family: var(--np-font-mono);
+  font-size: 0.875rem;
+}
+.np-docs-cmdline-prompt { color: #34d399; }
+.np-docs-cmdline-cmd { color: #e2e8f0; }
+.np-docs-cmdline-copy {
+  padding: 0.2rem 0.55rem;
+  font-size: 0.7rem;
+  color: #94a3b8;
+  background: transparent;
+  border: 1px solid #1e293b;
+  border-radius: 5px;
+  cursor: pointer;
+}
+.np-docs-cmdline-copy:hover { color: #e2e8f0; border-color: #334155; }
+
+/* ============================================================
+ * Numbered steps \u2014 counter on a soft pill before each step.
+ * ============================================================ */
+.np-docs-steps {
+  counter-reset: step;
+  list-style: none;
+  padding: 0;
+  margin: 1.5rem 0;
+  display: grid;
+  gap: 1rem;
+}
+.np-docs-steps > li {
+  counter-increment: step;
+  display: grid;
+  grid-template-columns: 2.1rem 1fr;
+  gap: 0.85rem;
+  align-items: start;
+}
+.np-docs-steps > li::before {
+  content: counter(step);
+  width: 1.85rem;
+  height: 1.85rem;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font-family: var(--np-font-mono);
+  font-size: 0.85rem;
+  font-weight: 600;
+  color: var(--np-color-primary);
+  background: color-mix(in oklab, var(--np-color-primary) 14%, var(--np-color-card));
+  border-radius: 50%;
+}
+.np-docs-step-title {
+  font-weight: 600;
+  margin: 0.25rem 0 0.25rem;
+}
+.np-docs-step-body {
+  margin: 0;
+  color: var(--np-color-muted-foreground);
+}
+
+/* ============================================================
+ * API / reference tables \u2014 uppercase mono headers.
+ * ============================================================ */
+.np-docs-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 0.875rem;
+  margin: 1.25rem 0;
+}
+.np-docs-table thead { background: var(--np-color-muted); }
+.np-docs-table th,
+.np-docs-table td {
+  text-align: left;
+  padding: 0.7rem 0.85rem;
+  border-bottom: 1px solid var(--np-color-border);
+  vertical-align: top;
+}
+.np-docs-table th {
+  font-family: var(--np-font-mono);
+  font-size: 0.72rem;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--np-color-muted-foreground);
+  font-weight: 600;
+}
+.np-docs-table td:first-child code {
+  color: var(--np-color-foreground);
+  font-weight: 500;
+}
+.np-docs-table-required {
+  display: inline-block;
+  font-family: var(--np-font-mono);
+  font-size: 0.65rem;
+  padding: 0.05rem 0.35rem;
+  margin-left: 0.4rem;
+  background: #fef3c7;
+  color: #92400e;
+  border-radius: 4px;
+  vertical-align: 1px;
 }
 
+/* ============================================================
+ * Prev / next \u2014 symmetric pair at the foot of every doc page.
+ * Hover lifts the bordered card and tints the border primary.
+ * ============================================================ */
 .np-docs-prev-next {
   display: grid;
   grid-template-columns: 1fr 1fr;
   gap: 1rem;
-  margin-top: 3rem;
-  padding-top: 1.5rem;
+  margin: 3.5rem 0 1rem;
+  padding-top: 2rem;
   border-top: 1px solid var(--np-color-border);
 }
-
 .np-docs-prev-next a {
   display: block;
-  padding: 0.75rem 1rem;
+  padding: 1rem 1.15rem;
+  background: var(--np-color-card);
   border: 1px solid var(--np-color-border);
-  border-radius: 0.5rem;
-  color: var(--np-color-foreground);
+  border-radius: 10px;
   text-decoration: none;
+  transition: border-color 0.15s ease, transform 0.2s ease;
 }
-
 .np-docs-prev-next a:hover {
   border-color: var(--np-color-primary);
+  transform: translateY(-1px);
 }
-
+.np-docs-prev-next-dir,
 .np-docs-prev-next-label {
-  display: block;
-  font-size: 0.75rem;
+  font-family: var(--np-font-mono);
+  font-size: 0.72rem;
   color: var(--np-color-muted-foreground);
+  letter-spacing: 0.05em;
   margin-bottom: 0.25rem;
 }
+.np-docs-prev-next-title {
+  font-weight: 600;
+  font-size: 0.95rem;
+}
+.np-docs-prev-next a.np-docs-prev-next-next,
+.np-docs-prev-next a:last-child { text-align: right; }
 
-/* M.* member surface \u2014 narrow auth-form column under the
-   masthead, no sidebar (the docs sidebar is hierarchical
-   doc nav, useless on auth forms). */
-.np-docs-members {
+/* ============================================================
+ * Feedback row \u2014 Yes / Could be better buttons under each page.
+ * ============================================================ */
+.np-docs-feedback {
+  margin-top: 3rem;
+  padding: 1.25rem;
+  background: var(--np-color-muted);
+  border: 1px solid var(--np-color-border);
+  border-radius: 10px;
   display: flex;
-  justify-content: center;
-  min-height: 60vh;
-  padding: 3rem 1.5rem;
+  gap: 1rem;
+  align-items: center;
+  justify-content: space-between;
+  flex-wrap: wrap;
 }
-.np-docs-members-column {
-  width: 100%;
-  max-width: 440px;
+.np-docs-feedback-title { font-weight: 600; font-size: 0.95rem; }
+.np-docs-feedback-helper {
+  font-size: 0.825rem;
+  color: var(--np-color-muted-foreground);
+  margin-top: 0.15rem;
+}
+.np-docs-feedback-buttons {
+  display: flex;
+  gap: 0.5rem;
+}
+.np-docs-feedback-buttons button {
+  padding: 0.4rem 0.85rem;
+  font: inherit;
+  font-size: 0.825rem;
+  background: var(--np-color-card);
+  border: 1px solid var(--np-color-border);
+  border-radius: 7px;
+  cursor: pointer;
+}
+.np-docs-feedback-buttons button:hover {
+  border-color: var(--np-color-primary);
+  color: var(--np-color-primary);
+}
+
+/* ============================================================
+ * On-page TOC \u2014 right rail, sticky, current section gets a
+ * primary border + soft gradient.
+ * ============================================================ */
+.np-docs-toc {
+  position: sticky;
+  top: 4.25rem;
+  align-self: start;
+  max-height: calc(100vh - 5rem);
+  overflow-y: auto;
+  font-size: 0.825rem;
+}
+.np-docs-toc-eyebrow {
+  font-family: var(--np-font-mono);
+  font-size: 0.7rem;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--np-color-muted-foreground);
+  margin: 0 0 0.75rem;
+  font-weight: 600;
+}
+.np-docs-toc ul {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+.np-docs-toc li { margin: 0.05rem 0; }
+.np-docs-toc a {
+  display: block;
+  padding: 0.3rem 0.5rem;
+  color: var(--np-color-muted-foreground);
+  text-decoration: none;
+  border-left: 2px solid transparent;
+  margin-left: -2px;
+  line-height: 1.4;
+}
+.np-docs-toc a:hover { color: var(--np-color-foreground); }
+.np-docs-toc a[data-current="true"],
+.np-docs-toc a[aria-current="location"],
+.np-docs-toc a[aria-current="true"] {
+  color: var(--np-color-primary);
+  border-left-color: var(--np-color-primary);
+  background: linear-gradient(
+    to right,
+    color-mix(in oklab, var(--np-color-primary) 14%, var(--np-color-card)),
+    transparent 80%
+  );
+}
+.np-docs-toc ul ul { margin-left: 0.85rem; }
+.np-docs-toc-secondary {
+  margin-top: 1.5rem;
+  padding-top: 1rem;
+  border-top: 1px solid var(--np-color-border);
+}
+.np-docs-toc-secondary a {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+  padding: 0.2rem 0;
+  border-left: 0;
+  margin: 0;
 }
+.np-docs-toc-secondary a:hover { background: transparent; }
 
-/* Member form token overrides \u2014 docs aesthetic: slightly
-   rounded corners, neutral palette, monospace label accent. */
-.np-docs .np-members-form {
-  --np-member-form-input-bg: var(--np-color-background);
-  --np-member-form-input-border: var(--np-color-border);
-  --np-member-form-input-border-focus: var(--np-color-primary);
-  --np-member-form-input-radius: 0.375rem;
-  --np-member-form-button-radius: 0.375rem;
+/* Empty / not-found surfaces \u2014 used by routes/not-found and
+ * the docs collection's empty state. */
+.np-docs-empty {
+  padding: 4rem 1.5rem;
+  text-align: center;
+  color: var(--np-color-muted-foreground);
 }
-.np-docs .np-members-form .np-form-label {
-  font-family: var(--np-font-mono, ui-monospace, monospace);
-  font-size: 0.8125rem;
+.np-docs-empty h1 {
+  font-size: 1.5rem;
+  margin: 0 0 0.5rem;
+  color: var(--np-color-foreground);
 }
 `;
 
 // src/index.ts
+var SEED_NAV = {
+  header: [
+    { id: "nav-docs-docs", label: "Docs", type: "link", url: "/docs" },
+    { id: "nav-docs-reference", label: "Reference", type: "link", url: "/docs/reference" },
+    { id: "nav-docs-blog", label: "Blog", type: "link", url: "/blog" }
+  ],
+  footer: [
+    { id: "nav-docs-footer-docs", label: "Documentation", type: "link", url: "/docs" },
+    { id: "nav-docs-footer-reference", label: "Reference", type: "link", url: "/docs/reference" },
+    { id: "nav-docs-footer-changelog", label: "Changelog", type: "link", url: "/changelog" },
+    { id: "nav-docs-footer-github", label: "GitHub", type: "link", url: "https://github.com" }
+  ]
+};
 var docsTheme = defineTheme({
   manifest: {
     id: "docs",
     name: "Docs",
-    version: "0.1.0",
-    description: "Documentation theme \u2014 hierarchical sidebar, prev/next nav, search masthead. Pairs with a `docs` collection that has parent/order fields.",
+    version: "0.2.0",
+    description: "Documentation theme \u2014 three-column layout with hierarchical sidebar, breadcrumbs + lede + meta pills on the article column, on-this-page TOC on the right rail. Blue accent on a near-white surface; pairs with a `docs` collection.",
     author: { name: "NexPress" },
     nexpress: { minVersion: "0.1.0" },
     requires: {
       collections: {
-        docs: {
-          createIfAbsent: true,
+        posts: {
+          // Universal-content-model #748 — docs are posts with
+          // `kind: "doc"`. The framework's built-in `posts`
+          // collection already supplies `title` / `body` /
+          // `parent` (rel→posts) / `order`. Docs theme adds the
+          // doc-specific meta pills and contributes the kind
+          // option + kinds metadata block for admin / URL
+          // routing.
           fields: {
-            title: { type: "text", required: true },
-            body: { type: "richText" },
-            parent: {
-              type: "relationship",
-              relationTo: "docs",
-              hard: false
+            kind: {
+              type: "select",
+              options: [{ label: "Doc", value: "doc" }]
             },
-            order: { type: "number" }
+            // Short opening paragraph rendered as a lede under
+            // the h1. Optional — the article still renders
+            // without it. Lives in a "Docs" sidebar group with
+            // `stableSince`; the group + fields hide entirely
+            // when the active kind isn't `"doc"`.
+            lede: {
+              type: "textarea",
+              hard: false,
+              admin: {
+                position: "sidebar",
+                group: "Docs",
+                condition: { when: "kind", equals: "doc" }
+              }
+            },
+            // Meta-pill slot — advisory hint the doc-page
+            // template surfaces in the strap row. Note: portfolio
+            // theme also contributes a `badge: text` field on
+            // posts; the merge-requirements union picks the first
+            // declarer. Docs reads `doc.badge` regardless of which
+            // theme declared the column.
+            stableSince: {
+              type: "text",
+              hard: false,
+              admin: {
+                position: "sidebar",
+                group: "Docs",
+                condition: { when: "kind", equals: "doc" }
+              }
+            }
+          },
+          groupMeta: {
+            Docs: {
+              icon: "BookOpen",
+              description: "Doc-specific meta \u2014 lede and API stability hint."
+            }
+          },
+          kinds: {
+            doc: {
+              label: "Doc",
+              labelPlural: "Documentation",
+              icon: "BookOpen",
+              // Public-site URL pattern. The catch-all router
+              // matches `/docs/<slug>` and queries posts with
+              // `where: { kind: "doc", slug }`.
+              urlPattern: "/docs/:slug",
+              // Hint to admin: show parent + order controls and
+              // render the list as a tree, not a flat table.
+              hierarchical: true
+            }
           }
         }
       }
@@ -716,28 +1602,41 @@ var docsTheme = defineTheme({
     },
     css: docsCss,
     tokens: {
-      // Docs lean cool/neutral with a sharp accent — distinct
-      // from magazine's warm cream so a side-by-side preview
-      // makes the swap obvious.
       colors: {
-        primary: "oklch(0.55 0.18 260)",
-        primaryForeground: "oklch(0.985 0.005 260)",
-        background: "oklch(0.99 0.005 260)",
-        foreground: "oklch(0.18 0.025 260)",
-        muted: "oklch(0.95 0.012 260)",
-        mutedForeground: "oklch(0.5 0.025 260)",
-        border: "oklch(0.9 0.012 260)",
-        card: "oklch(0.985 0.008 260)",
-        cardForeground: "oklch(0.18 0.025 260)",
-        accent: "oklch(0.92 0.05 260)",
-        accentForeground: "oklch(0.18 0.025 260)"
+        primary: "#2563eb",
+        primaryForeground: "#ffffff",
+        background: "#fbfcfe",
+        foreground: "#0c1320",
+        muted: "#f1f4f9",
+        mutedForeground: "#5b6478",
+        border: "#e2e7ef",
+        card: "#ffffff"
+      },
+      typography: {
+        fontHeading: '"Geist", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+        fontBody: '"Geist", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+        fontMono: '"Geist Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace'
+      },
+      shape: {
+        radiusSm: "5px",
+        radiusMd: "9px",
+        radiusLg: "10px"
       }
     },
+    seedContent: {
+      navigation: SEED_NAV
+    },
     templates: {
-      docs: {
-        default: {
+      // Universal-content-model #748 — docs are posts with
+      // `kind: "doc"`. The template key matches the kind value so
+      // the per-kind template lookup picks this up automatically.
+      // Article-kind posts continue rendering through the
+      // framework's inline article markup unless the operator
+      // declares a `templates.posts.default` of their own.
+      posts: {
+        doc: {
           label: "Doc page",
-          description: "Hierarchical sidebar + body + prev/next nav. Optional 'Edit on GitHub' link when settings.githubRepo is set.",
+          description: "Three-column reference layout \u2014 breadcrumbs + lede + meta + Lexical body + feedback + prev/next, with the docs sidebar slotted on the left and the on-page TOC on the right.",
           component: DocPageTemplate
         }
       }
@@ -758,12 +1657,11 @@ var docsTheme = defineTheme({
       // by the parametric detail route below (dispatcher is
       // first-match-wins).
       { pattern: "/docs/search", component: DocsSearch },
-      // Doc detail dispatch (#614). The sidebar + template emit
-      // `/docs/<slug>` links; without this route those 404 in
-      // the reference app — the catch-all only resolves `pages`
-      // rows, not arbitrary `docs` collection rows. The
-      // component looks up the docs row by slug and renders
-      // through `templates.docs.default` (DocPageTemplate).
+      // Doc detail dispatch. The sidebar + template emit
+      // `/docs/<slug>` links; the route component looks up the
+      // doc-kind post by slug and renders through DocPageTemplate.
+      // Universal-content-model #748 — docs are posts with
+      // `kind="doc"`; the lookup filters on kind, not collection.
       { pattern: "/docs/:slug", component: DocsDetailRoute }
     ],
     navLocations: {