@vercel/geistdocs 2.7.9 → 2.8.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.
- package/dist/assets/icons/icon-thumb-down.d.ts +26 -0
- package/dist/assets/icons/icon-thumb-down.d.ts.map +1 -0
- package/dist/assets/icons/icon-thumb-down.js +25 -0
- package/dist/assets/icons/index.d.ts +1 -0
- package/dist/assets/icons/index.d.ts.map +1 -1
- package/dist/assets/icons/index.js +1 -0
- package/dist/cli/index.js +1 -1
- package/dist/components/dialog.d.ts +2 -0
- package/dist/components/dialog.d.ts.map +1 -0
- package/dist/components/dialog.js +3 -0
- package/dist/config.d.ts +67 -3
- package/dist/config.d.ts.map +1 -1
- package/dist/controls.d.ts +23 -1
- package/dist/controls.d.ts.map +1 -1
- package/dist/controls.js +44 -3
- package/dist/footer.js +1 -1
- package/dist/internal/chat/activity.d.ts +5 -1
- package/dist/internal/chat/activity.d.ts.map +1 -1
- package/dist/internal/chat/activity.js +11 -4
- package/dist/internal/chat/chat-user.d.ts +12 -0
- package/dist/internal/chat/chat-user.d.ts.map +1 -0
- package/dist/internal/chat/chat-user.js +27 -0
- package/dist/internal/chat/commands.d.ts +91 -0
- package/dist/internal/chat/commands.d.ts.map +1 -0
- package/dist/internal/chat/commands.js +165 -0
- package/dist/internal/chat/context.d.ts +46 -2
- package/dist/internal/chat/context.d.ts.map +1 -1
- package/dist/internal/chat/context.js +50 -4
- package/dist/internal/chat/message-actions.d.ts +15 -0
- package/dist/internal/chat/message-actions.d.ts.map +1 -0
- package/dist/internal/chat/message-actions.js +113 -0
- package/dist/internal/chat/message-feedback.d.ts +68 -0
- package/dist/internal/chat/message-feedback.d.ts.map +1 -0
- package/dist/internal/chat/message-feedback.js +188 -0
- package/dist/internal/chat/message-metadata.d.ts.map +1 -1
- package/dist/internal/chat/message-metadata.js +7 -1
- package/dist/internal/chat/message-text.d.ts +9 -0
- package/dist/internal/chat/message-text.d.ts.map +1 -0
- package/dist/internal/chat/message-text.js +15 -0
- package/dist/internal/chat/message.d.ts +4 -2
- package/dist/internal/chat/message.d.ts.map +1 -1
- package/dist/internal/chat/message.js +10 -6
- package/dist/internal/chat/options.d.ts +94 -0
- package/dist/internal/chat/options.d.ts.map +1 -0
- package/dist/internal/chat/options.js +171 -0
- package/dist/internal/chat/page-attachment.d.ts +12 -0
- package/dist/internal/chat/page-attachment.d.ts.map +1 -0
- package/dist/internal/chat/page-attachment.js +18 -0
- package/dist/internal/chat/session-provider.d.ts +33 -0
- package/dist/internal/chat/session-provider.d.ts.map +1 -0
- package/dist/internal/chat/session-provider.js +138 -0
- package/dist/internal/chat/session.d.ts +60 -0
- package/dist/internal/chat/session.d.ts.map +1 -0
- package/dist/internal/chat/session.js +85 -0
- package/dist/internal/chat/shell.d.ts.map +1 -1
- package/dist/internal/chat/shell.js +81 -157
- package/dist/internal/chat/use-chat-commands.d.ts +28 -0
- package/dist/internal/chat/use-chat-commands.d.ts.map +1 -0
- package/dist/internal/chat/use-chat-commands.js +62 -0
- package/dist/internal/chat/user-avatar.d.ts +7 -0
- package/dist/internal/chat/user-avatar.d.ts.map +1 -0
- package/dist/internal/chat/user-avatar.js +27 -0
- package/dist/internal/eve-agent-session-cookie.d.ts +68 -0
- package/dist/internal/eve-agent-session-cookie.d.ts.map +1 -0
- package/dist/internal/eve-agent-session-cookie.js +164 -0
- package/dist/internal/eve-agent-session.d.ts +9 -7
- package/dist/internal/eve-agent-session.d.ts.map +1 -1
- package/dist/internal/eve-agent-session.js +10 -13
- package/dist/internal/eve-agent.d.ts +96 -24
- package/dist/internal/eve-agent.d.ts.map +1 -1
- package/dist/internal/eve-agent.js +74 -51
- package/dist/internal/feedback-action.d.ts +14 -0
- package/dist/internal/feedback-action.d.ts.map +1 -1
- package/dist/internal/feedback-action.js +37 -5
- package/dist/internal/page-actions-client.d.ts +9 -0
- package/dist/internal/page-actions-client.d.ts.map +1 -1
- package/dist/internal/page-actions-client.js +8 -4
- package/dist/internal/provider-client.d.ts.map +1 -1
- package/dist/internal/provider-client.js +2 -2
- package/dist/internal/use-mobile.d.ts +7 -0
- package/dist/internal/use-mobile.d.ts.map +1 -1
- package/dist/internal/use-mobile.js +17 -1
- package/dist/internal/webmcp-client.d.ts.map +1 -1
- package/dist/internal/webmcp-client.js +13 -3
- package/dist/internal/webmcp.d.ts +5 -1
- package/dist/internal/webmcp.d.ts.map +1 -1
- package/dist/internal/webmcp.js +31 -1
- package/dist/pages/changelog.d.ts.map +1 -1
- package/dist/pages/changelog.js +4 -0
- package/dist/pages/docs.d.ts.map +1 -1
- package/dist/pages/docs.js +2 -0
- package/dist/providers/public/components/dialog.d.ts +27 -0
- package/dist/providers/public/components/dialog.d.ts.map +1 -0
- package/dist/providers/public/components/dialog.js +17 -0
- package/dist/routes/chat.d.ts +83 -5
- package/dist/routes/chat.d.ts.map +1 -1
- package/dist/routes/chat.js +517 -80
- package/dist/routes/discovery.d.ts +1 -1
- package/dist/routes/discovery.d.ts.map +1 -1
- package/dist/routes/discovery.js +7 -11
- package/dist/routes/openapi.d.ts.map +1 -1
- package/dist/routes/openapi.js +47 -25
- package/docs/agents.md +4 -3
- package/docs/llms.txt +711 -35
- package/docs/manifest.json +12 -3
- package/docs/pages/agent-readiness.md +1 -1
- package/docs/pages/ask-ai.md +567 -24
- package/docs/pages/components/dialog.md +74 -0
- package/docs/pages/components/index.md +1 -0
- package/docs/pages/configuration.md +21 -1
- package/docs/pages/env.md +17 -3
- package/docs/pages/feedback.md +4 -0
- package/docs/pages/webmcp.md +18 -3
- package/docs/sitemap.md +2 -1
- package/package.json +5 -2
- package/public-foundation.css +12 -0
- package/template/.env.example +5 -0
- package/template/AGENTS.md +2 -0
- package/template/components/geistdocs/dialog-demo.tsx +44 -0
- package/template/content/docs/agent-readiness.mdx +1 -1
- package/template/content/docs/ask-ai.cn.mdx +466 -15
- package/template/content/docs/ask-ai.mdx +567 -24
- package/template/content/docs/components/dialog.mdx +70 -0
- package/template/content/docs/components/index.mdx +1 -0
- package/template/content/docs/components/meta.json +1 -0
- package/template/content/docs/configuration.cn.mdx +39 -0
- package/template/content/docs/configuration.mdx +21 -1
- package/template/content/docs/env.cn.mdx +15 -1
- package/template/content/docs/env.mdx +18 -4
- package/template/content/docs/feedback.cn.mdx +4 -0
- package/template/content/docs/feedback.mdx +4 -0
- package/template/content/docs/webmcp.mdx +18 -3
- package/template/package.json +1 -2
- package/dist/providers/public/components/modal.d.ts +0 -22
- package/dist/providers/public/components/modal.d.ts.map +0 -1
- package/dist/providers/public/components/modal.js +0 -19
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.
|
|
3
|
+
These docs are bundled with `@vercel/geistdocs` 2.8.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.
|
|
@@ -30,6 +30,7 @@ They describe how to build package-backed Geistdocs sites and how to use the pac
|
|
|
30
30
|
- [Configure sidebar navigation](pages/guides/nested-navigation.md): Configure sidebar order, section labels, folder landing pages, and deeply nested page trees with meta.json files.
|
|
31
31
|
- [Copy Prompt](pages/components/copy-prompt.md): Use CopyPrompt for reusable instructions that readers can send to an AI assistant.
|
|
32
32
|
- [Details](pages/components/details.md): Compose Details and Summary for accessible browser-native disclosures.
|
|
33
|
+
- [Dialog](pages/components/dialog.md): Compose Dialog primitives for modal search, chat, forms, and confirmations.
|
|
33
34
|
- [Dropdown Menu](pages/components/dropdown-menu.md): Compose DropdownMenu primitives for application-owned menus outside MDX.
|
|
34
35
|
- [Edit on GitHub](pages/edit-on-github.md): A direct link on every documentation page that lets readers propose changes through GitHub pull requests.
|
|
35
36
|
- [Feedback](pages/feedback.md): An interactive feedback widget that collects user sentiment and creates structured GitHub Issues automatically.
|
|
@@ -53,7 +54,7 @@ They describe how to build package-backed Geistdocs sites and how to use the pac
|
|
|
53
54
|
- [Toggle](pages/components/toggle.md): Toggle is the provider-backed replacement for the former Switch export.
|
|
54
55
|
- [Tooltip](pages/components/tooltip.md): Wrap controls with provider-backed Tooltip content outside MDX.
|
|
55
56
|
- [Video](pages/components/video.md): Use Video for embedded video sources inside React UI or authored MDX.
|
|
56
|
-
- [WebMCP](pages/webmcp.md): Expose documentation search
|
|
57
|
+
- [WebMCP](pages/webmcp.md): Expose documentation search, page reading, and Ask AI to browser agents.
|
|
57
58
|
|
|
58
59
|
---
|
|
59
60
|
|
|
@@ -325,7 +326,7 @@ Then follow [Deploy to Vercel](/docs/deployment), including environment-variable
|
|
|
325
326
|
title: Environment Variables
|
|
326
327
|
description: Learn about the environment variables used in Geistdocs
|
|
327
328
|
type: reference
|
|
328
|
-
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.
|
|
329
330
|
url: /docs/env
|
|
330
331
|
source: apps/template/content/docs/env.mdx
|
|
331
332
|
prerequisites:
|
|
@@ -337,9 +338,9 @@ related:
|
|
|
337
338
|
|
|
338
339
|
# Environment Variables
|
|
339
340
|
|
|
340
|
-
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.
|
|
341
342
|
|
|
342
|
-
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.
|
|
343
344
|
|
|
344
345
|
## `AI_GATEWAY_API_KEY`
|
|
345
346
|
|
|
@@ -388,6 +389,20 @@ To route Ask AI through Vertex:
|
|
|
388
389
|
|
|
389
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.
|
|
390
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
|
+
|
|
391
406
|
## `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL`
|
|
392
407
|
|
|
393
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.
|
|
@@ -1323,7 +1338,27 @@ export const ai = {
|
|
|
1323
1338
|
|
|
1324
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.
|
|
1325
1340
|
|
|
1326
|
-
|
|
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.
|
|
1327
1362
|
|
|
1328
1363
|
Use [Versioned docs](/docs/versioned-docs) for versioned source setup and [Proxy and markdown routes](/docs/proxy) for route mappings.
|
|
1329
1364
|
|
|
@@ -3756,7 +3791,7 @@ export const agent = {
|
|
|
3756
3791
|
|
|
3757
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.
|
|
3758
3793
|
|
|
3759
|
-
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
|
|
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.
|
|
3760
3795
|
|
|
3761
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.
|
|
3762
3797
|
|
|
@@ -3811,11 +3846,19 @@ The AI chat assistant is available in two ways:
|
|
|
3811
3846
|
|
|
3812
3847
|
### 1. Per-Page Quick Access
|
|
3813
3848
|
|
|
3814
|
-
Each documentation page has an "Ask AI about this page"
|
|
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:
|
|
3850
|
+
|
|
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.
|
|
3815
3856
|
|
|
3816
|
-
|
|
3817
|
-
|
|
3818
|
-
|
|
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.
|
|
3819
3862
|
|
|
3820
3863
|
### 2. Global Chat Interface
|
|
3821
3864
|
|
|
@@ -3827,10 +3870,87 @@ Users can open the chat interface at any time by:
|
|
|
3827
3870
|
Once open, users can:
|
|
3828
3871
|
|
|
3829
3872
|
- Ask questions about any part of your documentation
|
|
3830
|
-
-
|
|
3831
|
-
-
|
|
3873
|
+
- View the documentation pages used as sources for each answer
|
|
3874
|
+
- Copy an answer as Markdown
|
|
3832
3875
|
- Get step-by-step guidance on complex topics
|
|
3833
3876
|
|
|
3877
|
+
## Control Ask AI from your own components
|
|
3878
|
+
|
|
3879
|
+
`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.
|
|
3880
|
+
|
|
3881
|
+
| Property | Type | Description |
|
|
3882
|
+
| -------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
|
|
3883
|
+
| `enabled` | `boolean` | `false` when `ai.enabled` is `false`. All actions are then no-ops. |
|
|
3884
|
+
| `isOpen` | `boolean` | Whether the chat panel is open. |
|
|
3885
|
+
| `open` | `() => void` | Opens the chat. |
|
|
3886
|
+
| `close` | `() => void` | Closes the chat. |
|
|
3887
|
+
| `toggle` | `() => void` | Opens the chat when it's closed and closes it when it's open. |
|
|
3888
|
+
| `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. |
|
|
3889
|
+
| `ask` | `(text: string) => void` | Opens the chat and sends `text` as a user message. |
|
|
3890
|
+
|
|
3891
|
+
### Add an "Ask about this page" button to a custom header
|
|
3892
|
+
|
|
3893
|
+
`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.
|
|
3894
|
+
|
|
3895
|
+
```tsx title="components/ask-about-page-button.tsx"
|
|
3896
|
+
"use client";
|
|
3897
|
+
|
|
3898
|
+
import { useGeistdocsChat } from "@vercel/geistdocs/controls";
|
|
3899
|
+
|
|
3900
|
+
export const AskAboutPageButton = () => {
|
|
3901
|
+
const { enabled, openWithPage } = useGeistdocsChat();
|
|
3902
|
+
|
|
3903
|
+
if (!enabled) {
|
|
3904
|
+
return null;
|
|
3905
|
+
}
|
|
3906
|
+
|
|
3907
|
+
return (
|
|
3908
|
+
<button onClick={() => openWithPage()} type="button">
|
|
3909
|
+
Ask about this page
|
|
3910
|
+
</button>
|
|
3911
|
+
);
|
|
3912
|
+
};
|
|
3913
|
+
```
|
|
3914
|
+
|
|
3915
|
+
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.
|
|
3916
|
+
|
|
3917
|
+
### Send a question with `ask`
|
|
3918
|
+
|
|
3919
|
+
`ask` opens the chat and sends the text as if the reader typed it. Use it for buttons that start a specific conversation:
|
|
3920
|
+
|
|
3921
|
+
```tsx title="components/ask-button.tsx"
|
|
3922
|
+
"use client";
|
|
3923
|
+
|
|
3924
|
+
import { useGeistdocsChat } from "@vercel/geistdocs/controls";
|
|
3925
|
+
|
|
3926
|
+
export const AskButton = ({ question }: { question: string }) => {
|
|
3927
|
+
const { ask, enabled } = useGeistdocsChat();
|
|
3928
|
+
|
|
3929
|
+
if (!enabled) {
|
|
3930
|
+
return null;
|
|
3931
|
+
}
|
|
3932
|
+
|
|
3933
|
+
return (
|
|
3934
|
+
<button onClick={() => ask(question)} type="button">
|
|
3935
|
+
{question}
|
|
3936
|
+
</button>
|
|
3937
|
+
);
|
|
3938
|
+
};
|
|
3939
|
+
```
|
|
3940
|
+
|
|
3941
|
+
`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.
|
|
3942
|
+
|
|
3943
|
+
Call `openWithPage` before `ask` to send a question about a page in a new conversation:
|
|
3944
|
+
|
|
3945
|
+
```tsx
|
|
3946
|
+
const { ask, openWithPage } = useGeistdocsChat();
|
|
3947
|
+
|
|
3948
|
+
const summarize = () => {
|
|
3949
|
+
openWithPage();
|
|
3950
|
+
ask("Summarize this page in three bullet points.");
|
|
3951
|
+
};
|
|
3952
|
+
```
|
|
3953
|
+
|
|
3834
3954
|
## Add a chat footer
|
|
3835
3955
|
|
|
3836
3956
|
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.
|
|
@@ -3845,6 +3965,111 @@ export const ai = {
|
|
|
3845
3965
|
};
|
|
3846
3966
|
```
|
|
3847
3967
|
|
|
3968
|
+
## Rename the chat panel
|
|
3969
|
+
|
|
3970
|
+
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.
|
|
3971
|
+
|
|
3972
|
+
```tsx title="geistdocs.tsx"
|
|
3973
|
+
export const ai = {
|
|
3974
|
+
title: "Ask Acme AI",
|
|
3975
|
+
};
|
|
3976
|
+
```
|
|
3977
|
+
|
|
3978
|
+
`ai.title` only changes the chat panel. The navbar "Ask AI" button and the "Ask AI about this page" page action keep their labels.
|
|
3979
|
+
|
|
3980
|
+
## Serve chat from a different route
|
|
3981
|
+
|
|
3982
|
+
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.
|
|
3983
|
+
|
|
3984
|
+
```tsx title="geistdocs.tsx"
|
|
3985
|
+
export const ai = {
|
|
3986
|
+
endpoint: "/api/ai-chat",
|
|
3987
|
+
};
|
|
3988
|
+
```
|
|
3989
|
+
|
|
3990
|
+
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.
|
|
3991
|
+
|
|
3992
|
+
`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.
|
|
3993
|
+
|
|
3994
|
+
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.
|
|
3995
|
+
|
|
3996
|
+
## Copy an answer
|
|
3997
|
+
|
|
3998
|
+
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.
|
|
3999
|
+
|
|
4000
|
+
To copy the whole conversation, use the copy button in the chat header.
|
|
4001
|
+
|
|
4002
|
+
## Collect feedback on answers
|
|
4003
|
+
|
|
4004
|
+
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`.
|
|
4005
|
+
|
|
4006
|
+
```tsx title="geistdocs.tsx"
|
|
4007
|
+
export const ai = {
|
|
4008
|
+
messageFeedback: true,
|
|
4009
|
+
};
|
|
4010
|
+
```
|
|
4011
|
+
|
|
4012
|
+
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:
|
|
4013
|
+
|
|
4014
|
+
| Field | Content |
|
|
4015
|
+
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
4016
|
+
| `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. |
|
|
4017
|
+
| `thumbs` | `"up"` or `"down"`. The feedback service labels the issue `thumbs-up` or `thumbs-down`. |
|
|
4018
|
+
| `url` | The page the reader was on when they voted. |
|
|
4019
|
+
| `label` | Your `siteId`. |
|
|
4020
|
+
| `ua`, `ip` | The reader's user agent and IP address, as with page feedback. |
|
|
4021
|
+
|
|
4022
|
+
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`.
|
|
4023
|
+
|
|
4024
|
+
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.
|
|
4025
|
+
|
|
4026
|
+
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.
|
|
4027
|
+
|
|
4028
|
+
## Show the signed-in reader's avatar
|
|
4029
|
+
|
|
4030
|
+
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.
|
|
4031
|
+
|
|
4032
|
+
`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.
|
|
4033
|
+
|
|
4034
|
+
| Prop | Type | Description |
|
|
4035
|
+
| ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
4036
|
+
| `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. |
|
|
4037
|
+
| `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. |
|
|
4038
|
+
|
|
4039
|
+
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:
|
|
4040
|
+
|
|
4041
|
+
```tsx title="components/ask-ai-user.tsx"
|
|
4042
|
+
"use client";
|
|
4043
|
+
|
|
4044
|
+
import { AskAIUser } from "@vercel/geistdocs/controls";
|
|
4045
|
+
import { useSession } from "@/lib/auth-client";
|
|
4046
|
+
|
|
4047
|
+
export const SignedInAskAIUser = () => {
|
|
4048
|
+
const { data: session } = useSession();
|
|
4049
|
+
|
|
4050
|
+
if (!session?.user.image) {
|
|
4051
|
+
return null;
|
|
4052
|
+
}
|
|
4053
|
+
|
|
4054
|
+
return (
|
|
4055
|
+
<AskAIUser avatarUrl={session.user.image} name={session.user.name} />
|
|
4056
|
+
);
|
|
4057
|
+
};
|
|
4058
|
+
```
|
|
4059
|
+
|
|
4060
|
+
Then render it once inside `GeistdocsProvider` in your root layout:
|
|
4061
|
+
|
|
4062
|
+
```tsx title="app/[lang]/layout.tsx"
|
|
4063
|
+
<GeistdocsProvider basePath={config.basePath} lang={lang}>
|
|
4064
|
+
<SignedInAskAIUser />
|
|
4065
|
+
<Navbar config={config} />
|
|
4066
|
+
{children}
|
|
4067
|
+
<Footer />
|
|
4068
|
+
</GeistdocsProvider>
|
|
4069
|
+
```
|
|
4070
|
+
|
|
4071
|
+
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.
|
|
4072
|
+
|
|
3848
4073
|
## AI SDK dependency ownership
|
|
3849
4074
|
|
|
3850
4075
|
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.
|
|
@@ -3909,7 +4134,9 @@ https://<geistdocs-platform-deployment>/vertex
|
|
|
3909
4134
|
|
|
3910
4135
|
4. Leave `GEISTDOCS_CHAT_PROXY_TOKEN` unset unless you are using a custom proxy that requires bearer authentication.
|
|
3911
4136
|
|
|
3912
|
-
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.
|
|
4137
|
+
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.
|
|
4138
|
+
|
|
4139
|
+
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).
|
|
3913
4140
|
|
|
3914
4141
|
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.
|
|
3915
4142
|
|
|
@@ -3926,15 +4153,15 @@ export const ai = {
|
|
|
3926
4153
|
};
|
|
3927
4154
|
```
|
|
3928
4155
|
|
|
3929
|
-
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
|
|
4156
|
+
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.
|
|
3930
4157
|
|
|
3931
|
-
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.
|
|
4158
|
+
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.
|
|
3932
4159
|
|
|
3933
4160
|
Eve agent mode keeps the platform-owned behavior from proxy mode:
|
|
3934
4161
|
|
|
3935
|
-
- Local docs retrieval runs on the first user message, and the current page plus related docs are inlined into the message the agent receives.
|
|
4162
|
+
- 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.
|
|
3936
4163
|
- Locally computed source citations are injected into the response stream, and `excludeFrom: [chat]` page visibility is enforced before anything reaches the agent.
|
|
3937
|
-
- 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.
|
|
4164
|
+
- 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).
|
|
3938
4165
|
|
|
3939
4166
|
**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:
|
|
3940
4167
|
|
|
@@ -3948,9 +4175,314 @@ export const { POST, maxDuration } = createChatRoute({
|
|
|
3948
4175
|
});
|
|
3949
4176
|
```
|
|
3950
4177
|
|
|
3951
|
-
Never put authentication material in `geistdocs.tsx
|
|
4178
|
+
Never put authentication material in `geistdocs.tsx`, because the config ships to the client bundle. The agent URL is public configuration; tokens are not.
|
|
4179
|
+
|
|
4180
|
+
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.
|
|
4181
|
+
|
|
4182
|
+
| `eveAgent` option | Type | Default | Description |
|
|
4183
|
+
| ----------------- | ------------------------------------- | ------------------ | ----------- |
|
|
4184
|
+
| `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`. |
|
|
4185
|
+
| `headers` | `HeadersInit \| (request: Request) => HeadersInit \| Promise<HeadersInit>` | OIDC headers | Extra request headers. An `authorization` header replaces the OIDC bearer token. |
|
|
4186
|
+
| `secret` | `string` | `GEISTDOCS_CHAT_SECRET` | Secret that signs the eve session cookie, at least 32 bytes. |
|
|
4187
|
+
| `clientContext` | `boolean` | `false` | Send the current page as eve `clientContext` with every message. |
|
|
4188
|
+
| `visibleTools` | `string[]` | All tools | Tool names whose calls the chat shows. |
|
|
4189
|
+
| `toolCitations` | `boolean` | `true` | Forward tool outputs and show the URLs in them as source citations. |
|
|
4190
|
+
|
|
4191
|
+
#### Keep eve sessions across turns with `GEISTDOCS_CHAT_SECRET`
|
|
4192
|
+
|
|
4193
|
+
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.
|
|
4194
|
+
|
|
4195
|
+
The `geistdocs_eve_session` cookie has these attributes:
|
|
4196
|
+
|
|
4197
|
+
| Attribute | Value |
|
|
4198
|
+
| ---------- | ------------------------------------------------------------ |
|
|
4199
|
+
| `HttpOnly` | Always set |
|
|
4200
|
+
| `SameSite` | `Strict` |
|
|
4201
|
+
| `Secure` | Set when the request uses HTTPS, including behind a proxy that sends `x-forwarded-proto: https` |
|
|
4202
|
+
| `Path` | The chat route's own path, such as `/api/chat` or `/docs/api/chat` under a base path |
|
|
4203
|
+
| `Max-Age` | 7 days, renewed after every turn |
|
|
4204
|
+
|
|
4205
|
+
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:
|
|
4206
|
+
|
|
4207
|
+
- The reader deleted the chat, or the cookie expired after 7 days without a turn.
|
|
4208
|
+
- 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.
|
|
4209
|
+
- 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.
|
|
4210
|
+
- The eve session is no longer active on the agent.
|
|
4211
|
+
|
|
4212
|
+
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.
|
|
4213
|
+
|
|
4214
|
+
##### Set the secret
|
|
4215
|
+
|
|
4216
|
+
Generate a secret of at least 32 bytes:
|
|
4217
|
+
|
|
4218
|
+
```bash title="Terminal"
|
|
4219
|
+
openssl rand -base64 32
|
|
4220
|
+
```
|
|
4221
|
+
|
|
4222
|
+
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.
|
|
4223
|
+
|
|
4224
|
+
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.
|
|
4225
|
+
|
|
4226
|
+
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.
|
|
4227
|
+
|
|
4228
|
+
```ts title="app/api/chat/route.ts"
|
|
4229
|
+
export const { POST, maxDuration } = createChatRoute({
|
|
4230
|
+
config,
|
|
4231
|
+
sources: [geistdocsSource],
|
|
4232
|
+
eveAgent: {
|
|
4233
|
+
secret: process.env.ASK_AI_SESSION_SECRET,
|
|
4234
|
+
},
|
|
4235
|
+
});
|
|
4236
|
+
```
|
|
4237
|
+
|
|
4238
|
+
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.
|
|
4239
|
+
|
|
4240
|
+
A secret shorter than 32 bytes throws when the route module loads, so a weak secret fails the deployment instead of signing cookies.
|
|
4241
|
+
|
|
4242
|
+
##### Serve the chat route from the same site
|
|
4243
|
+
|
|
4244
|
+
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.
|
|
4245
|
+
|
|
4246
|
+
##### Run without a secret
|
|
4247
|
+
|
|
4248
|
+
Without `GEISTDOCS_CHAT_SECRET`, eve agent mode still answers every question, but it never sets or reads the session cookie:
|
|
4249
|
+
|
|
4250
|
+
- Every turn starts a new eve session, with up to 8,000 characters of the prior conversation inlined into the message.
|
|
4251
|
+
- The route refuses `{ prewarm: true }` requests with a `400` response, so `prewarm: true` only adds a failed request when Ask AI loads.
|
|
4252
|
+
- The server logs a warning that names `GEISTDOCS_CHAT_SECRET`.
|
|
4253
|
+
|
|
4254
|
+
### Choose what context the proxy or agent receives
|
|
4255
|
+
|
|
4256
|
+
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.
|
|
4257
|
+
|
|
4258
|
+
| `contextInjection` | Message without an attached page | Message with an attached page (`pageContext`) | Source citations Geistdocs adds |
|
|
4259
|
+
| ------------------ | -------------------------------- | --------------------------------------------- | ------------------------------- |
|
|
4260
|
+
| `"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 |
|
|
4261
|
+
| `"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 |
|
|
4262
|
+
|
|
4263
|
+
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`.
|
|
4264
|
+
|
|
4265
|
+
```ts title="app/api/chat/route.ts"
|
|
4266
|
+
export const { POST, maxDuration } = createChatRoute({
|
|
4267
|
+
config,
|
|
4268
|
+
contextInjection: "page-only",
|
|
4269
|
+
proxy: { url: process.env.GEISTDOCS_CHAT_PROXY_URL! },
|
|
4270
|
+
sources: [geistdocsSource],
|
|
4271
|
+
});
|
|
4272
|
+
```
|
|
4273
|
+
|
|
4274
|
+
In `"page-only"` mode, proxy mode replaces the text of the last user message with the attached page followed by the question:
|
|
4275
|
+
|
|
4276
|
+
```md
|
|
4277
|
+
Here's the content from the current page:
|
|
4278
|
+
|
|
4279
|
+
**Page:** Routing
|
|
4280
|
+
**URL:** https://docs.example.com/docs/routing
|
|
4281
|
+
|
|
4282
|
+
---
|
|
4283
|
+
|
|
4284
|
+
<full page Markdown>
|
|
4285
|
+
|
|
4286
|
+
---
|
|
4287
|
+
|
|
4288
|
+
User question: How do I add a redirect?
|
|
4289
|
+
```
|
|
4290
|
+
|
|
4291
|
+
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:
|
|
4292
|
+
|
|
4293
|
+
```json
|
|
4294
|
+
{
|
|
4295
|
+
"message": [
|
|
4296
|
+
{
|
|
4297
|
+
"type": "text",
|
|
4298
|
+
"text": "Page context:\n{\"title\":\"Routing\",\"url\":\"https://docs.example.com/docs/routing\",\"content\":\"<full page Markdown>\"}"
|
|
4299
|
+
},
|
|
4300
|
+
{ "type": "text", "text": "How do I add a redirect?" }
|
|
4301
|
+
]
|
|
4302
|
+
}
|
|
4303
|
+
```
|
|
4304
|
+
|
|
4305
|
+
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.
|
|
4306
|
+
|
|
4307
|
+
### Send the current page to an eve agent
|
|
4308
|
+
|
|
4309
|
+
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.
|
|
4310
|
+
|
|
4311
|
+
```ts title="app/api/chat/route.ts"
|
|
4312
|
+
export const { POST, maxDuration } = createChatRoute({
|
|
4313
|
+
config,
|
|
4314
|
+
eveAgent: { clientContext: true },
|
|
4315
|
+
sources: [geistdocsSource],
|
|
4316
|
+
});
|
|
4317
|
+
```
|
|
4318
|
+
|
|
4319
|
+
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:
|
|
4320
|
+
|
|
4321
|
+
```json
|
|
4322
|
+
{
|
|
4323
|
+
"message": "How do I add a redirect?",
|
|
4324
|
+
"clientContext": {
|
|
4325
|
+
"currentPage": {
|
|
4326
|
+
"url": "https://docs.example.com/docs/routing",
|
|
4327
|
+
"title": "Routing"
|
|
4328
|
+
}
|
|
4329
|
+
}
|
|
4330
|
+
}
|
|
4331
|
+
```
|
|
4332
|
+
|
|
4333
|
+
The route derives `clientContext` from the `currentRoute` the Ask AI client already sends, so the client needs no changes:
|
|
4334
|
+
|
|
4335
|
+
- `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.
|
|
4336
|
+
- `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`.
|
|
4337
|
+
- A request without `currentRoute`, or with a `currentRoute` longer than 2,048 characters, sends no `clientContext`.
|
|
4338
|
+
|
|
4339
|
+
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.
|
|
4340
|
+
|
|
4341
|
+
### Choose which agent tool calls the chat shows
|
|
4342
|
+
|
|
4343
|
+
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:
|
|
4344
|
+
|
|
4345
|
+
- `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.
|
|
4346
|
+
- `toolCitations: false` keeps the activity label but sends each tool output to the chat as `null` and adds no source citations.
|
|
4347
|
+
|
|
4348
|
+
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:
|
|
4349
|
+
|
|
4350
|
+
```tsx title="geistdocs.tsx"
|
|
4351
|
+
export const ai = {
|
|
4352
|
+
toolLabels: {
|
|
4353
|
+
web_search: "Searching...",
|
|
4354
|
+
web_fetch: "Searching...",
|
|
4355
|
+
},
|
|
4356
|
+
};
|
|
4357
|
+
```
|
|
4358
|
+
|
|
4359
|
+
Tools without a non-blank label keep the default label.
|
|
4360
|
+
|
|
4361
|
+
### Forward per-request values in upstream headers
|
|
4362
|
+
|
|
4363
|
+
`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.
|
|
4364
|
+
|
|
4365
|
+
```ts title="app/api/chat/route.ts"
|
|
4366
|
+
export const { POST, maxDuration } = createChatRoute({
|
|
4367
|
+
config,
|
|
4368
|
+
eveAgent: {
|
|
4369
|
+
headers: (request) => ({
|
|
4370
|
+
"x-evo-surface": "docs",
|
|
4371
|
+
"x-docs-locale": request.headers.get("accept-language") ?? "en",
|
|
4372
|
+
}),
|
|
4373
|
+
},
|
|
4374
|
+
sources: [geistdocsSource],
|
|
4375
|
+
});
|
|
4376
|
+
```
|
|
4377
|
+
|
|
4378
|
+
Use a static object for fixed values such as `x-evo-surface: docs`.
|
|
4379
|
+
|
|
4380
|
+
### Match a production Vertex or eve setup
|
|
4381
|
+
|
|
4382
|
+
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.
|
|
4383
|
+
|
|
4384
|
+
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.
|
|
4385
|
+
|
|
4386
|
+
```ts title="app/api/ai-chat/route.ts"
|
|
4387
|
+
import { createChatRoute } from "@vercel/geistdocs/routes/chat";
|
|
4388
|
+
import { config } from "@/lib/geistdocs/config";
|
|
4389
|
+
import { geistdocsSource } from "@/lib/geistdocs/source";
|
|
4390
|
+
import { enableDocsAgent } from "@/flags";
|
|
4391
|
+
|
|
4392
|
+
const vertex = createChatRoute({
|
|
4393
|
+
config,
|
|
4394
|
+
contextInjection: "page-only",
|
|
4395
|
+
proxy: {
|
|
4396
|
+
url: `${process.env.VERTEX_URL}/api/chat/docs`,
|
|
4397
|
+
headers: {
|
|
4398
|
+
"x-vercel-protection-bypass": process.env.VERTEX_BYPASS_SECRET ?? "",
|
|
4399
|
+
},
|
|
4400
|
+
},
|
|
4401
|
+
sources: [geistdocsSource],
|
|
4402
|
+
});
|
|
4403
|
+
|
|
4404
|
+
const agent = createChatRoute({
|
|
4405
|
+
config,
|
|
4406
|
+
contextInjection: "page-only",
|
|
4407
|
+
eveAgent: {
|
|
4408
|
+
url: process.env.EVE_AGENT_URL,
|
|
4409
|
+
clientContext: true,
|
|
4410
|
+
headers: { "x-evo-surface": "docs" },
|
|
4411
|
+
visibleTools: ["web_search", "web_fetch", "knowledge-search"],
|
|
4412
|
+
toolCitations: false,
|
|
4413
|
+
},
|
|
4414
|
+
sources: [geistdocsSource],
|
|
4415
|
+
});
|
|
4416
|
+
|
|
4417
|
+
export const maxDuration = 800;
|
|
4418
|
+
|
|
4419
|
+
export const POST = async (request: Request) =>
|
|
4420
|
+
(await enableDocsAgent()) ? agent.POST(request) : vertex.POST(request);
|
|
4421
|
+
```
|
|
4422
|
+
|
|
4423
|
+
```tsx title="geistdocs.tsx"
|
|
4424
|
+
export const ai = {
|
|
4425
|
+
endpoint: "/api/ai-chat",
|
|
4426
|
+
toolLabels: {
|
|
4427
|
+
web_search: "Searching...",
|
|
4428
|
+
web_fetch: "Searching...",
|
|
4429
|
+
"knowledge-search": "Searching...",
|
|
4430
|
+
},
|
|
4431
|
+
};
|
|
4432
|
+
```
|
|
4433
|
+
|
|
4434
|
+
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.
|
|
4435
|
+
|
|
4436
|
+
## Request size limits
|
|
4437
|
+
|
|
4438
|
+
`createChatRoute` rejects oversized requests before they reach the model, the chat proxy, or the eve agent. The same defaults apply in every AI mode:
|
|
4439
|
+
|
|
4440
|
+
| Limit option | Default | Response when exceeded |
|
|
4441
|
+
| --------------------- | ---------------------------- | ---------------------- |
|
|
4442
|
+
| `maxRequestBytes` | `1_000_000` bytes (1 MB) | `413` |
|
|
4443
|
+
| `maxMessages` | `200` messages | `400` |
|
|
4444
|
+
| `maxPageContextChars` | `200_000` characters | `400` |
|
|
4445
|
+
|
|
4446
|
+
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.
|
|
4447
|
+
|
|
4448
|
+
`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`.
|
|
4449
|
+
|
|
4450
|
+
Change the limits with the `limits` option:
|
|
4451
|
+
|
|
4452
|
+
```ts title="app/api/chat/route.ts"
|
|
4453
|
+
export const { POST, maxDuration } = createChatRoute({
|
|
4454
|
+
config,
|
|
4455
|
+
sources: [geistdocsSource],
|
|
4456
|
+
limits: {
|
|
4457
|
+
maxRequestBytes: 500_000,
|
|
4458
|
+
maxMessages: 100,
|
|
4459
|
+
maxPageContextChars: 100_000,
|
|
4460
|
+
},
|
|
4461
|
+
});
|
|
4462
|
+
```
|
|
4463
|
+
|
|
4464
|
+
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`:
|
|
4465
|
+
|
|
4466
|
+
```ts title="app/api/chat/route.ts"
|
|
4467
|
+
import { checkRateLimit } from "@vercel/firewall";
|
|
4468
|
+
import { createChatRoute } from "@vercel/geistdocs/routes/chat";
|
|
4469
|
+
import { config } from "@/lib/geistdocs/config";
|
|
4470
|
+
import { geistdocsSource } from "@/lib/geistdocs/source";
|
|
3952
4471
|
|
|
3953
|
-
|
|
4472
|
+
const chat = createChatRoute({ config, sources: [geistdocsSource] });
|
|
4473
|
+
|
|
4474
|
+
export const maxDuration = 800;
|
|
4475
|
+
|
|
4476
|
+
export const POST = async (request: Request) => {
|
|
4477
|
+
const { rateLimited } = await checkRateLimit("ask-ai", { request });
|
|
4478
|
+
|
|
4479
|
+
if (rateLimited) {
|
|
4480
|
+
return Response.json({ error: "Too many requests." }, { status: 429 });
|
|
4481
|
+
}
|
|
4482
|
+
|
|
4483
|
+
return chat.POST(request);
|
|
4484
|
+
};
|
|
4485
|
+
```
|
|
3954
4486
|
|
|
3955
4487
|
## Features
|
|
3956
4488
|
|
|
@@ -3963,26 +4495,48 @@ By default, the AI assistant includes a built-in `search_docs` tool that:
|
|
|
3963
4495
|
3. Shows source citations with links to the referenced pages
|
|
3964
4496
|
4. Uses the content to provide accurate, contextual answers
|
|
3965
4497
|
|
|
3966
|
-
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.
|
|
4498
|
+
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.
|
|
3967
4499
|
|
|
3968
4500
|
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.
|
|
3969
4501
|
|
|
3970
4502
|
### Persistent Chat History
|
|
3971
4503
|
|
|
3972
|
-
|
|
4504
|
+
Ask AI saves the conversation to the browser's IndexedDB, so users can:
|
|
4505
|
+
|
|
4506
|
+
- Keep the conversation across page reloads and navigation
|
|
4507
|
+
- Continue the conversation in a later visit
|
|
4508
|
+
- Copy the conversation or delete it from the chat header
|
|
4509
|
+
|
|
4510
|
+
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.
|
|
4511
|
+
|
|
4512
|
+
Set `ai.history.retentionDays` to change the window:
|
|
4513
|
+
|
|
4514
|
+
```tsx title="geistdocs.tsx"
|
|
4515
|
+
export const ai = {
|
|
4516
|
+
history: {
|
|
4517
|
+
retentionDays: 7,
|
|
4518
|
+
},
|
|
4519
|
+
};
|
|
4520
|
+
```
|
|
3973
4521
|
|
|
3974
|
-
|
|
3975
|
-
|
|
3976
|
-
|
|
3977
|
-
|
|
4522
|
+
| Value | Behavior |
|
|
4523
|
+
| ------------------------------------ | ------------------------------------------------------------------------------- |
|
|
4524
|
+
| Unset | Keeps conversations for 30 days after the most recent message. |
|
|
4525
|
+
| A positive number | Keeps conversations for that many days. `0.5` keeps them for 12 hours. |
|
|
4526
|
+
| `0` | Stores no history. Ask AI clears any stored conversation when it loads. |
|
|
4527
|
+
| `Infinity` | Never expires stored conversations. |
|
|
4528
|
+
| Negative, `NaN`, or `-Infinity` | Uses the 30-day default and logs a warning in the browser console. |
|
|
4529
|
+
|
|
4530
|
+
Chat history is stored per site, keyed by the site `title`, so changing `ai.title` keeps existing history.
|
|
3978
4531
|
|
|
3979
4532
|
### Interactive Features
|
|
3980
4533
|
|
|
3981
|
-
- **Suggestions**:
|
|
3982
|
-
- **File Upload**: Users can attach files or images for context
|
|
4534
|
+
- **Suggestions**: Users see up to four suggested questions when the chat is empty
|
|
3983
4535
|
- **Markdown Support**: Responses are formatted with proper Markdown rendering
|
|
3984
4536
|
- **Code Syntax Highlighting**: Code blocks in responses include syntax highlighting
|
|
3985
|
-
- **
|
|
4537
|
+
- **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
|
|
4538
|
+
|
|
4539
|
+
Ask AI accepts text questions only. It does not support file or image attachments.
|
|
3986
4540
|
|
|
3987
4541
|
### Mobile-Responsive
|
|
3988
4542
|
|
|
@@ -3993,13 +4547,37 @@ The chat interface adapts to different screen sizes:
|
|
|
3993
4547
|
|
|
3994
4548
|
## Configuration
|
|
3995
4549
|
|
|
3996
|
-
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.
|
|
4550
|
+
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.
|
|
3997
4551
|
|
|
3998
4552
|
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.
|
|
3999
4553
|
|
|
4000
4554
|
## Suggested Prompts
|
|
4001
4555
|
|
|
4002
|
-
|
|
4556
|
+
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.
|
|
4557
|
+
|
|
4558
|
+
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:
|
|
4559
|
+
|
|
4560
|
+
```tsx title="geistdocs.tsx"
|
|
4561
|
+
const RocketIcon = () => (
|
|
4562
|
+
<svg aria-hidden="true" fill="none" height="16" viewBox="0 0 16 16" width="16">
|
|
4563
|
+
<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" />
|
|
4564
|
+
</svg>
|
|
4565
|
+
);
|
|
4566
|
+
|
|
4567
|
+
const BookIcon = () => (
|
|
4568
|
+
<svg aria-hidden="true" fill="none" height="16" viewBox="0 0 16 16" width="16">
|
|
4569
|
+
<path d="M3 2.5h7.5v11H3zM10.5 2.5H13v11h-2.5" stroke="currentColor" />
|
|
4570
|
+
</svg>
|
|
4571
|
+
);
|
|
4572
|
+
|
|
4573
|
+
export const suggestions = [
|
|
4574
|
+
"What is Acme?",
|
|
4575
|
+
{ text: "How do I deploy?", icon: <RocketIcon /> },
|
|
4576
|
+
{ text: "Where is the API reference?", icon: <BookIcon /> },
|
|
4577
|
+
];
|
|
4578
|
+
```
|
|
4579
|
+
|
|
4580
|
+
The generated `lib/geistdocs/config.tsx` forwards `suggestions` to `ai.suggestions`. Read the [Configuration](/docs/configuration) section for the rest of the configuration file.
|
|
4003
4581
|
|
|
4004
4582
|
|
|
4005
4583
|
---
|
|
@@ -4310,6 +4888,7 @@ Internal projects using `@vercel/geistdocs-private` use the same component subpa
|
|
|
4310
4888
|
| [Tabs](/docs/components/tabs) | `components/tabs`, `components/tabs-with-children` | Tab navigation and mounted content panels |
|
|
4311
4889
|
| [Collapsible](/docs/components/collapsible) | `components/collapsible` | Expandable content regions |
|
|
4312
4890
|
| [Details](/docs/components/details) | `components/details` | Styled native disclosure elements |
|
|
4891
|
+
| [Dialog](/docs/components/dialog) | `components/dialog` | Modal search, chat, forms, and confirmations |
|
|
4313
4892
|
| [Callout](/docs/components/callout) | `components/callout` | Notices with optional titles and descriptions |
|
|
4314
4893
|
| [Code Block](/docs/components/code-block) | `components/code-block`, `components/code-block-tabs` | Highlighted code and tabbed code groups |
|
|
4315
4894
|
| [Command Prompt](/docs/components/command-prompt) | `components/command-prompt` | Command surfaces with copy support and alternatives |
|
|
@@ -4636,6 +5215,84 @@ export function Disclosure() {
|
|
|
4636
5215
|
`Details` and `Summary` are also included in the default MDX component map.
|
|
4637
5216
|
|
|
4638
5217
|
|
|
5218
|
+
---
|
|
5219
|
+
|
|
5220
|
+
---
|
|
5221
|
+
title: Dialog
|
|
5222
|
+
description: Display focused content in an accessible modal
|
|
5223
|
+
type: reference
|
|
5224
|
+
summary: Compose Dialog primitives for modal search, chat, forms, and confirmations.
|
|
5225
|
+
url: /docs/components/dialog
|
|
5226
|
+
source: apps/template/content/docs/components/dialog.mdx
|
|
5227
|
+
related:
|
|
5228
|
+
- /docs/components
|
|
5229
|
+
- /docs/components/button
|
|
5230
|
+
- /docs/components/popover
|
|
5231
|
+
---
|
|
5232
|
+
|
|
5233
|
+
# Dialog
|
|
5234
|
+
|
|
5235
|
+
import { DialogDemo } from "@/components/geistdocs/dialog-demo";
|
|
5236
|
+
|
|
5237
|
+
<div className="not-prose my-6 flex min-h-32 items-center justify-center rounded-lg border border-gray-400 bg-background-100 p-6">
|
|
5238
|
+
<DialogDemo />
|
|
5239
|
+
</div>
|
|
5240
|
+
|
|
5241
|
+
```tsx
|
|
5242
|
+
"use client";
|
|
5243
|
+
|
|
5244
|
+
import {
|
|
5245
|
+
Dialog,
|
|
5246
|
+
DialogAction,
|
|
5247
|
+
DialogClose,
|
|
5248
|
+
DialogContent,
|
|
5249
|
+
DialogDescription,
|
|
5250
|
+
DialogFooter,
|
|
5251
|
+
DialogHeader,
|
|
5252
|
+
DialogTitle,
|
|
5253
|
+
} from "@vercel/geistdocs/components/dialog";
|
|
5254
|
+
import { useState } from "react";
|
|
5255
|
+
|
|
5256
|
+
export function SearchDialog() {
|
|
5257
|
+
const [active, setActive] = useState(false);
|
|
5258
|
+
|
|
5259
|
+
return (
|
|
5260
|
+
<>
|
|
5261
|
+
<button onClick={() => setActive(true)}>Search</button>
|
|
5262
|
+
<Dialog
|
|
5263
|
+
active={active}
|
|
5264
|
+
drawer={false}
|
|
5265
|
+
onClickOutside={() => setActive(false)}
|
|
5266
|
+
>
|
|
5267
|
+
<DialogContent>
|
|
5268
|
+
<DialogHeader>
|
|
5269
|
+
<DialogTitle>Search documentation</DialogTitle>
|
|
5270
|
+
<DialogDescription>Type a query to find a page.</DialogDescription>
|
|
5271
|
+
</DialogHeader>
|
|
5272
|
+
{/* Search input and results */}
|
|
5273
|
+
</DialogContent>
|
|
5274
|
+
<DialogFooter>
|
|
5275
|
+
<DialogClose
|
|
5276
|
+
onClick={() => setActive(false)}
|
|
5277
|
+
variant="secondary"
|
|
5278
|
+
>
|
|
5279
|
+
Cancel
|
|
5280
|
+
</DialogClose>
|
|
5281
|
+
<DialogAction onClick={() => setActive(false)}>Search</DialogAction>
|
|
5282
|
+
</DialogFooter>
|
|
5283
|
+
</Dialog>
|
|
5284
|
+
</>
|
|
5285
|
+
);
|
|
5286
|
+
}
|
|
5287
|
+
```
|
|
5288
|
+
|
|
5289
|
+
`Dialog` is controlled through `active` and `onClickOutside`. Set `drawer={false}` for a centered dialog on every viewport, or omit it to allow mobile drawer behavior where supported.
|
|
5290
|
+
|
|
5291
|
+
Always provide a `DialogTitle` and `DialogDescription`. `DialogAction` and `DialogClose` render action buttons; call your close-state setter from `DialogClose.onClick`.
|
|
5292
|
+
|
|
5293
|
+
Import these components from `@vercel/geistdocs/components/dialog`. The public package provides a compatible implementation, while the private package aliases Geistcn's official Modal components under the same `Dialog*` names.
|
|
5294
|
+
|
|
5295
|
+
|
|
4639
5296
|
---
|
|
4640
5297
|
|
|
4641
5298
|
---
|
|
@@ -4782,6 +5439,10 @@ When feedback is submitted:
|
|
|
4782
5439
|
|
|
4783
5440
|
Each piece of feedback creates a separate issue, allowing for individual tracking and resolution.
|
|
4784
5441
|
|
|
5442
|
+
### Feedback on Ask AI answers
|
|
5443
|
+
|
|
5444
|
+
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.
|
|
5445
|
+
|
|
4785
5446
|
## Feedback Schema
|
|
4786
5447
|
|
|
4787
5448
|
The API accepts the following fields:
|
|
@@ -6147,14 +6808,14 @@ export function Demo() {
|
|
|
6147
6808
|
|
|
6148
6809
|
---
|
|
6149
6810
|
title: WebMCP
|
|
6150
|
-
description: Expose documentation search
|
|
6811
|
+
description: Expose documentation search, page reading, and Ask AI to browser agents.
|
|
6151
6812
|
url: /docs/webmcp
|
|
6152
6813
|
source: apps/template/content/docs/webmcp.mdx
|
|
6153
6814
|
---
|
|
6154
6815
|
|
|
6155
6816
|
# WebMCP
|
|
6156
6817
|
|
|
6157
|
-
Geistdocs uses [mcp-handler's WebMCP bridge](https://github.com/vercel/mcp-handler/blob/main/docs/WEBMCP.md) for search and
|
|
6818
|
+
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`:
|
|
6158
6819
|
|
|
6159
6820
|
```ts
|
|
6160
6821
|
import { createMcpRoute } from "@vercel/geistdocs/routes/mcp";
|
|
@@ -6174,10 +6835,23 @@ The canonical template includes this setup. Existing consumers must add the rout
|
|
|
6174
6835
|
| --- | --- | --- |
|
|
6175
6836
|
| `search_docs` | Nonblank `query` up to 500 characters; optional configured `locale` | MCP result containing search results as JSON text |
|
|
6176
6837
|
| `read_current_page` | None | Current page as Markdown |
|
|
6838
|
+
| `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 |
|
|
6177
6839
|
|
|
6178
6840
|
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`.
|
|
6179
6841
|
|
|
6180
|
-
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.
|
|
6842
|
+
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.
|
|
6843
|
+
|
|
6844
|
+
## Let browser agents ask Ask AI
|
|
6845
|
+
|
|
6846
|
+
`ask_ai` is opt-in. Set `webmcp.askAI` to `true` to register it when Ask AI is enabled:
|
|
6847
|
+
|
|
6848
|
+
```tsx title="lib/geistdocs/config.tsx"
|
|
6849
|
+
webmcp: { enabled: true, askAI: true },
|
|
6850
|
+
```
|
|
6851
|
+
|
|
6852
|
+
`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.
|
|
6853
|
+
|
|
6854
|
+
`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.
|
|
6181
6855
|
|
|
6182
6856
|
## Lifecycle and safety
|
|
6183
6857
|
|
|
@@ -6202,6 +6876,8 @@ agent-browser --session docs-check open http://localhost:3000/docs
|
|
|
6202
6876
|
agent-browser --session docs-check webmcp list
|
|
6203
6877
|
agent-browser --session docs-check webmcp invoke search_docs --params '{"query":"configuration","locale":"en"}'
|
|
6204
6878
|
agent-browser --session docs-check webmcp invoke read_current_page --params '{}'
|
|
6879
|
+
# Requires webmcp.askAI: true
|
|
6880
|
+
agent-browser --session docs-check webmcp invoke ask_ai --params '{"question":"How do I configure search?"}'
|
|
6205
6881
|
agent-browser --session docs-check close
|
|
6206
6882
|
```
|
|
6207
6883
|
|