@heyo-sh/create-heyo-docs 0.4.0 → 1.0.1

package/deployments/cloudflare/astro/src/env.d.ts

@@ -0,0 +1,5 @@
+declare namespace Cloudflare {
+  interface Env {
+    OPENAI_API_KEY: string;
+  }
+}

package/deployments/cloudflare/astro/src/pages/heyo-docs-internal/ai-chat.ts

@@ -0,0 +1,30 @@
+import { createAiChatResponse } from "@heyo-sh/heyo-docs/ai";
+import type { APIRoute } from "astro";
+import { env } from "cloudflare:workers";
+
+import config from "../../../heyo-docs.config";
+import { pages as markdownPages } from "virtual:heyo-docs-content/server";
+
+export const prerender = false;
+
+export const POST: APIRoute = ({ request }) => {
+  const apiKey = env.OPENAI_API_KEY;
+  if (!apiKey)
+    return Response.json(
+      { error: "The OPENAI_API_KEY Worker secret is not configured." },
+      { status: 500 },
+    );
+
+  return createAiChatResponse(request, {
+    ai: config.ai,
+    auth: { type: "api-key", token: apiKey },
+    markdownPages,
+    pages: markdownPages.map((page) => ({
+      description: page.description,
+      searchContent: page.raw,
+      slug: page.slug,
+      title: page.title,
+    })),
+    title: config.title,
+  });
+};

package/deployments/cloudflare/next/app/heyo-docs-internal/ai-chat/route.ts

@@ -0,0 +1,25 @@
+import { createAiChatResponse } from "@heyo-sh/heyo-docs/ai";
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+
+import config from "../../../heyo-docs.config";
+import { docsPages, markdownPages } from "../../_heyo-docs/server";
+
+export const runtime = "nodejs";
+
+export async function POST(request: Request) {
+  const { env } = getCloudflareContext();
+  const apiKey = env.OPENAI_API_KEY;
+  if (!apiKey)
+    return Response.json(
+      { error: "The OPENAI_API_KEY Worker secret is not configured." },
+      { status: 500 },
+    );
+
+  return createAiChatResponse(request, {
+    ai: config.ai,
+    auth: { type: "api-key", token: apiKey },
+    markdownPages,
+    pages: docsPages,
+    title: config.title,
+  });
+}

package/deployments/cloudflare/next/cloudflare-env.d.ts

@@ -0,0 +1,4 @@
+/** Cloudflare Worker secret configured with `wrangler secret put`. */
+interface CloudflareEnv {
+  OPENAI_API_KEY: string;
+}

package/deployments/cloudflare/react-router/app/cloudflare-env.d.ts

@@ -0,0 +1,4 @@
+/** Cloudflare Worker secret configured with `wrangler secret put`. */
+interface Env {
+  OPENAI_API_KEY: string;
+}

package/deployments/cloudflare/react-router/app/lib/cloudflare-context.ts

@@ -0,0 +1,4 @@
+import { createContext } from "react-router";
+
+/** Cloudflare bindings supplied to the Worker for the current request. */
+export const cloudflareContext = createContext<Env>();

package/deployments/cloudflare/react-router/app/routes/ai-chat.ts

@@ -0,0 +1,30 @@
+import type { ActionFunctionArgs } from "react-router";
+
+import config from "../../heyo-docs.config";
+import { cloudflareContext } from "../lib/cloudflare-context";
+import { pages } from "virtual:heyo-docs-content";
+import { pages as markdownPages } from "virtual:heyo-docs-content/server";
+
+export async function action({ context, request }: ActionFunctionArgs) {
+  if (request.method !== "POST")
+    return new Response("Method Not Allowed", {
+      headers: { Allow: "POST" },
+      status: 405,
+    });
+
+  const apiKey = context.get(cloudflareContext).OPENAI_API_KEY;
+  if (!apiKey)
+    return Response.json(
+      { error: "The OPENAI_API_KEY Worker secret is not configured." },
+      { status: 500 },
+    );
+
+  const { createAiChatResponse } = await import("@heyo-sh/heyo-docs/ai");
+  return createAiChatResponse(request, {
+    ai: config.ai,
+    auth: { type: "api-key", token: apiKey },
+    markdownPages,
+    pages,
+    title: config.title,
+  });
+}

package/deployments/cloudflare/react-router/workers/app.ts

@@ -1,12 +1,16 @@
 import { createRequestHandler, RouterContextProvider } from "react-router";
 
