camelmind 0.2.0 → 0.2.2

package/dist/index.js

@@ -135,6 +135,45 @@ async function init(projectName, options) {
 `);
 }
 
+// src/commands/version.ts
+import chalk2 from "chalk";
+import ora2 from "ora";
+async function checkVersion(currentVersion) {
+  const spinner = ora2("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: ${chalk2.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  ${chalk2.cyan(currentVersion)}
+  Latest     ${isOutdated ? chalk2.yellow(latestVersion) : chalk2.green(latestVersion)}
+`);
+  if (isOutdated) {
+    console.log(
+      `  ${chalk2.yellow("\u26A0")}  A new version is available. Run:
+
+    ${chalk2.cyan("npm install -g camelmind@latest")}
+`
+    );
+  } else {
+    console.log(`  ${chalk2.green("\u2713")}  You're up to date.
+`);
+  }
+}
+
 // src/index.ts
 var __dirname2 = path2.dirname(fileURLToPath2(import.meta.url));
 var pkgPath = path2.join(__dirname2, "../package.json");
@@ -142,4 +181,5 @@ var pkg = JSON.parse(fs2.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.parse();

package/package.json

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

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

package/template/components/Nav/TopNav.tsx

@@ -132,7 +132,7 @@ export function TopNav({ nav, userRoles, userName, authEnabled = false, versions
               currentVersionId={currentVersionId}
               currentSlug={currentSlug}
               versionSlugs={versionSlugs}
-              isLoggedIn={!!userName}
+              isLoggedIn={!!userName || !authEnabled}
             />
             {authEnabled && (
               userName ? (

package/template/components/Nav/VersionSelector.tsx

@@ -21,6 +21,14 @@ export function VersionSelector({ versions, currentVersionId, currentSlug, versi
 
   function navigateToVersion(targetId: string) {
     setOpen(false)
+
+    // API reference pages use a different URL scheme (/api-reference/[version]/...)
+    // so navigate directly to the target version's API reference overview
+    if (currentSlug.startsWith("/api-reference")) {
+      router.push(`/api-reference/${targetId}`)
+      return
+    }
+
     const bare = currentVersionId
       ? currentSlug.replace(new RegExp(`^/${currentVersionId}`), "") || "/"
       : currentSlug

package/template/components/mdx/Callout.tsx

@@ -23,10 +23,12 @@ const defaultIcons: Record<CalloutType, string> = {
 export function Callout({
   type = "note",
   icon,
+  title,
   children,
 }: {
   type?: CalloutType
   icon?: string
+  title?: string
   children: React.ReactNode
 }) {
   const iconName = icon ?? defaultIcons[type]
@@ -35,7 +37,7 @@ export function Callout({
     <div className={`callout ${type} my-4`}>
       <div className="callout-header flex items-center gap-1.5">
         <Icon name={iconName} size={13} />
-        {labels[type]}
+        {title ?? labels[type]}
       </div>
       <div className="callout-body">{children}</div>
     </div>

package/template/components/mdx/LLMIgnore.tsx

@@ -0,0 +1,4 @@
+// Renders normally for humans — stripped from .md responses served to LLMs.
+export function LLMIgnore({ children }: { children?: React.ReactNode }) {
+  return <>{children}</>
+}

package/template/components/mdx/LLMOnly.tsx

@@ -0,0 +1,4 @@
+// Hidden from the rendered page — visible only in .md responses served to LLMs.
+export function LLMOnly({ children }: { children?: React.ReactNode }) {
+  return null
+}

package/template/components/mdx/index.tsx

@@ -3,6 +3,8 @@ import { Steps, Step } from "./Steps"
 import { Tabs, Tab } from "./Tabs"
 import { Icon } from "./Icon"
 import { Details } from "./Details"
+import { LLMOnly } from "./LLMOnly"
+import { LLMIgnore } from "./LLMIgnore"
 import { CodeBlock } from "@/components/Code/CodeBlock"
 
 export const mdxComponents = {
@@ -13,6 +15,8 @@ export const mdxComponents = {
   Tab,
   Icon,
   Details,
+  LLMOnly,
+  LLMIgnore,
   pre: ({ children }: { children: React.ReactNode }) => {
     // If the child code block has a language class, let CodeBlock handle it
     const child = children as React.ReactElement<{ className?: string }>

package/template/lib/api-reference.ts

@@ -15,22 +15,21 @@ import type {
   HttpMethod,
 } from "./api-types"
 
-let _cache: ParsedSpec | null = null
-let _cachedLanguages: string | null = null
+const _specCache = new Map<string, ParsedSpec>()
 
 export function loadApiSpec(specPath: string, languages?: string[]): ParsedSpec {
-  const langKey = JSON.stringify(languages ?? null)
-  if (_cache && _cachedLanguages === langKey) return _cache
+  const cacheKey = `${specPath}|${JSON.stringify(languages ?? null)}`
+  const cached = _specCache.get(cacheKey)
+  if (cached) return cached
   const raw = fs.readFileSync(path.join(process.cwd(), specPath), "utf-8")
   const doc = yaml.load(raw) as Record<string, unknown>
-  _cache = parseOpenApi(doc, languages)
-  _cachedLanguages = langKey
-  return _cache
+  const parsed = parseOpenApi(doc, languages)
+  _specCache.set(cacheKey, parsed)
+  return parsed
 }
 
 export function clearApiCache() {
-  _cache = null
-  _cachedLanguages = null
+  _specCache.clear()
 }
 
 function slugify(str: string): string {

package/template/lib/config-types.ts

@@ -22,14 +22,24 @@ export type SiteFeatures = {
   showFeedbackWidget?: boolean
 }
 
+export type ApiSpecEntry = {
+  label: string
+  file: string
+}
+
 export type ApiReferenceConfig = {
   enabled: boolean
-  spec: string
+  specs: Record<string, ApiSpecEntry>
   navLabel?: string
   languages?: string[]
   roles?: string[]
 }
 
+export type LlmsConfig = {
+  enabled?: boolean
+  directive?: string
+}
+
 export type CamelMindConfig = {
   title: string
   tagline: string
@@ -43,4 +53,5 @@ export type CamelMindConfig = {
   }
   site?: SiteFeatures
   apiReference?: ApiReferenceConfig
+  llms?: LlmsConfig
 }

package/template/lib/config.ts

@@ -1,7 +1,7 @@
 import siteConfig from "@/camelmind.config"
 import type { AuthConfig, CamelMindConfig } from "./config-types"
 
-export type { AuthConfig, AuthProvider, CamelMindConfig, OidcConfig } from "./config-types"
+export type { AuthConfig, AuthProvider, CamelMindConfig, LlmsConfig, OidcConfig } from "./config-types"
 
 let _config: CamelMindConfig | null = null
 

package/template/lib/mdx.ts

@@ -44,6 +44,19 @@ function extractToc(source: string): TocEntry[] {
   return entries
 }
 
+export function processForLLM(source: string): string {
+  let result = source.replace(/<LLMIgnore>[\s\S]*?<\/LLMIgnore>/g, "")
+  result = result.replace(/<LLMOnly>([\s\S]*?)<\/LLMOnly>/g, "$1")
+  return result.replace(/\n{3,}/g, "\n\n").trim()
+}
+
+export function loadFrontmatterOnly(filePath: string): FrontMatter {
+  const fullPath = path.join(process.cwd(), filePath)
+  const raw = fs.readFileSync(fullPath, "utf-8")
+  const { data } = matter(raw)
+  return data as FrontMatter
+}
+
 export function loadMdxFile(filePath: string): DocContent {
   const fullPath = path.join(process.cwd(), filePath)
   const raw = fs.readFileSync(fullPath, "utf-8")

package/template/lib/nav.ts

@@ -8,11 +8,59 @@ export { isNavGroup } from "./nav-types"
 
 let _navCache: NavConfig | null = null
 
+function stripPrefix(slug: string, prefix: string): string {
+  if (slug.startsWith(prefix + "/")) return slug.slice(prefix.length)
+  if (slug === prefix) return "/"
+  return slug
+}
+
+function stripNavPrefix(nav: NavConfig, prefix: string): NavConfig {
+  const s = (slug: string) => stripPrefix(slug, prefix)
+
+  const walkChildren = (children: NavChild[]): NavChild[] =>
+    children.map((c) => ({
+      ...c,
+      slug: s(c.slug),
+      children: c.children ? walkChildren(c.children) : undefined,
+    }))
+
+  const walkEntries = (entries: NavEntry[]): NavEntry[] =>
+    entries.map((e) => ({
+      ...e,
+      slug: s(e.slug),
+      section: e.section ? walkChildren(e.section) : undefined,
+    }))
+
+  return {
+    nav: nav.nav.map((item) => {
+      if ("dropdown" in item) {
+        const group = item as NavGroup
+        return {
+          ...group,
+          ...(group.slug ? { slug: s(group.slug) } : {}),
+          items: group.items ? walkEntries(group.items) : undefined,
+        }
+      }
+      const entry = item as NavEntry
+      return { ...entry, slug: s(entry.slug) }
+    }),
+  } as NavConfig
+}
+
 export function loadNav(): NavConfig {
   if (process.env.NODE_ENV !== "development" && _navCache) return _navCache
-  const navPath = path.join(process.cwd(), "nav", "nav.yml")
-  const raw = fs.readFileSync(navPath, "utf-8")
-  _navCache = yaml.load(raw) as NavConfig
+
+  // Derive the unversioned nav from the first stable version in versions.yml,
+  // stripping the version prefix from all slugs so /v2/foo becomes /foo.
+  const versionsPath = path.join(process.cwd(), "versions.yml")
+  const { versions } = yaml.load(fs.readFileSync(versionsPath, "utf-8")) as {
+    versions: { id: string; stable: boolean; nav: string }[]
+  }
+  const latest = versions.find((v) => v.stable) ?? versions[0]
+  const navPath = path.join(process.cwd(), latest.nav)
+  const nav = yaml.load(fs.readFileSync(navPath, "utf-8")) as NavConfig
+
+  _navCache = stripNavPrefix(nav, `/${latest.id}`)
   return _navCache
 }
 
@@ -123,3 +171,24 @@ export function getSectionForSlugFromConfig(nav: NavConfig, slug: string): NavEn
 export function getSectionForSlug(slug: string): NavEntry | null {
   return getSectionForSlugFromConfig(loadNav(), slug)
 }
+
+export function getAllPublicEntries(nav: NavConfig): (NavEntry | NavChild)[] {
+  const entries: (NavEntry | NavChild)[] = []
+  for (const item of nav.nav) {
+    if ("dropdown" in item) {
+      const group = item as NavGroup
+      for (const entry of (group.items ?? [])) {
+        if (entry.roles.length === 0) entries.push(entry)
+        if (entry.section) {
+          for (const child of flattenChildren(entry.section)) {
+            if (child.roles.length === 0) entries.push(child)
+          }
+        }
+      }
+    } else if ("slug" in item) {
+      const entry = item as NavEntry
+      if (entry.roles.length === 0) entries.push(entry)
+    }
+  }
+  return entries
+}

package/template/lib/versions.ts

@@ -3,20 +3,24 @@ import path from "path"
 import yaml from "js-yaml"
 import { loadNav } from "./nav"
 import type { NavConfig } from "./nav-types"
+import type { ApiReferenceConfig } from "./config-types"
 
-export type VersionApiReference = {
-  spec: string
-  nav_label?: string
-  languages?: string[]
+export type VersionApiReferenceTab = {
+  id: string
+  spec: string  // key into camelmind.config.ts apiReference.specs
 }
 
+export type VersionApiReference =
+  | { spec: string }                       // single named spec
+  | { tabs: VersionApiReferenceTab[] }     // multi-spec tabs
+
 export type Version = {
   id: string
   label: string
   stable: boolean
   badge?: string
   nav: string
-  // true/omitted = use site-level spec, false = hide, object = version-specific spec
+  // false = disabled, omitted/true = use first spec in registry, object = explicit config
   api_reference?: boolean | VersionApiReference
 }
 
@@ -24,6 +28,18 @@ export type VersionsConfig = {
   versions: Version[]
 }
 
+// Resolved output types
+export type ResolvedTab = {
+  id: string
+  label: string
+  file: string
+  languages?: string[]
+}
+
+export type ResolvedApiReference =
+  | { mode: "single"; label: string; file: string; languages?: string[] }
+  | { mode: "tabs"; tabs: ResolvedTab[] }
+
 let _versionsCache: VersionsConfig | null = null
 
 export function loadVersions(): VersionsConfig {
@@ -33,12 +49,52 @@ export function loadVersions(): VersionsConfig {
   return _versionsCache
 }
 
+// Resolve which spec(s) to show for a given version.
+// Resolution: versions.yml api_reference → apiReference.specs registry → first spec in registry
+// Returns null if api_reference is explicitly disabled for this version.
+export function getApiReferenceForVersion(
+  versionId: string | null,
+  config: ApiReferenceConfig
+): ResolvedApiReference | null {
+  const { versions } = loadVersions()
+
+  let versionAr: boolean | VersionApiReference | undefined
+  if (versionId) {
+    const v = versions.find((v) => v.id === versionId)
+    versionAr = v?.api_reference
+  }
+
+  if (versionAr === false) return null
+
+  // Default: use first spec in registry
+  if (!versionAr || versionAr === true) {
+    const firstEntry = Object.entries(config.specs)[0]
+    if (!firstEntry) return null
+    const [, entry] = firstEntry
+    return { mode: "single", label: entry.label, file: entry.file, languages: config.languages }
+  }
+
+  // Tabs mode
+  if ("tabs" in versionAr) {
+    const tabs: ResolvedTab[] = versionAr.tabs.flatMap((tab) => {
+      const entry = config.specs[tab.spec]
+      if (!entry) return []
+      return [{ id: tab.id, label: entry.label, file: entry.file, languages: config.languages }]
+    })
+    return tabs.length ? { mode: "tabs", tabs } : null
+  }
+
+  // Single named spec
+  const entry = config.specs[versionAr.spec]
+  if (!entry) return null
+  return { mode: "single", label: entry.label, file: entry.file, languages: config.languages }
+}
+
 export function getVersionFromSlug(slug: string): string | null {
   const { versions } = loadVersions()
   for (const v of versions) {
     if (slug.startsWith(`/${v.id}/`) || slug === `/${v.id}`) return v.id
   }
-  // no version prefix = default (latest)
   return null
 }
 
@@ -57,30 +113,10 @@ export function getLatestVersion(): Version {
   return versions[0]
 }
 
-// Resolve which OpenAPI spec to use for a given version, with site-level fallback.
-// Returns null if api_reference is explicitly disabled for this version.
-export function getApiSpecForVersion(
-  versionId: string | null,
-  siteSpec: string,
-  siteLanguages?: string[]
-): { spec: string; languages?: string[] } | null {
-  if (!versionId) return { spec: siteSpec, languages: siteLanguages }
-  const { versions } = loadVersions()
-  const v = versions.find((v) => v.id === versionId)
-  if (!v) return { spec: siteSpec, languages: siteLanguages }
-
-  const ar = v.api_reference
-  if (ar === false) return null
-  if (!ar || ar === true) return { spec: siteSpec, languages: siteLanguages }
-  return { spec: ar.spec, languages: ar.languages ?? siteLanguages }
-}
-
-// Given a slug like /v1.9/getting-started/overview, return /getting-started/overview
 export function stripVersionPrefix(slug: string, versionId: string): string {
   return slug.replace(new RegExp(`^/${versionId}`), "") || "/"
 }
 
-// Given /getting-started/overview and a target version, return /v1.9/getting-started/overview
 export function swapVersion(slug: string, currentVersionId: string | null, targetVersionId: string): string {
   const bare = currentVersionId ? stripVersionPrefix(slug, currentVersionId) : slug
   return `/${targetVersionId}${bare}`

package/template/proxy.ts

@@ -6,6 +6,14 @@ import { isAuthEnabled, isPrivateSite, isPublicPath } from "@/lib/config"
 export async function proxy(req: NextRequest) {
   const { pathname } = req.nextUrl
 
+  // Rewrite /<slug>.md to /api/llms/<slug> before auth runs.
+  // /api/llms is in publicPaths so the handler is always reachable.
+  if (pathname.endsWith(".md") && !pathname.startsWith("/api/")) {
+    const url = req.nextUrl.clone()
+    url.pathname = `/api/llms${pathname.slice(0, -3)}`
+    return NextResponse.rewrite(url)
+  }
+
   // Auth disabled — all traffic passes through
   if (!isAuthEnabled()) {
     return NextResponse.next()
@@ -46,5 +54,6 @@ export async function proxy(req: NextRequest) {
 }
 
 export const config = {
-  matcher: ["/((?!_next/static|_next/image|favicon.ico|public/).*)"],
+  // Exclude Next.js internals and common static asset extensions served from public/
+  matcher: ["/((?!_next/static|_next/image|favicon\\.ico|.*\\.(?:png|jpg|jpeg|gif|svg|ico|webp|woff2?|ttf|eot|otf)).*)"],
 }

package/template/scripts/build-offline.sh

@@ -10,7 +10,7 @@
 
 set -euo pipefail
 
-VERSION=${1:-v2.0}
+VERSION=${1:-latest}
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 OUT_DIR="$ROOT/out"
 BUILDS_DIR="$ROOT/offline-builds"
@@ -21,6 +21,8 @@ SERVER_ROUTES=(
   "app/api/raw/route.ts"
   "app/api/download/route.ts"
   "app/api/search/route.ts"
+  "app/api/feedback/route.ts"
+  "app/api/llms"
   "app/api/auth"
 )
 
@@ -48,7 +50,17 @@ restore_routes() {
 }
 
 # Always restore on exit (even on error)
-trap restore_routes EXIT
+PAGES_DIR="$ROOT/.pdf-pages"
+
+cleanup() {
+  restore_routes
+  rm -rf "$PAGES_DIR"
+  # Kill the static server if still running
+  if [[ -n "${STATIC_PID:-}" ]]; then
+    kill "$STATIC_PID" 2>/dev/null || true
+  fi
+}
+trap cleanup EXIT
 
 echo "▶ Building offline package for version: $VERSION"
 
@@ -69,10 +81,14 @@ OFFLINE_MODE=true TARGET_VERSION="$VERSION" npx next build
 
 cat > "$OUT_DIR/launch.sh" <<'LAUNCHER'
 #!/usr/bin/env bash
-# Game Warden Help Center — offline launcher (Mac / Linux)
+# CamelMind offline launcher (Mac / Linux)
+cd "$(dirname "$0")"
 PORT=8765
 URL="http://localhost:$PORT/home/"
 
+# Free the port if a previous server is still running
+lsof -ti:$PORT 2>/dev/null | xargs kill 2>/dev/null || true
+
 # Try Python 3 first (available on most systems without internet)
 if command -v python3 &>/dev/null; then
   echo "Starting local server on $URL"
@@ -113,7 +129,8 @@ chmod +x "$OUT_DIR/launch.sh"
 
 cat > "$OUT_DIR/launch.bat" <<'LAUNCHER'
 @echo off
-REM Game Warden Help Center — offline launcher (Windows)
+REM CamelMind offline launcher (Windows)
+cd /D "%~dp0"
 set PORT=8765
 set URL=http://localhost:%PORT%/home/
 
@@ -180,7 +197,28 @@ NOTES
   Do not redistribute without authorization.
 EOF
 
-# 4. Zip the output
+# 4. Generate PDF from the static export
+echo "  → Generating PDF..."
+STATIC_PORT=8766
+
+# Serve the static output on a temporary port
+python3 -m http.server "$STATIC_PORT" --directory "$OUT_DIR" >/dev/null 2>&1 &
+STATIC_PID=$!
+
+# Wait up to 10s for the server to be ready
+for i in $(seq 1 20); do
+  if curl -s -o /dev/null "http://localhost:$STATIC_PORT/home/"; then break; fi
+  sleep 0.5
+done
+
+npx tsx scripts/generate-pdfs.ts --port="$STATIC_PORT" --out="$PAGES_DIR" --no-auth
+npx tsx scripts/generate-master-pdf.ts --version="$VERSION" --pages="$PAGES_DIR" --out="$BUILDS_DIR"
+
+kill "$STATIC_PID" 2>/dev/null || true
+unset STATIC_PID
+rm -rf "$PAGES_DIR"
+
+# 5. Zip the output
 echo "  → Packaging..."
 mkdir -p "$BUILDS_DIR"
 cd "$OUT_DIR"

package/template/scripts/build-pdf.sh

@@ -9,7 +9,7 @@
 
 set -euo pipefail
 
-VERSION=${1:-v2.0}
+VERSION=${1:-latest}
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 PAGES_DIR="$ROOT/.pdf-pages"
 PORT=3000
@@ -37,5 +37,5 @@ npx tsx scripts/generate-pdfs.ts --port="$PORT" --out="$PAGES_DIR"
 echo "  → Assembling master PDF..."
 npx tsx scripts/generate-master-pdf.ts --version="$VERSION" --pages="$PAGES_DIR" --out="$ROOT/offline-builds"
 
-SIZE=$(du -sh "$ROOT/offline-builds/Game-Warden-Help-Center-${VERSION}.pdf" | cut -f1)
-echo "✓ Done: offline-builds/Game-Warden-Help-Center-${VERSION}.pdf ($SIZE)"
+SIZE=$(du -sh "$ROOT/offline-builds/camelmind-${VERSION}.pdf" | cut -f1)
+echo "✓ Done: offline-builds/camelmind-${VERSION}.pdf ($SIZE)"

package/template/scripts/build-search-index.ts

@@ -10,9 +10,15 @@ import path from "path"
 import matter from "gray-matter"
 
 const ROOT = path.resolve(process.cwd())
-const NAV_FILE = path.join(ROOT, "nav", "nav.yml")
 const OUT_FILE = path.join(ROOT, "public", "search-index.json")
 
+// Resolve the latest stable version's nav file from versions.yml
+const { versions } = yaml.load(fs.readFileSync(path.join(ROOT, "versions.yml"), "utf-8")) as {
+  versions: { id: string; stable: boolean; nav: string }[]
+}
+const latestVersion = versions.find((v) => v.stable) ?? versions[0]
+const NAV_FILE = path.join(ROOT, latestVersion.nav)
+
 // Minimal YAML parser for our nav structure (avoids pulling in the full Next.js lib graph)
 import yaml from "js-yaml"
 

package/template/scripts/generate-master-pdf.ts

@@ -12,6 +12,9 @@
 import { PDFDocument, StandardFonts, rgb, PDFPage } from "pdf-lib"
 import fs from "fs"
 import path from "path"
+import config from "../camelmind.config"
+
+const SITE_TITLE = config.title
 
 const ROOT = path.resolve(process.cwd())
 
@@ -49,25 +52,15 @@ async function buildCoverPage(doc: PDFDocument): Promise<PDFPage> {
   // Thin accent line
   page.drawRectangle({ x: MARGIN, y: PH * 0.45 - 2, width: PW - MARGIN * 2, height: 2, color: rgb(0.3, 0.35, 0.45) })
 
-  // "SECOND FRONT SYSTEMS" label
-  page.drawText("SECOND FRONT SYSTEMS", {
-    x: MARGIN,
-    y: PH * 0.45 + 180,
-    size: 9,
-    font: regularFont,
-    color: rgb(0.6, 0.65, 0.75),
-    characterSpacing: 2,
-  })
-
   // Main title
-  page.drawText("Game Warden", {
+  page.drawText(SITE_TITLE, {
     x: MARGIN,
     y: PH * 0.45 + 130,
     size: 42,
     font: boldFont,
     color: WHITE,
   })
-  page.drawText("Help Center", {
+  page.drawText("Documentation", {
     x: MARGIN,
     y: PH * 0.45 + 78,
     size: 42,
@@ -94,13 +87,12 @@ async function buildCoverPage(doc: PDFDocument): Promise<PDFPage> {
 
   // Footer bar
   page.drawRectangle({ x: 0, y: 0, width: PW, height: 36, color: LIGHT })
-  page.drawText("game warden help center · secondfront.com", {
+  page.drawText(`${SITE_TITLE.toLowerCase()} documentation`, {
     x: MARGIN,
     y: 12,
     size: 8,
     font: regularFont,
     color: MID,
-    characterSpacing: 0.5,
   })
   page.drawText("CONFIDENTIAL — FOR AUTHORIZED USERS ONLY", {
     x: PW - MARGIN - 220,
@@ -126,7 +118,7 @@ async function buildTocPage(
 
   const drawPageHeader = (p: PDFPage) => {
     p.drawText("TABLE OF CONTENTS", {
-      x: MARGIN, y: PH - MARGIN + 10, size: 8, font: regularFont, color: MID, characterSpacing: 1.5
+      x: MARGIN, y: PH - MARGIN + 10, size: 8, font: regularFont, color: MID,
     })
     p.drawLine({ start: { x: MARGIN, y: PH - MARGIN - 4 }, end: { x: PW - MARGIN, y: PH - MARGIN - 4 }, thickness: 0.5, color: rgb(0.85, 0.85, 0.85) })
   }
@@ -152,7 +144,7 @@ async function buildTocPage(
     if (entry.group !== lastGroup) {
       if (lastGroup !== "") y -= 6
       page.drawText(entry.group.toUpperCase(), {
-        x: MARGIN, y, size: 7.5, font: boldFont, color: MID, characterSpacing: 1,
+        x: MARGIN, y, size: 7.5, font: boldFont, color: MID,
       })
       y -= 18
       lastGroup = entry.group
@@ -249,7 +241,7 @@ async function main() {
 
   // ── Write output ───────────────────────────────────────────────────────────
   fs.mkdirSync(OUT_DIR, { recursive: true })
-  const outFile = path.join(OUT_DIR, `Game-Warden-Help-Center-${VERSION}.pdf`)
+  const outFile = path.join(OUT_DIR, `camelmind-${VERSION}.pdf`)
   const pdfBytes = await masterDoc.save()
   fs.writeFileSync(outFile, pdfBytes)
 

package/template/scripts/generate-pdfs.ts

@@ -13,14 +13,25 @@ import { SignJWT } from "jose"
 import fs from "fs"
 import path from "path"
 import yaml from "js-yaml"
+import config from "../camelmind.config"
+
+const SITE_TITLE = config.title
 
 const ROOT = path.resolve(process.cwd())
-const NAV_FILE = path.join(ROOT, "nav", "nav.yml")
+
+// Resolve the latest stable version's nav file from versions.yml
+const { versions: _versions } = yaml.load(fs.readFileSync(path.join(ROOT, "versions.yml"), "utf-8")) as {
+  versions: { id: string; stable: boolean; nav: string }[]
+}
+const _latestVersion = _versions.find((v) => v.stable) ?? _versions[0]
+const NAV_FILE = path.join(ROOT, _latestVersion.nav)
 
 const PORT = parseInt(process.argv.find((a) => a.startsWith("--port="))?.split("=")[1] ?? "3000")
 const OUT_DIR = process.argv.find((a) => a.startsWith("--out="))?.split("=")[1]
   ? path.resolve(process.argv.find((a) => a.startsWith("--out="))!.split("=")[1])
   : path.join(ROOT, ".pdf-pages")
+// --no-auth: skip the login step (use when rendering a static offline export where auth is bypassed)
+const SKIP_AUTH = process.argv.includes("--no-auth")
 
 const CONCURRENCY = 4
 const BASE_URL = `http://localhost:${PORT}`
@@ -110,7 +121,7 @@ async function generatePage(
       headerTemplate: `
         <div style="width:100%;font-family:system-ui,sans-serif;font-size:8px;color:#6b7280;display:flex;justify-content:space-between;padding:0 16mm;">
           <span>${page.group}${page.section ? " › " + page.section : ""}</span>
-          <span style="color:#111827;font-weight:600;">Game Warden Help Center</span>
+          <span style="color:#111827;font-weight:600;">${SITE_TITLE}</span>
         </div>`,
       footerTemplate: `
         <div style="width:100%;font-family:system-ui,sans-serif;font-size:8px;color:#6b7280;display:flex;justify-content:space-between;padding:0 16mm;">
@@ -148,16 +159,19 @@ async function main() {
 
   const browser = await chromium.launch()
 
-  // Sign in via the dev login UI so we get a real session cookie
-  const authCtx = await browser.newContext()
-  const authPage = await authCtx.newPage()
-  await authPage.goto(`${BASE_URL}/login`, { waitUntil: "networkidle" })
-  // Click "Staff (vendor + admin)" persona button
-  await authPage.click("button:has-text('Staff')")
-  await authPage.waitForURL(/\/home|\/getting-started/, { timeout: 10000 })
-  const cookies = await authCtx.cookies()
-  await authPage.close()
-  await authCtx.close()
+  // Sign in via the dev login UI so we get a real session cookie.
+  // Skip when rendering against a static offline export (auth is bypassed there).
+  let cookies: Cookie[] = []
+  if (!SKIP_AUTH) {
+    const authCtx = await browser.newContext()
+    const authPage = await authCtx.newPage()
+    await authPage.goto(`${BASE_URL}/login`, { waitUntil: "networkidle" })
+    await authPage.click("button:has-text('Staff')")
+    await authPage.waitForURL(/\/home|\/getting-started/, { timeout: 10000 })
+    cookies = await authCtx.cookies()
+    await authPage.close()
+    await authCtx.close()
+  }
 
   const results: Array<{ page: PageEntry; file: string }> = []