@vercel/geistdocs 2.7.10 → 2.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (128) hide show
  1. package/dist/assets/icons/icon-fullscreen-close.d.ts +26 -0
  2. package/dist/assets/icons/icon-fullscreen-close.d.ts.map +1 -0
  3. package/dist/assets/icons/icon-fullscreen-close.js +25 -0
  4. package/dist/assets/icons/icon-fullscreen.d.ts +26 -0
  5. package/dist/assets/icons/icon-fullscreen.d.ts.map +1 -0
  6. package/dist/assets/icons/icon-fullscreen.js +25 -0
  7. package/dist/assets/icons/icon-thumb-down.d.ts +26 -0
  8. package/dist/assets/icons/icon-thumb-down.d.ts.map +1 -0
  9. package/dist/assets/icons/icon-thumb-down.js +25 -0
  10. package/dist/assets/icons/index.d.ts +3 -0
  11. package/dist/assets/icons/index.d.ts.map +1 -1
  12. package/dist/assets/icons/index.js +3 -0
  13. package/dist/cli/index.js +1 -1
  14. package/dist/config.d.ts +67 -3
  15. package/dist/config.d.ts.map +1 -1
  16. package/dist/controls.d.ts +23 -1
  17. package/dist/controls.d.ts.map +1 -1
  18. package/dist/controls.js +44 -3
  19. package/dist/footer.js +1 -1
  20. package/dist/internal/chat/activity.d.ts +5 -1
  21. package/dist/internal/chat/activity.d.ts.map +1 -1
  22. package/dist/internal/chat/activity.js +11 -4
  23. package/dist/internal/chat/chat-user.d.ts +12 -0
  24. package/dist/internal/chat/chat-user.d.ts.map +1 -0
  25. package/dist/internal/chat/chat-user.js +27 -0
  26. package/dist/internal/chat/commands.d.ts +91 -0
  27. package/dist/internal/chat/commands.d.ts.map +1 -0
  28. package/dist/internal/chat/commands.js +165 -0
  29. package/dist/internal/chat/context.d.ts +49 -2
  30. package/dist/internal/chat/context.d.ts.map +1 -1
  31. package/dist/internal/chat/context.js +57 -4
  32. package/dist/internal/chat/message-actions.d.ts +15 -0
  33. package/dist/internal/chat/message-actions.d.ts.map +1 -0
  34. package/dist/internal/chat/message-actions.js +113 -0
  35. package/dist/internal/chat/message-feedback.d.ts +68 -0
  36. package/dist/internal/chat/message-feedback.d.ts.map +1 -0
  37. package/dist/internal/chat/message-feedback.js +188 -0
  38. package/dist/internal/chat/message-metadata.d.ts.map +1 -1
  39. package/dist/internal/chat/message-metadata.js +7 -1
  40. package/dist/internal/chat/message-text.d.ts +9 -0
  41. package/dist/internal/chat/message-text.d.ts.map +1 -0
  42. package/dist/internal/chat/message-text.js +15 -0
  43. package/dist/internal/chat/message.d.ts +4 -2
  44. package/dist/internal/chat/message.d.ts.map +1 -1
  45. package/dist/internal/chat/message.js +8 -1
  46. package/dist/internal/chat/options.d.ts +94 -0
  47. package/dist/internal/chat/options.d.ts.map +1 -0
  48. package/dist/internal/chat/options.js +171 -0
  49. package/dist/internal/chat/page-attachment.d.ts +12 -0
  50. package/dist/internal/chat/page-attachment.d.ts.map +1 -0
  51. package/dist/internal/chat/page-attachment.js +18 -0
  52. package/dist/internal/chat/session-provider.d.ts +33 -0
  53. package/dist/internal/chat/session-provider.d.ts.map +1 -0
  54. package/dist/internal/chat/session-provider.js +138 -0
  55. package/dist/internal/chat/session.d.ts +60 -0
  56. package/dist/internal/chat/session.d.ts.map +1 -0
  57. package/dist/internal/chat/session.js +85 -0
  58. package/dist/internal/chat/shell.d.ts.map +1 -1
  59. package/dist/internal/chat/shell.js +86 -157
  60. package/dist/internal/chat/use-chat-commands.d.ts +28 -0
  61. package/dist/internal/chat/use-chat-commands.d.ts.map +1 -0
  62. package/dist/internal/chat/use-chat-commands.js +62 -0
  63. package/dist/internal/chat/user-avatar.d.ts +7 -0
  64. package/dist/internal/chat/user-avatar.d.ts.map +1 -0
  65. package/dist/internal/chat/user-avatar.js +27 -0
  66. package/dist/internal/eve-agent-session-cookie.d.ts +68 -0
  67. package/dist/internal/eve-agent-session-cookie.d.ts.map +1 -0
  68. package/dist/internal/eve-agent-session-cookie.js +164 -0
  69. package/dist/internal/eve-agent-session.d.ts +9 -7
  70. package/dist/internal/eve-agent-session.d.ts.map +1 -1
  71. package/dist/internal/eve-agent-session.js +10 -13
  72. package/dist/internal/eve-agent.d.ts +96 -24
  73. package/dist/internal/eve-agent.d.ts.map +1 -1
  74. package/dist/internal/eve-agent.js +74 -51
  75. package/dist/internal/feedback-action.d.ts +14 -0
  76. package/dist/internal/feedback-action.d.ts.map +1 -1
  77. package/dist/internal/feedback-action.js +37 -5
  78. package/dist/internal/mdx-to-markdown.d.ts.map +1 -1
  79. package/dist/internal/mdx-to-markdown.js +226 -19
  80. package/dist/internal/page-actions-client.d.ts +9 -0
  81. package/dist/internal/page-actions-client.d.ts.map +1 -1
  82. package/dist/internal/page-actions-client.js +8 -4
  83. package/dist/internal/provider-client.d.ts.map +1 -1
  84. package/dist/internal/provider-client.js +10 -4
  85. package/dist/internal/use-mobile.d.ts +7 -0
  86. package/dist/internal/use-mobile.d.ts.map +1 -1
  87. package/dist/internal/use-mobile.js +17 -1
  88. package/dist/internal/webmcp-client.d.ts.map +1 -1
  89. package/dist/internal/webmcp-client.js +13 -3
  90. package/dist/internal/webmcp.d.ts +5 -1
  91. package/dist/internal/webmcp.d.ts.map +1 -1
  92. package/dist/internal/webmcp.js +31 -1
  93. package/dist/pages/changelog.d.ts.map +1 -1
  94. package/dist/pages/changelog.js +4 -0
  95. package/dist/pages/docs.d.ts.map +1 -1
  96. package/dist/pages/docs.js +2 -0
  97. package/dist/routes/chat.d.ts +83 -5
  98. package/dist/routes/chat.d.ts.map +1 -1
  99. package/dist/routes/chat.js +517 -80
  100. package/dist/routes/discovery.d.ts +1 -1
  101. package/dist/routes/discovery.d.ts.map +1 -1
  102. package/dist/routes/discovery.js +7 -11
  103. package/dist/routes/openapi.d.ts.map +1 -1
  104. package/dist/routes/openapi.js +47 -25
  105. package/docs/agents.md +3 -3
  106. package/docs/llms.txt +634 -37
  107. package/docs/manifest.json +3 -3
  108. package/docs/pages/agent-readiness.md +1 -1
  109. package/docs/pages/ask-ai.md +570 -26
  110. package/docs/pages/configuration.md +21 -1
  111. package/docs/pages/env.md +17 -3
  112. package/docs/pages/feedback.md +4 -0
  113. package/docs/pages/webmcp.md +18 -3
  114. package/docs/sitemap.md +1 -1
  115. package/package.json +1 -2
  116. package/template/.env.example +5 -0
  117. package/template/AGENTS.md +2 -0
  118. package/template/content/docs/agent-readiness.mdx +1 -1
  119. package/template/content/docs/ask-ai.cn.mdx +466 -15
  120. package/template/content/docs/ask-ai.mdx +570 -26
  121. package/template/content/docs/configuration.cn.mdx +39 -0
  122. package/template/content/docs/configuration.mdx +21 -1
  123. package/template/content/docs/env.cn.mdx +15 -1
  124. package/template/content/docs/env.mdx +18 -4
  125. package/template/content/docs/feedback.cn.mdx +4 -0
  126. package/template/content/docs/feedback.mdx +4 -0
  127. package/template/content/docs/webmcp.mdx +18 -3
  128. package/template/package.json +1 -2
package/docs/llms.txt CHANGED
@@ -1,13 +1,13 @@
1
1
  # Geistdocs Package Documentation
2
2
 
3
- These docs are bundled with `@vercel/geistdocs` 2.7.10.
3
+ These docs are bundled with `@vercel/geistdocs` 2.9.0.
4
4
  They describe how to build package-backed Geistdocs sites and how to use the package APIs from generated project adapters.
