superlore-cli 0.3.0 → 0.4.0

package/dist/index.js

@@ -27,10 +27,10 @@ function banner() {
   }
   const seam = dim("\u258F");
   const lines = [
-    `  ${accent("\u2597\u259F\u2588")}${accentSoft("\u2599\u2596")}`,
-    `  ${accent("\u2590\u2588")}${seam}${accentSoft("\u2592\u258C")}   ${wordmark("superlore")}`,
-    `  ${accent("\u2590\u2588")}${seam}${accentSoft("\u2592\u258C")}   ${dim("the company knowledge base your agents run on")}`,
-    `  ${accent("\u259D\u259C\u2588")}${accentSoft("\u259B\u2598")}`
+    `  ${accent("\u2597\u2584")}${seam}${accentSoft("\u2584\u2596")}`,
+    `  ${accent("\u2588\u2588")}${seam}${accentSoft("\u2588\u2588")}   ${wordmark("superlore")}`,
+    `  ${accent("\u2588\u2588")}${seam}${accentSoft("\u2588\u2588")}   ${dim("the company knowledge base your agents run on")}`,
+    `  ${accent("\u259D\u2580")}${seam}${accentSoft("\u2580\u2598")}`
   ];
   process.stdout.write(`
 ${lines.join("\n")}
@@ -213,14 +213,15 @@ function detectPackageManager(root) {
 function isInstalled(root) {
   return existsSync(join(root, "node_modules"));
 }
-function runScript(root, script, extraArgs = []) {
+function runScript(root, script, extraArgs = [], env) {
   const pm = detectPackageManager(root);
   const args = ["run", script, ...extraArgs.length ? ["--", ...extraArgs] : []];
   return new Promise((resolvePromise, reject) => {
     const child = spawn(pm, args, {
       cwd: root,
       stdio: "inherit",
-      shell: process.platform === "win32"
+      shell: process.platform === "win32",
+      env: env ? { ...process.env, ...env } : process.env
     });
     child.on("error", reject);
     child.on("close", (code) => resolvePromise(code ?? 0));
@@ -417,7 +418,9 @@ function report(result) {
       log.success(`${bold(result.editor.label)} ${dim("\u2014 extension installed.")}`);
       break;
     case "already-installed":
-      log.info(`${accent("\u203A")} ${bold(result.editor.label)} ${dim("\u2014 already installed, up to date.")}`);
+      log.info(
+        `${accent("\u203A")} ${bold(result.editor.label)} ${dim("\u2014 already installed, up to date.")}`
+      );
       break;
     case "failed":
       log.error(`${bold(result.editor.label)} ${dim("\u2014 install failed:")} ${result.error}`);
@@ -437,12 +440,15 @@ function printManualInstall() {
 function printMcpNextStep() {
   log.blank();
   log.info(bold("Next: connect the MCP"));
+  log.info(`  ${dim("superlore's docs + help, in your agent \u2014 always current:")}`);
   log.info(
-    `  ${dim("Let your agent read the same corpus. Ask Claude")} ${cyan('"connect my superlore MCP"')}${dim(",")}`
+    `  ${cyan("claude mcp add --transport http -s user superlore-docs https://superlore.vercel.app/api/mcp")}`
   );
+  log.blank();
   log.info(
-    `  ${dim("or register it yourself:")} ${cyan("claude mcp add --transport http -s user superlore <url>/api/mcp")}`
+    `  ${dim("And your own KB once it's live (or ask Claude")} ${cyan('"connect my superlore MCP"')}${dim("):")}`
   );
+  log.info(`  ${cyan("claude mcp add --transport http -s user my-kb <your-kb-url>/api/mcp")}`);
 }
 
 // src/commands/deploy.ts
@@ -518,108 +524,30 @@ async function devCommand(flags) {
     );
   }
   log.blank();
-  const args = flags.port ? ["--port", String(flags.port)] : [];
-  const code = await runScript(project.root, "dev", args);
+  const code = await runScript(project.root, "dev", [], { PORT: String(port) });
   process.exit(code);
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync4 } from "fs";
-import { basename, resolve as resolve3 } from "path";
+import { existsSync as existsSync4, readdirSync as readdirSync2, statSync } from "fs";
+import { basename, join as join4, resolve as resolve3 } from "path";
 import { cancel, confirm, intro, isCancel, outro, select, text } from "@clack/prompts";
 
 // src/lib/scaffold.ts
 import { cpSync, existsSync as existsSync3, mkdirSync, readdirSync, writeFileSync as writeFileSync2 } from "fs";
 import { fileURLToPath } from "url";
 import { dirname as dirname2, join as join3, resolve as resolve2 } from "path";
-var here = dirname2(fileURLToPath(import.meta.url));
-function findStarterTemplate() {
-  let dir = here;
-  for (; ; ) {
-    const candidate = join3(dir, "templates", "starter");
-    if (existsSync3(candidate)) return candidate;
-    const bundled = join3(dir, "template");
-    if (existsSync3(bundled)) return bundled;
-    const parent = dirname2(dir);
-    if (parent === dir) return void 0;
-    dir = parent;
-  }
-}
-function isUsableTemplate(dir) {
-  if (!existsSync3(dir)) return false;
-  const entries = readdirSync(dir).filter((name) => name !== "README.md" && !name.startsWith("."));
-  return entries.length > 0;
-}
-function isEmptyDir(dir) {
-  if (!existsSync3(dir)) return true;
-  return readdirSync(dir).filter((n) => !n.startsWith(".")).length === 0;
-}
-function scaffold(options) {
-  const root = resolve2(options.dir);
-  mkdirSync(root, { recursive: true });
-  const template = findStarterTemplate();
-  let source;
-  if (template && isUsableTemplate(template)) {
-    cpSync(template, root, { recursive: true });
-    source = "template";
-  } else {
-    writeSkeleton(root, options.config);
-    source = "skeleton";
-  }
-  writeFileSync2(join3(root, "superlore.json"), serializeSuperloreJson(options.config), "utf8");
-  return { root, source };
-}
-function writeSkeleton(root, config) {
-  const accent2 = config.accent ?? SUPERLORE_VIOLET;
-  const mcpEnabled = config.mcp?.enabled ?? true;
-  const authEnabled = config.auth?.enabled ?? false;
-  const slug = config.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "superlore-kb";
-  const write = (rel, body) => {
-    const file = join3(root, rel);
-    mkdirSync(dirname2(file), { recursive: true });
-    writeFileSync2(file, body, "utf8");
-  };
+
+// src/lib/content/company.ts
+function writeCompanyContent(write, config) {
   write(
-    "package.json",
+    "content/docs/meta.json",
     `${JSON.stringify(
       {
-        name: slug,
-        version: "0.1.0",
-        private: true,
-        type: "module",
-        scripts: {
-          dev: "next dev",
-          build: "next build",
-          start: "next start",
-          postinstall: "fumadocs-mdx"
-        },
-        dependencies: {
-          "fumadocs-core": "16.8.2",
-          "fumadocs-mdx": "14.3.1",
-          "fumadocs-ui": "16.8.2",
-          superlore: "^0.5.1",
-          "lucide-react": "^1.21.0",
-          // superlore peers the rendered components pull in: Mermaid (Diagram), themes.
-          mermaid: "^11.15.0",
-          ...mcpEnabled ? { "@modelcontextprotocol/sdk": "^1.29.0", "mcp-handler": "^1.1.0" } : {},
-          // Auth.js v5 powers the optional Google SSO gate (superlore/auth). Self-disabling
-          // without AUTH_GOOGLE_ID, so it's harmless until the env is set.
-          ...authEnabled ? { "next-auth": "^5.0.0-beta.25" } : {},
-          next: "16.2.4",
-          "next-themes": "^0.4.6",
-          react: "^19.2.5",
-          "react-dom": "^19.2.5",
-          zod: "^4.4.3"
-        },
-        devDependencies: {
-          "@tailwindcss/postcss": "^4.2.2",
-          "@types/node": "^25.6.0",
-          "@types/react": "^19.2.14",
-          "@types/react-dom": "^19.2.3",
-          postcss: "^8.5.10",
-          tailwindcss: "^4.2.2",
-          typescript: "6.0.3"
-        }
+        title: config.name,
+        root: true,
+        icon: "BookOpen",
+        pages: ["index", "engineering", "product", "team"]
       },
       null,
       2
@@ -627,408 +555,830 @@ function writeSkeleton(root, config) {
 `
   );
   write(
-    "tsconfig.json",
+    "content/docs/index.mdx",
+    `---
+title: Home
+description: The home of the ${config.name} knowledge base \u2014 for humans and the agents working beside them.
+summary: Overview of the ${config.name} company knowledge base \u2014 what lives here, how it's organized, and how an agent should use it to answer questions and act on the team's behalf.
+tags: [overview, home, getting-started]
+---
+
+<PageHero
+  kicker="Company knowledge base"
+  title="${config.name}"
+  description="One corpus, two readers. Humans get this clean, navigable site; agents read the same structured content over MCP and act the way the team would."
+  icon="book-open"
+/>
+
+<Note title="This is a starter structure">
+  Everything here is **placeholder content** that shows the shape of a good company KB. Keep the
+  structure, then replace each page with what's true for your team. Run \`superlore dev\` to preview as
+  you go.
+</Note>
+
+## What lives here
+
+<FeatureList
+  items={[
+    { icon: "layers", title: "Engineering", description: "System architecture, the decisions behind it, and the runbooks that keep it up.", href: "/docs/engineering/architecture" },
+    { icon: "rocket", title: "Product", description: "The roadmap and what shipped \u2014 now, next, and later.", href: "/docs/product/roadmap" },
+    { icon: "users", title: "Team", description: "How to onboard, and who owns what.", href: "/docs/team/onboarding" },
+  ]}
+/>
+
+## How the company fits together
+
+A map of the domains and how they depend on each other. Edit the canvas \u2014 the agent reads the same
+graph the diagram is drawn from.
+
+\`\`\`superlore-canvas
+{
+  "title": "${config.name} \u2014 domains",
+  "layout": "flow",
+  "direction": "down",
+  "groups": [
+    { "id": "surface", "label": "Customer surface", "frame": true, "intent": "blue" },
+    { "id": "core", "label": "Core platform", "frame": true, "intent": "purple" },
+    { "id": "data", "label": "Data & insight", "frame": true, "intent": "green" },
+    { "id": "ops", "label": "Operations", "frame": true, "intent": "gray" }
+  ],
+  "nodes": [
+    { "id": "web", "kind": "rect", "intent": "blue", "group": "surface", "icon": "globe", "label": "Web app" },
+    { "id": "api", "kind": "rect", "intent": "blue", "group": "surface", "icon": "plug", "label": "Public API" },
+    { "id": "billing", "kind": "rect", "intent": "purple", "group": "core", "icon": "credit-card", "label": "Billing" },
+    { "id": "accounts", "kind": "rect", "intent": "purple", "group": "core", "icon": "users", "label": "Accounts" },
+    { "id": "workflow", "kind": "rect", "intent": "purple", "group": "core", "icon": "workflow", "label": "Workflow engine" },
+    { "id": "warehouse", "kind": "cylinder", "intent": "green", "group": "data", "label": "Warehouse" },
+    { "id": "insights", "kind": "rect", "intent": "green", "group": "data", "icon": "line-chart", "label": "Insights" },
+    { "id": "oncall", "kind": "rect", "intent": "gray", "group": "ops", "icon": "siren", "label": "On-call" }
+  ],
+  "edges": [
+    { "from": "web", "to": "api", "intent": "blue" },
+    { "from": "api", "to": "accounts", "rel": "depends-on" },
+    { "from": "api", "to": "workflow", "rel": "depends-on" },
+    { "from": "workflow", "to": "billing", "rel": "links" },
+    { "from": "workflow", "to": "warehouse", "intent": "green", "rel": "depends-on" },
+    { "from": "warehouse", "to": "insights", "intent": "green" },
+    { "from": "oncall", "to": "workflow", "kind": "dashed", "intent": "gray", "label": "watches" }
+  ]
+}
+\`\`\`
+
+## How to use this KB
+
+<KeyFacts
+  items={[
+    { label: "For humans", value: "Browse the sections, or search. Every diagram links to the page behind it." },
+    { label: "For agents", value: "Query the MCP \u2014 search, get a page, follow relations, read a component's data." },
+    { label: "Source of truth", value: "If it isn't written here, it isn't decided. Author once; both readers stay in sync." },
+    { label: "Keep it current", value: "Update the doc in the same PR as the change. Stale knowledge is worse than none." },
+  ]}
+/>
+`
+  );
+  write(
+    "content/docs/engineering/meta.json",
     `${JSON.stringify(
-      {
-        compilerOptions: {
-          target: "ES2022",
-          lib: ["dom", "dom.iterable", "esnext"],
-          module: "esnext",
-          moduleResolution: "bundler",
-          strict: true,
-          noEmit: true,
-          jsx: "preserve",
-          esModuleInterop: true,
-          resolveJsonModule: true,
-          isolatedModules: true,
-          skipLibCheck: true,
-          incremental: true,
-          paths: { "@/*": ["./*"], "collections/*": ["./.source/*"] },
-          plugins: [{ name: "next" }]
-        },
-        include: ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
-        exclude: ["node_modules", ".next", "out"]
-      },
+      { title: "Engineering", icon: "Layers", pages: ["architecture", "decisions", "runbooks"] },
       null,
       2
     )}
 `
   );
   write(
-    "next.config.mjs",
-    `import { createMDX } from "fumadocs-mdx/next";
+    "content/docs/engineering/architecture.mdx",
+    `---
+title: Architecture
+description: How the platform is built \u2014 the services, the request path, and where the data lives.
+summary: The system architecture \u2014 services and their tiers, the synchronous request path, and the data stores. The canvas is the authoritative diagram; the agent reads the same nodes and edges.
+tags: [engineering, architecture, system-design]
+---
 
-const withMDX = createMDX();
+<SectionHead
+  eyebrow="Engineering"
+  title="Architecture"
+  description="The system, as a diagram the humans read and the agent queries. Replace the services with yours."
+/>
 
-/** @type {import('next').NextConfig} */
-const config = {
-  reactStrictMode: true,
-  // superlore ships compiled ESM \u2014 consume it as a normal package (no transpilePackages).
-};
+This is placeholder architecture for a generic SaaS platform. Redraw the canvas to match your real
+system \u2014 the agent answers "how does X work?" from this graph, so keep it honest.
+
+\`\`\`superlore-canvas
+{
+  "title": "Request path",
+  "direction": "right",
+  "groups": [
+    { "id": "client", "label": "Client", "frame": true, "intent": "gray" },
+    { "id": "edge", "label": "Edge", "frame": true, "intent": "blue" },
+    { "id": "app", "label": "Services", "frame": true, "intent": "purple" },
+    { "id": "data", "label": "Data", "frame": true, "intent": "green" },
+    { "id": "async", "label": "Async", "frame": true, "intent": "orange" }
+  ],
+  "nodes": [
+    { "id": "user", "kind": "circle", "group": "client", "label": "User" },
+    { "id": "cdn", "kind": "icon", "icon": "globe", "group": "edge", "label": "CDN + WAF" },
+    { "id": "gw", "kind": "icon", "icon": "shield", "group": "edge", "label": "API Gateway" },
+    { "id": "api", "kind": "rect", "intent": "purple", "group": "app", "label": "API service" },
+    { "id": "workflow", "kind": "rect", "intent": "purple", "group": "app", "label": "Workflow engine" },
+    { "id": "cachehit", "kind": "diamond", "group": "app", "label": "Cache hit?" },
+    { "id": "worker", "kind": "rect", "intent": "orange", "group": "app", "label": "Background worker" },
+    { "id": "cache", "kind": "cylinder", "intent": "red", "group": "data", "label": "Redis" },
+    { "id": "db", "kind": "cylinder", "intent": "green", "group": "data", "label": "Postgres" },
+    { "id": "queue", "kind": "parallelogram", "intent": "orange", "group": "async", "label": "Job queue" }
+  ],
+  "edges": [
+    { "from": "user", "to": "cdn", "label": "HTTPS", "intent": "blue" },
+    { "from": "cdn", "to": "gw", "intent": "blue" },
+    { "from": "gw", "to": "api", "label": "authenticated", "rel": "links" },
+    { "from": "api", "to": "cachehit", "intent": "purple" },
+    { "from": "cachehit", "to": "cache", "label": "lookup", "intent": "red", "rel": "depends-on" },
+    { "from": "cachehit", "to": "db", "label": "miss", "kind": "dashed", "intent": "green" },
+    { "from": "api", "to": "workflow", "rel": "depends-on" },
+    { "from": "workflow", "to": "queue", "label": "enqueue", "intent": "orange" },
+    { "from": "queue", "to": "worker", "intent": "orange" },
+    { "from": "worker", "to": "db", "label": "write", "intent": "green", "rel": "depends-on" }
+  ]
+}
+\`\`\`
 
-export default withMDX(config);
+## Services
+
+<Table
+  caption="The services in the request path above"
+  columns={[
+    { key: "service", label: "Service", type: "text" },
+    { key: "owner", label: "Owner", type: "text" },
+    { key: "store", label: "Data store", type: "text" },
+    { key: "sla", label: "SLA", type: "text" }
+  ]}
+  rows={[
+    { service: "API service", owner: "Platform", store: "Postgres + Redis", sla: "99.95%" },
+    { service: "Workflow engine", owner: "Platform", store: "Postgres", sla: "99.9%" },
+    { service: "Background worker", owner: "Platform", store: "Job queue", sla: "best effort" }
+  ]}
+/>
+
+<KeyFacts
+  items={[
+    { label: "Language", value: "Replace with yours \u2014 e.g. TypeScript / Go" },
+    { label: "Runtime", value: "Where it runs \u2014 e.g. containers on your cloud" },
+    { label: "Primary store", value: "Postgres" },
+    { label: "Cache", value: "Redis" },
+  ]}
+/>
 `
   );
   write(
-    "source.config.ts",
-    `import { defineConfig, defineDocs } from "fumadocs-mdx/config";
-import { superloreFrontmatterSchema } from "superlore/frontmatter";
+    "content/docs/engineering/decisions.mdx",
+    `---
+title: Decisions
+description: The architectural decisions behind how things are built \u2014 and why.
+summary: Architecture decision records (ADRs). Each captures the context, the call, and its consequences so an agent can reason about why the system is the way it is.
+tags: [engineering, decisions, adr]
+---
 
-// Extend the superlore frontmatter schema in ONE place if you add custom fields.
-export const docs = defineDocs({
-  dir: "content/docs",
-  docs: { schema: superloreFrontmatterSchema },
-});
+<SectionHead
+  eyebrow="Engineering"
+  title="Decisions"
+  description="Why the system looks the way it does. Add an ADR whenever a choice is hard to reverse."
+/>
+
+These are placeholder ADRs. Keep the format \u2014 context, decision, consequences \u2014 so both a new hire
+and an agent can understand not just *what* was chosen but *why*.
+
+<Decision
+  title="Postgres as the primary store"
+  status="accepted"
+  identifier="ADR-001"
+  date="2024-01-15"
+  context={<>We needed a primary store with strong consistency, relational queries, and an operational track record the team already had.</>}
+  decision={<>Use a single Postgres cluster as the system of record; reach for other stores only when a workload clearly outgrows it.</>}
+  consequences={[
+    "One backup, failover, and migration story to learn.",
+    "Relational integrity by default; JSONB where we need flexibility.",
+    "We accept vertical-scaling limits until a workload proves it needs more.",
+  ]}
+/>
 
-export default defineConfig();
+<Decision
+  title="Redis cache in front of reads"
+  status="accepted"
+  identifier="ADR-002"
+  date="2024-03-02"
+  context={<>Hot read paths were hitting Postgres harder than necessary as traffic grew.</>}
+  decision={<>Add a Redis cache with a read-through pattern on the hottest endpoints; treat it as disposable.</>}
+  consequences={[
+    "Lower p99 on cached endpoints.",
+    "A cache-invalidation discipline we have to keep honest.",
+    "The system must stay correct when the cache is cold or down.",
+  ]}
+  refs={[{ rel: "see", target: "/docs/engineering/architecture", label: "Where the cache sits" }]}
+/>
 `
   );
   write(
-    "postcss.config.mjs",
-    `const config = {
-  plugins: { "@tailwindcss/postcss": {} },
-};
+    "content/docs/engineering/runbooks.mdx",
+    `---
+title: Runbooks
+description: What to do when things break \u2014 and who's on call.
+summary: Operational runbooks for common incidents, as ordered checklists, plus the on-call rotation. An agent can walk these steps or hand them to the person on call.
+tags: [engineering, operations, runbooks, on-call]
+---
 
-export default config;
+<SectionHead
+  eyebrow="Engineering"
+  title="Runbooks"
+  description="Calm, ordered steps for the bad days. Replace with your real incident procedures."
+/>
+
+## Runbook: elevated error rate
+
+<Checklist
+  label="Elevated 5xx on the API"
+  items={[
+    { text: "Confirm the alert against the dashboard \u2014 is it real and ongoing?", group: "Assess" },
+    { text: "Check the most recent deploy; roll back if the timeline lines up", group: "Assess" },
+    { text: "Check Redis and Postgres health and connection counts", group: "Assess" },
+    { text: "If a dependency is down, shed load and post status", group: "Mitigate" },
+    { text: "Once stable, capture a timeline for the post-incident review", group: "Recover" },
+  ]}
+/>
+
+## On-call rotation
+
+<Schedule
+  label="On-call this cycle"
+  events={[
+    { date: "2024-06-03", title: "Primary \u2014 replace with a name", body: "Carries the pager; first responder." },
+    { date: "2024-06-10", title: "Secondary \u2014 replace with a name", body: "Backup; escalation point." },
+    { date: "2024-06-17", title: "Primary \u2014 replace with a name", body: "Carries the pager; first responder." },
+  ]}
+/>
+
+<Tip title="Keep runbooks executable">
+  A good runbook is a list someone half-asleep can follow. If a step needs judgement, say what to
+  weigh. The agent can read these too \u2014 keep them concrete.
+</Tip>
 `
   );
   write(
-    "app/global.css",
-    `@import "tailwindcss";
-/* superlore theme tokens (light + dark, co-equal). Re-skin the whole KB from one accent. */
-@import "superlore/css";
-
-:root {
-  /* Brand accent \u2014 superlore derives the hover/weak/border/text family for both themes. */
-  --kp-accent: ${accent2};
-}
+    "content/docs/product/meta.json",
+    `${JSON.stringify(
+      { title: "Product", icon: "Rocket", pages: ["roadmap", "releases"] },
+      null,
+      2
+    )}
 `
   );
   write(
-    "app/layout.tsx",
-    `import type { ReactNode } from "react";
-import { RootProvider } from "superlore/ui";
-import "./global.css";
+    "content/docs/product/roadmap.mdx",
+    `---
+title: Roadmap
+description: What we're building \u2014 now, next, and later.
+summary: The product roadmap as a board (now / next / later) and a timeline of milestones. An agent can answer "what's planned" and "what's in flight" from this structured data.
+tags: [product, roadmap, planning]
+---
 
-export default function RootLayout({ children }: { children: ReactNode }) {
-  // Light and dark are co-equal; default to the system preference.
-  return (
-    <html lang="en" suppressHydrationWarning>
-      <body>
-        <RootProvider>{children}</RootProvider>
-      </body>
-    </html>
-  );
-}
+<SectionHead
+  eyebrow="Product"
+  title="Roadmap"
+  description="Where the work is heading. Replace the cards and milestones with yours."
+/>
+
+<Board
+  label="Now / Next / Later"
+  columns={[
+    { title: "Now", status: "in-progress", cards: [
+      { title: "Faster onboarding", body: "Cut time-to-first-value for new accounts.", status: "in-progress", tags: ["growth"] },
+      { title: "Audit log", body: "Per-account, exportable.", status: "in-progress", tags: ["enterprise"] }
+    ] },
+    { title: "Next", status: "planned", cards: [
+      { title: "SSO for teams", body: "SAML + SCIM.", status: "planned", tags: ["enterprise"] },
+      { title: "Usage-based billing", body: "Meter and invoice on usage.", status: "planned", tags: ["billing"] }
+    ] },
+    { title: "Later", status: "planned", cards: [
+      { title: "Public API v2", body: "Cleaner resources, better pagination.", status: "planned", tags: ["platform"] }
+    ] }
+  ]}
+/>
+
+## Milestones
+
+<Timeline
+  label="Product milestones"
+  items={[
+    { date: "2024-Q1", title: "GA launch", body: "First generally-available release.", status: "done", tags: ["launch"] },
+    { date: "2024-Q2", title: "Enterprise readiness", body: "Audit log, roles, SSO groundwork.", status: "in-progress", tags: ["enterprise"] },
+    { date: "2024-Q3", title: "Self-serve growth", body: "Onboarding and usage-based billing.", status: "planned", tags: ["growth"] },
+  ]}
+/>
 `
   );
   write(
-    "app/page.tsx",
-    `import Link from "next/link";
+    "content/docs/product/releases.mdx",
+    `---
+title: Releases
+description: What shipped, version by version.
+summary: The release history with versioned, categorized changes (added / changed / fixed). An agent can answer "what changed in 1.2?" from this structured changelog.
+tags: [product, releases, changelog]
+---
 
-export default function HomePage() {
-  return (
-    <main style={{ maxWidth: "42rem", margin: "0 auto", padding: "6rem 1.5rem" }}>
-      <h1 style={{ fontSize: "2rem", fontWeight: 700 }}>${escapeForJsx(config.name)}</h1>
-      <p style={{ marginTop: "0.75rem", opacity: 0.7 }}>
-        One corpus. Humans and agents. Start in <Link href="/docs">the docs</Link>.
-      </p>
-    </main>
-  );
-}
-`
-  );
-  write(
-    "app/docs/layout.tsx",
-    `import type { ReactNode } from "react";
-import { DocsLayout } from "fumadocs-ui/layouts/docs";
-import { source } from "@/lib/source";
-
-export default function Layout({ children }: { children: ReactNode }) {
-  return (
-    <DocsLayout tree={source.pageTree} nav={{ title: "${escapeForJsx(config.name)}" }}>
-      {children}
-    </DocsLayout>
-  );
-}
-`
-  );
-  write(
-    "app/docs/[[...slug]]/page.tsx",
-    `import { notFound } from "next/navigation";
-import { DocsBody, DocsPage } from "fumadocs-ui/page";
-import { getMDXComponents } from "superlore";
-import { source } from "@/lib/source";
+<SectionHead
+  eyebrow="Product"
+  title="Releases"
+  description="The changelog, as structured data. Replace with your real release notes."
+/>
 
-export default async function Page(props: { params: Promise<{ slug?: string[] }> }) {
-  const params = await props.params;
-  const page = source.getPage(params.slug);
-  if (!page) notFound();
-  const MDX = page.data.body;
-  return (
-    <DocsPage toc={page.data.toc}>
-      <DocsBody>
-        <MDX components={getMDXComponents()} />
-      </DocsBody>
-    </DocsPage>
-  );
-}
+<Releases
+  version="1.2.0"
+  date="2024-05-20"
+  status="done"
+  title="Audit log (beta)"
+  summary="Per-account audit logging, plus reliability fixes."
+  changes={[
+    { type: "added", text: "Exportable audit log for account admins." },
+    { type: "changed", text: "Faster account switching." },
+    { type: "fixed", text: "Rare double-charge on retried payments." },
+  ]}
+/>
 
-export function generateStaticParams() {
-  return source.generateParams();
-}
+<Releases
+  version="1.1.0"
+  date="2024-04-02"
+  status="done"
+  title="Onboarding refresh"
+  changes={[
+    { type: "added", text: "Guided setup for new accounts." },
+    { type: "fixed", text: "Invite emails occasionally landing in spam." },
+  ]}
+/>
 `
   );
   write(
-    "lib/source.ts",
-    `import { docs } from "collections/server";
-import { loader, lucideIconsPlugin } from "superlore/source";
-
-export const source = loader({
-  baseUrl: "/docs",
-  source: docs.toFumadocsSource(),
-  plugins: [lucideIconsPlugin()],
-});
+    "content/docs/team/meta.json",
+    `${JSON.stringify(
+      { title: "Team", icon: "Users", pages: ["onboarding", "people"] },
+      null,
+      2
+    )}
 `
   );
-  if (config.type === "personal-kb") {
-    writePersonalContent(write, config);
-  } else {
-    write(
-      "content/docs/index.mdx",
-      `---
-title: Welcome
-description: The home of your superlore knowledge base.
-summary: Landing page for the ${config.name} knowledge base.
-tags: [getting-started]
+  write(
+    "content/docs/team/onboarding.mdx",
+    `---
+title: Onboarding
+description: Your first week \u2014 what to set up, who to meet, and where to start.
+summary: The new-hire onboarding path as ordered steps and a first-week checklist. An agent can guide a new teammate through setup using these steps.
+tags: [team, onboarding, getting-started]
 ---
 
-# Welcome to ${config.name}
+<SectionHead
+  eyebrow="Team"
+  title="Onboarding"
+  description="Welcome. This is the path from day one to your first shipped change. Replace with yours."
+/>
 
-This is your superlore KB. Author once in MDX \u2014 humans get this clean, interactive site, and
-agents read the same structured content over MCP.
+<Steps>
+  <Step>
+    ### Get access
+    Accounts, repos, and the password manager. If something's missing, ask in the team channel.
+  </Step>
+  <Step>
+    ### Set up your machine
+    Clone the repo, install dependencies, and get the app running locally.
+  </Step>
+  <Step>
+    ### Read the architecture
+    Skim [Architecture](/docs/engineering/architecture) and the [Decisions](/docs/engineering/decisions) so the system isn't a black box.
+  </Step>
+  <Step>
+    ### Ship something small
+    Pick a starter issue. The goal of week one is a merged PR, however small.
+  </Step>
+</Steps>
+
+## First-week checklist
 
-Edit \`content/docs/index.mdx\` to make it yours, then run \`superlore dev\`.
+<Checklist
+  label="Your first week"
+  items={[
+    { text: "Access to repos, cloud, and the password manager", group: "Day 1" },
+    { text: "App running locally", group: "Day 1" },
+    { text: "Met your onboarding buddy", group: "Day 1" },
+    { text: "Read the architecture and recent decisions", group: "Week 1" },
+    { text: "Opened your first PR", group: "Week 1" },
+    { text: "Added yourself to the team page", group: "Week 1" },
+  ]}
+/>
 `
-    );
-  }
-  if (authEnabled) {
-    writeAuth(write, config);
-  }
-  if (mcpEnabled) {
-    const mcpPath = config.mcp?.path ?? "/api/mcp";
-    write(
-      "app/api/[transport]/route.ts",
-      `import { createMcpHandler } from "mcp-handler";
-import { z } from "zod";
-import { getComponentData, getPage, list, navigate, search } from "superlore/mcp";
-import { buildIndexFromSource } from "superlore/source";
-import type { KKind } from "superlore";
-import { source } from "@/lib/source";
+  );
+  write(
+    "content/docs/team/people.mdx",
+    `---
+title: People
+description: Who's on the team and what they own.
+summary: The team roster \u2014 who's here, their role, and who they report to \u2014 plus an example entity card. An agent can answer "who owns X?" from this structured directory.
+tags: [team, people, directory]
+---
 
-// Your KB's MCP endpoint. Served at ${mcpPath} \u2014 the same structured content the site renders,
-// exposed to agents. The index is built straight from your content \`source\`: author once, and
-// humans read the pages while agents query this corpus. No scraping, no drift.
-const index = buildIndexFromSource(source);
+<SectionHead
+  eyebrow="Team"
+  title="People"
+  description="Who to ask about what. Replace these placeholders with your real team."
+/>
 
-const json = (data: unknown) => ({
-  content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
-});
+<Roster
+  label="The team"
+  people={[
+    { name: "Replace Me", role: "Engineering lead", tags: ["platform"] },
+    { name: "Replace Me", role: "Product", reportsTo: "Replace Me", tags: ["roadmap"] },
+    { name: "Replace Me", role: "Engineer", reportsTo: "Replace Me", tags: ["platform"] },
+    { name: "Replace Me", role: "Design", reportsTo: "Replace Me", tags: ["product"] },
+  ]}
+/>
 
-const handler = createMcpHandler(
-  (server) => {
-    server.tool(
-      "search",
-      "Full-text search across the knowledge base.",
-      { query: z.string(), limit: z.number().int().positive().optional() },
-      async ({ query, limit }) => json(search(index, query, limit)),
-    );
-    server.tool(
-      "get_page",
-      "Get a page's full structured content by path.",
-      { path: z.string() },
-      async ({ path }) => json(getPage(index, path)),
-    );
-    server.tool(
-      "list",
-      "List knowledge nodes, filtered by kind / tag / entityType.",
-      { kind: z.string().optional(), tag: z.string().optional(), entityType: z.string().optional() },
-      async ({ kind, tag, entityType }) =>
-        json(list(index, { kind: kind as KKind | undefined, tag, entityType })),
-    );
-    server.tool(
-      "navigate",
-      "Follow relations from a page path / node id / entity ref.",
-      { target: z.string() },
-      async ({ target }) => json(navigate(index, target)),
-    );
-    server.tool(
-      "get_component_data",
-      "Get the structured data behind a rendered component (its knowledge face).",
-      { id: z.string() },
-      async ({ id }) => json(getComponentData(index, id)),
-    );
-  },
-  {},
-  { basePath: "/api" },
-);
+## Example: a person, as structured data
 
-export { handler as GET, handler as POST };
+<EntityCard
+  type="person"
+  slug="engineering-lead"
+  title="Engineering lead"
+  summary="One line on what they own and how to reach them."
+  icon="user"
+  fields={[
+    { key: "Owns", value: "Platform & architecture" },
+    { key: "Time zone", value: "UTC+0" },
+    { key: "Best reached", value: "Async, in the team channel" },
+  ]}
+  refs={[{ rel: "see", target: "/docs/engineering/architecture", label: "What they own" }]}
+/>
 `
-    );
-  }
+  );
+}
+
+// src/lib/content/product.ts
+function writeProductContent(write, config) {
   write(
-    ".gitignore",
-    `node_modules
-.next
-.source
-out
-*.tsbuildinfo
-.env*.local
+    "content/docs/meta.json",
+    `${JSON.stringify(
+      {
+        title: config.name,
+        root: true,
+        icon: "BookOpen",
+        pages: ["index", "getting-started", "concepts", "guides", "reference", "changelog"]
+      },
+      null,
+      2
+    )}
 `
   );
-  if (authEnabled) {
-    write(
-      ".env.example",
-      `# Auth.js v5 + Google SSO. The gate is OFF until AUTH_GOOGLE_ID is set, so local dev works with
-# this file empty. Copy to .env.local and fill in to enable it on a deploy.
-AUTH_SECRET=            # \`openssl rand -base64 32\`
-AUTH_GOOGLE_ID=         # presence of this turns the gate ON
-AUTH_GOOGLE_SECRET=
-AUTH_URL=               # the deploy's canonical URL, e.g. https://your-kb.vercel.app
-AUTH_TRUST_HOST=true
-${config.auth?.allowedDomain ? `AUTH_ALLOWED_DOMAIN=${config.auth.allowedDomain}` : "# AUTH_ALLOWED_DOMAIN=example.com   # restrict sign-in to one workspace domain (optional)"}
-# AUTH_ALLOWED_EMAILS=you@example.com   # comma-separated allowlist that bypasses the domain check
-# LOCAL=true                            # force the gate OFF locally even when configured
-`
-    );
-  }
-  const authReadme = authEnabled ? `
-
-## Auth
-
-This KB ships a Google SSO gate (Auth.js v5). It is **off until you set \`AUTH_GOOGLE_ID\`**, so local dev runs open. Copy \`.env.example\` to \`.env.local\` and fill it in to enable it. The gate lives in \`proxy.ts\`, in front of every route \u2014 so the MCP inherits it too.` : "";
   write(
-    "README.md",
-    `# ${config.name}
+    "content/docs/index.mdx",
+    `---
+title: Overview
+description: What ${config.name} is, who it's for, and where to start.
+summary: Overview of ${config.name} \u2014 what it does, the value it delivers, and the paths into the docs. The starting point for both a reader and an agent answering "what is this?".
+tags: [overview, getting-started]
+---
 
-A superlore knowledge base. One corpus. Humans and agents.
+<PageHero
+  kicker="Documentation"
+  title="${config.name}"
+  description="What it is, in one line you'll replace with your own. Author once in MDX \u2014 readers get this site, agents get the same content over MCP."
+  icon="book-open"
+/>
 
-## Develop
+<Note title="This is a starter structure">
+  Placeholder docs that show the shape of a good product site. Keep the structure, replace the
+  content. Preview with \`superlore dev\`.
+</Note>
 
-\`\`\`sh
-pnpm install   # or npm / yarn / bun
-superlore dev     # preview the site locally
-\`\`\`
+<StatGrid
+  stats={[
+    { label: "Set up in", value: "5 min", hint: "From install to first call" },
+    { label: "Works with", value: "Any stack", hint: "Replace with your real surface" },
+    { label: "Agent-ready", value: "MCP", hint: "The docs, queryable" },
+  ]}
+/>
 
-## Build
+## Start here
 
-\`\`\`sh
-superlore build
-\`\`\`
+<FeatureList
+  items={[
+    { icon: "rocket", title: "Getting started", description: "Install, configure, and make your first call.", href: "/docs/getting-started" },
+    { icon: "lightbulb", title: "Concepts", description: "How it works and the core ideas.", href: "/docs/concepts/how-it-works" },
+    { icon: "book-open", title: "Guides", description: "Step-by-step for common tasks.", href: "/docs/guides/first-integration" },
+    { icon: "settings", title: "Reference", description: "Every option, in one place.", href: "/docs/reference/configuration" },
+  ]}
+/>
+`
+  );
+  write(
+    "content/docs/getting-started.mdx",
+    `---
+title: Getting started
+description: Install ${config.name}, configure it, and make your first call.
+summary: The quickstart for ${config.name} \u2014 install, minimal configuration, and a first working call, as ordered steps an agent can also follow.
+tags: [getting-started, quickstart, install]
+---
 
-Config lives in \`superlore.json\`. Author content in \`content/docs/\`.${mcpEnabled ? `
+<SectionHead
+  eyebrow="Getting started"
+  title="Quickstart"
+  description="From nothing to a working call. Replace the commands and snippet with your real ones."
+/>
 
-The MCP endpoint is served at \`${config.mcp?.path ?? "/api/mcp"}\`.` : ""}${authReadme}
+<Steps>
+  <Step>
+    ### Install
+
+    \`\`\`bash
+    npm install your-package
+    \`\`\`
+  </Step>
+  <Step>
+    ### Configure
+
+    Set your API key in the environment:
+
+    \`\`\`bash
+    export YOUR_API_KEY=sk_...
+    \`\`\`
+  </Step>
+  <Step>
+    ### Make your first call
+
+    \`\`\`ts
+    import { Client } from "your-package";
+
+    const client = new Client({ apiKey: process.env.YOUR_API_KEY });
+    const result = await client.ping();
+    console.log(result);
+    \`\`\`
+  </Step>
+</Steps>
+
+<Tip title="That's it">
+  You've made your first call. Next, read [how it works](/docs/concepts/how-it-works) or jump into a
+  [guide](/docs/guides/first-integration).
+</Tip>
 `
   );
-}
-function writeAuth(write, config) {
-  const allowedDomain = config.auth?.allowedDomain;
   write(
-    "auth.ts",
-    `import { createSuperloreAuth } from "superlore/auth";
-
-// Auth.js v5 + Google SSO. Allowlists can come from env (AUTH_ALLOWED_DOMAIN / AUTH_ALLOWED_EMAILS)
-// or be passed explicitly here. Off until AUTH_GOOGLE_ID is set, so local dev needs no config.
-export const { handlers, auth, signIn, signOut } = createSuperloreAuth(${allowedDomain ? `{
-  allowedDomain: ${JSON.stringify(allowedDomain)},
-}` : "{}"});
+    "content/docs/concepts/meta.json",
+    `${JSON.stringify(
+      { title: "Concepts", icon: "Lightbulb", pages: ["how-it-works", "core-concepts"] },
+      null,
+      2
+    )}
 `
   );
   write(
-    "app/api/auth/[...nextauth]/route.ts",
-    `import { handlers } from "@/auth";
+    "content/docs/concepts/how-it-works.mdx",
+    `---
+title: How it works
+description: The path a request takes through ${config.name}, end to end.
+summary: How ${config.name} works under the hood \u2014 the request path from the caller's app through the API to the result. The canvas is the authoritative diagram; the agent reads the same graph.
+tags: [concepts, architecture, how-it-works]
+---
 
-export const { GET, POST } = handlers;
+<SectionHead
+  eyebrow="Concepts"
+  title="How it works"
+  description="The journey of a request. Redraw the canvas to match your real flow."
+/>
+
+\`\`\`superlore-canvas
+{
+  "title": "Request lifecycle",
+  "direction": "right",
+  "groups": [
+    { "id": "you", "label": "Your app", "frame": true, "intent": "gray" },
+    { "id": "svc", "label": "${config.name}", "frame": true, "intent": "accent" },
+    { "id": "out", "label": "Result", "frame": true, "intent": "green" }
+  ],
+  "nodes": [
+    { "id": "sdk", "kind": "rect", "intent": "blue", "group": "you", "icon": "code", "label": "SDK / HTTP call" },
+    { "id": "auth", "kind": "icon", "icon": "shield", "group": "svc", "label": "Auth" },
+    { "id": "validate", "kind": "diamond", "group": "svc", "label": "Valid request?" },
+    { "id": "process", "kind": "rect", "intent": "purple", "group": "svc", "label": "Process" },
+    { "id": "store", "kind": "cylinder", "intent": "green", "group": "svc", "label": "Store" },
+    { "id": "result", "kind": "rounded", "intent": "green", "group": "out", "label": "Response" },
+    { "id": "error", "kind": "callout", "intent": "red", "group": "out", "label": "Typed error" }
+  ],
+  "edges": [
+    { "from": "sdk", "to": "auth", "label": "request", "intent": "blue" },
+    { "from": "auth", "to": "validate", "rel": "links" },
+    { "from": "validate", "to": "process", "label": "yes", "intent": "purple" },
+    { "from": "validate", "to": "error", "label": "no", "kind": "dashed", "intent": "red" },
+    { "from": "process", "to": "store", "intent": "green", "rel": "depends-on" },
+    { "from": "process", "to": "result", "intent": "green" }
+  ]
+}
+\`\`\`
+
+<KeyFacts
+  items={[
+    { label: "Transport", value: "HTTPS / your SDK" },
+    { label: "Auth", value: "API key \u2014 replace with your real scheme" },
+    { label: "Errors", value: "Typed and predictable, never a bare 500" },
+    { label: "Idempotency", value: "Safe to retry \u2014 say how, here" },
+  ]}
+/>
 `
   );
   write(
-    "proxy.ts",
-    `import { auth } from "@/auth";
-import { createAuthProxy } from "superlore/auth";
+    "content/docs/concepts/core-concepts.mdx",
+    `---
+title: Core concepts
+description: The handful of ideas that explain everything else.
+summary: The core concepts of ${config.name} \u2014 the vocabulary a reader (or agent) needs, plus how the approaches compare.
+tags: [concepts, glossary]
+---
 
-// Next.js 16 middleware lives in proxy.ts. The gate is self-disabling: with no AUTH_GOOGLE_ID
-// (or LOCAL=true) every request passes through, so local dev and public deploys stay open.
-export default createAuthProxy(auth);
+<SectionHead
+  eyebrow="Concepts"
+  title="Core concepts"
+  description="Learn these five words and the rest of the docs make sense. Replace with yours."
+/>
 
-export const config = {
-  // Run on everything except static assets (the helper also skips the auth dance + icons).
-  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
-};
+<FeatureList
+  items={[
+    { icon: "box", title: "Resource", description: "The main thing you create and operate on. Define yours." },
+    { icon: "key", title: "API key", description: "How a request is authenticated." },
+    { icon: "webhook", title: "Webhook", description: "How you hear about events asynchronously." },
+    { icon: "repeat", title: "Idempotency key", description: "How a retry stays safe." },
+  ]}
+/>
+
+## Which approach fits?
+
+<Comparison
+  caption="Choosing how to integrate"
+  options={["SDK", "Raw HTTP"]}
+  rows={[
+    { criterion: "Setup time", cells: ["Minutes", "A bit more"] },
+    { criterion: "Type safety", cells: [true, false] },
+    { criterion: "Control", cells: ["partial", true] },
+    { criterion: "Best for", cells: ["Most apps", "Exotic runtimes"] },
+  ]}
+/>
 `
   );
   write(
-    "app/auth/signin/page.tsx",
-    `import { signIn } from "@/auth";
+    "content/docs/guides/meta.json",
+    `${JSON.stringify(
+      { title: "Guides", icon: "BookOpen", pages: ["first-integration"] },
+      null,
+      2
+    )}
+`
+  );
+  write(
+    "content/docs/guides/first-integration.mdx",
+    `---
+title: Your first integration
+description: A worked, end-to-end example of integrating ${config.name}.
+summary: A step-by-step guide to a first real integration with ${config.name}, with a verification checklist an agent can run through.
+tags: [guides, integration, tutorial]
+---
 
-export default async function SignInPage(props: {
-  searchParams: Promise<{ callbackUrl?: string }>;
-}) {
-  const { callbackUrl } = await props.searchParams;
-  return (
-    <main className="grid min-h-screen place-items-center p-6">
-      <form
-        action={async () => {
-          "use server";
-          await signIn("google", { redirectTo: callbackUrl ?? "/" });
-        }}
-        className="w-full max-w-sm rounded-lg border border-fd-border bg-fd-card p-6 text-center"
-      >
-        <h1 className="text-lg font-semibold text-fd-foreground">Sign in</h1>
-        <p className="mt-1 text-sm text-fd-muted-foreground">
-          This knowledge base is private. Continue with Google to read it.
-        </p>
-        <button
-          type="submit"
-          className="mt-5 inline-flex w-full items-center justify-center rounded-md border border-kp-accent-border bg-kp-accent px-4 py-2 text-sm font-medium text-white"
-        >
-          Continue with Google
-        </button>
-      </form>
-    </main>
+<SectionHead
+  eyebrow="Guides"
+  title="Your first integration"
+  description="A realistic, end-to-end task. Replace with a real flow your users care about."
+/>
+
+<Steps>
+  <Step>
+    ### Create a resource
+
+    \`\`\`ts
+    const item = await client.items.create({ name: "Example" });
+    \`\`\`
+  </Step>
+  <Step>
+    ### Handle the response
+
+    Check for the typed error before using the result. Never assume success.
+  </Step>
+  <Step>
+    ### Listen for events
+
+    Register a webhook so you hear about changes you didn't initiate.
+  </Step>
+</Steps>
+
+## Before you ship
+
+<Checklist
+  label="Integration checklist"
+  items={[
+    { text: "API key stored as a secret, never in code", group: "Security" },
+    { text: "Errors handled, not swallowed", group: "Correctness" },
+    { text: "Retries use an idempotency key", group: "Correctness" },
+    { text: "Webhook signature verified", group: "Security" },
+  ]}
+/>
+`
   );
-}
+  write(
+    "content/docs/reference/meta.json",
+    `${JSON.stringify(
+      { title: "Reference", icon: "Settings2", pages: ["configuration"] },
+      null,
+      2
+    )}
 `
   );
   write(
-    "app/auth/error/page.tsx",
-    `export default async function AuthErrorPage(props: {
-  searchParams: Promise<{ error?: string }>;
-}) {
-  const { error } = await props.searchParams;
-  return (
-    <main className="grid min-h-screen place-items-center p-6">
-      <div className="w-full max-w-sm rounded-lg border border-fd-border bg-fd-card p-6 text-center">
-        <h1 className="text-lg font-semibold text-fd-foreground">Can't sign in</h1>
-        <p className="mt-1 text-sm text-fd-muted-foreground">
-          {error === "AccessDenied"
-            ? "That account isn't allowed to access this knowledge base."
-            : "Something went wrong signing in. Try again."}
-        </p>
-        <a
-          href="/auth/signin"
-          className="mt-5 inline-flex w-full items-center justify-center rounded-md border border-fd-border px-4 py-2 text-sm font-medium text-fd-foreground no-underline"
-        >
-          Back to sign in
-        </a>
-      </div>
-    </main>
+    "content/docs/reference/configuration.mdx",
+    `---
+title: Configuration
+description: Every configuration option for ${config.name}, in one table.
+summary: The full configuration reference for ${config.name} \u2014 each option, its type, default, and what it does. An agent can answer "what does option X do?" from this table.
+tags: [reference, configuration, options]
+---
+
+<SectionHead
+  eyebrow="Reference"
+  title="Configuration"
+  description="The complete list of options. Replace these placeholders with your real surface."
+/>
+
+<Table
+  caption="Client options"
+  columns={[
+    { key: "option", label: "Option", type: "code" },
+    { key: "type", label: "Type", type: "text" },
+    { key: "default", label: "Default", type: "code" },
+    { key: "desc", label: "Description", type: "text" }
+  ]}
+  rows={[
+    { option: "apiKey", type: "string", default: "\u2014", desc: "Required. Your secret API key." },
+    { option: "baseUrl", type: "string", default: "https://api\u2026", desc: "Override for self-hosted or staging." },
+    { option: "timeout", type: "number", default: "30000", desc: "Request timeout in milliseconds." },
+    { option: "maxRetries", type: "number", default: "2", desc: "Automatic retries on transient errors." }
+  ]}
+/>
+
+## A design note
+
+<Decision
+  title="Sensible defaults over required config"
+  status="accepted"
+  identifier="DESIGN-01"
+  context={<>Every required option is friction between a developer and their first success.</>}
+  decision={<>Only \`apiKey\` is required; everything else has a default that works for most apps.</>}
+  consequences={[
+    "A working call needs one line of config.",
+    "Power users override exactly what they need.",
+  ]}
+/>
+`
   );
-}
+  write(
+    "content/docs/changelog.mdx",
+    `---
+title: Changelog
+description: What changed in ${config.name}, version by version.
+summary: The release history for ${config.name} with versioned, categorized changes. An agent can answer "what changed in version X?" from this structured changelog.
+tags: [changelog, releases]
+---
+
+<SectionHead
+  eyebrow="Changelog"
+  title="What's new"
+  description="Versioned, categorized changes. Replace with your real release notes."
+/>
+
+<Releases
+  version="1.1.0"
+  date="2024-05-20"
+  status="done"
+  title="Webhooks"
+  summary="Asynchronous events, plus reliability fixes."
+  changes={[
+    { type: "added", text: "Webhooks for resource events." },
+    { type: "changed", text: "Lower default timeout to 30s." },
+    { type: "fixed", text: "Retries no longer double-create on timeout." },
+  ]}
+/>
+
+<Releases
+  version="1.0.0"
+  date="2024-04-01"
+  status="done"
+  title="General availability"
+  changes={[
+    { type: "added", text: "Stable v1 API and the official SDK." },
+  ]}
+/>
 `
   );
 }
+
+// src/lib/content/personal.ts
 function writePersonalContent(write, config) {
   write(
     "content/docs/meta.json",
@@ -1036,6 +1386,7 @@ function writePersonalContent(write, config) {
       {
         title: config.name,
         root: true,
+        icon: "User",
         pages: ["index", "beliefs", "working-style", "pr-comments", "voice", "stories"]
       },
       null,
@@ -1168,6 +1519,34 @@ would.
   ]}
 />
 
+## How I approach a task
+
+This is the loop I run on anything non-trivial. An agent working for me should follow the same path.
+
+\`\`\`superlore-canvas
+{
+  "title": "How I approach a task",
+  "layout": "row",
+  "nodes": [
+    { "id": "outcome", "kind": "rounded", "intent": "accent", "icon": "target", "label": "Name the outcome", "body": "Goal + done-condition, in writing." },
+    { "id": "decompose", "kind": "rounded", "intent": "blue", "icon": "split", "label": "Decompose", "body": "Reversible steps, sequenced." },
+    { "id": "risk", "kind": "diamond", "intent": "orange", "label": "Riskiest part?" },
+    { "id": "spike", "kind": "rounded", "intent": "orange", "icon": "flask-conical", "label": "Spike it cheap", "body": "Prove the unknown first." },
+    { "id": "ship", "kind": "rounded", "intent": "green", "icon": "rocket", "label": "Ship small", "body": "Smallest reversible change." },
+    { "id": "reflect", "kind": "rounded", "intent": "purple", "icon": "repeat", "label": "Reflect", "body": "What did I learn? Write it down." }
+  ],
+  "edges": [
+    { "from": "outcome", "to": "decompose", "intent": "accent" },
+    { "from": "decompose", "to": "risk", "intent": "blue" },
+    { "from": "risk", "to": "spike", "label": "unknown", "intent": "orange" },
+    { "from": "risk", "to": "ship", "label": "clear", "intent": "green" },
+    { "from": "spike", "to": "ship", "intent": "green" },
+    { "from": "ship", "to": "reflect", "intent": "purple" },
+    { "from": "reflect", "to": "outcome", "kind": "dashed", "intent": "muted", "label": "next slice" }
+  ]
+}
+\`\`\`
+
 ## How I decide
 
 <Decision
@@ -1195,156 +1574,655 @@ would.
 />
 `
   );
-  write(
-    "content/docs/pr-comments.mdx",
-    `---
-title: How I give PR comments
-description: My review bar, the tone I use, and concrete examples of comments I leave.
-summary: How this person reviews code \u2014 what they block on versus nudge, the tone of their comments, and worked examples an agent can imitate when reviewing on their behalf.
-tags: [code-review, feedback, how-to]
----
+  write(
+    "content/docs/pr-comments.mdx",
+    `---
+title: How I give PR comments
+description: My review bar, the tone I use, and concrete examples of comments I leave.
+summary: How this person reviews code \u2014 what they block on versus nudge, the tone of their comments, and worked examples an agent can imitate when reviewing on their behalf.
+tags: [code-review, feedback, how-to]
+---
+
+<SectionHead
+  eyebrow="Code review"
+  title="How I give PR comments"
+  description="What I block on, what I just nudge, and how I phrase it. Replace with your own."
+/>
+
+## My review bar
+
+<Checklist
+  label="What I look for, in order"
+  items={[
+    { text: "Correctness \u2014 does it do the thing, including the edge cases?", group: "Block on" },
+    { text: "Tests that would fail without the change", group: "Block on" },
+    { text: "Names and structure I can read in one pass", group: "Block on" },
+    { text: "Unnecessary abstraction or dead code", group: "Nudge on" },
+    { text: "Comments that explain why, not what", group: "Nudge on" },
+    { text: "Nits \u2014 formatting, ordering, taste", group: "Optional" },
+  ]}
+/>
+
+## How I phrase comments
+
+I prefix to signal weight: **blocking:** must change, **suggestion:** take it or leave it,
+**nit:** ignore freely, **question:** I genuinely don't know. Examples:
+
+<Example title="A blocking comment">
+**blocking:** This drops the error on the floor \u2014 if the fetch fails we return \`undefined\` and
+the caller renders an empty state as if it were success. Surface it, or handle it explicitly.
+</Example>
+
+<Example title="A suggestion">
+**suggestion:** This loop reads cleanly, but \`items.flatMap\` would say the same thing in one line.
+Your call \u2014 not blocking.
+</Example>
+
+<Example title="A nit">
+**nit:** tiny \u2014 can we name this \`pendingCount\` so it matches the others? Ignore if you disagree.
+</Example>
+
+<Tip title="Tone">
+  Critique the code, never the author. Lead with the why. If I'd want it softened when it lands on
+  my own PR, I soften it.
+</Tip>
+`
+  );
+  write(
+    "content/docs/voice.mdx",
+    `---
+title: Voice & writing
+description: How I sound in writing \u2014 tone, defaults, and what I avoid.
+summary: This person's writing voice \u2014 tone, structure defaults, and explicit do/don't rules an agent should follow when drafting in their name.
+tags: [voice, writing, style]
+---
+
+<SectionHead
+  eyebrow="How I write"
+  title="Voice & writing"
+  description="So an agent drafting in my name sounds like me, not like a template."
+/>
+
+Placeholder \u2014 capture your actual voice. The more specific the do/don't list, the better an agent
+can match you.
+
+<KeyFacts
+  items={[
+    { label: "Tone", value: "Direct, warm, low ceremony" },
+    { label: "Sentence length", value: "Short. Then one longer one to breathe." },
+    { label: "Person", value: "First person, active voice" },
+    { label: "Jargon", value: "Only when it's the precise word" },
+  ]}
+/>
+
+## Do / don't
+
+<Comparison
+  caption="My writing defaults"
+  options={["Do", "Don't"]}
+  rows={[
+    { criterion: "Openers", cells: ["Get to the point in the first line", "Open with filler pleasantries"] },
+    { criterion: "Hedging", cells: ["Say what I think", "It might possibly be worth considering"] },
+    { criterion: "Structure", cells: ["Lead with the answer, then the why", "Bury the ask at the end"] },
+    { criterion: "Emoji", cells: ["Rarely, and never in serious writing", "Decorate every line"] },
+  ]}
+/>
+
+<Example title="A message in my voice">
+Shipping the import fix today. It was dropping rows when a column was empty \u2014 now we skip the row
+and log it. One follow-up: we should validate on upload so this can't happen again. Want me to take
+that next?
+</Example>
+`
+  );
+  write(
+    "content/docs/stories.mdx",
+    `---
+title: Stories
+description: Formative moments that explain how I got my defaults.
+summary: Formative experiences that shaped this person's beliefs and working style, as a dated timeline an agent can reference for context on why they think the way they do.
+tags: [stories, background, timeline]
+---
+
+<SectionHead
+  eyebrow="Where it comes from"
+  title="Stories"
+  description="The moments behind the takes. Replace these with your own \u2014 dates can be approximate."
+/>
+
+An agent that knows *why* you believe something reasons better than one that only knows *what*.
+These are placeholders.
+
+<Timeline
+  label="Formative moments"
+  items={[
+    {
+      date: "2016",
+      title: "The outage that taught me to write things down",
+      body: "A fix lived only in one person's head. When they were out, we relearned it the hard way. I've defaulted to docs ever since.",
+      status: "done",
+      tags: ["process", "writing"],
+    },
+    {
+      date: "2019",
+      title: "Shipped small for the first time",
+      body: "Replaced a six-month rewrite with weekly reversible changes. It landed. I stopped believing in big-bang.",
+      status: "done",
+      tags: ["shipping"],
+    },
+    {
+      date: "2022",
+      title: "A review that changed how I review",
+      body: "Someone critiqued my code without making me feel small. I've tried to give every review that way since.",
+      status: "done",
+      tags: ["code-review", "tone"],
+    },
+  ]}
+/>
+`
+  );
+}
+
+// src/lib/content/util.ts
+function escapeForJsx(value) {
+  return value.replace(/[\\"]/g, "\\$&").replace(/[{}]/g, "");
+}
+
+// src/lib/content/index.ts
+function writeContent(write, config) {
+  switch (config.type) {
+    case "company-kb":
+      writeCompanyContent(write, config);
+      return;
+    case "product-docs":
+      writeProductContent(write, config);
+      return;
+    case "personal-kb":
+      writePersonalContent(write, config);
+      return;
+  }
+}
+
+// src/lib/scaffold.ts
+var here = dirname2(fileURLToPath(import.meta.url));
+function findStarterTemplate() {
+  let dir = here;
+  for (; ; ) {
+    const candidate = join3(dir, "templates", "starter");
+    if (existsSync3(candidate)) return candidate;
+    const bundled = join3(dir, "template");
+    if (existsSync3(bundled)) return bundled;
+    const parent = dirname2(dir);
+    if (parent === dir) return void 0;
+    dir = parent;
+  }
+}
+function isUsableTemplate(dir) {
+  if (!existsSync3(dir)) return false;
+  const entries = readdirSync(dir).filter((name) => name !== "README.md" && !name.startsWith("."));
+  return entries.length > 0;
+}
+function isEmptyDir(dir) {
+  if (!existsSync3(dir)) return true;
+  return readdirSync(dir).filter((n) => !n.startsWith(".")).length === 0;
+}
+function scaffold(options) {
+  const root = resolve2(options.dir);
+  mkdirSync(root, { recursive: true });
+  const template = findStarterTemplate();
+  let source;
+  if (template && isUsableTemplate(template)) {
+    cpSync(template, root, { recursive: true });
+    source = "template";
+  } else {
+    writeSkeleton(root, options.config);
+    source = "skeleton";
+  }
+  writeFileSync2(join3(root, "superlore.json"), serializeSuperloreJson(options.config), "utf8");
+  return { root, source };
+}
+function writeSkeleton(root, config) {
+  const accent2 = config.accent ?? SUPERLORE_VIOLET;
+  const mcpEnabled = config.mcp?.enabled ?? true;
+  const authEnabled = config.auth?.enabled ?? false;
+  const slug = config.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "superlore-kb";
+  const write = (rel, body) => {
+    const file = join3(root, rel);
+    mkdirSync(dirname2(file), { recursive: true });
+    writeFileSync2(file, body, "utf8");
+  };
+  write(
+    "package.json",
+    `${JSON.stringify(
+      {
+        name: slug,
+        version: "0.1.0",
+        private: true,
+        type: "module",
+        scripts: {
+          dev: "next dev",
+          build: "next build",
+          start: "next start",
+          postinstall: "fumadocs-mdx"
+        },
+        dependencies: {
+          "fumadocs-core": "16.8.2",
+          "fumadocs-mdx": "14.3.1",
+          "fumadocs-ui": "16.8.2",
+          superlore: "^0.5.3",
+          "lucide-react": "^1.21.0",
+          // superlore peers the rendered components pull in: Mermaid (Diagram), themes.
+          mermaid: "^11.15.0",
+          ...mcpEnabled ? { "@modelcontextprotocol/sdk": "^1.29.0", "mcp-handler": "^1.1.0" } : {},
+          // Auth.js v5 powers the optional Google SSO gate (superlore/auth). Self-disabling
+          // without AUTH_GOOGLE_ID, so it's harmless until the env is set.
+          ...authEnabled ? { "next-auth": "^5.0.0-beta.25" } : {},
+          next: "16.2.4",
+          "next-themes": "^0.4.6",
+          react: "^19.2.5",
+          "react-dom": "^19.2.5",
+          zod: "^4.4.3"
+        },
+        devDependencies: {
+          "@tailwindcss/postcss": "^4.2.2",
+          "@types/node": "^25.6.0",
+          "@types/react": "^19.2.14",
+          "@types/react-dom": "^19.2.3",
+          postcss: "^8.5.10",
+          tailwindcss: "^4.2.2",
+          typescript: "6.0.3"
+        }
+      },
+      null,
+      2
+    )}
+`
+  );
+  write(
+    "tsconfig.json",
+    `${JSON.stringify(
+      {
+        compilerOptions: {
+          target: "ES2022",
+          lib: ["dom", "dom.iterable", "esnext"],
+          module: "esnext",
+          moduleResolution: "bundler",
+          strict: true,
+          noEmit: true,
+          jsx: "preserve",
+          esModuleInterop: true,
+          resolveJsonModule: true,
+          isolatedModules: true,
+          skipLibCheck: true,
+          incremental: true,
+          paths: { "@/*": ["./*"], "collections/*": ["./.source/*"] },
+          plugins: [{ name: "next" }]
+        },
+        include: ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+        exclude: ["node_modules", ".next", "out"]
+      },
+      null,
+      2
+    )}
+`
+  );
+  write(
+    "next.config.mjs",
+    `import { createMDX } from "fumadocs-mdx/next";
+
+const withMDX = createMDX();
+
+/** @type {import('next').NextConfig} */
+const config = {
+  reactStrictMode: true,
+  // superlore ships compiled ESM \u2014 consume it as a normal package (no transpilePackages).
+};
+
+export default withMDX(config);
+`
+  );
+  write(
+    "source.config.ts",
+    `import { defineConfig, defineDocs } from "fumadocs-mdx/config";
+import { superloreFrontmatterSchema } from "superlore/frontmatter";
+import { remarkSuperloreCanvas } from "superlore/mdx";
+
+// Extend the superlore frontmatter schema in ONE place if you add custom fields.
+export const docs = defineDocs({
+  dir: "content/docs",
+  docs: { schema: superloreFrontmatterSchema },
+});
+
+export default defineConfig({
+  mdxOptions: {
+    // Turn fenced \`\`\`superlore-canvas JSON blocks into <Canvas json="\u2026" /> \u2014 the headline
+    // authoring path: write a whiteboard as a code block, get a rendered + serialized canvas.
+    remarkPlugins: [remarkSuperloreCanvas],
+  },
+});
+`
+  );
+  write(
+    "postcss.config.mjs",
+    `const config = {
+  plugins: { "@tailwindcss/postcss": {} },
+};
+
+export default config;
+`
+  );
+  write(
+    "app/global.css",
+    `@import "tailwindcss";
+/* superlore theme tokens (light + dark, co-equal). Re-skin the whole KB from one accent. */
+@import "superlore/css";
+
+:root {
+  /* Brand accent \u2014 superlore derives the hover/weak/border/text family for both themes. */
+  --kp-accent: ${accent2};
+}
+`
+  );
+  write(
+    "app/layout.tsx",
+    `import type { ReactNode } from "react";
+import { RootProvider } from "superlore/ui";
+import "./global.css";
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  // Light and dark are co-equal; default to the system preference.
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <RootProvider>{children}</RootProvider>
+      </body>
+    </html>
+  );
+}
+`
+  );
+  write(
+    "app/page.tsx",
+    `import { redirect } from "next/navigation";
+
+// A superlore KB *is* its docs \u2014 there's no separate marketing home to maintain. Land visitors
+// straight in the docs (full nav, header, sidebar, search). Replace this with a custom landing
+// only if you actually want one.
+export default function HomePage() {
+  redirect("/docs");
+}
+`
+  );
+  write(
+    "app/docs/layout.tsx",
+    `import type { ReactNode } from "react";
+import { DocsLayout } from "fumadocs-ui/layouts/docs";
+import { source } from "@/lib/source";
+
+export default function Layout({ children }: { children: ReactNode }) {
+  return (
+    <DocsLayout tree={source.pageTree} nav={{ title: "${escapeForJsx(config.name)}" }}>
+      {children}
+    </DocsLayout>
+  );
+}
+`
+  );
+  write(
+    "app/docs/[[...slug]]/page.tsx",
+    `import { notFound } from "next/navigation";
+import { DocsBody, DocsPage } from "fumadocs-ui/page";
+import { getMDXComponents } from "superlore";
+import { source } from "@/lib/source";
+
+export default async function Page(props: { params: Promise<{ slug?: string[] }> }) {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) notFound();
+  const MDX = page.data.body;
+  return (
+    <DocsPage toc={page.data.toc}>
+      <DocsBody>
+        <MDX components={getMDXComponents()} />
+      </DocsBody>
+    </DocsPage>
+  );
+}
+
+export function generateStaticParams() {
+  return source.generateParams();
+}
+`
+  );
+  write(
+    "lib/source.ts",
+    `import { docs } from "collections/server";
+import { loader, lucideIconsPlugin } from "superlore/source";
+
+export const source = loader({
+  baseUrl: "/docs",
+  source: docs.toFumadocsSource(),
+  plugins: [lucideIconsPlugin()],
+});
+`
+  );
+  writeContent(write, config);
+  if (authEnabled) {
+    writeAuth(write, config);
+  }
+  if (mcpEnabled) {
+    const mcpPath = config.mcp?.path ?? "/api/mcp";
+    write(
+      "app/api/[transport]/route.ts",
+      `import { createMcpHandler } from "mcp-handler";
+import { z } from "zod";
+import { getComponentData, getPage, list, navigate, search } from "superlore/mcp";
+import { buildIndexFromSource } from "superlore/source";
+import type { KKind } from "superlore";
+import { source } from "@/lib/source";
+
+// Your KB's MCP endpoint. Served at ${mcpPath} \u2014 the same structured content the site renders,
+// exposed to agents. The index is built straight from your content \`source\`: author once, and
+// humans read the pages while agents query this corpus. No scraping, no drift.
+const index = buildIndexFromSource(source);
+
+const json = (data: unknown) => ({
+  content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
+});
+
+const handler = createMcpHandler(
+  (server) => {
+    server.tool(
+      "search",
+      "Full-text search across the knowledge base.",
+      { query: z.string(), limit: z.number().int().positive().optional() },
+      async ({ query, limit }) => json(search(index, query, limit)),
+    );
+    server.tool(
+      "get_page",
+      "Get a page's full structured content by path.",
+      { path: z.string() },
+      async ({ path }) => json(getPage(index, path)),
+    );
+    server.tool(
+      "list",
+      "List knowledge nodes, filtered by kind / tag / entityType.",
+      { kind: z.string().optional(), tag: z.string().optional(), entityType: z.string().optional() },
+      async ({ kind, tag, entityType }) =>
+        json(list(index, { kind: kind as KKind | undefined, tag, entityType })),
+    );
+    server.tool(
+      "navigate",
+      "Follow relations from a page path / node id / entity ref.",
+      { target: z.string() },
+      async ({ target }) => json(navigate(index, target)),
+    );
+    server.tool(
+      "get_component_data",
+      "Get the structured data behind a rendered component (its knowledge face).",
+      { id: z.string() },
+      async ({ id }) => json(getComponentData(index, id)),
+    );
+  },
+  {},
+  { basePath: "/api" },
+);
+
+export { handler as GET, handler as POST };
+`
+    );
+  }
+  write(
+    ".gitignore",
+    `node_modules
+.next
+.source
+out
+*.tsbuildinfo
+.env*.local
+`
+  );
+  if (authEnabled) {
+    write(
+      ".env.example",
+      `# Auth.js v5 + Google SSO. The gate is OFF until AUTH_GOOGLE_ID is set, so local dev works with
+# this file empty. Copy to .env.local and fill in to enable it on a deploy.
+AUTH_SECRET=            # \`openssl rand -base64 32\`
+AUTH_GOOGLE_ID=         # presence of this turns the gate ON
+AUTH_GOOGLE_SECRET=
+AUTH_URL=               # the deploy's canonical URL, e.g. https://your-kb.vercel.app
+AUTH_TRUST_HOST=true
+${config.auth?.allowedDomain ? `AUTH_ALLOWED_DOMAIN=${config.auth.allowedDomain}` : "# AUTH_ALLOWED_DOMAIN=example.com   # restrict sign-in to one workspace domain (optional)"}
+# AUTH_ALLOWED_EMAILS=you@example.com   # comma-separated allowlist that bypasses the domain check
+# LOCAL=true                            # force the gate OFF locally even when configured
+`
+    );
+  }
+  const authReadme = authEnabled ? `
 
-<SectionHead
-  eyebrow="Code review"
-  title="How I give PR comments"
-  description="What I block on, what I just nudge, and how I phrase it. Replace with your own."
-/>
+## Auth
 
-## My review bar
+This KB ships a Google SSO gate (Auth.js v5). It is **off until you set \`AUTH_GOOGLE_ID\`**, so local dev runs open. Copy \`.env.example\` to \`.env.local\` and fill it in to enable it. The gate lives in \`proxy.ts\`, in front of every route \u2014 so the MCP inherits it too.` : "";
+  write(
+    "README.md",
+    `# ${config.name}
 
-<Checklist
-  label="What I look for, in order"
-  items={[
-    { text: "Correctness \u2014 does it do the thing, including the edge cases?", group: "Block on" },
-    { text: "Tests that would fail without the change", group: "Block on" },
-    { text: "Names and structure I can read in one pass", group: "Block on" },
-    { text: "Unnecessary abstraction or dead code", group: "Nudge on" },
-    { text: "Comments that explain why, not what", group: "Nudge on" },
-    { text: "Nits \u2014 formatting, ordering, taste", group: "Optional" },
-  ]}
-/>
+A superlore knowledge base. One corpus. Humans and agents.
 
-## How I phrase comments
+## Develop
 
-I prefix to signal weight: **blocking:** must change, **suggestion:** take it or leave it,
-**nit:** ignore freely, **question:** I genuinely don't know. Examples:
+\`\`\`sh
+pnpm install   # or npm / yarn / bun
+superlore dev     # preview the site locally
+\`\`\`
 
-<Example title="A blocking comment">
-**blocking:** This drops the error on the floor \u2014 if the fetch fails we return \`undefined\` and
-the caller renders an empty state as if it were success. Surface it, or handle it explicitly.
-</Example>
+## Build
 
-<Example title="A suggestion">
-**suggestion:** This loop reads cleanly, but \`items.flatMap\` would say the same thing in one line.
-Your call \u2014 not blocking.
-</Example>
+\`\`\`sh
+superlore build
+\`\`\`
 
-<Example title="A nit">
-**nit:** tiny \u2014 can we name this \`pendingCount\` so it matches the others? Ignore if you disagree.
-</Example>
+Config lives in \`superlore.json\`. Author content in \`content/docs/\`.${mcpEnabled ? `
 
-<Tip title="Tone">
-  Critique the code, never the author. Lead with the why. If I'd want it softened when it lands on
-  my own PR, I soften it.
-</Tip>
+The MCP endpoint is served at \`${config.mcp?.path ?? "/api/mcp"}\`.` : ""}${authReadme}
 `
   );
+}
+function writeAuth(write, config) {
+  const allowedDomain = config.auth?.allowedDomain;
   write(
-    "content/docs/voice.mdx",
-    `---
-title: Voice & writing
-description: How I sound in writing \u2014 tone, defaults, and what I avoid.
-summary: This person's writing voice \u2014 tone, structure defaults, and explicit do/don't rules an agent should follow when drafting in their name.
-tags: [voice, writing, style]
----
-
-<SectionHead
-  eyebrow="How I write"
-  title="Voice & writing"
-  description="So an agent drafting in my name sounds like me, not like a template."
-/>
-
-Placeholder \u2014 capture your actual voice. The more specific the do/don't list, the better an agent
-can match you.
-
-<KeyFacts
-  items={[
-    { label: "Tone", value: "Direct, warm, low ceremony" },
-    { label: "Sentence length", value: "Short. Then one longer one to breathe." },
-    { label: "Person", value: "First person, active voice" },
-    { label: "Jargon", value: "Only when it's the precise word" },
-  ]}
-/>
-
-## Do / don't
+    "auth.ts",
+    `import { createSuperloreAuth } from "superlore/auth";
 
-<Comparison
-  caption="My writing defaults"
-  options={["Do", "Don't"]}
-  rows={[
-    { criterion: "Openers", cells: ["Get to the point in the first line", "Open with filler pleasantries"] },
-    { criterion: "Hedging", cells: ["Say what I think", "It might possibly be worth considering"] },
-    { criterion: "Structure", cells: ["Lead with the answer, then the why", "Bury the ask at the end"] },
-    { criterion: "Emoji", cells: ["Rarely, and never in serious writing", "Decorate every line"] },
-  ]}
-/>
+// Auth.js v5 + Google SSO. Allowlists can come from env (AUTH_ALLOWED_DOMAIN / AUTH_ALLOWED_EMAILS)
+// or be passed explicitly here. Off until AUTH_GOOGLE_ID is set, so local dev needs no config.
+export const { handlers, auth, signIn, signOut } = createSuperloreAuth(${allowedDomain ? `{
+  allowedDomain: ${JSON.stringify(allowedDomain)},
+}` : "{}"});
+`
+  );
+  write(
+    "app/api/auth/[...nextauth]/route.ts",
+    `import { handlers } from "@/auth";
 
-<Example title="A message in my voice">
-Shipping the import fix today. It was dropping rows when a column was empty \u2014 now we skip the row
-and log it. One follow-up: we should validate on upload so this can't happen again. Want me to take
-that next?
-</Example>
+export const { GET, POST } = handlers;
 `
   );
   write(
-    "content/docs/stories.mdx",
-    `---
-title: Stories
-description: Formative moments that explain how I got my defaults.
-summary: Formative experiences that shaped this person's beliefs and working style, as a dated timeline an agent can reference for context on why they think the way they do.
-tags: [stories, background, timeline]
----
+    "proxy.ts",
+    `import { auth } from "@/auth";
+import { createAuthProxy } from "superlore/auth";
 
-<SectionHead
-  eyebrow="Where it comes from"
-  title="Stories"
-  description="The moments behind the takes. Replace these with your own \u2014 dates can be approximate."
-/>
+// Next.js 16 middleware lives in proxy.ts. The gate is self-disabling: with no AUTH_GOOGLE_ID
+// (or LOCAL=true) every request passes through, so local dev and public deploys stay open.
+export default createAuthProxy(auth);
 
-An agent that knows *why* you believe something reasons better than one that only knows *what*.
-These are placeholders.
+export const config = {
+  // Run on everything except static assets (the helper also skips the auth dance + icons).
+  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+};
+`
+  );
+  write(
+    "app/auth/signin/page.tsx",
+    `import { signIn } from "@/auth";
 
-<Timeline
-  label="Formative moments"
-  items={[
-    {
-      date: "2016",
-      title: "The outage that taught me to write things down",
-      body: "A fix lived only in one person's head. When they were out, we relearned it the hard way. I've defaulted to docs ever since.",
-      status: "done",
-      tags: ["process", "writing"],
-    },
-    {
-      date: "2019",
-      title: "Shipped small for the first time",
-      body: "Replaced a six-month rewrite with weekly reversible changes. It landed. I stopped believing in big-bang.",
-      status: "done",
-      tags: ["shipping"],
-    },
-    {
-      date: "2022",
-      title: "A review that changed how I review",
-      body: "Someone critiqued my code without making me feel small. I've tried to give every review that way since.",
-      status: "done",
-      tags: ["code-review", "tone"],
-    },
-  ]}
-/>
+export default async function SignInPage(props: {
+  searchParams: Promise<{ callbackUrl?: string }>;
+}) {
+  const { callbackUrl } = await props.searchParams;
+  return (
+    <main className="grid min-h-screen place-items-center p-6">
+      <form
+        action={async () => {
+          "use server";
+          await signIn("google", { redirectTo: callbackUrl ?? "/" });
+        }}
+        className="w-full max-w-sm rounded-lg border border-fd-border bg-fd-card p-6 text-center"
+      >
+        <h1 className="text-lg font-semibold text-fd-foreground">Sign in</h1>
+        <p className="mt-1 text-sm text-fd-muted-foreground">
+          This knowledge base is private. Continue with Google to read it.
+        </p>
+        <button
+          type="submit"
+          className="mt-5 inline-flex w-full items-center justify-center rounded-md border border-kp-accent-border bg-kp-accent px-4 py-2 text-sm font-medium text-white"
+        >
+          Continue with Google
+        </button>
+      </form>
+    </main>
+  );
+}
 `
   );
+  write(
+    "app/auth/error/page.tsx",
+    `export default async function AuthErrorPage(props: {
+  searchParams: Promise<{ error?: string }>;
+}) {
+  const { error } = await props.searchParams;
+  return (
+    <main className="grid min-h-screen place-items-center p-6">
+      <div className="w-full max-w-sm rounded-lg border border-fd-border bg-fd-card p-6 text-center">
+        <h1 className="text-lg font-semibold text-fd-foreground">Can't sign in</h1>
+        <p className="mt-1 text-sm text-fd-muted-foreground">
+          {error === "AccessDenied"
+            ? "That account isn't allowed to access this knowledge base."
+            : "Something went wrong signing in. Try again."}
+        </p>
+        <a
+          href="/auth/signin"
+          className="mt-5 inline-flex w-full items-center justify-center rounded-md border border-fd-border px-4 py-2 text-sm font-medium text-fd-foreground no-underline"
+        >
+          Back to sign in
+        </a>
+      </div>
+    </main>
+  );
 }
-function escapeForJsx(value) {
-  return value.replace(/[\\"]/g, "\\$&").replace(/[{}]/g, "");
+`
+  );
 }
 
 // src/commands/init.ts
@@ -1459,9 +2337,41 @@ ${result.issues.map((i) => `  - ${i.path} ${i.message}`).join("\n")}`
       `This is a ${bold(kind)} but auth is ${bold("not enabled")}. A ${kind} should gate access before you deploy \u2014 re-run with ${cyan("--auth")} or set ${cyan('"auth": { "enabled": true }')} in superlore.json.`
     );
   }
+  printStructure(root);
   printNextSteps(root, config);
   await maybeConnectEditor(flags, interactive);
 }
+function printStructure(root) {
+  const docs = join4(root, "content", "docs");
+  if (!existsSync4(docs)) return;
+  const lines = [];
+  const walk = (dir, depth) => {
+    let names;
+    try {
+      names = readdirSync2(dir).sort((a, b) => a.localeCompare(b));
+    } catch {
+      return;
+    }
+    const dirs = names.filter((n) => !n.startsWith(".") && statSync(join4(dir, n)).isDirectory());
+    const pages = names.filter((n) => n.endsWith(".mdx"));
+    for (const name of dirs) {
+      lines.push(`${"  ".repeat(depth)}${cyan(`${name}/`)}`);
+      walk(join4(dir, name), depth + 1);
+    }
+    for (const name of pages) {
+      lines.push(`${"  ".repeat(depth)}${name}`);
+    }
+  };
+  walk(docs, 1);
+  log.blank();
+  log.info(bold("Your starter structure"));
+  log.info(`${dim("  content/docs/")} ${dim("\u2014 a full KB, pre-filled with placeholder content:")}`);
+  for (const line of lines) log.info(line);
+  log.blank();
+  log.info(
+    `${bold("Now bring your content in.")} Keep the structure and replace the placeholder pages with what's true for you \u2014 page by page, or ask your agent: ${cyan('"fill in my superlore KB"')}.`
+  );
+}
 async function maybeConnectEditor(flags, interactive) {
   if (flags.connect === false) return;
   const editors = detectEditors();
@@ -1508,7 +2418,7 @@ function printNextSteps(root, config) {
 }
 
 // src/index.ts
-var VERSION = "0.3.0";
+var VERSION = "0.4.0";
 function buildCli(argv = process3.argv) {
   const cli = cac("superlore");
   cli.command("init [dir]", "Scaffold a new superlore knowledge base").option("--name <name>", "KB name").option("--type <type>", "KB type: company-kb | product-docs | personal-kb").option("--auth", "Enable the Google SSO auth gate").option("--no-auth", "Disable the auth gate").option("--allowed-domain <domain>", "Restrict SSO to one email domain (implies --auth)").option("--accent <color>", "Brand accent colour (any CSS colour)").option("--no-mcp", "Disable the MCP endpoint (on by default)").option("--connect", "Install the editor extension after scaffolding (skip the prompt)").option("--no-connect", "Don't set up the editor extension").option("-y, --yes", "Skip prompts; use flags + defaults").example("superlore init my-kb --type product-docs").example("superlore init acme --type company-kb --auth --allowed-domain acme.com").example("superlore init me --type personal-kb").action(