doccupine 0.0.93 → 0.0.94

package/README.md

@@ -14,6 +14,7 @@
 - **MCP server** - exposes `search_docs`, `get_doc`, and `list_docs` tools for AI agents
 - **Custom fonts** - Google Fonts or local fonts via `fonts.json`
 - **Static assets** - `public/` directory is watched and synced to the generated app
+- **Password protection** - gate the whole site behind a shared password with `SITE_PASSWORD`
 - **Zero config to start** - `npx doccupine` scaffolds everything and starts the server
 
 ## Quick Start
@@ -226,6 +227,24 @@ The generated app exposes an MCP endpoint at `/api/mcp` with three tools:
 
 This lets AI agents (Claude, ChatGPT, etc.) query your docs programmatically. Requires the AI chat setup above for embeddings.
 
+## Password Protection
+
+Gate your entire documentation site behind a shared password by setting `SITE_PASSWORD` in the generated app's environment - add it to `.env` for local development, or your host's environment variables in production:
+
+```env
+SITE_PASSWORD=choose-a-strong-shared-password
+```
+
+When set, every visitor sees a login screen until they enter the password. Protection is enforced across three layers:
+
+- **Pages** are gated behind the login screen.
+- **Content APIs** (`/api/rag` chat and `/api/search`) return `401` without a valid session, so the docs can't be scraped around the login.
+- **Search engines and crawlers** are blocked: `robots.txt` disallows everything, pages carry a `noindex, nofollow` tag, and responses include an `X-Robots-Tag` header.
+
+A successful login sets a signed, `httpOnly` cookie that lasts 30 days. The cookie stores an HMAC of the password, never the password itself. Leave `SITE_PASSWORD` unset (the default) to keep the site fully public. Documentation pages stay statically rendered either way - the gate is enforced in middleware.
+
+> **Note:** The [MCP endpoint](#mcp-server) uses its own `DOCS_API_KEY` bearer token and is not affected by `SITE_PASSWORD`.
+
 ## License
 
 This project is licensed under a modified MIT license with a SaaS restriction. See [LICENSE](LICENSE) for details.

package/dist/index.js

@@ -7,7 +7,7 @@ import { fileURLToPath } from "url";
 import matter from "gray-matter";
 import chalk from "chalk";
 import { appStructure, startingDocsStructure } from "./lib/structures.js";
-import { layoutTemplate } from "./lib/layout.js";
+import { rootLayoutTemplate, siteLayoutTemplate } from "./lib/layout.js";
 import { ConfigManager } from "./lib/config-manager.js";
 import { findAvailablePort, generateSlug, getFullSlug, escapeTemplateContent, } from "./lib/utils.js";
 import { generateMetadataBlock, generateRuntimeOnlyMetadataBlock, generateJsonLdScript, } from "./lib/metadata.js";
@@ -80,6 +80,13 @@ class MDXToNextJSGenerator {
         console.log(chalk.white("   npm install && npm run dev"));
     }
     async createNextJSStructure() {
+        // Clear the generated app/ directory first so a fresh run never inherits
+        // stale routes from a previous version (e.g. pages left at their old paths
+        // after a route-group move would collide with the newly generated ones).
+        // Everything under app/ is regenerated below and by processAllMDXFiles /
+        // generateSectionIndexPages, so nothing here is user-authored. Config JSONs
+        // and other generated dirs live outside app/ and are untouched.
+        await fs.remove(path.join(this.outputDir, "app"));
         const siteUrl = await this.loadSiteUrl();
         const structure = {
             ...appStructure,
@@ -94,6 +101,7 @@ class MDXToNextJSGenerator {
             "theme.json": `{}\n`,
             "app/robots.ts": robotsTemplate(siteUrl !== null),
             "app/layout.tsx": this.generateRootLayout(),
+            "app/(site)/layout.tsx": this.generateSiteLayout(),
         };
         for (const [filePath, content] of Object.entries(structure)) {
             const fullPath = path.join(this.outputDir, filePath);
@@ -710,7 +718,7 @@ class MDXToNextJSGenerator {
                 // We don't have frontmatter for deleted files, so use directory-based matching
                 const { sectionSlug, pageSlug } = this.determineSectionForFile(filePath, {});
                 const fullSlug = getFullSlug(pageSlug, sectionSlug);
-                const pagePath = path.join(this.outputDir, "app", fullSlug);
+                const pagePath = path.join(this.outputDir, "app", "(site)", fullSlug);
                 await fs.remove(pagePath);
             }
             await this.updatePagesIndex();
@@ -749,10 +757,13 @@ class MDXToNextJSGenerator {
         return files;
     }
     async generateRootLayout() {
-        const pages = await this.buildAllPagesMeta();
         const fontConfig = await this.loadFontConfig();
         const analyticsEnabled = this.analyticsConfig !== null;
-        return layoutTemplate(pages, fontConfig, this.sectionsConfig, analyticsEnabled);
+        return rootLayoutTemplate(fontConfig, analyticsEnabled);
+    }
+    async generateSiteLayout() {
+        const pages = await this.buildAllPagesMeta();
+        return siteLayoutTemplate(pages, this.sectionsConfig);
     }
     async generateSectionIndexPages() {
         if (!this.sectionsConfig || this.sectionsConfig.length === 0)
@@ -782,7 +793,7 @@ export default function SectionIndex() {
   redirect("/${firstPage.slug}");
 }
 `;
-            const pagePath = path.join(this.outputDir, "app", section.slug, "page.tsx");
+            const pagePath = path.join(this.outputDir, "app", "(site)", section.slug, "page.tsx");
             await fs.ensureDir(path.dirname(pagePath));
             await fs.writeFile(pagePath, redirectContent, "utf8");
             console.log(chalk.blue(`🔀 Generated section index redirect: /${section.slug} -> /${firstPage.slug}`));
@@ -838,7 +849,7 @@ export default function Page() {
   );
 }
 `;
-        const pagePath = path.join(this.outputDir, "app", mdxFile.slug, "page.tsx");
+        const pagePath = path.join(this.outputDir, "app", "(site)", mdxFile.slug, "page.tsx");
         await fs.ensureDir(path.dirname(pagePath));
         await fs.writeFile(pagePath, pageContent, "utf8");
     }
@@ -908,7 +919,9 @@ export default function Home() {
   );
 }
 `;
-        await fs.writeFile(path.join(this.outputDir, "app", "page.tsx"), indexContent, "utf8");
+        const homePath = path.join(this.outputDir, "app", "(site)", "page.tsx");
+        await fs.ensureDir(path.dirname(homePath));
+        await fs.writeFile(homePath, indexContent, "utf8");
     }
     async updateSectionIndex(sectionSlug, frontmatter, mdxContent) {
         const metadataBlock = generateMetadataBlock({
@@ -956,13 +969,15 @@ export default function Page() {
   );
 }
 `;
-        const pagePath = path.join(this.outputDir, "app", sectionSlug, "page.tsx");
+        const pagePath = path.join(this.outputDir, "app", "(site)", sectionSlug, "page.tsx");
         await fs.ensureDir(path.dirname(pagePath));
         await fs.writeFile(pagePath, indexContent, "utf8");
     }
     async updateRootLayout() {
-        const layoutContent = await this.generateRootLayout();
-        await fs.writeFile(path.join(this.outputDir, "app", "layout.tsx"), layoutContent, "utf8");
+        await fs.writeFile(path.join(this.outputDir, "app", "layout.tsx"), await this.generateRootLayout(), "utf8");
+        const siteLayoutPath = path.join(this.outputDir, "app", "(site)", "layout.tsx");
+        await fs.ensureDir(path.dirname(siteLayoutPath));
+        await fs.writeFile(siteLayoutPath, await this.generateSiteLayout(), "utf8");
     }
     async loadSiteUrl() {
         const configPath = path.join(this.rootDir, "config.json");

package/dist/lib/layout.d.ts

@@ -26,5 +26,22 @@ interface FontConfig {
         src?: LocalFontSrc[];
     };
 }
-export declare const layoutTemplate: (pages: PageData[], fontConfig: FontConfig | null, sectionsConfig?: SectionConfig[] | null, analyticsEnabled?: boolean) => string;
+/**
+ * Root layout ("app/layout.tsx"). Minimal shell: html/body, fonts, the theme
+ * provider stack, and (optionally) PostHog. It renders `children` directly so
+ * both the docs (via the "(site)" layout) and the password gate ("app/gate")
+ * share the same providers and theme without the docs chrome. Deliberately has
+ * NO request-time data (cookies/headers) so pages stay statically renderable —
+ * the SITE_PASSWORD gate is enforced in the middleware (proxy.ts), which
+ * rewrites locked page requests to "/gate".
+ */
+export declare const rootLayoutTemplate: (fontConfig: FontConfig | null, analyticsEnabled?: boolean) => string;
+/**
+ * Docs chrome layout ("app/(site)/layout.tsx"). Wraps every documentation page
+ * with the header, sidebar/section navigation, chat, and footer. Lives in the
+ * URL-transparent "(site)" route group so it wraps the docs but NOT the gate
+ * screen at "/gate", which renders under the root shell alone. Renders inside
+ * the root layout's providers, so it needs no html/body or theme provider.
+ */
+export declare const siteLayoutTemplate: (pages: PageData[], sectionsConfig?: SectionConfig[] | null) => string;
 export {};

package/dist/lib/layout.js

@@ -35,59 +35,54 @@ function getLocalFontSrc(fc) {
         return `"${fc.localFonts}"`;
     return JSON.stringify(fc.localFonts?.src, null, 2).replace(/"([^"]+)":/g, "$1:");
 }
-export const layoutTemplate = (pages, fontConfig, sectionsConfig = null, analyticsEnabled = false) => {
-    const hasSections = sectionsConfig !== null && sectionsConfig.length > 0;
-    // Extra indent when PostHogProvider wraps the inner content
-    const a = analyticsEnabled ? "  " : "";
-    // ChtProvider line wraps at wider indent
-    const chtOpen = analyticsEnabled
-        ? `<ChtProvider
-${a}              isChatActive={process.env.LLM_PROVIDER ? true : false}
-${a}            >`
-        : `<ChtProvider isChatActive={process.env.LLM_PROVIDER ? true : false}>`;
-    return `import type { Metadata } from "next";
-${isGoogleFont(fontConfig) ? `import { ${fontConfig.googleFont.fontName} } from "next/font/google";` : isLocalFont(fontConfig) ? 'import localFont from "next/font/local";' : 'import { Inter } from "next/font/google";'}
-import dynamic from "next/dynamic";
-import { StyledComponentsRegistry } from "cherry-styled-components";
-import { theme } from "@/app/theme";
-import { CherryThemeProvider } from "@/components/layout/CherryThemeProvider";
-import { ChtProvider } from "@/components/Chat";
-import { SearchProvider } from "@/components/SearchDocs";
-${hasSections
-        ? ""
-        : `import { Footer } from "@/components/layout/Footer";
-`}import { Header } from "@/components/layout/Header";
-import { DocsWrapper } from "@/components/layout/DocsComponents";
-${hasSections
-        ? ""
-        : `import { SectionBarProvider } from "@/components/layout/DocsComponents";
-import { SideBar } from "@/components/SideBar";
-import { DocsNavigation } from "@/components/layout/DocsNavigation";
-`}import { type PagesProps } from "@/utils/orderNavItems";
-${hasSections
-        ? ""
-        : `import { transformPagesToGroupedStructure } from "@/utils/orderNavItems";
-`}
-${hasSections
-        ? ""
-        : `import { StaticLinks } from "@/components/layout/StaticLinks";
-`}import { config } from "@/utils/config";
-import { verifyBrandingKey } from "@/utils/branding";
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-import navigation from "@/navigation.json";
-${hasSections
-        ? `import { SectionBar } from "@/components/layout/SectionBar";
-import { SectionNavProvider } from "@/components/SectionNavProvider";
-`
-        : ""}${analyticsEnabled ? `import { PostHogProvider } from "@/components/PostHogProvider";\n` : ""}const Chat = dynamic(() => import("@/components/Chat").then((mod) => mod.Chat));
-
-${isGoogleFont(fontConfig)
-        ? `const font = ${fontConfig.googleFont.fontName}({ ${[fontConfig.googleFont.subsets?.length ? `subsets: ${JSON.stringify(fontConfig.googleFont.subsets)}` : "", fontConfig.googleFont.weight?.length ? `weight: ${Array.isArray(fontConfig.googleFont.weight) ? JSON.stringify(fontConfig.googleFont.weight) : `"${fontConfig.googleFont.weight}"`}` : ""].filter(Boolean).join(", ")} });`
+function fontImportLine(fontConfig) {
+    return isGoogleFont(fontConfig)
+        ? `import { ${fontConfig.googleFont.fontName} } from "next/font/google";`
+        : isLocalFont(fontConfig)
+            ? 'import localFont from "next/font/local";'
+            : 'import { Inter } from "next/font/google";';
+}
+function fontDeclLine(fontConfig) {
+    return isGoogleFont(fontConfig)
+        ? `const font = ${fontConfig.googleFont.fontName}({ ${[
+            fontConfig.googleFont.subsets?.length
+                ? `subsets: ${JSON.stringify(fontConfig.googleFont.subsets)}`
+                : "",
+            fontConfig.googleFont.weight?.length
+                ? `weight: ${Array.isArray(fontConfig.googleFont.weight)
+                    ? JSON.stringify(fontConfig.googleFont.weight)
+                    : `"${fontConfig.googleFont.weight}"`}`
+                : "",
+        ]
+            .filter(Boolean)
+            .join(", ")} });`
         : isLocalFont(fontConfig)
             ? `const font = localFont({
   src: ${getLocalFontSrc(fontConfig)},
 });`
-            : 'const font = Inter({ subsets: ["latin"] });'}
+            : 'const font = Inter({ subsets: ["latin"] });';
+}
+// The inline blocking script that resolves dark mode before first paint by
+// adding the "dark" class to <html>. Shared by the root layout's <head>.
+const THEME_INIT_SCRIPT = `(function(){try{var c=document.cookie.split(";").map(function(s){return s.trim();}).find(function(s){return s.indexOf("theme=")===0;});var v=c?c.split("=")[1]:null;var d=v?v==="dark":(window.matchMedia&&window.matchMedia("(prefers-color-scheme:dark)").matches);if(!v){document.cookie="theme="+(d?"dark":"light")+";path=/;max-age=31536000;SameSite=Lax";}if(d){document.documentElement.classList.add("dark");document.documentElement.style.colorScheme="dark";}else{document.documentElement.style.colorScheme="light";}}catch(e){}})();`;
+/**
+ * Root layout ("app/layout.tsx"). Minimal shell: html/body, fonts, the theme
+ * provider stack, and (optionally) PostHog. It renders `children` directly so
+ * both the docs (via the "(site)" layout) and the password gate ("app/gate")
+ * share the same providers and theme without the docs chrome. Deliberately has
+ * NO request-time data (cookies/headers) so pages stay statically renderable —
+ * the SITE_PASSWORD gate is enforced in the middleware (proxy.ts), which
+ * rewrites locked page requests to "/gate".
+ */
+export const rootLayoutTemplate = (fontConfig, analyticsEnabled = false) => {
+    return `import type { Metadata } from "next";
+${fontImportLine(fontConfig)}
+import { StyledComponentsRegistry } from "cherry-styled-components";
+import { theme } from "@/app/theme";
+import { CherryThemeProvider } from "@/components/layout/CherryThemeProvider";
+import { config } from "@/utils/config";
+${analyticsEnabled ? `import { PostHogProvider } from "@/components/PostHogProvider";\n` : ""}
+${fontDeclLine(fontConfig)}
 
 function resolveSiteUrl(): URL | undefined {
   const raw = process.env.NEXT_PUBLIC_SITE_URL ?? config.url;
@@ -115,18 +110,11 @@ export const metadata: Metadata = {
   },
 };
 
-const doccupinePages = ${formatObjectArray(pages)};${hasSections ? `\nconst doccupineSections = ${formatObjectArray(sectionsConfig)};` : ""}
-
-export default async function RootLayout({
+export default function RootLayout({
   children,
 }: Readonly<{
   children: React.ReactNode;
 }>) {
-  const hideBranding = verifyBrandingKey();
-${hasSections
-        ? `
-  const pages: PagesProps[] = doccupinePages;
-
   return (
     <html lang="en" suppressHydrationWarning>
       <head>
@@ -141,35 +129,94 @@ ${hasSections
             different between server (no class) and client (after script). */}
         <script
           dangerouslySetInnerHTML={{
-            __html: \`(function(){try{var c=document.cookie.split(";").map(function(s){return s.trim();}).find(function(s){return s.indexOf("theme=")===0;});var v=c?c.split("=")[1]:null;var d=v?v==="dark":(window.matchMedia&&window.matchMedia("(prefers-color-scheme:dark)").matches);if(!v){document.cookie="theme="+(d?"dark":"light")+";path=/;max-age=31536000;SameSite=Lax";}if(d){document.documentElement.classList.add("dark");document.documentElement.style.colorScheme="dark";}else{document.documentElement.style.colorScheme="light";}}catch(e){}})();\`,
+            __html: \`${THEME_INIT_SCRIPT}\`,
           }}
         />
       </head>
       <body className={font.className}>
         <StyledComponentsRegistry>
-${analyticsEnabled ? "          <PostHogProvider>\n" : ""}${a}          <CherryThemeProvider theme={theme}>
-${a}            ${chtOpen}
-${a}              <SearchProvider pages={pages} sections={doccupineSections}>
-${a}                <Header>
-${a}                  <SectionBar sections={doccupineSections} />
-${a}                </Header>
-${a}                {process.env.LLM_PROVIDER && <Chat />}
-${a}                <DocsWrapper>
-${a}                  <SectionNavProvider
-${a}                    sections={doccupineSections}
-${a}                    allPages={pages}
-${a}                    hideBranding={hideBranding}
-${a}                  >
-${a}                    {children}
-${a}                  </SectionNavProvider>
-${a}                </DocsWrapper>
-${a}              </SearchProvider>
-${a}            </ChtProvider>
-${a}          </CherryThemeProvider>
-${analyticsEnabled ? "          </PostHogProvider>\n" : ""}        </StyledComponentsRegistry>
+${analyticsEnabled
+        ? `          <PostHogProvider>
+            <CherryThemeProvider theme={theme}>{children}</CherryThemeProvider>
+          </PostHogProvider>`
+        : `          <CherryThemeProvider theme={theme}>{children}</CherryThemeProvider>`}
+        </StyledComponentsRegistry>
       </body>
     </html>
   );
+}
+`;
+};
+/**
+ * Docs chrome layout ("app/(site)/layout.tsx"). Wraps every documentation page
+ * with the header, sidebar/section navigation, chat, and footer. Lives in the
+ * URL-transparent "(site)" route group so it wraps the docs but NOT the gate
+ * screen at "/gate", which renders under the root shell alone. Renders inside
+ * the root layout's providers, so it needs no html/body or theme provider.
+ */
+export const siteLayoutTemplate = (pages, sectionsConfig = null) => {
+    const hasSections = sectionsConfig !== null && sectionsConfig.length > 0;
+    const chtOpen = `<ChtProvider isChatActive={process.env.LLM_PROVIDER ? true : false}>`;
+    return `import dynamic from "next/dynamic";
+import { ChtProvider } from "@/components/Chat";
+import { SearchProvider } from "@/components/SearchDocs";
+${hasSections
+        ? ""
+        : `import { Footer } from "@/components/layout/Footer";
+`}import { Header } from "@/components/layout/Header";
+import { DocsWrapper } from "@/components/layout/DocsComponents";
+${hasSections
+        ? ""
+        : `import { SectionBarProvider } from "@/components/layout/DocsComponents";
+import { SideBar } from "@/components/SideBar";
+import { DocsNavigation } from "@/components/layout/DocsNavigation";
+`}import { type PagesProps } from "@/utils/orderNavItems";
+${hasSections
+        ? ""
+        : `import { transformPagesToGroupedStructure } from "@/utils/orderNavItems";
+`}${hasSections
+        ? ""
+        : `import { StaticLinks } from "@/components/layout/StaticLinks";
+`}import { verifyBrandingKey } from "@/utils/branding";
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import navigation from "@/navigation.json";
+${hasSections
+        ? `import { SectionBar } from "@/components/layout/SectionBar";
+import { SectionNavProvider } from "@/components/SectionNavProvider";
+`
+        : ""}const Chat = dynamic(() => import("@/components/Chat").then((mod) => mod.Chat));
+
+const doccupinePages = ${formatObjectArray(pages)};${hasSections ? `\nconst doccupineSections = ${formatObjectArray(sectionsConfig)};` : ""}
+
+export default function SiteLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  const hideBranding = verifyBrandingKey();
+${hasSections
+        ? `
+  const pages: PagesProps[] = doccupinePages;
+
+  return (
+    ${chtOpen}
+      <SearchProvider pages={pages} sections={doccupineSections}>
+        <Header>
+          <SectionBar sections={doccupineSections} />
+        </Header>
+        {process.env.LLM_PROVIDER && <Chat />}
+        <DocsWrapper>
+          <SectionNavProvider
+            sections={doccupineSections}
+            allPages={pages}
+            hideBranding={hideBranding}
+          >
+            {children}
+          </SectionNavProvider>
+        </DocsWrapper>
+      </SearchProvider>
+    </ChtProvider>
+  );
 }`
         : `
   const defaultPages = [
@@ -193,47 +240,21 @@ ${analyticsEnabled ? "          </PostHogProvider>\n" : ""}        </StyledCompo
   const defaultResults = transformPagesToGroupedStructure(defaultPages);
 
   return (
-    <html lang="en" suppressHydrationWarning>
-      <head>
-        {/* Resolves dark mode before first paint by adding the "dark" class
-            to <html> when needed. CSS variables in GlobalStyles flip values
-            on :root vs :root.dark, so the right palette renders without a
-            React roundtrip. Inlined as a plain <script> (not next/script) so
-            it ships in the SSR HTML and runs synchronously before paint —
-            next/script with beforeInteractive is async in App Router and
-            would still show a flash. suppressHydrationWarning on <html>
-            tells React the class/colorScheme attributes are intentionally
-            different between server (no class) and client (after script). */}
-        <script
-          dangerouslySetInnerHTML={{
-            __html: \`(function(){try{var c=document.cookie.split(";").map(function(s){return s.trim();}).find(function(s){return s.indexOf("theme=")===0;});var v=c?c.split("=")[1]:null;var d=v?v==="dark":(window.matchMedia&&window.matchMedia("(prefers-color-scheme:dark)").matches);if(!v){document.cookie="theme="+(d?"dark":"light")+";path=/;max-age=31536000;SameSite=Lax";}if(d){document.documentElement.classList.add("dark");document.documentElement.style.colorScheme="dark";}else{document.documentElement.style.colorScheme="light";}}catch(e){}})();\`,
-          }}
-        />
-      </head>
-      <body className={font.className}>
-        <StyledComponentsRegistry>
-${analyticsEnabled ? "          <PostHogProvider>\n" : ""}${a}          <CherryThemeProvider theme={theme}>
-${a}            ${chtOpen}
-${a}              <SearchProvider pages={pages}>
-${a}                <Header />
-${a}                {process.env.LLM_PROVIDER && <Chat />}
-${a}                <SectionBarProvider hasSectionBar={false}>
-${a}                  <DocsWrapper>
-${a}                    <SideBar result={result.length ? result : defaultResults} />
-${a}                    {children}
-${a}                    <DocsNavigation
-${a}                      result={result.length ? result : defaultResults}
-${a}                    />
-${a}                    <StaticLinks />
-${a}                    <Footer hideBranding={hideBranding} />
-${a}                  </DocsWrapper>
-${a}                </SectionBarProvider>
-${a}              </SearchProvider>
-${a}            </ChtProvider>
-${a}          </CherryThemeProvider>
-${analyticsEnabled ? "          </PostHogProvider>\n" : ""}        </StyledComponentsRegistry>
-      </body>
-    </html>
+    ${chtOpen}
+      <SearchProvider pages={pages}>
+        <Header />
+        {process.env.LLM_PROVIDER && <Chat />}
+        <SectionBarProvider hasSectionBar={false}>
+          <DocsWrapper>
+            <SideBar result={result.length ? result : defaultResults} />
+            {children}
+            <DocsNavigation result={result.length ? result : defaultResults} />
+            <StaticLinks />
+            <Footer hideBranding={hideBranding} />
+          </DocsWrapper>
+        </SectionBarProvider>
+      </SearchProvider>
+    </ChtProvider>
   );
 }`}
 `;

package/dist/lib/structures.js

@@ -5,6 +5,8 @@ import { packageJsonTemplate } from "../templates/package.js";
 import { prettierrcTemplate } from "../templates/prettierrc.js";
 import { prettierignoreTemplate } from "../templates/prettierignore.js";
 import { tsconfigTemplate } from "../templates/tsconfig.js";
+import { gatePageTemplate } from "../templates/app/gate/page.js";
+import { gateRoutesTemplate } from "../templates/app/api/gate/route.js";
 import { mcpRoutesTemplate } from "../templates/app/api/mcp/route.js";
 import { ragRoutesTemplate } from "../templates/app/api/rag/route.js";
 import { searchRoutesTemplate } from "../templates/app/api/search/route.js";
@@ -45,6 +47,7 @@ import { headerTemplate } from "../templates/components/layout/Header.js";
 import { iconTemplate } from "../templates/components/layout/Icon.js";
 import { pictogramsTemplate } from "../templates/components/layout/Pictograms.js";
 import { sharedStyledTemplate } from "../templates/components/layout/SharedStyles.js";
+import { siteGateComponentTemplate } from "../templates/components/layout/SiteGate.js";
 import { staticLinksTemplate } from "../templates/components/layout/StaticLinks.js";
 import { stepsTemplate } from "../templates/components/layout/Steps.js";
 import { tabsTemplate } from "../templates/components/layout/Tabs.js";
@@ -61,6 +64,7 @@ import { llmFactoryTemplate } from "../templates/services/llm/factory.js";
 import { llmIndexTemplate } from "../templates/services/llm/index.js";
 import { llmTypesTemplate } from "../templates/services/llm/types.js";
 import { posthogServerTemplate } from "../templates/lib/posthog.js";
+import { siteGateTemplate } from "../templates/lib/siteGate.js";
 import { styledDTemplate } from "../templates/types/styled.js";
 import { orderNavItemsTemplate } from "../templates/utils/orderNavItems.js";
 import { rateLimitTemplate } from "../templates/utils/rateLimit.js";
@@ -69,6 +73,7 @@ import { configTemplate } from "../templates/utils/config.js";
 import { accordionMdxTemplate } from "../templates/mdx/accordion.mdx.js";
 import { aiAssistantMdxTemplate } from "../templates/mdx/ai-assistant.mdx.js";
 import { analyticsMdxTemplate } from "../templates/mdx/analytics.mdx.js";
+import { authenticationMdxTemplate } from "../templates/mdx/authentication.mdx.js";
 import { buttonsMdxTemplate } from "../templates/mdx/buttons.mdx.js";
 import { calloutsMdxTemplate } from "../templates/mdx/callouts.mdx.js";
 import { cardsMdxTemplate } from "../templates/mdx/cards.mdx.js";
@@ -119,8 +124,10 @@ export const appStructure = {
     "eslint.config.mjs": eslintConfigTemplate,
     "package.json": packageJsonTemplate,
     "tsconfig.json": tsconfigTemplate,
-    "app/not-found.tsx": notFoundTemplate,
+    "app/(site)/not-found.tsx": notFoundTemplate,
+    "app/gate/page.tsx": gatePageTemplate,
     "app/theme.ts": themeTemplate,
+    "app/api/gate/route.ts": gateRoutesTemplate,
     "app/api/mcp/route.ts": mcpRoutesTemplate,
     "app/api/rag/route.ts": ragRoutesTemplate,
     "app/api/search/route.ts": searchRoutesTemplate,
@@ -136,6 +143,7 @@ export const appStructure = {
     "services/llm/types.ts": llmTypesTemplate,
     "types/styled.d.ts": styledDTemplate,
     "lib/posthog.ts": posthogServerTemplate,
+    "lib/siteGate.ts": siteGateTemplate,
     "utils/branding.ts": brandingTemplate,
     "utils/orderNavItems.ts": orderNavItemsTemplate,
     "utils/rateLimit.ts": rateLimitTemplate,
@@ -174,6 +182,7 @@ export const appStructure = {
     "components/layout/Icon.tsx": iconTemplate,
     "components/layout/Pictograms.tsx": pictogramsTemplate,
     "components/layout/SharedStyled.ts": sharedStyledTemplate,
+    "components/layout/SiteGate.tsx": siteGateComponentTemplate,
     "components/layout/StaticLinks.tsx": staticLinksTemplate,
     "components/layout/Steps.tsx": stepsTemplate,
     "components/layout/Tabs.tsx": tabsTemplate,
@@ -185,6 +194,7 @@ export const startingDocsStructure = {
     "accordion.mdx": accordionMdxTemplate,
     "ai-assistant.mdx": aiAssistantMdxTemplate,
     "analytics.mdx": analyticsMdxTemplate,
+    "authentication.mdx": authenticationMdxTemplate,
     "buttons.mdx": buttonsMdxTemplate,
     "callouts.mdx": calloutsMdxTemplate,
     "cards.mdx": cardsMdxTemplate,

package/dist/templates/app/api/gate/route.d.ts

@@ -0,0 +1 @@
+export declare const gateRoutesTemplate = "import { NextResponse } from \"next/server\";\nimport { cookies } from \"next/headers\";\nimport { GATE_COOKIE_NAME, gateToken, timingSafeEqual } from \"@/lib/siteGate\";\nimport { rateLimit } from \"@/utils/rateLimit\";\n\nexport async function POST(req: Request) {\n  const password = process.env.SITE_PASSWORD;\n  if (!password) {\n    return NextResponse.json({ ok: true });\n  }\n\n  // Rate limit password attempts by IP to slow down brute-force guessing.\n  const ip =\n    req.headers.get(\"x-forwarded-for\")?.split(\",\")[0]?.trim() ?? \"unknown\";\n  const { allowed, retryAfter } = rateLimit(ip);\n  if (!allowed) {\n    return NextResponse.json(\n      { ok: false, error: \"Too many attempts\" },\n      { status: 429, headers: { \"Retry-After\": String(retryAfter) } },\n    );\n  }\n\n  let submitted: unknown;\n  try {\n    submitted = (await req.json())?.password;\n  } catch {\n    return NextResponse.json(\n      { ok: false, error: \"Bad Request\" },\n      { status: 400 },\n    );\n  }\n\n  const expected = await gateToken(password);\n  const candidate = await gateToken(\n    typeof submitted === \"string\" ? submitted : \"\",\n  );\n\n  if (!timingSafeEqual(candidate, expected)) {\n    return NextResponse.json(\n      { ok: false, error: \"Incorrect password\" },\n      { status: 401 },\n    );\n  }\n\n  const cookieStore = await cookies();\n  cookieStore.set(GATE_COOKIE_NAME, expected, {\n    httpOnly: true,\n    secure: process.env.NODE_ENV === \"production\",\n    sameSite: \"lax\",\n    path: \"/\",\n    maxAge: 60 * 60 * 24 * 30, // 30 days\n  });\n\n  return NextResponse.json({ ok: true });\n}\n";

package/dist/templates/app/api/gate/route.js

@@ -0,0 +1,56 @@
+export const gateRoutesTemplate = `import { NextResponse } from "next/server";
+import { cookies } from "next/headers";
+import { GATE_COOKIE_NAME, gateToken, timingSafeEqual } from "@/lib/siteGate";
+import { rateLimit } from "@/utils/rateLimit";
+
+export async function POST(req: Request) {
+  const password = process.env.SITE_PASSWORD;
+  if (!password) {
+    return NextResponse.json({ ok: true });
+  }
+
+  // Rate limit password attempts by IP to slow down brute-force guessing.
+  const ip =
+    req.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ?? "unknown";
+  const { allowed, retryAfter } = rateLimit(ip);
+  if (!allowed) {
+    return NextResponse.json(
+      { ok: false, error: "Too many attempts" },
+      { status: 429, headers: { "Retry-After": String(retryAfter) } },
+    );
+  }
+
+  let submitted: unknown;
+  try {
+    submitted = (await req.json())?.password;
+  } catch {
+    return NextResponse.json(
+      { ok: false, error: "Bad Request" },
+      { status: 400 },
+    );
+  }
+
+  const expected = await gateToken(password);
+  const candidate = await gateToken(
+    typeof submitted === "string" ? submitted : "",
+  );
+
+  if (!timingSafeEqual(candidate, expected)) {
+    return NextResponse.json(
+      { ok: false, error: "Incorrect password" },
+      { status: 401 },
+    );
+  }
+
+  const cookieStore = await cookies();
+  cookieStore.set(GATE_COOKIE_NAME, expected, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === "production",
+    sameSite: "lax",
+    path: "/",
+    maxAge: 60 * 60 * 24 * 30, // 30 days
+  });
+
+  return NextResponse.json({ ok: true });
+}
+`;

package/dist/templates/app/gate/page.d.ts

@@ -0,0 +1 @@
+export declare const gatePageTemplate = "import type { Metadata } from \"next\";\nimport { SiteGate } from \"@/components/layout/SiteGate\";\nimport { verifyBrandingKey } from \"@/utils/branding\";\n\n// The gate screen is never indexed. The middleware also sets X-Robots-Tag and\n// robots.txt disallows everything while SITE_PASSWORD is active.\nexport const metadata: Metadata = {\n  robots: { index: false, follow: false },\n};\n\n// The login form is identical for every visitor, so it can render statically.\n// The middleware (proxy.ts) decides who is shown this screen by rewriting\n// locked requests here; unlocked visitors are redirected back to the site.\nexport const dynamic = \"force-static\";\nexport const revalidate = false;\n\nexport default function GatePage() {\n  const hideBranding = verifyBrandingKey();\n  return <SiteGate hideBranding={hideBranding} />;\n}\n";

package/dist/templates/app/gate/page.js

@@ -0,0 +1,21 @@
+export const gatePageTemplate = `import type { Metadata } from "next";
+import { SiteGate } from "@/components/layout/SiteGate";
+import { verifyBrandingKey } from "@/utils/branding";
+
+// The gate screen is never indexed. The middleware also sets X-Robots-Tag and
+// robots.txt disallows everything while SITE_PASSWORD is active.
+export const metadata: Metadata = {
+  robots: { index: false, follow: false },
+};
+
+// The login form is identical for every visitor, so it can render statically.
+// The middleware (proxy.ts) decides who is shown this screen by rewriting
+// locked requests here; unlocked visitors are redirected back to the site.
+export const dynamic = "force-static";
+export const revalidate = false;
+
+export default function GatePage() {
+  const hideBranding = verifyBrandingKey();
+  return <SiteGate hideBranding={hideBranding} />;
+}
+`;