camelmind 0.2.1 → 0.2.3

package/dist/index.js

@@ -2,9 +2,9 @@
 
 // src/index.ts
 import { Command } from "commander";
-import { fileURLToPath as fileURLToPath2 } from "url";
-import path2 from "path";
-import fs2 from "fs";
+import { fileURLToPath as fileURLToPath3 } from "url";
+import path3 from "path";
+import fs3 from "fs";
 
 // src/commands/init.ts
 import path from "path";
@@ -135,11 +135,229 @@ async function init(projectName, options) {
 `);
 }
 
-// src/index.ts
+// src/commands/update.ts
+import path2 from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { execSync as execSync2 } from "child_process";
+import fs2 from "fs-extra";
+import chalk2 from "chalk";
+import ora2 from "ora";
+import prompts2 from "prompts";
 var __dirname2 = path2.dirname(fileURLToPath2(import.meta.url));
-var pkgPath = path2.join(__dirname2, "../package.json");
-var pkg = JSON.parse(fs2.readFileSync(pkgPath, "utf-8"));
+var TEMPLATE_DIR2 = path2.join(__dirname2, "../template");
+var FRAMEWORK_DIRS = ["app", "components", "lib", "public", "scripts"];
+var FRAMEWORK_FILES = [
+  "next.config.ts",
+  "postcss.config.mjs",
+  "tsconfig.json",
+  "eslint.config.mjs",
+  "proxy.ts"
+];
+async function walkFiles(dir) {
+  if (!await fs2.pathExists(dir)) return [];
+  const entries = await fs2.readdir(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    if (entry.name === "node_modules" || entry.name === ".next" || entry.name === ".git") {
+      continue;
+    }
+    const fullPath = path2.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await walkFiles(fullPath));
+    } else if (entry.isFile()) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+function mergePackageJson(current, template) {
+  return {
+    ...current,
+    scripts: {
+      ...template.scripts,
+      ...current.scripts
+    },
+    dependencies: {
+      ...current.dependencies,
+      ...template.dependencies
+    },
+    devDependencies: {
+      ...current.devDependencies,
+      ...template.devDependencies
+    },
+    overrides: {
+      ...current.overrides,
+      ...template.overrides
+    }
+  };
+}
+async function copyWithBackup(source, target, backupRoot, projectRoot) {
+  if (await fs2.pathExists(target)) {
+    await backupFile(target, backupRoot, projectRoot);
+  }
+  await fs2.ensureDir(path2.dirname(target));
+  await fs2.copy(source, target, { overwrite: true });
+}
+async function backupFile(file, backupRoot, projectRoot) {
+  const rel = path2.relative(projectRoot, file);
+  await fs2.ensureDir(path2.dirname(path2.join(backupRoot, rel)));
+  await fs2.copy(file, path2.join(backupRoot, rel), { overwrite: true });
+}
+async function updatePackageJson(projectRoot, backupRoot, dryRun) {
+  const projectPkgPath = path2.join(projectRoot, "package.json");
+  const templatePkgPath = path2.join(TEMPLATE_DIR2, "_package.json");
+  const current = await fs2.readJson(projectPkgPath);
+  const template = await fs2.readJson(templatePkgPath);
+  const merged = mergePackageJson(current, template);
+  if (dryRun) return;
+  await backupFile(projectPkgPath, backupRoot, projectRoot);
+  await fs2.writeJson(projectPkgPath, merged, { spaces: 2 });
+  await fs2.appendFile(projectPkgPath, "\n");
+}
+async function plannedTemplateFiles() {
+  const files = [];
+  for (const dir of FRAMEWORK_DIRS) {
+    const dirPath = path2.join(TEMPLATE_DIR2, dir);
+    const dirFiles = await walkFiles(dirPath);
+    files.push(...dirFiles.map((file) => path2.relative(TEMPLATE_DIR2, file)));
+  }
+  files.push(...FRAMEWORK_FILES);
+  return files.sort();
+}
+async function update(targetDir, options) {
+  const projectRoot = path2.resolve(process.cwd(), targetDir ?? ".");
+  const packageJsonPath = path2.join(projectRoot, "package.json");
+  const configPath = path2.join(projectRoot, "camelmind.config.ts");
+  if (!await fs2.pathExists(TEMPLATE_DIR2)) {
+    console.error(chalk2.red("Template directory not found in the installed CamelMind package."));
+    process.exit(1);
+  }
+  if (!await fs2.pathExists(packageJsonPath) || !await fs2.pathExists(configPath)) {
+    console.error(chalk2.red("Run this command from a CamelMind project root, or pass the project directory."));
+    process.exit(1);
+  }
+  const files = await plannedTemplateFiles();
+  const backupRoot = path2.join(
+    projectRoot,
+    ".camelmind-update-backup",
+    (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")
+  );
+  console.log(`
+  ${chalk2.hex("#D8A15B").bold("CamelMind update")}
+
+  Project: ${chalk2.cyan(projectRoot)}
+  Files:   ${chalk2.cyan(String(files.length))} framework files + package.json
+  Backup:  ${chalk2.cyan(path2.relative(projectRoot, backupRoot))}
+`);
+  if (options.dryRun) {
+    console.log(chalk2.bold("  Dry run \u2014 files that would be refreshed:\n"));
+    for (const file of files) console.log(`    ${file}`);
+    console.log("    package.json");
+    console.log("");
+    return;
+  }
+  if (!options.yes) {
+    const { proceed } = await prompts2(
+      {
+        type: "confirm",
+        name: "proceed",
+        message: "Refresh CamelMind framework files and merge package updates?",
+        initial: true
+      },
+      { onCancel: () => process.exit(0) }
+    );
+    if (!proceed) {
+      console.log(chalk2.gray("\n  Update cancelled.\n"));
+      return;
+    }
+  }
+  const spinner = ora2("Refreshing CamelMind framework files...").start();
+  try {
+    for (const rel of files) {
+      await copyWithBackup(
+        path2.join(TEMPLATE_DIR2, rel),
+        path2.join(projectRoot, rel),
+        backupRoot,
+        projectRoot
+      );
+    }
+    await updatePackageJson(projectRoot, backupRoot, false);
+    spinner.succeed("CamelMind files refreshed");
+  } catch (err) {
+    spinner.fail("Update failed");
+    console.error(chalk2.red(`
+  ${String(err)}
+`));
+    process.exit(1);
+  }
+  if (options.install) {
+    const installSpinner = ora2("Installing updated dependencies...").start();
+    try {
+      execSync2("npm install", {
+        cwd: projectRoot,
+        stdio: "ignore"
+      });
+      installSpinner.succeed("Dependencies installed");
+    } catch {
+      installSpinner.warn("Dependency install failed \u2014 run npm install inside your project");
+    }
+  }
+  console.log(`
+  ${chalk2.green("Done.")} Review the changes, then run:
+
+    ${chalk2.cyan("npm run lint")}
+    ${chalk2.cyan("npm run build")}
+
+  Backup saved in ${chalk2.cyan(path2.relative(projectRoot, backupRoot))}
+`);
+}
+
+// src/commands/version.ts
+import chalk3 from "chalk";
+import ora3 from "ora";
+async function checkVersion(currentVersion) {
+  const spinner = ora3("Checking latest version...").start();
+  let latestVersion;
+  try {
+    const res = await fetch("https://registry.npmjs.org/camelmind/latest");
+    if (!res.ok) throw new Error(`Registry responded with ${res.status}`);
+    const data = await res.json();
+    latestVersion = data.version;
+    spinner.stop();
+  } catch {
+    spinner.fail("Could not reach the npm registry");
+    console.log(`
+  Installed: ${chalk3.cyan(currentVersion)}
+`);
+    return;
+  }
+  const [curMajor, curMinor, curPatch] = currentVersion.split(".").map(Number);
+  const [latMajor, latMinor, latPatch] = latestVersion.split(".").map(Number);
+  const isOutdated = latMajor > curMajor || latMajor === curMajor && latMinor > curMinor || latMajor === curMajor && latMinor === curMinor && latPatch > curPatch;
+  console.log(`
+  Installed  ${chalk3.cyan(currentVersion)}
+  Latest     ${isOutdated ? chalk3.yellow(latestVersion) : chalk3.green(latestVersion)}
+`);
+  if (isOutdated) {
+    console.log(
+      `  ${chalk3.yellow("\u26A0")}  A new version is available. To update an existing site, run:
+
+    ${chalk3.cyan("npx camelmind@latest update")}
+`
+    );
+  } else {
+    console.log(`  ${chalk3.green("\u2713")}  You're up to date.
+`);
+  }
+}
+
+// src/index.ts
+var __dirname3 = path3.dirname(fileURLToPath3(import.meta.url));
+var pkgPath = path3.join(__dirname3, "../package.json");
+var pkg = JSON.parse(fs3.readFileSync(pkgPath, "utf-8"));
 var program = new Command();
 program.name("camelmind").description("CamelMind CLI \u2014 scaffold and manage documentation sites").version(pkg.version);
 program.command("init [project-name]").description("Create a new CamelMind documentation site").option("--no-install", "Skip installing npm dependencies").action(init);
+program.command("version").description("Show installed version and check for updates").action(() => checkVersion(pkg.version));
+program.command("update [project-dir]").description("Update an existing CamelMind site to the latest platform files").option("--no-install", "Skip installing npm dependencies").option("--dry-run", "Show what would change without writing files").option("-y, --yes", "Skip the confirmation prompt").action(update);
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "camelmind",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Create and manage CamelMind documentation sites",
   "license": "MIT",
   "type": "module",

package/template/_package.json

@@ -25,6 +25,10 @@
     "rehype-slug": "^6.0.0",
     "remark-gfm": "^4.0.1"
   },
+  "overrides": {
+    "js-yaml": "^4.2.0",
+    "postcss": "^8.5.10"
+  },
   "devDependencies": {
     "@tailwindcss/postcss": "^4",
     "@types/js-yaml": "^4.0.9",

package/template/app/[...slug]/page.tsx

@@ -71,7 +71,7 @@ export default async function DocPage({ params }: Props) {
   const currentVersion = versions.find((v) => v.id === versionId)
   const versionShowsApiRef = currentVersion ? (currentVersion.api_reference !== false) : true
   const apiRef = apiRefConfig?.enabled && versionShowsApiRef
-    ? { label: apiRefConfig.navLabel ?? "API Reference", href: "/api-reference", roles: apiRefConfig.roles ?? [] }
+    ? { label: apiRefConfig.navLabel ?? "API Reference", href: versionId ? `/api-reference/${versionId}` : "/api-reference", roles: apiRefConfig.roles ?? [] }
     : null
 
   if (shouldRedirectToLogin(navEntry.roles, session)) {

package/template/app/api/llms/[...slug]/route.ts

@@ -0,0 +1,34 @@
+import { NextRequest, NextResponse } from "next/server"
+import { loadNav, getEntryBySlugFromConfig } from "@/lib/nav"
+import { loadMdxFile, processForLLM } from "@/lib/mdx"
+import { getConfig } from "@/lib/config"
+
+export async function GET(
+  _req: NextRequest,
+  { params }: { params: Promise<{ slug: string[] }> }
+) {
+  const { slug: slugParts } = await params
+  const slug = "/" + slugParts.join("/")
+
+  const nav = loadNav()
+  const entry = getEntryBySlugFromConfig(nav, slug)
+
+  if (!entry) return new NextResponse("Not Found", { status: 404 })
+
+  if (entry.roles.length > 0) {
+    return new NextResponse("Unauthorized", { status: 401 })
+  }
+
+  const { source: rawSource } = loadMdxFile(entry.file)
+  const source = processForLLM(rawSource)
+  const config = getConfig()
+  const baseUrl = config.url.replace(/\/$/, "")
+
+  const directive =
+    config.llms?.directive ??
+    `For a complete documentation index, see ${baseUrl}/llms.txt. To read any public page as Markdown, append .md to the URL.`
+
+  return new NextResponse(`> ${directive}\n\n${source}`, {
+    headers: { "Content-Type": "text/plain; charset=utf-8" },
+  })
+}

package/template/app/api/raw/route.ts

@@ -1,8 +1,33 @@
 import { NextRequest, NextResponse } from "next/server"
 import fs from "fs"
 import path from "path"
-import { getSession } from "@/lib/auth"
+import { getSession, hasAccess } from "@/lib/auth"
 import { isAuthEnabled } from "@/lib/config"
+import { loadNav, flattenChildren } from "@/lib/nav"
+import { loadVersions, getNavForVersion } from "@/lib/versions"
+import type { NavConfig, NavEntry, NavChild } from "@/lib/nav-types"
+
+function getAllNavEntries(nav: NavConfig): (NavEntry | NavChild)[] {
+  const entries: (NavEntry | NavChild)[] = []
+  for (const item of nav.nav) {
+    if ("dropdown" in item) {
+      for (const entry of (item.items ?? [])) {
+        entries.push(entry)
+        if (entry.section) entries.push(...flattenChildren(entry.section))
+      }
+    } else if ("file" in item) {
+      entries.push(item as NavEntry)
+    }
+  }
+  return entries
+}
+
+function getNavEntriesForFile(file: string): (NavEntry | NavChild)[] {
+  const normalized = path.normalize(file)
+  const configs: NavConfig[] = [loadNav()]
+  for (const v of loadVersions().versions) configs.push(getNavForVersion(v.id))
+  return configs.flatMap(getAllNavEntries).filter((e) => path.normalize(e.file) === normalized)
+}
 
 export async function GET(req: NextRequest) {
   const session = await getSession()
@@ -24,6 +49,14 @@ export async function GET(req: NextRequest) {
     return new NextResponse("Forbidden", { status: 403 })
   }
 
+  // RBAC: file must appear in the nav and the user must satisfy at least one entry's roles
+  if (isAuthEnabled()) {
+    const navEntries = getNavEntriesForFile(file)
+    if (navEntries.length === 0 || !navEntries.some((e) => hasAccess(e.roles, session!.roles))) {
+      return new NextResponse("Forbidden", { status: 403 })
+    }
+  }
+
   if (!fs.existsSync(resolved)) {
     return new NextResponse("Not found", { status: 404 })
   }

package/template/app/api-reference/[[...slug]]/page.tsx

@@ -2,7 +2,8 @@ import { notFound, redirect } from "next/navigation"
 import { getConfig, isAuthEnabled } from "@/lib/config"
 import { loadApiSpec } from "@/lib/api-reference"
 import { getSession, hasAccess } from "@/lib/auth"
-import { loadVersions, getNavForVersion, getApiSpecForVersion } from "@/lib/versions"
+import { loadVersions, getNavForVersion, getApiReferenceForVersion } from "@/lib/versions"
+import type { ResolvedTab } from "@/lib/versions"
 import { getSlugsFromConfig } from "@/lib/nav"
 import { TopNav } from "@/components/Nav/TopNav"
 import { ApiSidebar } from "@/components/ApiReference/ApiSidebar"
@@ -13,9 +14,6 @@ type Props = {
   params: Promise<{ slug?: string[] }>
 }
 
-// Detect if the first slug segment is a known version ID.
-// /api-reference/v2.0/applications/create → versionId="v2.0", rest=["applications","create"]
-// /api-reference/applications/create      → versionId=null,   rest=["applications","create"]
 function parseVersionFromSlug(
   slug: string[] | undefined,
   versionIds: string[]
@@ -36,24 +34,37 @@ export async function generateStaticParams() {
   const params: Array<{ slug: string[] | undefined }> = [{ slug: undefined }]
 
   for (const version of versions) {
-    const resolved = getApiSpecForVersion(version.id, apiRef.spec, apiRef.languages)
+    const resolved = getApiReferenceForVersion(version.id, apiRef)
     if (!resolved) continue
 
-    let spec
-    try { spec = loadApiSpec(resolved.spec, resolved.languages) } catch { continue }
-
     params.push({ slug: [version.id] })
 
-    for (const op of spec.allOperations) {
-      params.push({ slug: [version.id, op.tagSlug, op.operationId] })
+    if (resolved.mode === "single") {
+      let spec
+      try { spec = loadApiSpec(resolved.file, resolved.languages) } catch { continue }
+      for (const op of spec.allOperations) {
+        params.push({ slug: [version.id, op.tagSlug, op.operationId] })
+      }
+    } else {
+      for (const tab of resolved.tabs) {
+        params.push({ slug: [version.id, tab.id] })
+        let spec
+        try { spec = loadApiSpec(tab.file, tab.languages) } catch { continue }
+        for (const op of spec.allOperations) {
+          params.push({ slug: [version.id, tab.id, op.tagSlug, op.operationId] })
+        }
+      }
     }
   }
 
-  // Also enumerate no-version-prefix routes using the default spec
-  let defaultSpec
-  try { defaultSpec = loadApiSpec(apiRef.spec, apiRef.languages) } catch { return params }
-  for (const op of defaultSpec.allOperations) {
-    params.push({ slug: [op.tagSlug, op.operationId] })
+  // No-version-prefix routes using the default (first) spec
+  const defaultResolved = getApiReferenceForVersion(null, apiRef)
+  if (defaultResolved?.mode === "single") {
+    let defaultSpec
+    try { defaultSpec = loadApiSpec(defaultResolved.file, defaultResolved.languages) } catch { return params }
+    for (const op of defaultSpec.allOperations) {
+      params.push({ slug: [op.tagSlug, op.operationId] })
+    }
   }
 
   return params
@@ -68,14 +79,37 @@ export default async function ApiReferencePage({ params }: Props) {
   const { versions } = loadVersions()
   const versionIds = versions.map((v) => v.id)
 
-  const { versionId, rest: slug } = parseVersionFromSlug(rawSlug, versionIds)
-  const base = versionId ? `/api-reference/${versionId}` : "/api-reference"
+  const { versionId, rest: afterVersion } = parseVersionFromSlug(rawSlug, versionIds)
 
-  const resolved = getApiSpecForVersion(versionId, apiRef.spec, apiRef.languages)
+  const resolved = getApiReferenceForVersion(versionId, apiRef)
   if (!resolved) return notFound()
 
+  // Resolve active tab and remaining slug segments
+  let activeTab: ResolvedTab | null = null
+  let slug: string[]
+
+  if (resolved.mode === "tabs") {
+    const tabIds = resolved.tabs.map((t) => t.id)
+    if (afterVersion.length && tabIds.includes(afterVersion[0])) {
+      activeTab = resolved.tabs.find((t) => t.id === afterVersion[0])!
+      slug = afterVersion.slice(1)
+    } else {
+      const versionBase = versionId ? `/api-reference/${versionId}` : "/api-reference"
+      redirect(`${versionBase}/${resolved.tabs[0].id}`)
+    }
+  } else {
+    slug = afterVersion
+  }
+
+  // Load spec for current tab or single spec
+  const specFile = resolved.mode === "tabs" ? activeTab!.file : resolved.file
+  const specLanguages = resolved.mode === "tabs" ? activeTab!.languages : resolved.languages
   let spec
-  try { spec = loadApiSpec(resolved.spec, resolved.languages) } catch { return notFound() }
+  try { spec = loadApiSpec(specFile, specLanguages) } catch { return notFound() }
+
+  // Base URL: /api-reference[/versionId][/tabId]
+  const versionBase = versionId ? `/api-reference/${versionId}` : "/api-reference"
+  const base = resolved.mode === "tabs" ? `${versionBase}/${activeTab!.id}` : versionBase
 
   const session = await getSession()
   const authEnabled = isAuthEnabled()
@@ -105,6 +139,13 @@ export default async function ApiReferencePage({ params }: Props) {
   const apiRefProp = { label: apiRef.navLabel ?? "API Reference", href: "/api-reference", roles }
   const currentSlug = slug.length ? `${base}/${slug.join("/")}` : base
 
+  // Tab switcher props for sidebar
+  const sidebarTabs = resolved.mode === "tabs"
+    ? resolved.tabs.map((t) => ({ id: t.id, label: t.label, href: `${versionBase}/${t.id}` }))
+    : undefined
+  const activeTabId = activeTab?.id
+
+  // Overview page
   if (!slug.length) {
     return (
       <div className="flex flex-col h-screen">
@@ -115,12 +156,12 @@ export default async function ApiReferencePage({ params }: Props) {
           authEnabled={authEnabled}
           versions={versions}
           currentVersionId={versionId}
-          currentSlug={base}
+          currentSlug={versionBase}
           versionSlugs={versionSlugs}
           apiRef={apiRefProp}
         />
         <div className="flex flex-1 overflow-hidden">
-          <ApiSidebar spec={spec} currentSlug={base} base={base} />
+          <ApiSidebar spec={spec} currentSlug={base} base={base} tabs={sidebarTabs} activeTabId={activeTabId} />
           <main className="flex-1 overflow-y-auto bg-white dark:bg-gray-950">
             <ApiOverview spec={spec} base={base} />
           </main>
@@ -129,12 +170,14 @@ export default async function ApiReferencePage({ params }: Props) {
     )
   }
 
+  // Tag-only slug → redirect to first endpoint
   if (slug.length === 1) {
     const tag = spec.tags.find((t) => t.slug === slug[0])
     if (!tag || !tag.operations.length) return notFound()
     redirect(`${base}/${tag.slug}/${tag.operations[0].operationId}`)
   }
 
+  // Endpoint page
   const [tagSlug, operationId] = slug
   const op = spec.allOperations.find(
     (o) => o.tagSlug === tagSlug && o.operationId === operationId
@@ -155,7 +198,7 @@ export default async function ApiReferencePage({ params }: Props) {
         apiRef={apiRefProp}
       />
       <div className="flex flex-1 overflow-hidden">
-        <ApiSidebar spec={spec} currentSlug={currentSlug} base={base} />
+        <ApiSidebar spec={spec} currentSlug={currentSlug} base={base} tabs={sidebarTabs} activeTabId={activeTabId} />
         <main className="flex-1 overflow-hidden bg-white dark:bg-gray-950 flex">
           <EndpointPage operation={op} spec={spec} />
         </main>

package/template/app/globals.css

@@ -90,13 +90,12 @@
   font-weight: 700;
   font-size: 0.85rem;
   padding: 0.4rem 0.75rem;
-  text-transform: uppercase;
   letter-spacing: 0.04em;
   color: #1f1f1f;
 }
 
 .callout-body {
-  padding: 0.75rem;
+  padding: 0.5rem 0.75rem 0.75rem;
   font-size: 0.95rem;
   color: #333;
 }

package/template/app/llms.txt/route.ts

@@ -0,0 +1,36 @@
+import { loadNav, getAllPublicEntries } from "@/lib/nav"
+import { loadFrontmatterOnly } from "@/lib/mdx"
+import { getConfig } from "@/lib/config"
+
+export const revalidate = 3600
+
+export async function GET() {
+  const config = getConfig()
+
+  if (!config.llms?.enabled) {
+    return new Response("Not Found", { status: 404 })
+  }
+
+  const nav = loadNav()
+  const entries = getAllPublicEntries(nav)
+  const baseUrl = config.url.replace(/\/$/, "")
+
+  const lines = entries.map((entry) => {
+    const frontmatter = loadFrontmatterOnly(entry.file)
+    const desc = frontmatter.description ?? frontmatter.title
+    return `- [${frontmatter.title}](${baseUrl}${entry.slug}): ${desc}`
+  })
+
+  const body = [
+    `# ${config.title}`,
+    "",
+    ...(config.tagline ? [`> ${config.tagline}`, ""] : []),
+    "## Docs",
+    "",
+    ...lines,
+  ].join("\n")
+
+  return new Response(body, {
+    headers: { "Content-Type": "text/plain; charset=utf-8" },
+  })
+}