5
5
 
6
6
  ## Documentation Index
7
7
 
8
8
  - [Overview](pages/index.md): Geistdocs is a packaged documentation system for creating Next.js and Fumadocs sites with shared runtime features.
9
9
  - [Getting Started](pages/getting-started.md): Create a Geistdocs project, run it locally, and edit your first documentation page.
10
- - [Environment Variables](pages/env.md): Environment variables required by Geistdocs for AI chat, Mixedbread retrieval, proxy mode, and production URL configuration.
10
+ - [Environment Variables](pages/env.md): Environment variables required by Geistdocs for AI chat, Mixedbread retrieval, proxy mode, eve agent session cookies, and production URL configuration.
11
11
  - [Deploy to Vercel](pages/deployment.md): Deploy a Geistdocs site to Vercel with the required project settings and environment variables.
12
12
  - [Migrate to Geistdocs](pages/migration.md): Move an existing documentation site to @vercel/geistdocs while keeping local content, routing, middleware behavior, and AI-readable surfaces intact.
13
13
  - [Choose a Geistdocs package](pages/packages.md): Use the public package by default and the private package only where restricted Vercel npm dependencies are already available.
@@ -54,7 +54,7 @@ They describe how to build package-backed Geistdocs sites and how to use the pac
54
54
  - [Toggle](pages/components/toggle.md): Toggle is the provider-backed replacement for the former Switch export.
55
55
  - [Tooltip](pages/components/tooltip.md): Wrap controls with provider-backed Tooltip content outside MDX.
56
56
  - [Video](pages/components/video.md): Use Video for embedded video sources inside React UI or authored MDX.
57
- - [WebMCP](pages/webmcp.md): Expose documentation search and page reading to browser agents.
57
+ - [WebMCP](pages/webmcp.md): Expose documentation search, page reading, and Ask AI to browser agents.
58
58
 
59
59
  ---
60
60
 
@@ -326,7 +326,7 @@ Then follow [Deploy to Vercel](/docs/deployment), including environment-variable
326
326
  title: Environment Variables
327
327
  description: Learn about the environment variables used in Geistdocs
328
328
  type: reference
329
- summary: Environment variables required by Geistdocs for AI chat, Mixedbread retrieval, proxy mode, and production URL configuration.
329
+ summary: Environment variables required by Geistdocs for AI chat, Mixedbread retrieval, proxy mode, eve agent session cookies, and production URL configuration.
330
330
  url: /docs/env
331
331
  source: apps/template/content/docs/env.mdx
332
332
  prerequisites:
@@ -338,9 +338,9 @@ related:
338
338
 
339
339
  # Environment Variables
340
340
 
341
- Geistdocs uses environment variables to configure Ask AI, optional Mixedbread retrieval, optional Vertex-backed proxy mode, and production URL behavior.
341
+ Geistdocs uses environment variables to configure Ask AI, optional Mixedbread retrieval, optional Vertex-backed proxy mode, eve agent session cookie signing, and production URL behavior.
342
342
 
343
- Review this Geistdocs project and help me configure the required environment variables. Check whether `AI_GATEWAY_API_KEY`, `MXBAI_API_KEY`, `MXBAI_STORE_ID`, `GEISTDOCS_CHAT_PROXY_URL`, and `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL` are needed for the features I enabled, then tell me where to set them locally and on Vercel.
343
+ Review this Geistdocs project and help me configure the required environment variables. Check whether `AI_GATEWAY_API_KEY`, `MXBAI_API_KEY`, `MXBAI_STORE_ID`, `GEISTDOCS_CHAT_PROXY_URL`, `GEISTDOCS_CHAT_SECRET`, and `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL` are needed for the features I enabled, then tell me where to set them locally and on Vercel.
344
344
 
345
345
  ## `AI_GATEWAY_API_KEY`
346
346
 
@@ -389,6 +389,20 @@ To route Ask AI through Vertex:
389
389
 
390
390
  The Vertex deployment does not need a Geistdocs-specific environment variable. Access is controlled by Trusted Sources and the OIDC token forwarded by the platform proxy.
391
391
 