+import { cloudflareContext } from "../app/lib/cloudflare-context";
+
 const handleRequest = createRequestHandler(
   () => import("virtual:react-router/server-build"),
   import.meta.env.MODE,
 );
 
 export default {
-  fetch(request) {
-    return handleRequest(request, new RouterContextProvider());
+  fetch(request, env) {
+    const context = new RouterContextProvider();
+    context.set(cloudflareContext, env);
+    return handleRequest(request, context);
   },
 } satisfies ExportedHandler<Env>;

package/dist/index.js

@@ -47,7 +47,7 @@ function packageManagerRunCommand(manager, script) {
 // src/project-name.ts
 var PROJECT_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/i;
 function projectNameError(value) {
-  if (!value.trim())
+  if (!value?.trim())
     return "Enter a project name.";
   if (!PROJECT_NAME_PATTERN.test(value))
     return "Use letters, numbers and hyphens only.";
@@ -289,14 +289,12 @@ function parseArguments(argv) {
 }
 async function askQuestions(defaults) {
   p.intro("Create Heyo Docs");
-  const projectName = await p.text({
+  const projectName = promptValue(await p.text({
     message: "Project name",
     placeholder: "my-docs",
     defaultValue: "my-docs",
     validate: projectNameError
-  });
-  if (p.isCancel(projectName))
-    cancelCreation();
+  }));
   const template = await selectAvailable("Template", TEMPLATE_OPTIONS, [
     "react-router",
     "next",
@@ -309,12 +307,10 @@ async function askQuestions(defaults) {
     "moss"
   ]);
   const packageManager = await selectAvailable("Package manager", PACKAGE_MANAGER_OPTIONS, ["bun", "pnpm", "npm", "yarn"], defaults.packageManager);
-  const install = await p.confirm({
+  const install = promptValue(await p.confirm({
     message: "Install dependencies?",
     initialValue: true
-  });
-  if (p.isCancel(install))
-    cancelCreation();
+  }));
   return {
     projectName,
     template,
@@ -334,14 +330,19 @@ async function selectDeployment(template, initialValue) {
 }
 async function selectAvailable(message, options, available, initialValue) {
   for (;; ) {
-    const answer = await p.select({ message, options, initialValue });
-    if (p.isCancel(answer))
-      cancelCreation();
+    const answer = promptValue(await p.select({ message, options, initialValue }));
     if (isOneOf(answer, available))
       return answer;
     p.log.warn("That option is planned but not available in this MVP.");
   }
 }
+function promptValue(value) {
+  if (typeof value !== "symbol")
+    return value;
+  if (p.isCancel(value))
+    cancelCreation();
+  throw new Error("Prompt did not return a value.");
+}
 function isOneOf(value, values) {
   return values.some((candidate) => candidate === value);
 }

package/dist/project-name.d.ts

@@ -1,3 +1,3 @@
-export declare function projectNameError(value: string): string | undefined;
+export declare function projectNameError(value: string | undefined): string | undefined;
 export declare function assertProjectName(value: string): string;
 //# sourceMappingURL=project-name.d.ts.map

package/dist/project-name.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project-name.d.ts","sourceRoot":"","sources":["../src/project-name.ts"],"names":[],"mappings":"AAEA,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIlE;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIvD"}
+{"version":3,"file":"project-name.d.ts","sourceRoot":"","sources":["../src/project-name.ts"],"names":[],"mappings":"AAEA,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,MAAM,GAAG,SAAS,CAIpB;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIvD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyo-sh/create-heyo-docs",
-  "version": "0.4.0",
+  "version": "1.0.1",
   "description": "Create a standalone Heyo Docs documentation project.",
   "homepage": "https://heyo.sh",
   "repository": {
@@ -27,7 +27,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@clack/prompts": "0.10.0"
+    "@clack/prompts": "1.8.0"
   },
   "scripts": {
     "dev": "bun run build --watch",

package/templates/astro/content/configuration.mdx

@@ -66,15 +66,15 @@ sidebar entry should point to a page outside the local documentation.
 
 ## AI chat
 
-Add `ai.chat` to enable a documentation-aware chat. `openai`, `claude`, and `grok`
-use the OpenAI, Anthropic, and xAI adapters respectively. Keep the key in a
-server environment variable; Heyo Docs sends it only from the chat endpoint.
+Add `ai.chat` to enable a documentation-aware chat through [Pi](https://github.com/badlogic/pi-mono).
+Use any provider identifier bundled with the installed Pi version, such as
+`openai`, `anthropic`, `google`, `openrouter`, or `xai`. Authentication stays
+server-only and is supplied by the route that handles the chat request.
 
 <CodeBlock language="ts" title="heyo-docs.config.ts">
   {`ai: {
   chat: {
     provider: "openai",
-    key: process.env.OPENAI_API_KEY!,
     model: "gpt-5-mini",
     variant: "right", // "center" shows the compact prompt first
     icon: "chat",
@@ -85,8 +85,15 @@ server environment variable; Heyo Docs sends it only from the chat endpoint.
 },`}
 </CodeBlock>
 
-`provider`, `key`, and `model` are required. The model must be an actual model
-identifier, not the provider name. `variant` defaults to `right`. `name`
+`provider` and `model` are required. Keep the credential out of this
+configuration and pass it as `auth` to `createAiChatResponse` in the server
+route. Cloudflare routes obtain the key from the Worker `env` binding; Node.js
+routes can read their server environment there. GitHub Copilot and OpenAI Codex
+use `auth: { type: "oauth", getAccessToken }`; Amazon Bedrock uses either
+`{ type: "aws", region?, profile? }` and the AWS credential chain, or
+`{ type: "bedrock-bearer", token, region? }`. The model must be an actual model
+identifier, not the provider name. Amazon Bedrock requires a Node.js chat
+endpoint. `variant` defaults to `right`. `name`
 defaults to `AI`; it is used for the drawer title and the assistant's message
 label. `placeholder` defaults to
 `Ask AI about the docs` and is shared by the compact prompt and drawer input.

package/templates/astro/content/deploying.mdx

@@ -30,6 +30,19 @@ the sitemap, RSS feed, robots file, and AI-facing documentation endpoints.
 Use the equivalent `npm run build`, `pnpm build`, or `yarn build` command
 when the project uses a different package manager.
 
+## Cloudflare secrets
+
+For AI chat, save the provider key as a Worker secret:
+
+<CodeBlock language="bash" title="Terminal">
+  {"bunx wrangler secret put OPENAI_API_KEY"}
+</CodeBlock>
+
+Keep the credential out of `heyo-docs.config.ts`. The Cloudflare overlay reads
+the native Worker `env.OPENAI_API_KEY` binding in the AI route, after the
+request reaches the Worker. It is never part of the documentation build or the
+browser bundle.
+
 <Callout type="tip" title="Set the canonical URL">
   Add the final public origin as <code>siteUrl</code> in
   <code>heyo-docs.config.ts</code> before the first production release. It keeps

package/templates/astro/src/layouts/docs-layout.astro

@@ -188,20 +188,16 @@ const zammadBootstrap = zammad ? zammadBootstrapScript() : undefined;
 <!doctype html>
 <html lang="en">
   <head>
-    {
-      transcendGoogleConsentDefaults && (
-        <script is:inline set:html={transcendGoogleConsentDefaults} />
-      )
-    }
-    {
-      transcend && (
-        <script
-          is:inline
-          data-cfasync={transcend.dataCfasync}
-          src={transcend.src}
-        />
-      )
-    }
+    {transcendGoogleConsentDefaults && (
+      <script is:inline set:html={transcendGoogleConsentDefaults}></script>
+    )}
+    {transcend && (
+      <script
+        is:inline
+        data-cfasync={transcend.dataCfasync}
+        src={transcend.src}
+      ></script>
+    )}
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <meta name="color-scheme" content="light dark" />
@@ -223,334 +219,280 @@ const zammadBootstrap = zammad ? zammadBootstrapScript() : undefined;
     <link rel="icon" href="/favicon-96x96.png" sizes="96x96" type="image/png" />
     <link rel="apple-touch-icon" href="/apple-touch-icon.png" sizes="180x180" />
     <link rel="manifest" href="/site.webmanifest" />
-    {
-      hasChangelog && (
-        <link
-          rel="alternate"
-          href="/rss.xml"
-          type="application/rss+xml"
-          title={`${config.title} updates`}
-        />
-      )
-    }
-    {osano && <script is:inline src={osano.src} />}
-    {
-      googleTagManager && (
-        <script
-          is:inline
-          data-google-tag-manager-container-id={
-            config.integrations.analytics.gtm?.containerId
-          }
-          set:html={googleTagManager}
-        />
-      )
-    }
+    {hasChangelog && (
+      <link
+        rel="alternate"
+        href="/rss.xml"
+        type="application/rss+xml"
+        title={`${config.title} updates`}
+      />
+    )}
+    {osano && <script is:inline src={osano.src}></script>}
+    {googleTagManager && (
+      <script
+        is:inline
+        data-google-tag-manager-container-id={
+          config.integrations.analytics.gtm?.containerId
+        }
+        set:html={googleTagManager}
+      ></script>
+    )}
     <script
       is:inline
       set:html={getThemeScript(THEME_STORAGE_KEY, config.mode)}
-    />
-    {adobe && <script is:inline async src={adobe.src} />}
-    {amplitude && <script is:inline src={amplitude.src} />}
-    {
-      clarity && (
+    ></script>
+    {adobe && <script is:inline async src={adobe.src}></script>}
+    {amplitude && <script is:inline src={amplitude.src}></script>}
+    {clarity && (
+      <script
+        is:inline
+        data-clarity-project-id={
+          config.integrations.analytics.clarity?.projectId
+        }
+        set:html={clarity}
+      ></script>
+    )}
+    {clearbit && <script is:inline src={clearbit.src}></script>}
+    {fathom && (
+      <script
+        is:inline
+        data-site={fathom.siteId}
+        data-spa={fathom.spa}
+        defer={fathom.defer}
+        src={fathom.src}
+      ></script>
+    )}
+    {googleAnalytics && googleAnalyticsBootstrap && (
+      <>
         <script
           is:inline
-          data-clarity-project-id={
-            config.integrations.analytics.clarity?.projectId
+          async={googleAnalytics.async}
+          src={googleAnalytics.src}
+        ></script>
+        <script
+          is:inline
+          data-google-analytics-measurement-id={
+            config.integrations.analytics.ga4?.measurementId
           }
-          set:html={clarity}
-        />
-      )
-    }
-    {clearbit && <script is:inline src={clearbit.src} />}
-    {
-      fathom && (
+          set:html={googleAnalyticsBootstrap}
+        ></script>
+      </>
+    )}
+    {heap && (
+      <script
+        is:inline
+        data-heap-environment-id={
+          config.integrations.analytics.heap?.environmentId
+        }
+        set:html={heap}
+      ></script>
+    )}
+    {hotjar && (
+      <script
+        is:inline
+        data-hotjar-site-id={config.integrations.analytics.hotjar?.siteId}
+        data-hotjar-snippet-version={
+          config.integrations.analytics.hotjar?.snippetVersion
+        }
+        set:html={hotjar}
+      ></script>
+    )}
+    {logRocket && logRocketBootstrap && (
+      <>
         <script
           is:inline
-          data-site={fathom.siteId}
-          data-spa={fathom.spa}
-          defer={fathom.defer}
-          src={fathom.src}
-        />
-      )
-    }
-    {
-      googleAnalytics && googleAnalyticsBootstrap && (
-        <>
-          <script
-            is:inline
-            async={googleAnalytics.async}
-            src={googleAnalytics.src}
-          />
-          <script
-            is:inline
-            data-google-analytics-measurement-id={
-              config.integrations.analytics.ga4?.measurementId
-            }
-            set:html={googleAnalyticsBootstrap}
-          />
-        </>
-      )
-    }
-    {
-      heap && (
+          crossorigin={logRocket.crossOrigin}
+          src={logRocket.src}
+        ></script>
         <script
           is:inline
-          data-heap-environment-id={
-            config.integrations.analytics.heap?.environmentId
-          }
-          set:html={heap}
-        />
-      )
-    }
-    {
-      hotjar && (
+          data-logrocket-app-id={config.integrations.analytics.logrocket?.appId}
+          set:html={logRocketBootstrap}
+        ></script>
+      </>
+    )}
+    {mixpanel && mixpanelBootstrap && (
+      <>
+        <script is:inline src={mixpanel.src}></script>
         <script
           is:inline
-          data-hotjar-site-id={config.integrations.analytics.hotjar?.siteId}
-          data-hotjar-snippet-version={
-            config.integrations.analytics.hotjar?.snippetVersion
+          data-mixpanel-project-token={
+            config.integrations.analytics.mixpanel?.projectToken
           }
-          set:html={hotjar}
-        />
-      )
-    }
-    {
-      logRocket && logRocketBootstrap && (
-        <>
-          <script
-            is:inline
-            crossorigin={logRocket.crossOrigin}
-            src={logRocket.src}
-          />
-          <script
-            is:inline
-            data-logrocket-app-id={
-              config.integrations.analytics.logrocket?.appId
-            }
-            set:html={logRocketBootstrap}
-          />
-        </>
-      )
-    }
-    {
-      mixpanel && mixpanelBootstrap && (
-        <>
-          <script is:inline src={mixpanel.src} />
-          <script
-            is:inline
-            data-mixpanel-project-token={
-              config.integrations.analytics.mixpanel?.projectToken
-            }
-            set:html={mixpanelBootstrap}
-          />
-        </>
-      )
-    }
-    {
-      openpanel && openpanelBootstrap && (
-        <>
-          <script
-            is:inline
-            data-openpanel-api-url={
-              config.integrations.analytics.openpanel?.apiUrl
-            }
-            data-openpanel-client-id={
-              config.integrations.analytics.openpanel?.clientId
-            }
-            set:html={openpanelBootstrap}
-          />
-          <script
-            is:inline
-            async={openpanel.async}
-            defer={openpanel.defer}
-            src={openpanel.src}
-          />
-        </>
-      )
-    }
-    {
-      openReplay && (
+          set:html={mixpanelBootstrap}
+        ></script>
+      </>
+    )}
+    {openpanel && openpanelBootstrap && (
+      <>
         <script
           is:inline
-          data-openreplay-ingest-point={
-            config.integrations.analytics.openreplay?.ingestPoint
+          data-openpanel-api-url={
+            config.integrations.analytics.openpanel?.apiUrl
           }
-          data-openreplay-project-key={
-            config.integrations.analytics.openreplay?.projectKey
+          data-openpanel-client-id={
+            config.integrations.analytics.openpanel?.clientId
           }
-          set:html={openReplay}
-        />
-      )
-    }
-    {
-      pirsch && (
-        <script
-          is:inline
-          data-code={pirsch.code}
-          defer={pirsch.defer}
-          src={pirsch.src}
-        />
-      )
-    }
-    {
-      plausible && (
-        <script
-          is:inline
-          data-domain={plausible.domain}
-          defer={plausible.defer}
-          src={plausible.src}
-        />
-      )
-    }
-    {
-      posthog && posthogBootstrap && posthogHost && (
-        <>
-          <script is:inline src={posthog.src} />
-          <script
-            is:inline
-            data-posthog-api-host={posthogHost}
-            data-posthog-project-api-key={
-              config.integrations.analytics.posthog?.projectApiKey
-            }
-            set:html={posthogBootstrap}
-          />
-        </>
-      )
-    }
-    {
-      rybbit && (
-        <script
-          is:inline
-          data-site-id={rybbit.siteId}
-          defer={rybbit.defer}
-          src={rybbit.src}
-        />
-      )
-    }
-    {
-      umami && (
+          set:html={openpanelBootstrap}
+        ></script>
         <script
           is:inline
-          data-website-id={umami.websiteId}
-          defer={umami.defer}
-          src={umami.src}
-        />
-      )
-    }
-    {
-      chaskiq && (
+          async={openpanel.async}
+          defer={openpanel.defer}
+          src={openpanel.src}
+        ></script>
+      </>
+    )}
+    {openReplay && (
+      <script
+        is:inline
+        data-openreplay-ingest-point={
+          config.integrations.analytics.openreplay?.ingestPoint
+        }
+        data-openreplay-project-key={
+          config.integrations.analytics.openreplay?.projectKey
+        }
+        set:html={openReplay}
+      ></script>
+    )}
+    {pirsch && (
+      <script
+        is:inline
+        data-code={pirsch.code}
+        defer={pirsch.defer}
+        src={pirsch.src}
+      ></script>
+    )}
+    {plausible && (
+      <script
+        is:inline
+        data-domain={plausible.domain}
+        defer={plausible.defer}
+        src={plausible.src}
+      ></script>
+    )}
+    {posthog && posthogBootstrap && posthogHost && (
+      <>
+        <script is:inline src={posthog.src}></script>
         <script
           is:inline
-          data-chaskiq-app-id={config.integrations.support.chaskiq?.appId}
-          data-chaskiq-base-url={config.integrations.support.chaskiq?.baseUrl}
-          data-chaskiq-ws-url={config.integrations.support.chaskiq?.wsUrl}
-          set:html={chaskiq}
-        />
-      )
-    }
-    {
-      papercups && (
-        <script
-          is:inline
-          data-papercups-base-url={
-            config.integrations.support.papercups?.baseUrl
+          data-posthog-api-host={posthogHost}
+          data-posthog-project-api-key={
+            config.integrations.analytics.posthog?.projectApiKey
           }
-          data-papercups-inbox={config.integrations.support.papercups?.inbox}
-          data-papercups-token={config.integrations.support.papercups?.token}
-          set:html={papercups}
-        />
-      )
-    }
-    {
-      typebot && (
-        <script
-          is:inline
-          data-heyo-typebot
-          data-typebot-api-host={config.integrations.support.typebot?.apiHost}
-          data-typebot-id={config.integrations.support.typebot?.typebot}
-          set:html={typebot}
-          type="module"
-        />
-      )
-    }
-    <script is:inline type="application/ld+json" set:html={jsonLd} />
+          set:html={posthogBootstrap}
+        ></script>
+      </>
+    )}
+    {rybbit && (
+      <script
+        is:inline
+        data-site-id={rybbit.siteId}
+        defer={rybbit.defer}
+        src={rybbit.src}
+      ></script>
+    )}
+    {umami && (
+      <script
+        is:inline
+        data-website-id={umami.websiteId}
+        defer={umami.defer}
+        src={umami.src}
+      ></script>
+    )}
+    {chaskiq && (
+      <script
+        is:inline
+        data-chaskiq-app-id={config.integrations.support.chaskiq?.appId}
+        data-chaskiq-base-url={config.integrations.support.chaskiq?.baseUrl}
+        data-chaskiq-ws-url={config.integrations.support.chaskiq?.wsUrl}
+        set:html={chaskiq}
+      ></script>
+    )}
+    {papercups && (
+      <script
+        is:inline
+        data-papercups-base-url={config.integrations.support.papercups?.baseUrl}
+        data-papercups-inbox={config.integrations.support.papercups?.inbox}
+        data-papercups-token={config.integrations.support.papercups?.token}
+        set:html={papercups}
+      ></script>
+    )}
+    {typebot && (
+      <script
+        is:inline
+        data-heyo-typebot
+        data-typebot-api-host={config.integrations.support.typebot?.apiHost}
+        data-typebot-id={config.integrations.support.typebot?.typebot}
+        set:html={typebot}
+        type="module"
+      ></script>
+    )}
+    <script is:inline type="application/ld+json" set:html={jsonLd}></script>
   </head>
   <body>
-    {
-      googleTagManagerNoScript && (
-        <noscript>
-          <iframe
-            height="0"
-            src={googleTagManagerNoScript}
-            style="display:none;visibility:hidden"
-            title="Google Tag Manager"
-            width="0"
-          />
-        </noscript>
-      )
-    }
+    {googleTagManagerNoScript && (
+      <noscript>
+        <iframe
+          height="0"
+          src={googleTagManagerNoScript}
+          style="display:none;visibility:hidden"
+          title="Google Tag Manager"
+          width="0"
+        ></iframe>
+      </noscript>
+    )}
     <slot />
-    {
-      swetrix && swetrixBootstrap && (
-        <>
-          <script is:inline defer={swetrix.defer} src={swetrix.src} />
-          <script
-            is:inline
-            data-swetrix-api-url={config.integrations.analytics.swetrix?.apiUrl}
-            data-swetrix-project-id={
-              config.integrations.analytics.swetrix?.projectId
-            }
-            set:html={swetrixBootstrap}
-          />
-        </>
-      )
-    }
-    {
-      intercom && (
+    {swetrix && swetrixBootstrap && (
+      <>
+        <script is:inline defer={swetrix.defer} src={swetrix.src}></script>
         <script
           is:inline
-          data-intercom-app-id={config.integrations.support.intercom?.appId}
-          data-intercom-api-base={config.integrations.support.intercom?.apiBase}
-          set:html={intercom}
-        />
-      )
-    }
-    {
-      front && frontBootstrap && (
-        <>
-          <script is:inline src={front.src} />
-          <script
-            is:inline
-            data-front-chat-id={config.integrations.support.front?.chatId}
-            set:html={frontBootstrap}
-          />
-        </>
-      )
-    }
-    {
-      chatwoot && (
+          data-swetrix-api-url={config.integrations.analytics.swetrix?.apiUrl}
+          data-swetrix-project-id={
+            config.integrations.analytics.swetrix?.projectId
+          }
+          set:html={swetrixBootstrap}
+        ></script>
+      </>
+    )}
+    {intercom && (
+      <script
+        is:inline
+        data-intercom-app-id={config.integrations.support.intercom?.appId}
+        data-intercom-api-base={config.integrations.support.intercom?.apiBase}
+        set:html={intercom}
+      ></script>
+    )}
+    {front && frontBootstrap && (
+      <>
+        <script is:inline src={front.src}></script>
         <script
           is:inline
-          data-chatwoot-base-url={config.integrations.support.chatwoot?.baseUrl}
-          data-chatwoot-website-token={
-            config.integrations.support.chatwoot?.websiteToken
-          }
-          set:html={chatwoot}
-        />
-      )
-    }
-    {
-      zammad && zammadBootstrap && (
-        <>
-          <script is:inline src={zammad.src} />
-          <script
-            is:inline
-            data-zammad-chat-id={config.integrations.support.zammad?.chatId}
-            set:html={zammadBootstrap}
-          />
-        </>
-      )
-    }
+          data-front-chat-id={config.integrations.support.front?.chatId}
+          set:html={frontBootstrap}
+        ></script>
+      </>
+    )}
+    {chatwoot && (
+      <script
+        is:inline
+        data-chatwoot-base-url={config.integrations.support.chatwoot?.baseUrl}
+        data-chatwoot-website-token={
+          config.integrations.support.chatwoot?.websiteToken
+        }
+        set:html={chatwoot}
+      ></script>
+    )}
+    {zammad && zammadBootstrap && (
+      <>
+        <script is:inline src={zammad.src}></script>
+        <script
+          is:inline
+          data-zammad-chat-id={config.integrations.support.zammad?.chatId}
+          set:html={zammadBootstrap}
+        ></script>
+      </>
+    )}
   </body>
 </html>

package/templates/astro/src/pages/heyo-docs-internal/ai-chat.ts

@@ -6,9 +6,17 @@ import { pages as markdownPages } from "virtual:heyo-docs-content/server";
 
 export const prerender = false;
 
-export const POST: APIRoute = ({ request }) =>
-  createAiChatResponse(request, {
+export const POST: APIRoute = ({ request }) => {
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey)
+    return Response.json(
+      { error: "OPENAI_API_KEY is not configured." },
+      { status: 500 },
+    );
+
+  return createAiChatResponse(request, {
     ai: config.ai,
+    auth: { type: "api-key", token: apiKey },
     markdownPages,
     pages: markdownPages.map((page) => ({
       description: page.description,
@@ -18,3 +26,4 @@ export const POST: APIRoute = ({ request }) =>
     })),
     title: config.title,
   });
+};

package/templates/next/app/heyo-docs-internal/ai-chat/route.ts

@@ -6,8 +6,16 @@ import { docsPages, markdownPages } from "../../_heyo-docs/server";
 export const runtime = "nodejs";
 
 export async function POST(request: Request) {
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey)
+    return Response.json(
+      { error: "OPENAI_API_KEY is not configured." },
+      { status: 500 },
+    );
+
   return createAiChatResponse(request, {
     ai: config.ai,
+    auth: { type: "api-key", token: apiKey },
     markdownPages,
     pages: docsPages,
     title: config.title,

package/templates/next/content/configuration.mdx

@@ -66,15 +66,15 @@ sidebar entry should point to a page outside the local documentation.
 
 ## AI chat
 
-Add `ai.chat` to enable a documentation-aware chat. `openai`, `claude`, and `grok`
-use the OpenAI, Anthropic, and xAI adapters respectively. Keep the key in a
-server environment variable; Heyo Docs sends it only from the chat endpoint.
+Add `ai.chat` to enable a documentation-aware chat through [Pi](https://github.com/badlogic/pi-mono).
+Use any provider identifier bundled with the installed Pi version, such as
+`openai`, `anthropic`, `google`, `openrouter`, or `xai`. Authentication stays
+server-only and is supplied by the route that handles the chat request.
 
 <CodeBlock language="ts" title="heyo-docs.config.ts">
   {`ai: {
   chat: {
     provider: "openai",
-    key: process.env.OPENAI_API_KEY!,
     model: "gpt-5-mini",
     variant: "right", // "center" shows the compact prompt first
     icon: "chat",
@@ -85,8 +85,15 @@ server environment variable; Heyo Docs sends it only from the chat endpoint.
 },`}
 </CodeBlock>
 
-`provider`, `key`, and `model` are required. The model must be an actual model
-identifier, not the provider name. `variant` defaults to `right`. `name`
+`provider` and `model` are required. Keep the credential out of this
+configuration and pass it as `auth` to `createAiChatResponse` in the server
+route. Cloudflare routes obtain the key from the Worker `env` binding; Node.js
+routes can read their server environment there. GitHub Copilot and OpenAI Codex
+use `auth: { type: "oauth", getAccessToken }`; Amazon Bedrock uses either
+`{ type: "aws", region?, profile? }` and the AWS credential chain, or
+`{ type: "bedrock-bearer", token, region? }`. The model must be an actual model
+identifier, not the provider name. Amazon Bedrock requires a Node.js chat
+endpoint. `variant` defaults to `right`. `name`
 defaults to `AI`; it is used for the drawer title and the assistant's message
 label. `placeholder` defaults to
 `Ask AI about the docs` and is shared by the compact prompt and drawer input.

package/templates/next/content/deploying.mdx

@@ -30,6 +30,19 @@ the sitemap, RSS feed, robots file, and AI-facing documentation endpoints.
 Use the equivalent `npm run build`, `pnpm build`, or `yarn build` command
 when the project uses a different package manager.
 
+## Cloudflare secrets
+
+For AI chat, save the provider key as a Worker secret:
+
+<CodeBlock language="bash" title="Terminal">
+  {"bunx wrangler secret put OPENAI_API_KEY"}
+</CodeBlock>
+
+Keep the credential out of `heyo-docs.config.ts`. The Cloudflare overlay reads
+the native Worker `env.OPENAI_API_KEY` binding in the AI route, after the
+request reaches the Worker. It is never part of the documentation build or the
+browser bundle.
+
 <Callout type="tip" title="Set the canonical URL">
   Add the final public origin as <code>siteUrl</code> in
   <code>heyo-docs.config.ts</code> before the first production release. It keeps

package/templates/react-router/app/routes/ai-chat.ts

@@ -1,4 +1,3 @@
-import { createAiChatResponse } from "@heyo-sh/heyo-docs/ai";
 import type { ActionFunctionArgs } from "react-router";
 
 import config from "../../heyo-docs.config";
@@ -12,8 +11,17 @@ export async function action({ request }: ActionFunctionArgs) {
       status: 405,
     });
 
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey)
+    return Response.json(
+      { error: "OPENAI_API_KEY is not configured." },
+      { status: 500 },
+    );
+
+  const { createAiChatResponse } = await import("@heyo-sh/heyo-docs/ai");
   return createAiChatResponse(request, {
     ai: config.ai,
+    auth: { type: "api-key", token: apiKey },
     markdownPages,
     pages,
     title: config.title,

package/templates/react-router/content/configuration.mdx

@@ -66,15 +66,15 @@ sidebar entry should point to a page outside the local documentation.
 
 ## AI chat
 
-Add `ai.chat` to enable a documentation-aware chat. `openai`, `claude`, and `grok`
-use the OpenAI, Anthropic, and xAI adapters respectively. Keep the key in a
-server environment variable; Heyo Docs sends it only from the chat endpoint.
+Add `ai.chat` to enable a documentation-aware chat through [Pi](https://github.com/badlogic/pi-mono).
+Use any provider identifier bundled with the installed Pi version, such as
+`openai`, `anthropic`, `google`, `openrouter`, or `xai`. Authentication stays
+server-only and is supplied by the route that handles the chat request.
 
 <CodeBlock language="ts" title="heyo-docs.config.ts">
   {`ai: {
   chat: {
     provider: "openai",
-    key: process.env.OPENAI_API_KEY!,
     model: "gpt-5-mini",
     variant: "right", // "center" shows the compact prompt first
     icon: "chat",
@@ -85,8 +85,15 @@ server environment variable; Heyo Docs sends it only from the chat endpoint.
 },`}
 </CodeBlock>
 
-`provider`, `key`, and `model` are required. The model must be an actual model
-identifier, not the provider name. `variant` defaults to `right`. `name`
+`provider` and `model` are required. Keep the credential out of this
+configuration and pass it as `auth` to `createAiChatResponse` in the server
+route. Cloudflare routes obtain the key from the Worker `env` binding; Node.js
+routes can read their server environment there. GitHub Copilot and OpenAI Codex
+use `auth: { type: "oauth", getAccessToken }`; Amazon Bedrock uses either
+`{ type: "aws", region?, profile? }` and the AWS credential chain, or
+`{ type: "bedrock-bearer", token, region? }`. The model must be an actual model
+identifier, not the provider name. Amazon Bedrock requires a Node.js chat
+endpoint. `variant` defaults to `right`. `name`
 defaults to `AI`; it is used for the drawer title and the assistant's message
 label. `placeholder` defaults to
 `Ask AI about the docs` and is shared by the compact prompt and drawer input.

package/templates/react-router/content/deploying.mdx

@@ -30,6 +30,19 @@ the sitemap, RSS feed, robots file, and AI-facing documentation endpoints.
 Use the equivalent `npm run build`, `pnpm build`, or `yarn build` command
 when the project uses a different package manager.
 
+## Cloudflare secrets
+
+For AI chat, save the provider key as a Worker secret:
+
+<CodeBlock language="bash" title="Terminal">
+  {"bunx wrangler secret put OPENAI_API_KEY"}
+</CodeBlock>
+
+Keep the credential out of `heyo-docs.config.ts`. The Cloudflare overlay reads
+the native Worker `env.OPENAI_API_KEY` binding in the AI route, after the
+request reaches the Worker. It is never part of the documentation build or the
+browser bundle.
+
 <Callout type="tip" title="Set the canonical URL">
   Add the final public origin as <code>siteUrl</code> in
   <code>heyo-docs.config.ts</code> before the first production release. It keeps