superlore-cli 0.2.0 → 0.3.1

package/dist/config.d.ts

@@ -11,8 +11,12 @@
  * imported from anywhere — including the browser or an edge runtime — without dragging in a
  * validator. Keep it that way.
  */
-/** The two kinds of superlore KB. Drives defaults (notably the auth warning for company KBs). */
-type SuperloreType = "company-kb" | "product-docs";
+/**
+ * The kinds of superlore KB. Drives defaults — the auth warning for company KBs, and an
+ * auth-ON-by-default, MCP-ON private posture for a `personal-kb` (a digital replica of how one
+ * person thinks, works, and writes).
+ */
+type SuperloreType = "company-kb" | "product-docs" | "personal-kb";
 /** Supported SSO providers. Only Google ships today (Auth.js v5 + Google SSO). */
 type SuperloreAuthProvider = "google";
 /** The human gate. Optional and per-deploy — public by default. */
@@ -35,7 +39,7 @@ interface SuperloreMcpConfig {
 interface SuperloreJson {
     /** Human-facing KB name. */
     name: string;
-    /** Whether this is a private company KB or public product docs. */
+    /** Whether this is a private company KB, public product docs, or a private personal KB. */
     type: SuperloreType;
     /** Brand accent — any CSS colour. superlore derives the rest of the family (light + dark). */
     accent?: string;

package/dist/config.js

@@ -1,7 +1,11 @@
 // src/config.ts
 var DEFAULT_MCP_PATH = "/api/mcp";
 var SUPERLORE_JSON_FILENAME = "superlore.json";
-var SUPERLORE_TYPES = ["company-kb", "product-docs"];
+var SUPERLORE_TYPES = [
+  "company-kb",
+  "product-docs",
+  "personal-kb"
+];
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/dist/index.d.ts

@@ -13,8 +13,12 @@ import * as cac from 'cac';
  * imported from anywhere — including the browser or an edge runtime — without dragging in a
  * validator. Keep it that way.
  */
-/** The two kinds of superlore KB. Drives defaults (notably the auth warning for company KBs). */
-type SuperloreType = "company-kb" | "product-docs";
+/**
+ * The kinds of superlore KB. Drives defaults — the auth warning for company KBs, and an
+ * auth-ON-by-default, MCP-ON private posture for a `personal-kb` (a digital replica of how one
+ * person thinks, works, and writes).
+ */
+type SuperloreType = "company-kb" | "product-docs" | "personal-kb";
 /** Supported SSO providers. Only Google ships today (Auth.js v5 + Google SSO). */
 type SuperloreAuthProvider = "google";
 /** The human gate. Optional and per-deploy — public by default. */
@@ -37,7 +41,7 @@ interface SuperloreMcpConfig {
 interface SuperloreJson {
     /** Human-facing KB name. */
     name: string;
-    /** Whether this is a private company KB or public product docs. */
+    /** Whether this is a private company KB, public product docs, or a private personal KB. */
     type: SuperloreType;
     /** Brand accent — any CSS colour. superlore derives the rest of the family (light + dark). */
     accent?: string;
@@ -83,7 +87,7 @@ declare function serializeSuperloreJson(config: SuperloreJson): string;
 declare function resolveMcpPath(config: SuperloreJson): string | undefined;
 
 /** The CLI version, kept in sync with package.json at build time. */
-declare const VERSION = "0.2.0";
+declare const VERSION = "0.3.1";
 /** Build the argument parser. Exported for tests; `run()` wires it to argv. */
 declare function buildCli(argv?: readonly string[]): cac.CAC;
 /** Parse argv and dispatch. Reports unknown commands and unexpected errors cleanly. */

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")}
@@ -71,7 +71,11 @@ import { dirname, join, resolve } from "path";
 // src/config.ts
 var DEFAULT_MCP_PATH = "/api/mcp";
 var SUPERLORE_JSON_FILENAME = "superlore.json";
-var SUPERLORE_TYPES = ["company-kb", "product-docs"];
+var SUPERLORE_TYPES = [
+  "company-kb",
+  "product-docs",
+  "personal-kb"
+];
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -209,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));
@@ -413,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}`);
@@ -433,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
@@ -514,8 +524,7 @@ 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);
 }
 
@@ -568,6 +577,7 @@ function scaffold(options) {
 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);
@@ -592,9 +602,14 @@ function writeSkeleton(root, config) {
           "fumadocs-core": "16.8.2",
           "fumadocs-mdx": "14.3.1",
           "fumadocs-ui": "16.8.2",
-          superlore: "^0.1.0",
+          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",
@@ -633,7 +648,7 @@ function writeSkeleton(root, config) {
           isolatedModules: true,
           skipLibCheck: true,
           incremental: true,
-          paths: { "@/*": ["./*"] },
+          paths: { "@/*": ["./*"], "collections/*": ["./.source/*"] },
           plugins: [{ name: "next" }]
         },
         include: ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
@@ -653,8 +668,7 @@ const withMDX = createMDX();
 /** @type {import('next').NextConfig} */
 const config = {
   reactStrictMode: true,
-  // \`superlore\` ships source (.ts/.tsx) for frictionless consumption \u2014 Next transpiles it.
-  transpilePackages: ["superlore"],
+  // superlore ships compiled ESM \u2014 consume it as a normal package (no transpilePackages).
 };
 
 export default withMDX(config);
@@ -698,7 +712,7 @@ export default config;
   write(
     "app/layout.tsx",
     `import type { ReactNode } from "react";
-import { RootProvider } from "fumadocs-ui/provider";
+import { RootProvider } from "superlore/ui";
 import "./global.css";
 
 export default function RootLayout({ children }: { children: ReactNode }) {
@@ -772,18 +786,22 @@ export function generateStaticParams() {
   );
   write(
     "lib/source.ts",
-    `import { loader } from "fumadocs-core/source";
-import { docs } from "@/.source";
+    `import { docs } from "collections/server";
+import { loader, lucideIconsPlugin } from "superlore/source";
 
 export const source = loader({
   baseUrl: "/docs",
   source: docs.toFumadocsSource(),
+  plugins: [lucideIconsPlugin()],
 });
 `
   );
-  write(
-    "content/docs/index.mdx",
-    `---
+  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.
@@ -797,7 +815,11 @@ agents read the same structured content over MCP.
 
 Edit \`content/docs/index.mdx\` to make it yours, then run \`superlore dev\`.
 `
-  );
+    );
+  }
+  if (authEnabled) {
+    writeAuth(write, config);
+  }
   if (mcpEnabled) {
     const mcpPath = config.mcp?.path ?? "/api/mcp";
     write(
@@ -805,10 +827,14 @@ Edit \`content/docs/index.mdx\` to make it yours, then run \`superlore dev\`.
       `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. Build the index from your content source and pass it to each tool.
-// See the superlore docs (Agents & MCP) for wiring the index from \`source\`.
+// 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) }],
@@ -820,31 +846,32 @@ const handler = createMcpHandler(
       "search",
       "Full-text search across the knowledge base.",
       { query: z.string(), limit: z.number().int().positive().optional() },
-      async ({ query, limit }) => json(search(/* index */ {} as never, query, limit)),
+      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 */ {} as never, path)),
+      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 (args) => json(list(/* index */ {} as never, args)),
+      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 */ {} as never, target)),
+      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 */ {} as never, id)),
+      async ({ id }) => json(getComponentData(index, id)),
     );
   },
   {},