package/template/components/ApiReference/ApiSidebar.tsx

@@ -1,19 +1,84 @@
 "use client"
 
+import { useState, useRef, useEffect } from "react"
 import Link from "next/link"
+import { ChevronDown } from "lucide-react"
 import type { ParsedSpec } from "@/lib/api-types"
 import { MethodBadge } from "./MethodBadge"
 
+type SidebarTab = {
+  id: string
+  label: string
+  href: string
+}
+
 type Props = {
   spec: ParsedSpec
   currentSlug: string
   base?: string
+  tabs?: SidebarTab[]
+  activeTabId?: string
 }
 
-export function ApiSidebar({ spec, currentSlug, base = "/api-reference" }: Props) {
+export function ApiSidebar({ spec, currentSlug, base = "/api-reference", tabs, activeTabId }: Props) {
+  const [dropdownOpen, setDropdownOpen] = useState(false)
+  const dropdownRef = useRef<HTMLDivElement>(null)
+  const activeTab = tabs?.find((t) => t.id === activeTabId)
+
+  useEffect(() => {
+    function handleClickOutside(e: MouseEvent) {
+      if (dropdownRef.current && !dropdownRef.current.contains(e.target as Node)) {
+        setDropdownOpen(false)
+      }
+    }
+    if (dropdownOpen) document.addEventListener("mousedown", handleClickOutside)
+    return () => document.removeEventListener("mousedown", handleClickOutside)
+  }, [dropdownOpen])
+
   return (
     <aside className="hidden md:block w-64 shrink-0 border-r border-gray-200 dark:border-gray-800 overflow-y-auto bg-white dark:bg-gray-950">
       <div className="px-4 py-4">
+
+        {/* Spec dropdown */}
+        {tabs && tabs.length > 1 && (
+          <div ref={dropdownRef} className="relative mb-4">
+            <button
+              onClick={() => setDropdownOpen((o) => !o)}
+              className="w-full flex items-center justify-between px-3 py-2 text-xs font-medium rounded border border-gray-200 dark:border-gray-700 bg-white dark:bg-gray-900 text-gray-700 dark:text-gray-300 hover:bg-gray-50 dark:hover:bg-gray-800 transition-colors"
+            >
+              <span style={{ color: "var(--sf-active)" }}>{activeTab?.label ?? "Select API"}</span>
+              <ChevronDown
+                size={12}
+                className={`ml-2 shrink-0 text-gray-400 transition-transform ${dropdownOpen ? "rotate-180" : ""}`}
+              />
+            </button>
+
+            {dropdownOpen && (
+              <div className="absolute top-full left-0 right-0 mt-1 rounded border border-gray-200 dark:border-gray-700 bg-white dark:bg-gray-900 shadow-lg z-10 py-1">
+                {tabs.map((tab) => {
+                  const isActive = tab.id === activeTabId
+                  return (
+                    <Link
+                      key={tab.id}
+                      href={tab.href}
+                      onClick={() => setDropdownOpen(false)}
+                      style={isActive ? { color: "var(--sf-active)" } : {}}
+                      className={`flex items-center justify-between px-3 py-2 text-xs transition-colors ${
+                        isActive
+                          ? "font-medium bg-black/5 dark:bg-white/10"
+                          : "text-gray-600 dark:text-gray-400 hover:bg-gray-50 dark:hover:bg-gray-800"
+                      }`}
+                    >
+                      <span>{tab.label}</span>
+                      {isActive && <span className="text-gray-400">✓</span>}
+                    </Link>
+                  )
+                })}
+              </div>
+            )}
+          </div>
+        )}
+
         {/* Overview link */}
         <div className="mb-4">
           <Link
@@ -32,17 +97,13 @@ export function ApiSidebar({ spec, currentSlug, base = "/api-reference" }: Props
         {/* Tags */}
         {spec.tags.map((tag) => (
           <div key={tag.slug} className="mb-4">
-            {/* Tag header — ALL CAPS */}
             <p className="px-2 pb-1 text-xs font-semibold uppercase tracking-widest text-gray-400 dark:text-gray-500 select-none">
               {tag.name}
             </p>
-
-            {/* Operations */}
             <ul className="space-y-0.5">
               {tag.operations.map((op) => {
                 const href = `${base}/${tag.slug}/${op.operationId}`
                 const isActive = currentSlug === href
-
                 return (
                   <li key={op.operationId}>
                     <Link