From 68d00a8b035ea5fcd4756eb5347cb2aebdb3ecff Mon Sep 17 00:00:00 2001
From: Oreofe <oreofeolurin@gmail.com>
Date: Thu, 11 Jun 2026 13:11:01 +0100
Subject: [PATCH 1/2] fix(ui): real document icon for AI sources, unnumbered
 nav groups, flat callout border
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Ask AI 'Used N sources' rows showed a spine-less book glyph that read as an
  empty box; replace with a document/page icon (folded corner + text lines).
- Drop the '01 / 02' index prefix from sidebar section headings (and the dead
  .n CSS) — titles read cleaner without it.
- Callouts: remove the 2px left accent stripe so the card has a uniform
  hairline border + background tint (docs + API reference).
---
 app/api-reference.css           |  6 +++---
 app/docs.css                    |  7 +++----
 components/docs/ai/ask-dock.tsx | 21 ++++++++++++++++++++-
 components/docs/nav.tsx         |  8 +++-----
 4 files changed, 29 insertions(+), 13 deletions(-)

diff --git a/app/api-reference.css b/app/api-reference.css
index 0070af5..1a3d007 100644
--- a/app/api-reference.css
+++ b/app/api-reference.css
@@ -283,7 +283,7 @@
 /* MDX callouts (Note / Tip / Info / Warning / Danger / Check) in section &
    operation overlays — ported from docs.css since the API route doesn't load it. */
 .ml-apiref .callout {
-  margin-top: 20px; border: 1px solid var(--line); border-left: 2px solid var(--accent);
+  margin-top: 20px; border: 1px solid var(--line);
   border-radius: 9px; padding: 14px 16px;
   background: color-mix(in srgb, var(--accent) 5%, var(--panel));
   display: flex; gap: 12px; max-width: 68ch;
@@ -294,9 +294,9 @@
 .ml-apiref .callout p, .ml-apiref .callout .callout-body { margin: 0; font-size: 14px; color: var(--ink-2); line-height: 1.6; }
 .ml-apiref .callout .callout-body > * + * { margin-top: 8px; }
 .ml-apiref .callout strong { color: var(--ink); }
-.ml-apiref .callout.tone-warn { border-left-color: var(--warn); background: color-mix(in srgb, var(--warn) 6%, var(--panel)); }
+.ml-apiref .callout.tone-warn { background: color-mix(in srgb, var(--warn) 6%, var(--panel)); }
 .ml-apiref .callout.tone-warn .ic { color: var(--warn); }
-.ml-apiref .callout.tone-ok { border-left-color: var(--ok); background: color-mix(in srgb, var(--ok) 6%, var(--panel)); }
+.ml-apiref .callout.tone-ok { background: color-mix(in srgb, var(--ok) 6%, var(--panel)); }
 .ml-apiref .callout.tone-ok .ic { color: var(--ok); }
 
 /* ---------- dark code rail ---------- */
diff --git a/app/docs.css b/app/docs.css
index 922af94..4b1c1bc 100644
--- a/app/docs.css
+++ b/app/docs.css
@@ -98,7 +98,6 @@
   font-family: var(--mono); font-size: 10.5px; letter-spacing: 0.13em; text-transform: uppercase;
   color: var(--ink-4); padding: 0 9px; margin-bottom: 8px; display: flex; align-items: center; gap: 7px;
 }
