superlore-cli 0.1.2 → 0.3.0

package/README.md

@@ -40,11 +40,17 @@ curl -fsSL https://superlore.vercel.app/install.sh | sh    # or: npm i -g superl
 ```
 
 ```bash
-superlore init my-kb   # scaffold — 2 questions → superlore.json + starter pages
+superlore init my-kb   # scaffold — 2 questions → superlore.json + starter pages, then sets up your editor
+superlore connect      # detect VS Code / Cursor / Windsurf and install the live-preview extension
 superlore dev          # live preview at localhost:3000
 superlore build        # production build, deploy anywhere
 ```
 
+`init` ends by offering to run `connect` for you, so one command takes you from nothing to a
+scaffolded KB with the editor extension installed — then it points you at wiring the MCP to your
+agent. `connect` detects each editor via its CLI or standard install path (macOS / Linux / Windows)
+and is safe to re-run.
+
 `superlore deploy` is reserved for managed **superlore Cloud**
 ([waitlisted](https://superlore.vercel.app/cloud)) — self-host free with `superlore build`.
 

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.1.2";
+declare const VERSION = "0.3.0";
 /** 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

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { fileURLToPath as fileURLToPath2 } from "url";
-import process2 from "process";
+import process3 from "process";
 import { cac } from "cac";
 
 // src/lib/log.ts
@@ -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);
 }
@@ -253,6 +257,194 @@ async function buildCommand() {
   process.exit(code);
 }
 
+// src/lib/editors.ts
+import { execFileSync } from "child_process";
+import { existsSync as existsSync2, writeFileSync } from "fs";
+import { homedir, tmpdir } from "os";
+import { join as join2 } from "path";
+import process2 from "process";
+var EXTENSION_ID = "superlore.superlore-preview";
+var DEFAULT_VSIX_URL = "https://superlore.vercel.app/superlore-preview.vsix";
+async function downloadVsix(url = DEFAULT_VSIX_URL) {
+  const res = await fetch(url, { redirect: "follow" });
+  if (!res.ok) throw new Error(`couldn't fetch the extension (${res.status} ${res.statusText})`);
+  const bytes = Buffer.from(await res.arrayBuffer());
+  const path = join2(tmpdir(), "superlore-preview.vsix");
+  writeFileSync(path, bytes);
+  return path;
+}
+var EDITORS = [
+  { id: "vscode", label: "VS Code", bin: "code" },
+  { id: "cursor", label: "Cursor", bin: "cursor" },
+  { id: "windsurf", label: "Windsurf", bin: "windsurf" }
+];
+function onPath(bin) {
+  const probe = process2.platform === "win32" ? "where" : "which";
+  try {
+    execFileSync(probe, [bin], { stdio: "ignore", shell: process2.platform === "win32" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function fallbackPaths(editor) {
+  const home = homedir();
+  if (process2.platform === "darwin") {
+    const app = {
+      vscode: "Visual Studio Code.app",
+      cursor: "Cursor.app",
+      windsurf: "Windsurf.app"
+    };
+    const rel = `Contents/Resources/app/bin/${editor.bin}`;
+    return [
+      join2("/Applications", app[editor.id], rel),
+      join2(home, "Applications", app[editor.id], rel)
+    ];
+  }
+  if (process2.platform === "win32") {
+    const local = process2.env.LOCALAPPDATA ?? join2(home, "AppData", "Local");
+    const programs = join2(local, "Programs");
+    const dir = {
+      vscode: "Microsoft VS Code",
+      cursor: "cursor",
+      windsurf: "Windsurf"
+    };
+    const exe = `bin\\${editor.bin}.cmd`;
+    return [
+      join2(programs, dir[editor.id], exe),
+      join2(process2.env.ProgramFiles ?? "C:\\Program Files", dir[editor.id], exe)
+    ];
+  }
+  return [
+    join2("/usr/share", editor.bin, "bin", editor.bin),
+    join2("/usr/bin", editor.bin),
+    join2("/snap/bin", editor.bin),
+    join2(home, ".local", "bin", editor.bin)
+  ];
+}
+function resolveEditorCommand(editor) {
+  if (onPath(editor.bin)) return editor.bin;
+  for (const candidate of fallbackPaths(editor)) {
+    if (existsSync2(candidate)) return candidate;
+  }
+  return void 0;
+}
+function detectEditors() {
+  const found = [];
+  for (const editor of EDITORS) {
+    const command = resolveEditorCommand(editor);
+    if (command) found.push({ ...editor, command });
+  }
+  return found;
+}
+var execRunner = (command, args) => execFileSync(command, [...args], {
+  encoding: "utf8",
+  stdio: ["ignore", "pipe", "pipe"],
+  // Editor CLIs on Windows are .cmd shims; a shell is needed to invoke them.
+  shell: process2.platform === "win32",
+  timeout: 6e4
+}).trim();
+function classifyInstallOutput(editor, output) {
+  return /already installed/i.test(output) ? { editor, status: "already-installed" } : { editor, status: "installed" };
+}
+function installInto(editor, options = {}) {
+  const run2 = options.run ?? execRunner;
+  const target = options.vsix ?? EXTENSION_ID;
+  try {
+    const output = run2(editor.command, ["--install-extension", target, "--force"]);
+    return classifyInstallOutput(editor, output);
+  } catch (error) {
+    return { editor, status: "failed", error: failureReason(error) };
+  }
+}
+function failureReason(error) {
+  if (error instanceof Error) {
+    const stderr = error.stderr;
+    const text2 = typeof stderr === "string" ? stderr : Buffer.isBuffer(stderr) ? stderr.toString() : "";
+    const lines = text2.split("\n").map((l) => l.trim()).filter((l) => l.length > 0 && !/^\(node:/.test(l) && !/^\(Use /.test(l));
+    const meaningful = lines.find((l) => /(not found|error|fail|denied)/i.test(l)) ?? lines[0];
+    if (meaningful) return meaningful;
+    return error.message.replace(/^Command failed:.*/s, "the editor CLI returned an error").trim();
+  }
+  return String(error);
+}
+
+// src/commands/connect.ts
+async function connectCommand(flags = {}) {
+  log.blank();
+  log.info(`${accent("superlore connect")} ${dim("\u2014 set up your editor")}`);
+  log.blank();
+  const detected = detectEditors();
+  if (detected.length === 0) {
+    log.warn("No supported editor detected (looked for VS Code, Cursor, and Windsurf).");
+    log.blank();
+    log.info(`${dim("Install one, then re-run")} ${cyan("superlore connect")}${dim(".")}`);
+    log.info(
+      `${dim("If an editor is installed but its CLI isn't on PATH, open it and run")} ${cyan(`"Shell Command: Install '<editor>' command in PATH"`)}${dim(".")}`
+    );
+    printMcpNextStep();
+    process.exit(0);
+  }
+  const labels = detected.map((e) => bold(e.label)).join(", ");
+  log.step(`Found ${labels}. Installing the superlore Preview extension\u2026`);
+  log.blank();
+  let vsix;
+  try {
+    vsix = flags.vsix ?? await downloadVsix();
+  } catch (error) {
+    log.error(
+      `Couldn't fetch the extension: ${error instanceof Error ? error.message : String(error)}`
+    );
+    printManualInstall();
+    process.exit(flags.optional ? 0 : 1);
+  }
+  const results = detected.map((editor) => report(installInto(editor, { vsix })));
+  log.blank();
+  const failed = results.filter((r) => r.status === "failed");
+  if (failed.length > 0 && failed.length === results.length) {
+    log.error("Couldn't install the extension into any editor. See the errors above.");
+    printManualInstall();
+    process.exit(flags.optional ? 0 : 1);
+  }
+  log.success(
+    `superlore Preview is ready. Open a ${cyan(".mdx")} file and run ${cyan("superlore: Open Preview")} ${dim("(Cmd/Ctrl+K V)")}.`
+  );
+  printMcpNextStep();
+}
+function report(result) {
+  switch (result.status) {
+    case "installed":
+      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.")}`);
+      break;
+    case "failed":
+      log.error(`${bold(result.editor.label)} ${dim("\u2014 install failed:")} ${result.error}`);
+      break;
+  }
+  return result;
+}
+function printManualInstall() {
+  log.blank();
+  log.info(
+    `${dim("Install it by hand: download")} ${cyan("superlore.vercel.app/superlore-preview.vsix")}${dim(",")}`
+  );
+  log.info(
+    `${dim("then run")} ${cyan('"Extensions: Install from VSIX\u2026"')} ${dim("in your editor (or")} ${cyan("code --install-extension <file>.vsix")}${dim(").")}`
+  );
+}
+function printMcpNextStep() {
+  log.blank();
+  log.info(bold("Next: connect the MCP"));
+  log.info(
+    `  ${dim("Let your agent read the same corpus. Ask Claude")} ${cyan('"connect my superlore MCP"')}${dim(",")}`
+  );
+  log.info(
+    `  ${dim("or register it yourself:")} ${cyan("claude mcp add --transport http -s user superlore <url>/api/mcp")}`
+  );
+}
+
 // src/commands/deploy.ts
 import { spawn as spawn2 } from "child_process";
 
@@ -332,34 +524,34 @@ async function devCommand(flags) {
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync3 } from "fs";
+import { existsSync as existsSync4 } from "fs";
 import { basename, resolve as resolve3 } from "path";
 import { cancel, confirm, intro, isCancel, outro, select, text } from "@clack/prompts";
 
 // src/lib/scaffold.ts
-import { cpSync, existsSync as existsSync2, mkdirSync, readdirSync, writeFileSync } from "fs";
+import { cpSync, existsSync as existsSync3, mkdirSync, readdirSync, writeFileSync as writeFileSync2 } from "fs";
 import { fileURLToPath } from "url";
-import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
+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 = join2(dir, "templates", "starter");
-    if (existsSync2(candidate)) return candidate;
-    const bundled = join2(dir, "template");
-    if (existsSync2(bundled)) return bundled;
+    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 (!existsSync2(dir)) return false;
+  if (!existsSync3(dir)) return false;
   const entries = readdirSync(dir).filter((name) => name !== "README.md" && !name.startsWith("."));
   return entries.length > 0;
 }
 function isEmptyDir(dir) {
-  if (!existsSync2(dir)) return true;
+  if (!existsSync3(dir)) return true;
   return readdirSync(dir).filter((n) => !n.startsWith(".")).length === 0;
 }
 function scaffold(options) {
@@ -374,17 +566,18 @@ function scaffold(options) {
     writeSkeleton(root, options.config);
     source = "skeleton";
   }
-  writeFileSync(join2(root, "superlore.json"), serializeSuperloreJson(options.config), "utf8");
+  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 = join2(root, rel);
+    const file = join3(root, rel);
     mkdirSync(dirname2(file), { recursive: true });
-    writeFileSync(file, body, "utf8");
+    writeFileSync2(file, body, "utf8");
   };
   write(
     "package.json",
@@ -404,9 +597,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",
@@ -445,7 +643,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"],
@@ -465,8 +663,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);
@@ -510,7 +707,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 }) {
@@ -584,18 +781,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.
@@ -609,7 +810,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(
@@ -617,10 +822,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) }],
@@ -632,31 +841,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)),
     );
   },
   {},