392
+ ## `GEISTDOCS_CHAT_SECRET`
393
+
394
+ A server-only secret that signs the httpOnly cookie binding each reader's browser to its eve agent session. Set it when `ai.eveAgent` is configured so Ask AI can continue one eve session across turns and prewarm sessions. The chat route only contacts a session named by a cookie that verifies with this secret, so a reader can't point the chat route at another reader's eve session, and page scripts can't read the session ID.
395
+
396
+ The secret must be at least 32 bytes. Generate one with:
397
+
398
+ ```bash title="Terminal"
399
+ openssl rand -base64 32
400
+ ```
401
+
402
+ Add it to your site's Vercel project environment variables for the Production and Preview environments, and to `.env.local` for local development. Use a separate secret for each docs site. An existing base64-encoded 32-byte secret (44 characters) also works, because Geistdocs uses the value as-is and signs with its own versioned prefix. Rotating the secret invalidates existing session cookies, so each reader's next message starts a new eve session with the conversation inlined.
403
+
404
+ Without this variable, eve agent mode starts a new eve session on every turn with the prior conversation inlined, refuses prewarm requests, and logs a warning. A value shorter than 32 bytes throws when the chat route loads. Pass the `eveAgent.secret` option to `createChatRoute` to supply the secret another way. Never expose it with a `NEXT_PUBLIC_` prefix or put it in `geistdocs.tsx`. Read [Ask AI](/docs/ask-ai#keep-eve-sessions-across-turns-with-geistdocs_chat_secret) for the full behavior.
405
+
392
406
  ## `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL`
393
407
 
394
408
  The production URL of the Geistdocs site. Geistdocs uses it for canonical and Open Graph metadata, product JSON-LD, `sitemap.xml`, `robots.txt`, and RSS links. Vercel sets this variable automatically.
@@ -1324,7 +1338,27 @@ export const ai = {
1324
1338
 
1325
1339
  Set `eveAgent.prewarm` only when the agent runs eve 0.59 or newer and allocating an empty durable session as Ask AI loads is appropriate for the site.
1326
1340
 
1327
- See [Ask AI](/docs/ask-ai) for the full eve agent mode behavior, including authentication. Read [Improve Ask AI answers with Mixedbread](/docs/mixedbread-retrieval) before enabling semantic retrieval.
1341
+ The `ai` config also controls the chat panel and its route:
1342
+
1343
+ | Option | Type | Default | Description |
1344
+ | ------------------------ | --------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------- |
1345
+ | `endpoint` | `string` | `"/api/chat"` | App-local path of the chat route. `basePath` is added automatically. Invalid paths throw. |
1346
+ | `title` | `string` | `"Ask AI"` | Chat panel heading and accessible label. |
1347
+ | `suggestions` | `(string \| { text: string; icon?: ReactNode })[]` | `[]` | Suggested prompts. The first four distinct prompts are shown, and strings render without an icon. |
1348
+ | `history.retentionDays` | `number` | `30` | Days a stored conversation is kept after its most recent message. `0` stores no history, and `Infinity` never expires it. |
1349
+ | `messageFeedback` | `boolean` | `false` | Show thumbs up and thumbs down buttons on finished answers and send votes to the Geistdocs feedback service. |
1350
+ | `toolLabels` | `Record<string, string>` | `{}` | Activity label shown while a named tool runs, such as `{ web_search: "Searching..." }`. Other tools show `Running <tool name>...`. |
1351
+
1352
+ ```tsx title="geistdocs.tsx"
1353
+ export const ai = {
1354
+ endpoint: "/api/ai-chat",
1355
+ title: "Ask Acme AI",
1356
+ history: { retentionDays: 7 },
1357
+ messageFeedback: true,
1358
+ };
1359
+ ```
1360
+
1361
+ See [Ask AI](/docs/ask-ai) for the full eve agent mode behavior, including authentication, for moving the chat route adapter when you set `endpoint`, for what a `messageFeedback` vote sends, and for matching a production Vertex or eve setup with `toolLabels` and the server-only `createChatRoute` options. Read [Improve Ask AI answers with Mixedbread](/docs/mixedbread-retrieval) before enabling semantic retrieval.
1328
1362
 
1329
1363
  Use [Versioned docs](/docs/versioned-docs) for versioned source setup and [Proxy and markdown routes](/docs/proxy) for route mappings.
1330
1364
 
@@ -3757,7 +3791,7 @@ export const agent = {
3757
3791
 
3758
3792
  The generated OpenAPI 3.1 document states that it describes the documentation site and not the product, links the product spec when `openApiUrl` is set, and lists the languages the site serves. `/agents.md` renders `siteOpenApiUrl` as a separate "Documentation site API" link so agents do not confuse the two.
3759
3793
 
3760
- The document always lists the Markdown discovery routes (`/agents.md`, `/sitemap.md`, `/llms.txt`, and page-level `.md`), so keep those route files mounted. `/api/search` and `/api/chat` follow `search.enabled` and `ai.enabled`; pass `endpoints: { chat: false }` or `endpoints: { search: false }` to `createOpenApiRoute` when the route files differ from the feature flags. `/.well-known/mcp.json` appears only when `agent.mcp.servers` is configured.
3794
+ The document always lists the Markdown discovery routes (`/agents.md`, `/sitemap.md`, `/llms.txt`, and page-level `.md`), so keep those route files mounted. `/api/search` and the chat route follow `search.enabled` and `ai.enabled`; pass `endpoints: { chat: false }` or `endpoints: { search: false }` to `createOpenApiRoute` when the route files differ from the feature flags. The document lists the chat route at `ai.endpoint`, which defaults to `/api/chat`. `/.well-known/mcp.json` appears only when `agent.mcp.servers` is configured.
3761
3795
 
3762
3796
  The server URL comes from `siteUrl` when it is set, and from the request origin otherwise. Set `siteUrl` so the document names your production host.
3763
3797
 
@@ -3812,11 +3846,19 @@ The AI chat assistant is available in two ways:
3812
3846
 
3813
3847
  ### 1. Per-Page Quick Access
3814
3848
 
3815
- Each documentation page has an "Ask AI about this page" button in the table of contents sidebar. When clicked, it:
3849
+ Each documentation page has an "Ask AI about this page" action in the page actions menu beside the title, and in the action row below the description on mobile. When a reader selects it, Ask AI:
3816
3850
 
3817
- 1. Opens the chat interface
3818
- 2. Pre-fills a prompt asking the AI to read the current page
3819
- 3. Allows users to ask specific questions about that page
3851
+ 1. Clears the current conversation, including the history stored in the browser, and opens the chat
3852
+ 2. Shows a card above the prompt input that names the page. Readers can remove the card to ask without the page
3853
+ 3. Sends the page with the reader's next message, then replaces the card with a chip on that message that names the page
3854
+
3855
+ Ask AI sends only the page's path. The chat route reads the page's full Markdown from the site's own content and grounds the answer in it, so readers can ask "What does this page cover?" without pasting anything. Only the next message carries the page, and the chip stays on that message after a reload.
3856
+
3857
+ The chat route only reads pages that Ask AI can see. When the path names a page hidden with `excludeFrom: [chat]` or `internal: true`, a page that the route's `filterPage` option removes, or no page at all, the route ignores the page and answers the question normally.
3858
+
3859
+ Changelog entries aren't part of the chat route's sources, so on changelog pages "Ask AI about this page" keeps the earlier behavior: it opens the chat with a prompt that asks Ask AI to read the entry URL, which readers can edit before sending.
3860
+
3861
+ The "Open in ChatGPT", "Open in Claude", and other external providers in the same menu still open the provider with a prompt that links to the page.
3820
3862
 
3821
3863
  ### 2. Global Chat Interface
3822
3864
 
@@ -3828,10 +3870,88 @@ Users can open the chat interface at any time by:
3828
3870
  Once open, users can:
3829
3871
 
3830
3872
  - Ask questions about any part of your documentation
3831
- - Upload files or images for context
3832
- - View AI-powered search results from your docs
3873
+ - View the documentation pages used as sources for each answer
3874
+ - Copy an answer as Markdown
3875
+ - Expand the desktop panel to fill the viewport
3833
3876
  - Get step-by-step guidance on complex topics
3834
3877
 
3878
+ ## Control Ask AI from your own components
3879
+
3880
+ `useGeistdocsChat` from `@vercel/geistdocs/controls` opens, closes, and sends messages to the Ask AI chat from your own client components. Call it from any component rendered inside `GeistdocsProvider`, such as a custom header, a callout, or an MDX component.
3881
+
3882
+ | Property | Type | Description |
3883
+ | -------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
3884
+ | `enabled` | `boolean` | `false` when `ai.enabled` is `false`. All actions are then no-ops. |
3885
+ | `isOpen` | `boolean` | Whether the chat panel is open. |
3886
+ | `open` | `() => void` | Opens the chat. |
3887
+ | `close` | `() => void` | Closes the chat. |
3888
+ | `toggle` | `() => void` | Opens the chat when it's closed and closes it when it's open. |
3889
+ | `openWithPage` | `(page?: { url: string; title?: string }) => void` | Starts a new conversation about a page, like "Ask AI about this page". Defaults to the current page. |
3890
+ | `ask` | `(text: string) => void` | Opens the chat and sends `text` as a user message. |
3891
+
3892
+ ### Add an "Ask about this page" button to a custom header
3893
+
3894
+ `openWithPage` behaves like the "Ask AI about this page" action: it clears the conversation, opens the chat, and attaches the page to the reader's next message.
3895
+
3896
+ ```tsx title="components/ask-about-page-button.tsx"
3897
+ "use client";
3898
+
3899
+ import { useGeistdocsChat } from "@vercel/geistdocs/controls";
3900
+
3901
+ export const AskAboutPageButton = () => {
3902
+ const { enabled, openWithPage } = useGeistdocsChat();
3903
+
3904
+ if (!enabled) {
3905
+ return null;
3906
+ }
3907
+
3908
+ return (
3909
+ <button onClick={() => openWithPage()} type="button">
3910
+ Ask about this page
3911
+ </button>
3912
+ );
3913
+ };
3914
+ ```
3915
+
3916
+ Without arguments, `openWithPage` attaches the current page by its path, and the card shows that path. Pass a `title` to show the page title instead, for example `openWithPage({ url: "/docs/getting-started", title: "Getting Started" })`. `url` is a site-relative path, with or without `basePath`. For an absolute URL, Ask AI sends only its path, so a production URL still resolves on preview deployments.
3917
+
3918
+ ### Send a question with `ask`
3919
+
3920
+ `ask` opens the chat and sends the text as if the reader typed it. Use it for buttons that start a specific conversation:
3921
+
3922
+ ```tsx title="components/ask-button.tsx"
3923
+ "use client";
3924
+
3925
+ import { useGeistdocsChat } from "@vercel/geistdocs/controls";
3926
+
3927
+ export const AskButton = ({ question }: { question: string }) => {
3928
+ const { ask, enabled } = useGeistdocsChat();
3929
+
3930
+ if (!enabled) {
3931
+ return null;
3932
+ }
3933
+
3934
+ return (
3935
+ <button onClick={() => ask(question)} type="button">
3936
+ {question}
3937
+ </button>
3938
+ );
3939
+ };
3940
+ ```
3941
+
3942
+ `ask` trims the text and ignores empty strings. When the chat hasn't loaded yet, Ask AI loads it, restores the stored conversation, and then sends the message. When a response is streaming, the message waits until the response finishes, and several `ask` calls are sent in order.
3943
+
3944
+ Call `openWithPage` before `ask` to send a question about a page in a new conversation:
3945
+
3946
+ ```tsx
3947
+ const { ask, openWithPage } = useGeistdocsChat();
3948
+
3949
+ const summarize = () => {
3950
+ openWithPage();
3951
+ ask("Summarize this page in three bullet points.");
3952
+ };
3953
+ ```
3954
+
3835
3955
  ## Add a chat footer
3836
3956
 
3837
3957
  Set `ai.footer` to render content below the chat prompt in the desktop panel and mobile drawer. Use it for attribution, links, or other site-specific calls to action.
@@ -3846,6 +3966,111 @@ export const ai = {
3846
3966
  };
3847
3967
  ```
3848
3968
 
3969
+ ## Rename the chat panel
3970
+
3971
+ Set `ai.title` to change the chat panel heading, its accessible label, and the error message shown when the panel fails to load. The default is "Ask AI", and blank values fall back to it.
3972
+
3973
+ ```tsx title="geistdocs.tsx"
3974
+ export const ai = {
3975
+ title: "Ask Acme AI",
3976
+ };
3977
+ ```
3978
+
3979
+ `ai.title` only changes the chat panel. The navbar "Ask AI" button and the "Ask AI about this page" page action keep their labels.
3980
+
3981
+ ## Serve chat from a different route
3982
+
3983
+ Ask AI sends chat requests to `/api/chat` by default. Set `ai.endpoint` when the site must serve chat from another path, such as a microfrontend that owns `/api/ai-chat` and applies bot protection or Firewall rules to it.
3984
+
3985
+ ```tsx title="geistdocs.tsx"
3986
+ export const ai = {
3987
+ endpoint: "/api/ai-chat",
3988
+ };
3989
+ ```
3990
+
3991
+ Then move the chat route adapter to the matching App Router path, for example `app/api/ai-chat/route.ts`. The adapter code stays the same.
3992
+
3993
+ `ai.endpoint` is an app-local path, like other Geistdocs paths. The chat client adds `basePath` automatically, so a site with `basePath: "/help"` and `endpoint: "/api/ai-chat"` calls `/help/api/ai-chat`. The client uses the same URL for eve agent prewarm requests, and the [OpenAPI document](/docs/agent-readiness) generated by `createOpenApiRoute` lists the chat operation at the configured path.
3994
+
3995
+ The value must start with a single `/` and can't include a query string, fragment, whitespace, backslashes, `.` or `..` segments (including percent-encoded ones), or a trailing slash. It also can't be a path another Geistdocs route serves, including `/api/search`, `/agents.md`, `/llms.txt`, `/sitemap.md`, `/.well-known/mcp.json`, and the site OpenAPI document path. An invalid `ai.endpoint` throws when `createOpenApiRoute` runs and makes the chat panel show its error state instead of sending requests to an unexpected URL.
3996
+
3997
+ ## Copy an answer
3998
+
3999
+ Each finished Ask AI answer has a copy button below it that copies the answer's text as Markdown. The copied text leaves out the "Thinking..." and tool activity indicators and the source list. The button appears once the answer finishes streaming, isn't shown for an answer without text, and needs no configuration.
4000
+
4001
+ To copy the whole conversation, use the copy button in the chat header.
4002
+
4003
+ ## Collect feedback on answers
4004
+
4005
+ Set `ai.messageFeedback` to `true` to show thumbs up and thumbs down buttons beside the copy button on each finished answer. `ai.messageFeedback` defaults to `false`.
4006
+
4007
+ ```tsx title="geistdocs.tsx"
4008
+ export const ai = {
4009
+ messageFeedback: true,
4010
+ };
4011
+ ```
4012
+
4013
+ A vote is sent to the same Geistdocs feedback service that receives [page feedback](/docs/feedback) and creates a GitHub issue labeled with your `siteId`. The request contains these fields:
4014
+
4015
+ | Field | Content |
4016
+ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
4017
+ | `note` | Starts with `[Ask AI]`, the vote emoji, and a one-line summary of the question. Then lists the vote, the full question, the source URLs shown for the answer, and the answer as Markdown. |
4018
+ | `thumbs` | `"up"` or `"down"`. The feedback service labels the issue `thumbs-up` or `thumbs-down`. |
4019
+ | `url` | The page the reader was on when they voted. |
4020
+ | `label` | Your `siteId`. |
4021
+ | `ua`, `ip` | The reader's user agent and IP address, as with page feedback. |
4022
+
4023
+ The question is the reader's most recent message before the answer. Questions and answers longer than 4,000 characters are shortened, and up to 10 source URLs are sent. Because the note includes the reader's question as typed, check your site's privacy requirements before you enable `ai.messageFeedback`.
4024
+
4025
+ Readers can vote once per answer. After the feedback service accepts a vote, the chosen button stays selected, both buttons are disabled, and a "Thanks for your feedback" toast appears. If the request fails, an error toast appears and the reader can vote again.
4026
+
4027
+ Ask AI saves the vote with the conversation in the browser, so the chosen button stays selected after a reload until the chat history is cleared. The vote is stored in the answer's message metadata, which `createChatRoute` ignores, so voting doesn't change later chat requests.
4028
+
4029
+ ## Show the signed-in reader's avatar
4030
+
4031
+ Render `AskAIUser` from `@vercel/geistdocs/controls` to show the signed-in reader's avatar beside their messages in Ask AI. Geistdocs doesn't know who is signed in to your site, so you pass the reader's details at runtime from your own authentication.
4032
+
4033
+ `AskAIUser` renders nothing on the page. While it's mounted inside `GeistdocsProvider` with an `avatarUrl`, each user message shows a 24px round avatar. When `AskAIUser` unmounts or receives no `avatarUrl`, for example after the reader signs out, user messages render without an avatar again.
4034
+
4035
+ | Prop | Type | Description |
4036
+ | ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
4037
+ | `avatarUrl` | `string \| null` | URL of the reader's avatar. Only `https://` and `http://` URLs and root-relative paths, such as `/api/avatar`, are rendered. Other values, including `data:` URLs, are ignored. |
4038
+ | `name` | `string \| null` | The reader's name, used as the avatar's alt text. Without a name, the avatar is decorative and has empty alt text. |
4039
+
4040
+ Create a client component that reads the reader from your authentication library and renders `AskAIUser`. This example uses a `useSession` hook. Replace it with your library's client-side session hook:
4041
+
4042
+ ```tsx title="components/ask-ai-user.tsx"
4043
+ "use client";
4044
+
4045
+ import { AskAIUser } from "@vercel/geistdocs/controls";
4046
+ import { useSession } from "@/lib/auth-client";
4047
+
4048
+ export const SignedInAskAIUser = () => {
4049
+ const { data: session } = useSession();
4050
+
4051
+ if (!session?.user.image) {
4052
+ return null;
4053
+ }
4054
+
4055
+ return (
4056
+ <AskAIUser avatarUrl={session.user.image} name={session.user.name} />
4057
+ );
4058
+ };
4059
+ ```
4060
+
4061
+ Then render it once inside `GeistdocsProvider` in your root layout:
4062
+
4063
+ ```tsx title="app/[lang]/layout.tsx"
4064
+ <GeistdocsProvider basePath={config.basePath} lang={lang}>
4065
+ <SignedInAskAIUser />
4066
+ <Navbar config={config} />
4067
+ {children}
4068
+ <Footer />
4069
+ </GeistdocsProvider>
4070
+ ```
4071
+
4072
+ Avatars load lazily and are requested with `referrerPolicy="no-referrer"`, so the image host doesn't receive the docs page URL. An avatar that fails to load is hidden.
4073
+
3849
4074
  ## AI SDK dependency ownership
3850
4075
 
3851
4076
  Geistdocs Ask AI is built on AI SDK v6. Generated projects install `ai` v6 and `@ai-sdk/react` v3, and `@vercel/geistdocs` owns the chat client, transport, and `createChatRoute` server behavior.
@@ -3910,7 +4135,9 @@ https://<geistdocs-platform-deployment>/vertex
3910
4135
 
3911
4136
  4. Leave `GEISTDOCS_CHAT_PROXY_TOKEN` unset unless you are using a custom proxy that requires bearer authentication.
3912
4137
 
3913
- When `GEISTDOCS_CHAT_PROXY_URL` is set, Geistdocs searches local docs on the first user message, injects the current page and related docs into the final user message, forwards `{ messages, platform: "vercel" }` to the proxy, and streams the AI SDK UI stream response back to the browser.
4138
+ When `GEISTDOCS_CHAT_PROXY_URL` is set, Geistdocs searches local docs on the first user message, injects the attached page (or the current page when no page is attached) and related docs into the final user message, forwards `{ messages, platform: "vercel" }` to the proxy, and streams the AI SDK UI stream response back to the browser. Set [`contextInjection: "page-only"`](#choose-what-context-the-proxy-or-agent-receives) to forward messages as sent and inline only a page the reader attaches.
4139
+
4140
+ The proxy request also carries the reader's `x-client-ja4` and `x-client-ip` values, read from the incoming `x-vercel-ja4-digest` and `x-forwarded-for` headers, unless `proxy.headers` sets them. `proxy.headers` accepts a static object or a function that receives the incoming chat `Request`; see [Forward per-request values in upstream headers](#forward-per-request-values-in-upstream-headers).
3914
4141
 
3915
4142
  The platform proxy forwards a Vercel OIDC token to Vertex in the `x-vercel-trusted-oidc-idp-token` header. The Vertex deployment should validate the caller through Trusted Sources; the Geistdocs site does not need a Vertex API key.
3916
4143
 
@@ -3927,15 +4154,15 @@ export const ai = {
3927
4154
  };
3928
4155
  ```
3929
4156
 
3930
- Set `prewarm: true` to start an empty session when the Ask AI client loads, including when a reader hovers or focuses the Ask AI control. The first message waits for that request and reuses the accepted session, avoiding workflow startup latency. Prewarming requires eve 0.59 or newer and falls back to normal session creation if the early request fails. Leave it disabled when opening the chat should not allocate a durable session before the reader sends a message.
4157
+ Set `prewarm: true` to start an empty session when the Ask AI client loads, including when a reader hovers or focuses the Ask AI control. The prewarm response binds the session to the reader's browser with the session cookie, and the first message waits for that request and reuses the session, avoiding workflow startup latency. Prewarming requires eve 0.59 or newer and [`GEISTDOCS_CHAT_SECRET`](#keep-eve-sessions-across-turns-with-geistdocs_chat_secret), and falls back to normal session creation if the early request fails. Leave it disabled when opening the chat should not allocate a durable session before the reader sends a message.
3931
4158
 
3932
- The URL flows to `createChatRoute` through the config object you already pass in `app/api/chat/route.ts` — no route changes are required. Geistdocs speaks eve's session API directly: it starts or resumes a durable eve session, streams the agent's NDJSON events, and translates them into the same UI message stream the chat panel already renders. Conversation continuity is handled automatically by round-tripping the eve session handle through message metadata.
4159
+ The URL flows to `createChatRoute` through the config object you already pass in `app/api/chat/route.ts` — no route changes are required. Geistdocs speaks eve's session API directly: it starts or resumes a durable eve session, streams the agent's NDJSON events, and translates them into the same UI message stream the chat panel already renders. With `GEISTDOCS_CHAT_SECRET` set, Geistdocs continues one eve session across turns by binding it to the reader's browser with a signed, httpOnly cookie.
3933
4160
 
3934
4161
  Eve agent mode keeps the platform-owned behavior from proxy mode:
3935
4162
 
3936
- - Local docs retrieval runs on the first user message, and the current page plus related docs are inlined into the message the agent receives.
4163
+ - Local docs retrieval runs on the first user message, and the attached page (or the current page when no page is attached) plus related docs are inlined into the message the agent receives. Set [`contextInjection: "page-only"`](#choose-what-context-the-proxy-or-agent-receives) when the agent does its own retrieval.
3937
4164
  - Locally computed source citations are injected into the response stream, and `excludeFrom: [chat]` page visibility is enforced before anything reaches the agent.
3938
- - The agent's reasoning shows as a "Thinking..." indicator, its tool calls show as activity labels, and stopping a response cancels the in-flight eve turn.
4165
+ - The agent's reasoning shows as a "Thinking..." indicator, its tool calls show as activity labels, and stopping a response cancels the in-flight eve turn. URLs in tool outputs show as source citations. To limit which tool calls the chat shows, read [Choose which agent tool calls the chat shows](#choose-which-agent-tool-calls-the-chat-shows).
3939
4166
 
3940
4167
  **Authentication.** Requests carry a Vercel OIDC token minted per request, in two headers for the two layers that may guard the agent: `Authorization: Bearer` for eve's channel auth, and `x-vercel-trusted-oidc-idp-token` for Vercel Deployment Protection. Eve's default channel auth (`vercelOidc()`) accepts deployments from the same Vercel team out of the box; cross-team agents can allow the site with `vercelSubject`. If the agent deployment uses Deployment Protection, add the docs site's project as a Trusted Source. For agents with custom auth, pass server-only headers through the `eveAgent` option:
3941
4168
 
@@ -3949,9 +4176,314 @@ export const { POST, maxDuration } = createChatRoute({
3949
4176
  });
3950
4177
  ```
3951
4178
 
3952
- Never put authentication material in `geistdocs.tsx` — the config ships to the client bundle. The agent URL is public configuration; tokens are not.
4179
+ Never put authentication material in `geistdocs.tsx`, because the config ships to the client bundle. The agent URL is public configuration; tokens are not.
4180
+
4181
+ The `eveAgent` option also accepts a `url` override for pointing staging deployments at a different agent, and a `secret` override for the session signing secret. Configuring both `proxy` and an eve agent throws at route creation.
4182
+
4183
+ | `eveAgent` option | Type | Default | Description |
4184
+ | ----------------- | ------------------------------------- | ------------------ | ----------- |
4185
+ | `url` | `string` | `ai.eveAgent.url` | Agent base URL. Overrides `ai.eveAgent.url`; setting it here alone enables eve agent mode without exposing the URL in `geistdocs.tsx`. |
4186
+ | `headers` | `HeadersInit \| (request: Request) => HeadersInit \| Promise<HeadersInit>` | OIDC headers | Extra request headers. An `authorization` header replaces the OIDC bearer token. |
4187
+ | `secret` | `string` | `GEISTDOCS_CHAT_SECRET` | Secret that signs the eve session cookie, at least 32 bytes. |
4188
+ | `clientContext` | `boolean` | `false` | Send the current page as eve `clientContext` with every message. |
4189
+ | `visibleTools` | `string[]` | All tools | Tool names whose calls the chat shows. |
4190
+ | `toolCitations` | `boolean` | `true` | Forward tool outputs and show the URLs in them as source citations. |
4191
+
4192
+ #### Keep eve sessions across turns with `GEISTDOCS_CHAT_SECRET`
4193
+
4194
+ Eve agent mode needs the server-only `GEISTDOCS_CHAT_SECRET` environment variable to continue one eve session across turns and to prewarm sessions. The chat route binds each reader's eve session to an httpOnly cookie signed with this secret, so page scripts can't read the session ID or replay it from another browser. The browser only keeps the stream position and a short, non-reversible session tag in each answer's metadata.
4195
+
4196
+ The `geistdocs_eve_session` cookie has these attributes:
4197
+
4198
+ | Attribute | Value |
4199
+ | ---------- | ------------------------------------------------------------ |
4200
+ | `HttpOnly` | Always set |
4201
+ | `SameSite` | `Strict` |
4202
+ | `Secure` | Set when the request uses HTTPS, including behind a proxy that sends `x-forwarded-proto: https` |
4203
+ | `Path` | The chat route's own path, such as `/api/chat` or `/docs/api/chat` under a base path |
4204
+ | `Max-Age` | 7 days, renewed after every turn |
4205
+
4206
+ The chat route continues the cookie's session only when the conversation's latest answer carries that session's tag, or when the session was prewarmed and the conversation has no eve answers yet. In every other case, the route starts a new eve session, inlines up to 8,000 characters of the prior conversation into the first message, and sets a new cookie. This happens when:
4207
+
4208
+ - The reader deleted the chat, or the cookie expired after 7 days without a turn.
4209
+ - Another tab started its own session. The cookie holds one session per browser, so alternating between two conversations starts a new session on each switch.
4210
+ - The cookie was altered, signed with a different secret, or issued for a different agent URL. The route never contacts the session that such a cookie names.
4211
+ - The eve session is no longer active on the agent.
4212
+
4213
+ Chats saved in a reader's browser by earlier Geistdocs versions carry session details in a format the route ignores, so they continue in a new session with the conversation inlined.
4214
+
4215
+ ##### Set the secret
4216
+
4217
+ Generate a secret of at least 32 bytes:
4218
+
4219
+ ```bash title="Terminal"
4220
+ openssl rand -base64 32
4221
+ ```
4222
+
4223
+ Add the value as `GEISTDOCS_CHAT_SECRET` to your site's Vercel project environment variables for the Production and Preview environments, then redeploy. For local development, add it to `.env.local`. Use a separate secret for each docs site.
4224
+
4225
+ Geistdocs uses the value as-is, so any value of 32 bytes or more works, including an existing base64-encoded 32-byte secret (44 characters). Geistdocs signs with its own versioned prefix, so a secret that another service also signs with can't produce values that either service accepts from the other.
4226
+
4227
+ To read the secret from a differently named variable, pass it through the `eveAgent.secret` option. Never put the secret in `geistdocs.tsx` or give it a `NEXT_PUBLIC_` prefix.
4228
+
4229
+ ```ts title="app/api/chat/route.ts"
4230
+ export const { POST, maxDuration } = createChatRoute({
4231
+ config,
4232
+ sources: [geistdocsSource],
4233
+ eveAgent: {
4234
+ secret: process.env.ASK_AI_SESSION_SECRET,
4235
+ },
4236
+ });
4237
+ ```
4238
+
4239
+ Rotating the secret invalidates every existing session cookie. Each reader's next message starts a new eve session with their conversation inlined, so rotation needs no downtime.
4240
+
4241
+ A secret shorter than 32 bytes throws when the route module loads, so a weak secret fails the deployment instead of signing cookies.
4242
+
4243
+ ##### Serve the chat route from the same site
4244
+
4245
+ Browsers only send a `SameSite=Strict` cookie with requests that start on the same site as the cookie. The default `/api/chat` route lives on the same domain as your docs pages, so this works without configuration. If the docs pages call a chat route on a different site, the browser never sends the cookie and every turn starts a new eve session.
4246
+
4247
+ ##### Run without a secret
3953
4248
 
3954
- The `eveAgent` option also accepts a `url` override for pointing staging deployments at a different agent. Configuring both `proxy` and an eve agent throws at route creation.
4249
+ Without `GEISTDOCS_CHAT_SECRET`, eve agent mode still answers every question, but it never sets or reads the session cookie:
4250
+
4251
+ - Every turn starts a new eve session, with up to 8,000 characters of the prior conversation inlined into the message.
4252
+ - The route refuses `{ prewarm: true }` requests with a `400` response, so `prewarm: true` only adds a failed request when Ask AI loads.
4253
+ - The server logs a warning that names `GEISTDOCS_CHAT_SECRET`.
4254
+
4255
+ ### Choose what context the proxy or agent receives
4256
+
4257
+ The `contextInjection` option on `createChatRoute` controls the docs context Geistdocs adds to the messages it forwards in proxy and eve agent modes. The default AI Gateway mode ignores it, because that mode retrieves docs with its own tools and always inlines a page the reader attaches.
4258
+
4259
+ | `contextInjection` | Message without an attached page | Message with an attached page (`pageContext`) | Source citations Geistdocs adds |
4260
+ | ------------------ | -------------------------------- | --------------------------------------------- | ------------------------------- |
4261
+ | `"auto"` (default) | On the first user message, a 1,500-character excerpt of the current page plus up to 5 related pages from retrieval. Later messages are forwarded as sent. | On the first user message, the attached page replaces the current page in the same format. | One per injected page |
4262
+ | `"page-only"` | Forwarded as sent, on every turn | The attached page is inlined in full on the message that carries it, on any turn | None |
4263
+
4264
+ Use `"page-only"` when the proxy or agent retrieves documentation itself and should receive the reader's question unchanged. Both modes drop UI-only messages whose metadata sets `isPageContext: true`.
4265
+
4266
+ ```ts title="app/api/chat/route.ts"
4267
+ export const { POST, maxDuration } = createChatRoute({
4268
+ config,
4269
+ contextInjection: "page-only",
4270
+ proxy: { url: process.env.GEISTDOCS_CHAT_PROXY_URL! },
4271
+ sources: [geistdocsSource],
4272
+ });
4273
+ ```
4274
+
4275
+ In `"page-only"` mode, proxy mode replaces the text of the last user message with the attached page followed by the question:
4276
+
4277
+ ```md
4278
+ Here's the content from the current page:
4279
+
4280
+ **Page:** Routing
4281
+ **URL:** https://docs.example.com/docs/routing
4282
+
4283
+ ---
4284
+
4285
+ <full page Markdown>
4286
+
4287
+ ---
4288
+
4289
+ User question: How do I add a redirect?
4290
+ ```
4291
+
4292
+ Eve agent mode sends the attached page as a leading text part, with the page as one line of JSON, followed by the question. When the message starts a new eve session, including one that replaces an inactive session, the inlined conversation follows the page part instead:
4293
+
4294
+ ```json
4295
+ {
4296
+ "message": [
4297
+ {
4298
+ "type": "text",
4299
+ "text": "Page context:\n{\"title\":\"Routing\",\"url\":\"https://docs.example.com/docs/routing\",\"content\":\"<full page Markdown>\"}"
4300
+ },
4301
+ { "type": "text", "text": "How do I add a redirect?" }
4302
+ ]
4303
+ }
4304
+ ```
4305
+
4306
+ For a `pageContext: { url }` reference, Geistdocs reads the page's full Markdown from the route's sources, as Geistdocs renders it for the page's Markdown route, and truncates it to `limits.maxPageContextChars` (200,000 characters by default). The URL is the page's absolute public URL on `siteUrl`, or on the request origin when `siteUrl` is unset. A legacy `pageContext: { title, url, content }` is used as sent. A reference to a page that is hidden from Ask AI or doesn't exist is ignored, and the message is forwarded as sent.
4307
+
4308
+ ### Send the current page to an eve agent
4309
+
4310
+ Set `eveAgent.clientContext: true` to send the page the reader is viewing with every eve message. eve passes `clientContext` to every model call in that turn as turn-scoped context and doesn't store it in the session history.
4311
+
4312
+ ```ts title="app/api/chat/route.ts"
4313
+ export const { POST, maxDuration } = createChatRoute({
4314
+ config,
4315
+ eveAgent: { clientContext: true },
4316
+ sources: [geistdocsSource],
4317
+ });
4318
+ ```
4319
+
4320
+ Geistdocs adds `clientContext` next to `message` in the body of every request that sends a message, including follow-ups to the session in the reader's session cookie and the first message of a session that replaces an inactive one:
4321
+
4322
+ ```json
4323
+ {
4324
+ "message": "How do I add a redirect?",
4325
+ "clientContext": {
4326
+ "currentPage": {
4327
+ "url": "https://docs.example.com/docs/routing",
4328
+ "title": "Routing"
4329
+ }
4330
+ }
4331
+ }
4332
+ ```
4333
+
4334
+ The route derives `clientContext` from the `currentRoute` the Ask AI client already sends, so the client needs no changes:
4335
+
4336
+ - `url` is the absolute public URL of the route's path, with `basePath`, on `siteUrl` or the request origin. The query string, fragment, and any origin in `currentRoute` are ignored.
4337
+ - `title` is the page title, up to 256 characters, when the route is a page Ask AI may see. For other routes, such as pages with `excludeFrom: [chat]`, `currentPage` carries only `url`.
4338
+ - A request without `currentRoute`, or with a `currentRoute` longer than 2,048 characters, sends no `clientContext`.
4339
+
4340
+ The agent's eve version must accept `clientContext` on its session routes; eve 0.59 does. Prewarm requests never carry `clientContext`, because eve rejects it on a session created without a message.
4341
+
4342
+ ### Choose which agent tool calls the chat shows
4343
+
4344
+ By default, the chat shows every eve tool call as an activity label, and URLs found in tool outputs become source citations. Two server-only `eveAgent` options change that:
4345
+
4346
+ - `visibleTools` lists the tool names whose calls reach the chat. Calls to other tools, with their results and any citations in them, aren't forwarded. An empty array hides every tool call.
4347
+ - `toolCitations: false` keeps the activity label but sends each tool output to the chat as `null` and adds no source citations.
4348
+
4349
+ The client-side `ai.toolLabels` config in `geistdocs.tsx` replaces the `Running <tool name>...` activity label for the tools it names. It applies in every AI mode:
4350
+
4351
+ ```tsx title="geistdocs.tsx"
4352
+ export const ai = {
4353
+ toolLabels: {
4354
+ web_search: "Searching...",
4355
+ web_fetch: "Searching...",
4356
+ },
4357
+ };
4358
+ ```
4359
+
4360
+ Tools without a non-blank label keep the default label.
4361
+
4362
+ ### Forward per-request values in upstream headers
4363
+
4364
+ `proxy.headers` and `eveAgent.headers` accept a static object or a function. The function receives the incoming chat `Request` and can be async, so it can forward values from the reader's request. Existing functions that take no arguments keep working.
4365
+
4366
+ ```ts title="app/api/chat/route.ts"
4367
+ export const { POST, maxDuration } = createChatRoute({
4368
+ config,
4369
+ eveAgent: {
4370
+ headers: (request) => ({
4371
+ "x-evo-surface": "docs",
4372
+ "x-docs-locale": request.headers.get("accept-language") ?? "en",
4373
+ }),
4374
+ },
4375
+ sources: [geistdocsSource],
4376
+ });
4377
+ ```
4378
+
4379
+ Use a static object for fixed values such as `x-evo-surface: docs`.
4380
+
4381
+ ### Match a production Vertex or eve setup
4382
+
4383
+ Vercel's own docs answer Ask AI through a Vertex-backed service by default and through an eve agent behind a feature flag. Both responders do their own retrieval, so the route forwards questions unchanged, inlines a page only when the reader attaches one, and shows the eve agent's web tools under one generic label without citations.
4384
+
4385
+ Create one route per responder at module scope and choose between them per request. Keep `ai.eveAgent` out of `geistdocs.tsx` here: the eve route sets its URL with the server-only `eveAgent.url` option, because a route that has `proxy` throws when `ai.eveAgent.url` is set.
4386
+
4387
+ ```ts title="app/api/ai-chat/route.ts"
4388
+ import { createChatRoute } from "@vercel/geistdocs/routes/chat";
4389
+ import { config } from "@/lib/geistdocs/config";
4390
+ import { geistdocsSource } from "@/lib/geistdocs/source";
4391
+ import { enableDocsAgent } from "@/flags";
4392
+
4393
+ const vertex = createChatRoute({
4394
+ config,
4395
+ contextInjection: "page-only",
4396
+ proxy: {
4397
+ url: `${process.env.VERTEX_URL}/api/chat/docs`,
4398
+ headers: {
4399
+ "x-vercel-protection-bypass": process.env.VERTEX_BYPASS_SECRET ?? "",
4400
+ },
4401
+ },
4402
+ sources: [geistdocsSource],
4403
+ });
4404
+
4405
+ const agent = createChatRoute({
4406
+ config,
4407
+ contextInjection: "page-only",
4408
+ eveAgent: {
4409
+ url: process.env.EVE_AGENT_URL,
4410
+ clientContext: true,
4411
+ headers: { "x-evo-surface": "docs" },
4412
+ visibleTools: ["web_search", "web_fetch", "knowledge-search"],
4413
+ toolCitations: false,
4414
+ },
4415
+ sources: [geistdocsSource],
4416
+ });
4417
+
4418
+ export const maxDuration = 800;
4419
+
4420
+ export const POST = async (request: Request) =>
4421
+ (await enableDocsAgent()) ? agent.POST(request) : vertex.POST(request);
4422
+ ```
4423
+
4424
+ ```tsx title="geistdocs.tsx"
4425
+ export const ai = {
4426
+ endpoint: "/api/ai-chat",
4427
+ toolLabels: {
4428
+ web_search: "Searching...",
4429
+ web_fetch: "Searching...",
4430
+ "knowledge-search": "Searching...",
4431
+ },
4432
+ };
4433
+ ```
4434
+
4435
+ The Vertex route forwards `{ messages, platform: "vercel" }` with the `x-client-ja4` and `x-client-ip` headers, and the chat shows the citations Vertex returns in its tool outputs. The eve route keeps the default Vercel OIDC authentication. Sessions continue across turns when `GEISTDOCS_CHAT_SECRET` is set, and prewarming stays off because `ai.eveAgent.prewarm` isn't configured.
4436
+
4437
+ ## Request size limits
4438
+
4439
+ `createChatRoute` rejects oversized requests before they reach the model, the chat proxy, or the eve agent. The same defaults apply in every AI mode:
4440
+
4441
+ | Limit option | Default | Response when exceeded |
4442
+ | --------------------- | ---------------------------- | ---------------------- |
4443
+ | `maxRequestBytes` | `1_000_000` bytes (1 MB) | `413` |
4444
+ | `maxMessages` | `200` messages | `400` |
4445
+ | `maxPageContextChars` | `200_000` characters | `400` |
4446
+
4447
+ Rejected requests receive a JSON body in the form `{ "error": "..." }`. The route reads the request body as a stream and stops as soon as it passes `maxRequestBytes`, and rejects a request whose `Content-Length` header is over the cap without reading the body. An oversized `pageContext.content` is rejected, not truncated.
4448
+
4449
+ `maxPageContextChars` only rejects `pageContext.content` that API callers send with the page text. The Ask AI client sends `pageContext: { url }` without content, and the route reads that page from the site's own sources; with `contextInjection: "page-only"`, that page's Markdown is truncated to `maxPageContextChars` before it is forwarded. `pageContext.url` must be a non-empty string of at most 2,048 characters in both shapes; other values receive `400`.
4450
+
4451
+ Change the limits with the `limits` option:
4452
+
4453
+ ```ts title="app/api/chat/route.ts"
4454
+ export const { POST, maxDuration } = createChatRoute({
4455
+ config,
4456
+ sources: [geistdocsSource],
4457
+ limits: {
4458
+ maxRequestBytes: 500_000,
4459
+ maxMessages: 100,
4460
+ maxPageContextChars: 100_000,
4461
+ },
4462
+ });
4463
+ ```
4464
+
4465
+ Request size limits don't control how often a client can call the route. `/api/chat` is public, and every accepted request calls a model or agent on your account, so wrap the route with your own rate limiting. For example, install `@vercel/firewall`, create a [Firewall rate limit rule](https://vercel.com/docs/vercel-firewall/vercel-waf/rate-limiting-sdk) with the rate limit ID `ask-ai`, and check it before calling `POST`:
4466
+
4467
+ ```ts title="app/api/chat/route.ts"
4468
+ import { checkRateLimit } from "@vercel/firewall";
4469
+ import { createChatRoute } from "@vercel/geistdocs/routes/chat";
4470
+ import { config } from "@/lib/geistdocs/config";
4471
+ import { geistdocsSource } from "@/lib/geistdocs/source";
4472
+
4473
+ const chat = createChatRoute({ config, sources: [geistdocsSource] });
4474
+
4475
+ export const maxDuration = 800;
4476
+
4477
+ export const POST = async (request: Request) => {
4478
+ const { rateLimited } = await checkRateLimit("ask-ai", { request });
4479
+
4480
+ if (rateLimited) {
4481
+ return Response.json({ error: "Too many requests." }, { status: 429 });
4482
+ }
4483
+
4484
+ return chat.POST(request);
4485
+ };
4486
+ ```
3955
4487
 
3956
4488
  ## Features
3957
4489
 
@@ -3964,43 +4496,89 @@ By default, the AI assistant includes a built-in `search_docs` tool that:
3964
4496
  3. Shows source citations with links to the referenced pages
3965
4497
  4. Uses the content to provide accurate, contextual answers
3966
4498
 
3967
- When `GEISTDOCS_CHAT_PROXY_URL` is set, Geistdocs runs local documentation retrieval on the first user message before forwarding the request to the configured proxy. This gives proxy-backed services access to the current page and related local documentation without requiring them to read the site's source files directly.
4499
+ When `GEISTDOCS_CHAT_PROXY_URL` is set, Geistdocs runs local documentation retrieval on the first user message before forwarding the request to the configured proxy. This gives proxy-backed services access to the current page and related local documentation without requiring them to read the site's source files directly. With `contextInjection: "page-only"`, Geistdocs skips this retrieval.
3968
4500
 
3969
4501
  Set `ai.retrieval` to `"mixedbread"` to replace local keyword retrieval with semantic retrieval for default, proxy, and hosted eve modes. Mixedbread returns the matching content chunk, while the AI model and the visible search dialog remain unchanged. Geistdocs falls back to local Orama retrieval when Mixedbread is unavailable. Read [Improve Ask AI answers with Mixedbread](/docs/mixedbread-retrieval) to provision a Store and configure production sync.
3970
4502
 
3971
4503
  ### Persistent Chat History
3972
4504
 
3973
- Conversations are automatically saved to the browser's IndexedDB, providing:
4505
+ Ask AI saves the conversation to the browser's IndexedDB, so users can:
4506
+
4507
+ - Keep the conversation across page reloads and navigation
4508
+ - Continue the conversation in a later visit
4509
+ - Copy the conversation or delete it from the chat header
4510
+
4511
+ Geistdocs keeps a stored conversation for 30 days after its most recent message. Each new message restarts that window, and reloading a page doesn't. When Ask AI loads a conversation older than the window, it clears the conversation and starts empty.
3974
4512
 
3975
- - Chat history that persists across page reloads
3976
- - Ability to continue previous conversations
3977
- - Option to start a new chat or clear history
3978
- - Offline access to past conversations
4513
+ Set `ai.history.retentionDays` to change the window:
4514
+
4515
+ ```tsx title="geistdocs.tsx"
4516
+ export const ai = {
4517
+ history: {
4518
+ retentionDays: 7,
4519
+ },
4520
+ };
4521
+ ```
4522
+
4523
+ | Value | Behavior |
4524
+ | ------------------------------------ | ------------------------------------------------------------------------------- |
4525
+ | Unset | Keeps conversations for 30 days after the most recent message. |
4526
+ | A positive number | Keeps conversations for that many days. `0.5` keeps them for 12 hours. |
4527
+ | `0` | Stores no history. Ask AI clears any stored conversation when it loads. |
4528
+ | `Infinity` | Never expires stored conversations. |
4529
+ | Negative, `NaN`, or `-Infinity` | Uses the 30-day default and logs a warning in the browser console. |
4530
+
4531
+ Chat history is stored per site, keyed by the site `title`, so changing `ai.title` keeps existing history.
3979
4532
 
3980
4533
  ### Interactive Features
3981
4534
 
3982
- - **Suggestions**: First-time users see suggested questions to get started
3983
- - **File Upload**: Users can attach files or images for context
4535
+ - **Suggestions**: Users see up to four suggested questions when the chat is empty
3984
4536
  - **Markdown Support**: Responses are formatted with proper Markdown rendering
3985
4537
  - **Code Syntax Highlighting**: Code blocks in responses include syntax highlighting
3986
- - **Reasoning Display**: In development mode, view the AI's reasoning process
4538
+ - **Activity Indicators**: While a response streams, the chat shows "Thinking..." during model reasoning and an activity label while tools run. Set `ai.toolLabels` to replace the label for specific tools
4539
+
4540
+ Ask AI accepts text questions only. It does not support file or image attachments.
3987
4541
 
3988
4542
  ### Mobile-Responsive
3989
4543
 
3990
4544
  The chat interface adapts to different screen sizes:
3991
4545
 
3992
- - **Desktop**: Slides in from the right side as a sidebar panel
3993
- - **Mobile**: Opens as a bottom drawer.
4546
+ - **Desktop**: Slides in from the right side as a sidebar panel. Select **Expand chat** in the panel header to fill the viewport, which gives long answers and code blocks more width without losing the conversation. Select **Collapse chat** or press `Escape` to return to the sidebar. Closing the chat also returns it to the sidebar, so the next open starts there.
4547
+ - **Mobile**: Opens as a bottom drawer. The drawer has no expanded view.
3994
4548
 
3995
4549
  ## Configuration
3996
4550
 
3997
- The environment variables `AI_GATEWAY_API_KEY` and `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL` must be set for the default AI Gateway mode. Set `GEISTDOCS_CHAT_PROXY_URL` to route Ask AI through a Vertex-backed proxy instead. You can read more in the [Environment Variables](/docs/env) section.
4551
+ The environment variables `AI_GATEWAY_API_KEY` and `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL` must be set for the default AI Gateway mode. Set `GEISTDOCS_CHAT_PROXY_URL` to route Ask AI through a Vertex-backed proxy instead. Eve agent mode needs `GEISTDOCS_CHAT_SECRET` for multi-turn sessions and prewarming. You can read more in the [Environment Variables](/docs/env) section.
3998
4552
 
3999
4553
  In default AI Gateway mode, Geistdocs uses `openai/gpt-5.6-sol` via the Vercel AI Gateway. In Vertex-backed proxy mode, the configured proxy controls the upstream model.
4000
4554
 
4001
4555
  ## Suggested Prompts
4002
4556
 
4003
- You can customize the initial suggested prompts shown to users. These are configured in the Geistdocs configuration file, which you can read more about in the [Configuration](/docs/configuration) section.
4557
+ Set `ai.suggestions` to the prompts readers see before they send their first message. Selecting a suggestion sends its text as the first message. Ask AI shows the first four distinct, non-blank suggestions.
4558
+
4559
+ Each suggestion is a string or an object with `text` and an optional `icon`. String suggestions render without an icon. The `icon` field accepts any React element, such as an inline SVG component or an icon from a library your site already installs:
4560
+
4561
+ ```tsx title="geistdocs.tsx"
4562
+ const RocketIcon = () => (
4563
+ <svg aria-hidden="true" fill="none" height="16" viewBox="0 0 16 16" width="16">
4564
+ <path d="M8 1.5c2.5 1.5 3.5 4 3.5 6.5L8 12 4.5 8c0-2.5 1-5 3.5-6.5Z" stroke="currentColor" />
4565
+ </svg>
4566
+ );
4567
+
4568
+ const BookIcon = () => (
4569
+ <svg aria-hidden="true" fill="none" height="16" viewBox="0 0 16 16" width="16">
4570
+ <path d="M3 2.5h7.5v11H3zM10.5 2.5H13v11h-2.5" stroke="currentColor" />
4571
+ </svg>
4572
+ );
4573
+
4574
+ export const suggestions = [
4575
+ "What is Acme?",
4576
+ { text: "How do I deploy?", icon: <RocketIcon /> },
4577
+ { text: "Where is the API reference?", icon: <BookIcon /> },
4578
+ ];
4579
+ ```
4580
+
4581
+ The generated `lib/geistdocs/config.tsx` forwards `suggestions` to `ai.suggestions`. Read the [Configuration](/docs/configuration) section for the rest of the configuration file.
4004
4582
 
4005
4583
 
4006
4584
  ---
@@ -4862,6 +5440,10 @@ When feedback is submitted:
4862
5440
 
4863
5441
  Each piece of feedback creates a separate issue, allowing for individual tracking and resolution.
4864
5442
 
5443
+ ### Feedback on Ask AI answers
5444
+
5445
+ When `ai.messageFeedback` is enabled, readers can rate each Ask AI answer with a thumbs up or thumbs down. Ask AI answer votes go to the same feedback service with the same `siteId` label. Each answer vote creates an issue labeled `thumbs-up` or `thumbs-down`, and its note starts with `[Ask AI]` so you can tell answer feedback from page feedback. Thumbs-down issues also get the `reason-empty` label because Ask AI doesn't ask for a reason. Read [Collect feedback on answers](/docs/ask-ai#collect-feedback-on-answers) for the fields each vote sends.
5446
+
4865
5447
  ## Feedback Schema
4866
5448
 
4867
5449
  The API accepts the following fields:
@@ -6227,14 +6809,14 @@ export function Demo() {
6227
6809
 
6228
6810
  ---
6229
6811
  title: WebMCP
6230
- description: Expose documentation search and page reading to browser agents.
6812
+ description: Expose documentation search, page reading, and Ask AI to browser agents.
6231
6813
  url: /docs/webmcp
6232
6814
  source: apps/template/content/docs/webmcp.mdx
6233
6815
  ---
6234
6816
 
6235
6817
  # WebMCP
6236
6818
 
6237
- Geistdocs uses [mcp-handler's WebMCP bridge](https://github.com/vercel/mcp-handler/blob/main/docs/WEBMCP.md) for search and a browser-local tool for reading the current page. Enable `webmcp: { enabled: true }` in `lib/geistdocs/config.tsx` and add `app/api/mcp/route.ts`:
6819
+ Geistdocs uses [mcp-handler's WebMCP bridge](https://github.com/vercel/mcp-handler/blob/main/docs/WEBMCP.md) for search, and browser-local tools for reading the current page and, optionally, asking the site's Ask AI chat. Enable `webmcp: { enabled: true }` in `lib/geistdocs/config.tsx` and add `app/api/mcp/route.ts`:
6238
6820
 
6239
6821
  ```ts
6240
6822
  import { createMcpRoute } from "@vercel/geistdocs/routes/mcp";
@@ -6254,10 +6836,23 @@ The canonical template includes this setup. Existing consumers must add the rout
6254
6836
  | --- | --- | --- |
6255
6837
  | `search_docs` | Nonblank `query` up to 500 characters; optional configured `locale` | MCP result containing search results as JSON text |
6256
6838
  | `read_current_page` | None | Current page as Markdown |
6839
+ | `ask_ai` | `question` of 2 to 2,000 characters after trimming whitespace | Confirmation that the question was submitted to the site's Ask AI chat |
6257
6840
 
6258
6841
  The provider loads `/api/mcp?webmcp-script` once through `next/script`. The script discovers the MCP server's tools and registers only `search_docs`. Do not add another copy of the script or register search yourself. Remote MCP clients connect to `/api/mcp` directly. Geistdocs prefixes public paths with `basePath`.
6259
6842
 
6260
- Search calls the supplied search handler directly, retaining its visibility filters and request headers/cookies without another network hop. Pass `locale` explicitly for translated results; omitting it selects `defaultLanguage`, even after navigating to another language. Neither tool modifies documentation or sends it to an external model.
6843
+ Search calls the supplied search handler directly, retaining its visibility filters and request headers/cookies without another network hop. Pass `locale` explicitly for translated results; omitting it selects `defaultLanguage`, even after navigating to another language. `search_docs` and `read_current_page` don't modify documentation or send it to an external model.
6844
+
6845
+ ## Let browser agents ask Ask AI
6846
+
6847
+ `ask_ai` is opt-in. Set `webmcp.askAI` to `true` to register it when Ask AI is enabled:
6848
+
6849
+ ```tsx title="lib/geistdocs/config.tsx"
6850
+ webmcp: { enabled: true, askAI: true },
6851
+ ```
6852
+
6853
+ `ask_ai` opens the site's Ask AI chat and submits the question as a user message, the same way the `ask` action from [`useGeistdocsChat`](/docs/ask-ai#control-ask-ai-from-your-own-components) does. The tool returns as soon as the question is queued and doesn't return the answer, which streams into the chat panel on the page. Questions sent while a response is streaming wait for it to finish. The tool rejects a missing `question`, or one shorter than 2 or longer than 2,000 characters after trimming whitespace, without opening the chat.
6854
+
6855
+ `ask_ai` isn't registered when `webmcp.askAI` is unset, when `ai.enabled` is `false`, or when `webmcp.enabled` is `false`. Unlike the read-only tools, `ask_ai` sets `readOnlyHint: false` because it changes the page and sends the question to your Ask AI model or agent, which counts toward your usage. Like `read_current_page`, it runs in the browser and isn't part of the `/api/mcp` server, so remote MCP clients and the `?webmcp-script` bridge don't list it.
6261
6856
 
6262
6857
  ## Lifecycle and safety
6263
6858
 
@@ -6282,6 +6877,8 @@ agent-browser --session docs-check open http://localhost:3000/docs
6282
6877
  agent-browser --session docs-check webmcp list
6283
6878
  agent-browser --session docs-check webmcp invoke search_docs --params '{"query":"configuration","locale":"en"}'
6284
6879
  agent-browser --session docs-check webmcp invoke read_current_page --params '{}'
6880
+ # Requires webmcp.askAI: true
6881
+ agent-browser --session docs-check webmcp invoke ask_ai --params '{"question":"How do I configure search?"}'
6285
6882
  agent-browser --session docs-check close
6286
6883
  ```
6287
6884