@@ -865,6 +892,27 @@ out
 .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 ? `
+
+## 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}
@@ -886,7 +934,417 @@ superlore build
 
 Config lives in \`superlore.json\`. Author content in \`content/docs/\`.${mcpEnabled ? `
 
-The MCP endpoint is served at \`${config.mcp?.path ?? "/api/mcp"}\`.` : ""}
+The MCP endpoint is served at \`${config.mcp?.path ?? "/api/mcp"}\`.` : ""}${authReadme}
+`
+  );
+}
+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)},
+}` : "{}"});
+`
+  );
+  write(
+    "app/api/auth/[...nextauth]/route.ts",
+    `import { handlers } from "@/auth";
+
+export const { GET, POST } = handlers;
+`
+  );
+  write(
+    "proxy.ts",
+    `import { auth } from "@/auth";
+import { createAuthProxy } from "superlore/auth";
+
+// 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);
+
+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";
+
+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 writePersonalContent(write, config) {
+  write(
+    "content/docs/meta.json",
+    `${JSON.stringify(
+      {
+        title: config.name,
+        root: true,
+        pages: ["index", "beliefs", "working-style", "pr-comments", "voice", "stories"]
+      },
+      null,
+      2
+    )}
+`
+  );
+  write(
+    "content/docs/index.mdx",
+    `---
+title: About me
+description: Who I am, what I care about, and how to work with me.
+summary: Overview of this person \u2014 role, focus, what they optimize for, and how an agent should use this KB to act on their behalf.
+tags: [overview, about, profile]
+---
+
+<PageHero
+  kicker="Personal KB"
+  title="About me"
+  description="A private, queryable replica of how I think, work, and write. Humans read this; my agents read the same content over MCP and act the way I would."
+/>
+
+I'm a placeholder. Replace this with a short, honest description of who you are \u2014 your role, what
+you build, and the through-line in your work. Keep it concrete: an agent should be able to read
+this and understand what you'd care about in a decision.
+
+<KeyFacts
+  items={[
+    { label: "Role", value: "What you do, in five words or fewer" },
+    { label: "Focus", value: "The problem you spend most days on" },
+    { label: "Optimizes for", value: "Speed, correctness, clarity \u2014 pick yours" },
+    { label: "Time zone", value: "UTC+0" },
+    { label: "Best reached", value: "Async, in writing" },
+    { label: "Decides by", value: "Evidence over opinion" },
+  ]}
+/>
+
+<EntityCard
+  type="person"
+  slug="me"
+  title="Your Name"
+  summary="One line that captures how you'd want an agent to introduce you."
+  icon="user"
+  fields={[
+    { key: "Discipline", value: "Engineering" },
+    { key: "Superpower", value: "Turning ambiguity into a plan" },
+    { key: "Allergic to", value: "Meetings that should have been a doc" },
+  ]}
+  refs={[
+    { rel: "see", target: "/docs/working-style", label: "How I work" },
+    { rel: "see", target: "/docs/voice", label: "How I write" },
+  ]}
+/>
+
+## How to use this KB
+
+Ask it how I'd think about something before you ask me. The pages below are the source of truth
+for my beliefs, working style, review bar, voice, and the stories that shaped them.
+`
+  );
+  write(
+    "content/docs/beliefs.mdx",
+    `---
+title: Beliefs & takes
+description: The positions I hold and the principles I keep coming back to.
+summary: This person's strongly-held beliefs and operating principles, each phrased as a position an agent can apply when reasoning on their behalf.
+tags: [beliefs, principles, takes]
+---
+
+<SectionHead
+  eyebrow="What I believe"
+  title="Beliefs & takes"
+  description="Strongly held, loosely coupled. Each is a position you can act on, not a vibe."
+/>
+
+These are placeholders \u2014 rewrite them as your own. Phrase each as a clear position so an agent can
+reason from it.
+
+<KeyFacts
+  items={[
+    { label: "On shipping", value: "Small and reversible beats big and perfect." },
+    { label: "On code", value: "Delete more than you add." },
+    { label: "On process", value: "Process is scar tissue \u2014 keep only what earned its place." },
+    { label: "On disagreement", value: "Disagree in the doc, commit in the room." },
+    { label: "On estimates", value: "Confidence intervals, not single numbers." },
+    { label: "On tools", value: "Boring tech for load-bearing things." },
+  ]}
+/>
+
+## A take I'll defend
+
+<Decision
+  title="Prefer clarity over cleverness"
+  status="accepted"
+  identifier="TAKE-01"
+  context={<>Clever code feels good to write and is expensive to read. Most code is read far more than it is written.</>}
+  decision={<>Optimize for the next person (often future me). If a reviewer has to ask what it does, it isn't done.</>}
+  consequences={[
+    "Fewer abstractions until they pay rent.",
+    "Comments explain why, names explain what.",
+    "I'll trade a few keystrokes for a faster read every time.",
+  ]}
+/>
+`
+  );
+  write(
+    "content/docs/working-style.mdx",
+    `---
+title: Working style
+description: How I plan, decide, focus, and collaborate.
+summary: How this person works day to day \u2014 how they plan, make decisions, manage focus, and collaborate. Use this to predict how they'd approach a task.
+tags: [working-style, how-to, collaboration]
+---
+
+<SectionHead
+  eyebrow="How I work"
+  title="Working style"
+  description="If you handed me a task, this is the shape of what I'd do with it."
+/>
+
+Placeholder content \u2014 make it yours. Be specific enough that an agent could run a task the way you
+would.
+
+<FeatureList
+  items={[
+    { icon: "target", title: "Start from the outcome", description: "I write the goal and the done-condition before touching the work." },
+    { icon: "split", title: "Decompose, then sequence", description: "Break into reversible steps; do the riskiest cheap thing first." },
+    { icon: "message-square", title: "Default to writing", description: "A short doc beats a meeting. Decisions live in text, not memory." },
+    { icon: "gauge", title: "Protect deep work", description: "Mornings are for the hard thing. Coordination batches in the afternoon." },
+  ]}
+/>
+
+## How I decide
+
+<Decision
+  title="Two-way doors don't need a meeting"
+  status="accepted"
+  identifier="STYLE-01"
+  context={<>Many decisions are easily reversible. Treating them as if they aren't is the real cost.</>}
+  decision={<>For reversible calls, I pick quickly and move; for one-way doors, I slow down and write the trade-offs out.</>}
+  consequences={[
+    "Speed on the 80% that's reversible.",
+    "Care on the 20% that isn't.",
+  ]}
+/>
+
+## A day, roughly
+
+<Schedule
+  label="Typical working day"
+  events={[
+    { date: "Weekday", time: "09:00", title: "Deep work", body: "The hardest task of the day, no notifications." },
+    { date: "Weekday", time: "12:30", title: "Reviews & async", body: "PRs, comments, written replies." },
+    { date: "Weekday", time: "15:00", title: "Collaboration", body: "Pairing, calls, unblock others." },
+    { date: "Weekday", time: "17:00", title: "Wind-down", body: "Plan tomorrow's first task." },
+  ]}
+/>
+`
+  );
+  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"],
+    },
+  ]}
+/>
 `
   );
 }
@@ -915,8 +1373,8 @@ async function initCommand(dir, flags) {
   }
   if (!name) bail("A name is required (pass --name, a [dir] argument, or run interactively).");
   let type = flags.type;
-  if (type && type !== "company-kb" && type !== "product-docs") {
-    bail(`Invalid --type "${type}". Use "company-kb" or "product-docs".`);
+  if (type && type !== "company-kb" && type !== "product-docs" && type !== "personal-kb") {
+    bail(`Invalid --type "${type}". Use "company-kb", "product-docs", or "personal-kb".`);
   }
   if (!type && interactive) {
     const answer = await select({
@@ -931,6 +1389,11 @@ async function initCommand(dir, flags) {
           value: "product-docs",
           label: "Product docs",
           hint: "public-facing documentation"
+        },
+        {
+          value: "personal-kb",
+          label: "Personal KB",
+          hint: "a private, queryable replica of how you think, work, and write"
         }
       ]
     });
@@ -938,6 +1401,7 @@ async function initCommand(dir, flags) {
     type = answer;
   }
   if (!type) bail("A type is required (pass --type or run interactively).");
+  const wantsGate = type === "company-kb" || type === "personal-kb";
   let authEnabled;
   if (flags.auth !== void 0) {
     authEnabled = flags.auth;
@@ -946,12 +1410,12 @@ async function initCommand(dir, flags) {
   } else if (interactive) {
     const answer = await confirm({
       message: "Gate the site behind Google SSO (auth)?",
-      initialValue: type === "company-kb"
+      initialValue: wantsGate
     });
     if (isCancel(answer)) bail("Cancelled.");
     authEnabled = answer;
   } else {
-    authEnabled = type === "company-kb";
+    authEnabled = wantsGate;
   }
   let allowedDomain = flags.allowedDomain?.trim();
   if (authEnabled && !allowedDomain && interactive) {
@@ -993,10 +1457,11 @@ ${result.issues.map((i) => `  - ${i.path} ${i.message}`).join("\n")}`
   }
   const { root, source } = scaffold({ dir: targetDir, config });
   outro(`${bold("Scaffolded")} ${config.name} ${dim(`(${source})`)}`);