@@ -677,6 +887,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}
@@ -698,7 +929,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"],
+    },
+  ]}
+/>
 `
   );
 }
@@ -727,8 +1368,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({
@@ -743,6 +1384,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"
         }
       ]
     });
@@ -750,6 +1396,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;
@@ -758,12 +1405,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) {
@@ -792,7 +1439,7 @@ ${result.issues.map((i) => `  - ${i.path} ${i.message}`).join("\n")}`
   const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
   const targetName = dir ?? (slug || "superlore-kb");
   const targetDir = resolve3(process.cwd(), targetName);
-  if (existsSync3(targetDir) && !isEmptyDir(targetDir)) {
+  if (existsSync4(targetDir) && !isEmptyDir(targetDir)) {
     if (interactive) {
       const proceed = await confirm({
         message: `${cyan(targetDir)} is not empty. Scaffold into it anyway?`,
@@ -805,13 +1452,45 @@ ${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);
+  await maybeConnectEditor(flags, interactive);
+}
+async function maybeConnectEditor(flags, interactive) {
+  if (flags.connect === false) return;
+  const editors = detectEditors();
+  if (editors.length === 0) {
+    log.blank();
+    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.`
+    );
+    return;
+  }
+  if (flags.connect !== true) {
+    const proceed = await confirm({
+      message: `Install the superlore Preview extension into ${names}?`,
+      initialValue: true
+    });
+    if (isCancel(proceed) || !proceed) {
+      log.info(`${dim("Skipped \u2014 run")} ${cyan("superlore connect")} ${dim("any time.")}`);
+      return;
+    }
+  }
+  await connectCommand({ optional: true });
 }
 function printNextSteps(root, config) {
   const rel = basename(root);
@@ -829,14 +1508,17 @@ function printNextSteps(root, config) {
 }
 
 // src/index.ts
-var VERSION = "0.1.2";
-function buildCli(argv = process2.argv) {
+var VERSION = "0.3.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").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("-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");
       const auth = authExplicit ? true : noAuthExplicit ? false : void 0;
+      const connectExplicit = argv.includes("--connect");
+      const noConnectExplicit = argv.includes("--no-connect");
+      const connect = connectExplicit ? true : noConnectExplicit ? false : void 0;
       await initCommand(dir, {
         name: flags.name,
         type: flags.type,
@@ -845,6 +1527,7 @@ function buildCli(argv = process2.argv) {
         accent: flags.accent,
         // `--no-mcp` flips this to false; default true is the intended behaviour.
         mcp: flags.mcp,
+        connect,
         yes: flags.yes
       });
     }
@@ -855,6 +1538,9 @@ function buildCli(argv = process2.argv) {
   cli.command("build", "Production build of the KB").action(async () => {
     await buildCommand();
   });
+  cli.command("connect", "Install the superlore editor extension (VS Code \xB7 Cursor \xB7 Windsurf)").option("--vsix <path>", "Install from a local .vsix instead of the Marketplace").example("superlore connect").action(async (flags) => {
+    await connectCommand({ vsix: flags.vsix });
+  });
   cli.command("deploy", "Managed deploy (superlore Cloud) \u2014 private beta, joins the waitlist").option("--open", "Open the waitlist URL in your browser").action(async (flags) => {
     await deployCommand({ open: flags.open });
   });
@@ -862,7 +1548,7 @@ function buildCli(argv = process2.argv) {
   cli.version(VERSION);
   return cli;
 }
-async function run(argv = process2.argv) {
+async function run(argv = process3.argv) {
   const cli = buildCli(argv);
   const tokens = argv.slice(2);
   const hasCommand = tokens.some((t) => !t.startsWith("-"));
@@ -878,10 +1564,10 @@ async function run(argv = process2.argv) {
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     log.error(message);
-    process2.exit(1);
+    process3.exit(1);
   }
 }
-var isEntrypoint = Boolean(process2.argv[1]) && fileURLToPath2(import.meta.url) === process2.argv[1];
+var isEntrypoint = Boolean(process3.argv[1]) && fileURLToPath2(import.meta.url) === process3.argv[1];
 if (isEntrypoint) {
   void run();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlore-cli",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "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",