-.docs-shell .docs-nav-grp > .t .n { color: var(--ink-4); opacity: .6; }
 .docs-shell .docs-nav a {
   display: flex; align-items: center; gap: 8px; padding: 6.5px 9px; border-radius: 7px;
   font-size: 13.5px; color: var(--ink-3); line-height: 1.3; position: relative; text-decoration: none;
@@ -190,7 +189,7 @@
 
 /* callout */
 .docs-shell .callout {
-  margin-top: 20px; border: 1px solid var(--line); border-left: 2px solid var(--accent);
+  margin-top: 20px; border: 1px solid var(--line);
   border-radius: 9px; padding: 14px 16px;
   background: color-mix(in srgb, var(--accent) 5%, var(--panel));
   display: flex; gap: 12px; max-width: 68ch;
@@ -201,9 +200,9 @@
 .docs-shell .callout p, .docs-shell .callout .callout-body { margin: 0; font-size: 14px; color: var(--ink-2); line-height: 1.6; }
 .docs-shell .callout .callout-body > * + * { margin-top: 8px; }
 .docs-shell .callout strong { color: var(--ink); }
-.docs-shell .callout.tone-warn { border-left-color: var(--warn); background: color-mix(in srgb, var(--warn) 6%, var(--panel)); }
+.docs-shell .callout.tone-warn { background: color-mix(in srgb, var(--warn) 6%, var(--panel)); }
 .docs-shell .callout.tone-warn .ic { color: var(--warn); }
-.docs-shell .callout.tone-ok { border-left-color: var(--ok); background: color-mix(in srgb, var(--ok) 6%, var(--panel)); }
+.docs-shell .callout.tone-ok { background: color-mix(in srgb, var(--ok) 6%, var(--panel)); }
 .docs-shell .callout.tone-ok .ic { color: var(--ok); }
 
 /* steps */
diff --git a/components/docs/ai/ask-dock.tsx b/components/docs/ai/ask-dock.tsx
index 2f8b5f8..8a03041 100644
--- a/components/docs/ai/ask-dock.tsx
+++ b/components/docs/ai/ask-dock.tsx
@@ -548,7 +548,7 @@ function Sources({ list }: { list: string[] }) {
         {list.map((s) => (
           <div key={s} className="ac-src">
             <span className="bk">
-              <Book sm />
+              <PageIcon />
             </span>
             {s}
           </div>
@@ -596,3 +596,22 @@ function Book({ sm }: { sm?: boolean }) {
     </svg>
   );
 }
+/** Document/page glyph for retrieved sources (a file with a folded corner). */
+function PageIcon() {
+  return (
+    <svg
+      width="13"
+      height="13"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M14 3v4a1 1 0 0 0 1 1h4" />
+      <path d="M14 3H6a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z" />
+      <path d="M8.5 13.5h7M8.5 17h4.5" />
+    </svg>
+  );
+}
diff --git a/components/docs/nav.tsx b/components/docs/nav.tsx
index 08ff34d..09eb14a 100644
--- a/components/docs/nav.tsx
+++ b/components/docs/nav.tsx
@@ -41,8 +41,8 @@ function pickActiveTabId(tabs: TopTab[], pathname: string): string {
   return tabs.find((t) => t.matchPrefixes.includes("__default__"))?.id ?? tabs[0]?.id ?? "";
 }
 
-/** Numbered nav groups (the design's .docs-nav): "01 Get started", etc. The
- *  index is derived from the section's position. Method/badge chips are kept. */
+/** Nav groups (the design's .docs-nav): a section title over its links.
+ *  Method/badge chips on links are kept. */
 function SidebarSections({
   sections,
   pathname,
@@ -56,9 +56,7 @@ function SidebarSections({
     <nav className="docs-nav">
       {sections.map((sec, si) => (
         <div key={sec.title} className="docs-nav-grp">
-          <div className="t">
-            <span className="n">{String(si + 1).padStart(2, "0")}</span> {sec.title}
-          </div>
+          <div className="t">{sec.title}</div>
           {sec.links.map((l) => {
             const active = pathname === l.href;
             return (

From b3376924013a8775f6d1495d865344b30e51ab6e Mon Sep 17 00:00:00 2001
From: Oreofe <oreofeolurin@gmail.com>
Date: Thu, 11 Jun 2026 13:22:32 +0100
Subject: [PATCH 2/2] feat(ai): page-custom Ask AI starter questions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The empty-state suggestion chips were one generic set for every page. Make
them page-aware with a three-layer resolution (no runtime AI cost, never
embarrassing on arbitrary docs):

1. Frontmatter — authors set `aiSuggestions: [...]` per page (max 3).
   Parsed in lib/docs.ts, threaded DocsShell → DocsSidebar → AskDock.
2. Build-time generation (opt-in: `ai.suggestions: true` + MARKLINE_AI_KEY) —
   scripts/build-search.mjs asks the operator's model for 3 short questions
   per page and writes public/ai-suggestions.json (gitignored, like llms.txt).
   Pages are cached by content hash, so rebuilds only re-call the provider for
   changed pages; per-page retry; failures keep the stale entry. max_tokens is
   generous because reasoning models (deepseek-flash) burn tokens on hidden
   reasoning before any visible content — a small cap returns empty answers.
   The dock fetches the JSON once per session and looks up the current path.
3. Fallback — the existing generic trio; also used on pages with no entry.

The API reference passes surface-aware defaults (auth / 'use the {resource}
API' / error shape) — resource tags are controlled OpenAPI names, safe to
template. Heading-template generation was rejected: arbitrary docs headings
(imperatives, fragments, code, non-English) produce visibly broken grammar.

Verified against the rune docs copy: 73/73 pages generated (58 new + 15
cached, 0 failed), second run fully cached in 0.5s; frontmatter questions
render only on their page; production build green (78 pages).
---
 .gitignore                                    |   1 +
 app/[[...slug]]/page.tsx                      |   2 +-
 components/docs/ai/ask-dock.tsx               |  47 ++++++-
 .../docs/api/reference/markline-apiref.tsx    |  11 +-
 components/docs/nav.tsx                       |  27 +++-
 lib/config.ts                                 |   6 +
 lib/docs.ts                                   |   5 +
 scripts/build-search.mjs                      | 132 +++++++++++++++++-
 8 files changed, 219 insertions(+), 12 deletions(-)

diff --git a/.gitignore b/.gitignore
index 6283920..6586d4e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -19,6 +19,7 @@ next-env.d.ts
 /public/llms-full.txt
 /public/sitemap.xml
 /public/robots.txt
+/public/ai-suggestions.json
 
 # misc
 .DS_Store
diff --git a/app/[[...slug]]/page.tsx b/app/[[...slug]]/page.tsx
index 08379fa..518ae8c 100644
--- a/app/[[...slug]]/page.tsx
+++ b/app/[[...slug]]/page.tsx
@@ -96,7 +96,7 @@ export default async function DocsCatchAll({ params }: { params: Promise<{ slug?
   // SiteNav. Only docs routes mount it — the home + API reference render their
   // own full-width content.
   return (
-    <DocsShell nav={getNav(config)} ai={aiConfig()}>
+    <DocsShell nav={getNav(config)} ai={aiConfig()} aiSuggestions={doc.fm.aiSuggestions}>
       <DocsPage
         crumbs={crumbs}
         title={doc.fm.title}
diff --git a/components/docs/ai/ask-dock.tsx b/components/docs/ai/ask-dock.tsx
index 8a03041..76be103 100644
--- a/components/docs/ai/ask-dock.tsx
+++ b/components/docs/ai/ask-dock.tsx
@@ -1,6 +1,7 @@
 "use client";
 
 import { useEffect, useRef, useState } from "react";
+import { usePathname } from "next/navigation";
 import type { AiPublicConfig } from "@/lib/config";
 
 /**
@@ -46,8 +47,22 @@ const CHATS_KEY = "markline-ai-chats";
 const OPEN_KEY = "markline-ai-open";
 const RKEY_KEY = "markline-ai-key";
 
+/** Last-resort starter questions — page-agnostic so they're never wrong. */
 const SUGGEST = ["Summarize this page", "Explain this with an example", "What are the key concepts here?"];
 
+/** Build-time generated per-page starter questions (public/ai-suggestions.json,
+ *  written by scripts/build-search.mjs when `ai.suggestions` is enabled).
+ *  Fetched once per session; missing file → empty map (fallbacks apply). */
+let suggestionsPromise: Promise<Record<string, { q: string[] }>> | null = null;
+function loadGeneratedSuggestions(basePath: string): Promise<Record<string, { q: string[] }>> {
+  if (!suggestionsPromise) {
+    suggestionsPromise = fetch(`${basePath}/ai-suggestions.json`)
+      .then((r) => (r.ok ? r.json() : {}))
+      .catch(() => ({}));
+  }
+  return suggestionsPromise;
+}
+
 /** Condense the first question into a clean chat title: strip filler, capitalize,
  *  cut on a word boundary (never mid-word), drop trailing punctuation. Purely
  *  deterministic — no model call, so it works even when the assistant is down. */
@@ -106,7 +121,15 @@ function mdBlocks(s: string): string {
   return html;
 }
 
-export function AskDock({ ai }: { ai: AiPublicConfig }) {
+export function AskDock({
+  ai,
+  suggestions,
+}: {
+  ai: AiPublicConfig;
+  /** Page-specific starter questions. Resolution: this prop (frontmatter /
+   *  surface defaults) → build-time generated (ai-suggestions.json) → generic. */
+  suggestions?: string[];
+}) {
   const [chats, setChats] = useState<Chat[]>([{ title: "New chat", messages: [] }]);
   const [cur, setCur] = useState(0);
   const [open, setOpen] = useState(false);
@@ -117,12 +140,32 @@ export function AskDock({ ai }: { ai: AiPublicConfig }) {
   const [needKey, setNeedKey] = useState(false);
   const [keyDraft, setKeyDraft] = useState("");
   const [attachments, setAttachments] = useState<Attachment[]>([]);
+  const [generated, setGenerated] = useState<string[] | null>(null);
   const bodyRef = useRef<HTMLDivElement>(null);
   const inputRef = useRef<HTMLTextAreaElement>(null);
   const fileRef = useRef<HTMLInputElement>(null);
+  const pathname = usePathname();
 
   const messages = chats[cur]?.messages ?? [];
 
+  /* per-page starter questions from the build-time generator (when present);
+     skipped entirely when the page supplies its own via the prop. */
+  useEffect(() => {
+    if (suggestions?.length) return;
+    let on = true;
+    const basePath = process.env.NEXT_PUBLIC_MARKLINE_BASE_PATH || "";
+    const key =
+      (basePath && pathname.startsWith(basePath) ? pathname.slice(basePath.length) : pathname).replace(/\/+$/, "") || "/";
+    loadGeneratedSuggestions(basePath).then((map) => {
+      if (on) setGenerated(map[key]?.q?.length ? map[key].q.slice(0, 3) : null);
+    });
+    return () => {
+      on = false;
+    };
+  }, [pathname, suggestions]);
+
+  const starters = suggestions?.length ? suggestions.slice(0, 3) : generated ?? SUGGEST;
+
   /* hydrate from localStorage + restore open state */
   useEffect(() => {
     try {
@@ -387,7 +430,7 @@ export function AskDock({ ai }: { ai: AiPublicConfig }) {
                 Tip: start a new chat with <kbd>⌘</kbd> <kbd>E</kbd>
               </div>
               <div className="ac-sugg">
-                {SUGGEST.map((s) => (
+                {starters.map((s) => (
                   <button key={s} className="ac-sg" onClick={() => submit(s)}>
                     {s}
                   </button>
diff --git a/components/docs/api/reference/markline-apiref.tsx b/components/docs/api/reference/markline-apiref.tsx
index a52df86..a55614e 100644
--- a/components/docs/api/reference/markline-apiref.tsx
+++ b/components/docs/api/reference/markline-apiref.tsx
@@ -463,7 +463,16 @@ export function MarklineApiRef({
 
       <SearchPalette index={view.search} aiEnabled={aiOn} />
       <MarkdownModal />
-      {ai && <AskDock ai={ai} />}
+      {ai && (
+        <AskDock
+          ai={ai}
+          suggestions={[
+            "How do I authenticate requests?",
+            `How do I use the ${r.name} API?`,
+            "What does an error response look like?",
+          ]}
+        />
+      )}
     </div>
    </EventColorsContext.Provider>
   );
diff --git a/components/docs/nav.tsx b/components/docs/nav.tsx
index 09eb14a..6e40fab 100644
--- a/components/docs/nav.tsx
+++ b/components/docs/nav.tsx
@@ -84,10 +84,21 @@ function SidebarSections({
  * <SiteNav/>; it no longer carries a topbar. The grid (sidebar · main · toc)
  * is styled in app/docs.css.
  */
-export function DocsShell({ nav, ai = null, children }: { nav: NavData; ai?: AiPublicConfig | null; children: React.ReactNode }) {
+export function DocsShell({
+  nav,
+  ai = null,
+  aiSuggestions,
+  children,
+}: {
+  nav: NavData;
+  ai?: AiPublicConfig | null;
+  /** Page-specific Ask AI starter questions (frontmatter `aiSuggestions`). */
+  aiSuggestions?: string[];
+  children: React.ReactNode;
+}) {
   return (
     <div className="docs-shell grid">
-      <DocsSidebar nav={nav} ai={ai} />
+      <DocsSidebar nav={nav} ai={ai} aiSuggestions={aiSuggestions} />
       {children}
       {/* ⌘K / sidebar-trigger search palette (modal only — the inline trigger
           lives in the sidebar). */}
@@ -96,7 +107,15 @@ export function DocsShell({ nav, ai = null, children }: { nav: NavData; ai?: AiP
   );
 }
 
-export function DocsSidebar({ nav, ai = null }: { nav: NavData; ai?: AiPublicConfig | null }) {
+export function DocsSidebar({
+  nav,
+  ai = null,
+  aiSuggestions,
+}: {
+  nav: NavData;
+  ai?: AiPublicConfig | null;
+  aiSuggestions?: string[];
+}) {
   const pathname = usePathname();
   const tabs = nav.tabsByVariant[pickVariantId(nav, pathname)] ?? [];
   const activeId = pickActiveTabId(tabs, pathname);
@@ -113,7 +132,7 @@ export function DocsSidebar({ nav, ai = null }: { nav: NavData; ai?: AiPublicCon
       </aside>
       {/* Page-level AI affordances (the doc-ai row + View-as-Markdown modal) live
           in the docs shell so they're available on every docs page. */}
-      {ai && <AskDock ai={ai} />}
+      {ai && <AskDock ai={ai} suggestions={aiSuggestions} />}
       <MarkdownModal />
     </>
   );
diff --git a/lib/config.ts b/lib/config.ts
index ac15616..06302b4 100644
--- a/lib/config.ts
+++ b/lib/config.ts
@@ -197,6 +197,12 @@ export type AiConfig = {
    * the paperclip on/off regardless of the heuristic.
    */
   vision?: boolean;
+  /**
+   * Opt-in: generate per-page Ask-AI starter questions at build time (on the
+   * operator's key) into public/ai-suggestions.json. Cached by content hash,
+   * so only changed pages re-call the provider on rebuilds.
+   */
+  suggestions?: boolean;
   maxTokens?: number;
   /** Per-IP abuse limits for the proxy route. */
   rateLimit?: { perMinute?: number; perDay?: number };
diff --git a/lib/docs.ts b/lib/docs.ts
index 6005bd3..0ae3880 100644
--- a/lib/docs.ts
+++ b/lib/docs.ts
@@ -16,6 +16,8 @@ export type DocFrontmatter = {
   crumbs?: { label: string; href?: string }[];
   /** Page layout: "doc" (default, sidebar+TOC) or "landing" (full-width marketing). */
   layout?: "doc" | "landing";
+  /** Author-curated starter questions for the Ask AI panel on this page (max 3). */
+  aiSuggestions?: string[];
 };
 
 export type Doc = {
@@ -45,6 +47,9 @@ function readMdx(filePath: string): { fm: DocFrontmatter; body: string } {
     last_updated: data.last_updated ? String(data.last_updated) : undefined,
     crumbs: Array.isArray(data.crumbs) ? data.crumbs : undefined,
     layout: data.layout === "landing" ? "landing" : undefined,
+    aiSuggestions: Array.isArray(data.aiSuggestions)
+      ? data.aiSuggestions.filter((s: unknown) => typeof s === "string" && s.trim()).map((s: string) => s.trim()).slice(0, 3)
+      : undefined,
   };
   return { fm, body: content };
 }
diff --git a/scripts/build-search.mjs b/scripts/build-search.mjs
index 597989a..2c429fd 100644
--- a/scripts/build-search.mjs
+++ b/scripts/build-search.mjs
@@ -11,13 +11,14 @@ import path from "node:path";
 import matter from "gray-matter";
 import * as pagefind from "pagefind";
 
-/** Read MARKLINE_CONTENT from the environment, falling back to .env.local / .env. */
-function resolveContentEnv() {
-  if (process.env.MARKLINE_CONTENT) return process.env.MARKLINE_CONTENT;
+/** Read an env var, falling back to .env.local / .env (plain node script —
+ *  Next's automatic env loading doesn't apply here). */
+function readEnvVar(name) {
+  if (process.env[name]) return process.env[name];
   for (const f of [".env.local", ".env"]) {
     try {
       const txt = fs.readFileSync(path.join(process.cwd(), f), "utf8");
-      const m = txt.match(/^\s*MARKLINE_CONTENT\s*=\s*(.+?)\s*$/m);
+      const m = txt.match(new RegExp(`^\\s*${name}\\s*=\\s*(.+?)\\s*$`, "m"));
       if (m) return m[1].replace(/^["']|["']$/g, "");
     } catch {
       // no such file — keep looking
@@ -26,6 +27,11 @@ function resolveContentEnv() {
   return undefined;
 }
 
+/** Read MARKLINE_CONTENT from the environment, falling back to .env.local / .env. */
+function resolveContentEnv() {
+  return readEnvVar("MARKLINE_CONTENT");
+}
+
 function contentRoot() {
   const c = resolveContentEnv();
   if (c && c.length > 0) return path.isAbsolute(c) ? c : path.join(process.cwd(), c);
@@ -279,6 +285,123 @@ function writeLlms(root) {
   console.log(`[markline] llms.txt (${docCount} docs, ${apis.length} API resources) + llms-full.txt -> public/`);
 }
 
+/* ── ai-suggestions.json ───────────────────────────────────────────────────
+   Per-page Ask-AI starter questions, generated at build time on the operator's
+   key (opt-in: `ai.suggestions: true` + MARKLINE_AI_KEY). Written to public/
+   as a static file the dock fetches at runtime — zero runtime AI cost, works
+   on pure-static hosting. Pages are cached by content hash, so unchanged pages
+   never re-call the provider on rebuilds. Heading-template generation was
+   rejected on purpose: arbitrary docs headings produce embarrassing grammar. */
+
+const AI_BASE_URLS = {
+  openai: "https://api.openai.com/v1",
+  openrouter: "https://openrouter.ai/api/v1",
+  together: "https://api.together.xyz/v1",
+  groq: "https://api.groq.com/openai/v1",
+  fireworks: "https://api.fireworks.ai/inference/v1",
+  local: "http://localhost:11434/v1",
+};
+
+async function generateQuestions({ baseUrl, key, model, provider, title, lede, body }) {
+  const prompt =
+    `You write starter questions for a documentation page's AI assistant. ` +
+    `Given the page below, return a JSON array of exactly 3 short questions (each under 60 characters) ` +
+    `a reader of THIS page would actually ask. Write them in the same language as the page. ` +
+    `Return ONLY the JSON array, no prose.\n\n` +
+    `Page title: ${title}\n${lede ? `Summary: ${lede}\n` : ""}\n${body.slice(0, 5000)}`;
+  const headers = { Authorization: `Bearer ${key}`, "content-type": "application/json" };
+  if (provider === "openrouter") headers["X-Title"] = "Markline build (ai-suggestions)";
+  const res = await fetch(`${baseUrl}/chat/completions`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      model,
+      stream: false,
+      // Generous cap: reasoning models (e.g. deepseek-flash) spend tokens on
+      // hidden reasoning BEFORE the visible answer — a small cap yields
+      // finish_reason=length with empty content.
+      max_tokens: 1500,
+      messages: [{ role: "user", content: prompt }],
+    }),
+    signal: AbortSignal.timeout(45000),
+  });
+  if (!res.ok) throw new Error(`provider ${res.status}`);
+  const data = await res.json();
+  const text = data?.choices?.[0]?.message?.content ?? "";
+  if (!text.includes("[")) throw new Error(`no JSON array (finish=${data?.choices?.[0]?.finish_reason})`);
+  const arr = JSON.parse(text.slice(text.indexOf("["), text.lastIndexOf("]") + 1));
+  const qs = (Array.isArray(arr) ? arr : [])
+    .filter((q) => typeof q === "string" && q.trim())
+    .map((q) => q.trim().slice(0, 80))
+    .slice(0, 3);
+  if (!qs.length) throw new Error("no questions in response");
+  return qs;
+}
+
+async function writeAiSuggestions(root) {
+  const cfg = loadJsonConfig(root);
+  const ai = cfg.ai;
+  if (!ai?.enabled || ai.suggestions !== true) return; // opt-in only
+  const key = readEnvVar("MARKLINE_AI_KEY");
+  if (!key) {
+    console.log("[markline] ai-suggestions: skipped (no MARKLINE_AI_KEY)");
+    return;
+  }
+  const provider = ai.provider ?? "openai";
+  const baseUrl = (ai.baseUrl ?? AI_BASE_URLS[provider] ?? "").replace(/\/$/, "");
+  if (!baseUrl) {
+    console.log("[markline] ai-suggestions: skipped (no base URL for provider)");
+    return;
+  }
+  const model = ai.model ?? "gpt-4o-mini";
+
+  const outFile = path.join(process.cwd(), "public", "ai-suggestions.json");
+  let prev = {};
+  try {
+    prev = JSON.parse(fs.readFileSync(outFile, "utf8"));
+  } catch {
+    // first run — no cache
+  }
+
+  const { createHash } = await import("node:crypto");
+  const pages = [...docPagesForLlms(root).values()].filter((d) => d.layout !== "landing");
+  const out = {};
+  let generated = 0, cached = 0, failed = 0;
+
+  // Small concurrency pool — be polite to the provider.
+  const queue = [...pages];
+  const workers = Array.from({ length: 5 }, async () => {
+    for (let d = queue.shift(); d; d = queue.shift()) {
+      const h = createHash("sha1").update(`${d.title}\n${d.lede}\n${d.body}`).digest("hex").slice(0, 12);
+      if (prev[d.url]?.h === h && prev[d.url]?.q?.length) {
+        out[d.url] = prev[d.url];
+        cached++;
+        continue;
+      }
+      let q = null;
+      for (let attempt = 0; attempt < 2 && !q; attempt++) {
+        try {
+          q = await generateQuestions({ baseUrl, key, model, provider, title: d.title, lede: d.lede, body: d.body });
+        } catch (e) {
+          if (attempt === 1) {
+            failed++;
+            if (failed <= 3) console.warn(`[markline] ai-suggestions: ${d.url} failed (${e.message ?? e})`);
+            if (prev[d.url]?.q?.length) out[d.url] = prev[d.url]; // keep stale over nothing
+          }
+        }
+      }
+      if (q) {
+        out[d.url] = { h, q };
+        generated++;
+      }
+    }
+  });
+  await Promise.all(workers);
+
+  fs.writeFileSync(outFile, JSON.stringify(out));
+  console.log(`[markline] ai-suggestions.json: ${generated} generated, ${cached} cached, ${failed} failed -> public/`);
+}
+
 async function main() {
   const root = contentRoot();
   const prefixes = contentPrefixIds(root);
@@ -306,6 +429,7 @@ async function main() {
   console.log(`[markline] search index built: ${records.length} records -> public/pagefind`);
 
   writeLlms(root);
+  await writeAiSuggestions(root);
 }
 
 main().catch((err) => {