-  if (config.type === "company-kb" && !config.auth?.enabled) {
+  if ((config.type === "company-kb" || config.type === "personal-kb") && !config.auth?.enabled) {
+    const kind = config.type === "personal-kb" ? "personal KB" : "company KB";
     log.blank();
     log.warn(
-      `This is a ${bold("company KB")} but auth is ${bold("not enabled")}. A company KB should gate access before you deploy \u2014 re-run with ${cyan("--auth")} or set ${cyan('"auth": { "enabled": true }')} in superlore.json.`
+      `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.`
     );
   }
   printNextSteps(root, config);
@@ -1007,13 +1472,17 @@ async function maybeConnectEditor(flags, interactive) {
   const editors = detectEditors();
   if (editors.length === 0) {
     log.blank();
-    log.info(`${dim("Editor preview:")} install VS Code, Cursor, or Windsurf, then ${cyan("superlore connect")}.`);
+    log.info(
+      `${dim("Editor preview:")} install VS Code, Cursor, or Windsurf, then ${cyan("superlore connect")}.`
+    );
     return;
   }
   const names = editors.map((e) => e.label).join(", ");
   if (flags.connect !== true && !interactive) {
     log.blank();
-    log.info(`${dim(`Detected ${names}.`)} Run ${cyan("superlore connect")} to install the live-preview extension.`);
+    log.info(
+      `${dim(`Detected ${names}.`)} Run ${cyan("superlore connect")} to install the live-preview extension.`
+    );
     return;
   }
   if (flags.connect !== true) {
@@ -1044,10 +1513,10 @@ function printNextSteps(root, config) {
 }
 
 // src/index.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.1";
 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").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").action(
+  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(
     async (dir, flags) => {
       const authExplicit = argv.includes("--auth");
       const noAuthExplicit = argv.includes("--no-auth");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlore-cli",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "The superlore CLI — scaffold, run, and build an agent-native knowledge base. One corpus. Humans and agents.",
   "license": "Apache-2.0",
   "author": "Krishnan S G",