@vercel/geistdocs 2.4.2 → 2.6.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 (66) hide show
  1. package/dist/cli/index.js +1 -1
  2. package/dist/config.d.ts +14 -0
  3. package/dist/config.d.ts.map +1 -1
  4. package/dist/config.js +13 -0
  5. package/dist/internal/chat/context.d.ts +1 -0
  6. package/dist/internal/chat/context.d.ts.map +1 -1
  7. package/dist/internal/chat/context.js +1 -0
  8. package/dist/internal/chat/shell.d.ts.map +1 -1
  9. package/dist/internal/chat/shell.js +32 -10
  10. package/dist/internal/eve-agent-session.d.ts +12 -0
  11. package/dist/internal/eve-agent-session.d.ts.map +1 -0
  12. package/dist/internal/eve-agent-session.js +26 -0
  13. package/dist/internal/eve-agent.d.ts +9 -5
  14. package/dist/internal/eve-agent.d.ts.map +1 -1
  15. package/dist/internal/eve-agent.js +63 -15
  16. package/dist/internal/mdx-to-markdown.d.ts.map +1 -1
  17. package/dist/internal/mdx-to-markdown.js +68 -1
  18. package/dist/internal/provider-client.d.ts +13 -1
  19. package/dist/internal/provider-client.d.ts.map +1 -1
  20. package/dist/internal/provider-client.js +1 -1
  21. package/dist/internal/search.d.ts +23 -1
  22. package/dist/internal/search.d.ts.map +1 -1
  23. package/dist/internal/search.js +19 -4
  24. package/dist/internal/webmcp-client.d.ts +3 -4
  25. package/dist/internal/webmcp-client.d.ts.map +1 -1
  26. package/dist/internal/webmcp-client.js +9 -12
  27. package/dist/internal/webmcp.d.ts +2 -6
  28. package/dist/internal/webmcp.d.ts.map +1 -1
  29. package/dist/internal/webmcp.js +28 -79
  30. package/dist/proxy.d.ts.map +1 -1
  31. package/dist/proxy.js +10 -2
  32. package/dist/routes/agents.d.ts.map +1 -1
  33. package/dist/routes/agents.js +2 -0
  34. package/dist/routes/chat.d.ts.map +1 -1
  35. package/dist/routes/chat.js +51 -13
  36. package/dist/routes/discovery.d.ts +3 -2
  37. package/dist/routes/discovery.d.ts.map +1 -1
  38. package/dist/routes/discovery.js +49 -1
  39. package/dist/routes/mcp.d.ts +7 -2
  40. package/dist/routes/mcp.d.ts.map +1 -1
  41. package/dist/routes/mcp.js +101 -1
  42. package/dist/routes/openapi.d.ts +64 -0
  43. package/dist/routes/openapi.d.ts.map +1 -0
  44. package/dist/routes/openapi.js +481 -0
  45. package/docs/agents.md +1 -1
  46. package/docs/llms.txt +95 -29
  47. package/docs/manifest.json +1 -1
  48. package/docs/pages/agent-readiness.md +30 -0
  49. package/docs/pages/ask-ai.md +6 -1
  50. package/docs/pages/configuration.md +7 -1
  51. package/docs/pages/migration.md +1 -0
  52. package/docs/pages/provider.md +23 -0
  53. package/docs/pages/webmcp.md +27 -26
  54. package/package.json +9 -3
  55. package/template/AGENTS.md +2 -2
  56. package/template/app/[lang]/openapi.json/route.ts +6 -0
  57. package/template/app/api/mcp/route.ts +7 -0
  58. package/template/content/docs/agent-readiness.mdx +30 -0
  59. package/template/content/docs/ask-ai.mdx +6 -1
  60. package/template/content/docs/configuration.mdx +7 -1
  61. package/template/content/docs/migration.mdx +1 -0
  62. package/template/content/docs/provider.mdx +23 -0
  63. package/template/content/docs/webmcp.mdx +27 -26
  64. package/template/geistdocs.tsx +3 -0
  65. package/template/lib/geistdocs/config.tsx +1 -0
  66. package/template/package.json +1 -1
package/docs/llms.txt CHANGED
@@ -1,6 +1,6 @@
1
1
  # Geistdocs Package Documentation
2
2
 
3
- These docs are bundled with `@vercel/geistdocs` 2.4.2.
3
+ These docs are bundled with `@vercel/geistdocs` 2.6.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
@@ -1014,6 +1014,7 @@ Check these URLs locally:
1014
1014
  - `/sitemap.md`.
1015
1015
  - `/agents.md`.
1016
1016
  - `/.well-known/mcp.json` if `agent.mcp.servers` is configured.
1017
+ - `/openapi.json` if the site mounts `createOpenApiRoute`.
1017
1018
  - A page-level Markdown URL such as `/docs/getting-started.mdx`.
1018
1019
  - A non-docs route that should not be rewritten as Markdown, such as the homepage.
1019
1020
 
@@ -1127,6 +1128,7 @@ Configure Geistdocs through user-owned files in the generated project. Runtime f
1127
1128
  | `app/[lang]/docs/[[...slug]]/page.tsx` | Configures the package docs page renderer. |
1128
1129
  | `app/[lang]/agents.md/route.ts` | Configures the agent-readiness entry point. |
1129
1130
  | `app/[lang]/.well-known/mcp.json/route.ts` | Configures MCP server discovery. |
1131
+ | `app/[lang]/openapi.json/route.ts` | Serves an OpenAPI document for the site's own search, chat, and Markdown endpoints. |
1130
1132
  | `app/[lang]/llms.txt/route.ts` | Configures the all-docs Markdown endpoint. |
1131
1133
  | `app/[lang]/llms.mdx/[[...slug]]/route.ts` | Configures single-page Markdown responses. |
1132
1134
  | `proxy.ts` | Configures markdown negotiation, AI-agent rewrites, request tracking, and custom request hooks. |
@@ -1289,10 +1291,15 @@ The `ai` config accepts `retrieval: "mixedbread"` to use semantic documentation
1289
1291
  ```tsx title="geistdocs.tsx"
1290
1292
  export const ai = {
1291
1293
  retrieval: "mixedbread",
1292
- eveAgent: { url: "https://help-eve.example.dev" },
1294
+ eveAgent: {
1295
+ url: "https://help-eve.example.dev",
1296
+ prewarm: true,
1297
+ },
1293
1298
  };
1294
1299
  ```
1295
1300
 
1301
+ 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.
1302
+
1296
1303
  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.
1297
1304
 
1298
1305
  Use [Versioned docs](/docs/versioned-docs) for versioned source setup and [Proxy and markdown routes](/docs/proxy) for route mappings.
@@ -2378,6 +2385,29 @@ Pass the scope here rather than reading a header or a cookie in the route. The s
2378
2385
  > Note:
2379
2386
  `createSearchRoute` indexes pages without a `tag` field, and tagged queries match with `containsAll`, so a tag passed to the built-in route matches nothing.
2380
2387
 
2388
+ ### Let readers change the scope
2389
+
2390
+ `tag` alone fixes the scope: it follows the page and a reader cannot override it. Pass `tags` as well to render the alternatives as pills under the results:
2391
+
2392
+ ```tsx title="app/layout.tsx"
2393
+ <GeistdocsProvider
2394
+ config={config}
2395
+ search={{
2396
+ options: {
2397
+ tag: "v5",
2398
+ tags: [
2399
+ { name: "v4", value: "v4" },
2400
+ { name: "v5", value: "v5" },
2401
+ ],
2402
+ allowClear: true,
2403
+ onTagChange: (value) => persist(value),
2404
+ },
2405
+ }}
2406
+ >
2407
+ ```
2408
+
2409
+ The selection starts at `tag` and follows it when the page changes, so navigating still re-scopes the dialog. `allowClear` adds a pill that searches everything, and `onTagChange` reports each pick for sites that remember it across sessions.
2410
+
2381
2411
  ## AI Sidebar
2382
2412
 
2383
2413
  When users open the AI chat on desktop, the provider automatically adds padding to prevent content from being hidden behind the sidebar. On mobile, the chat opens as a drawer instead, so no padding is needed.
@@ -3651,6 +3681,36 @@ export const config = defineConfig({
3651
3681
  });
3652
3682
  ```
3653
3683
 
3684
+ ## Describe the documentation site's own API
3685
+
3686
+ `agent.api.openApiUrl` points at your product's API. The documentation site also has HTTP endpoints of its own: `/api/search`, `/api/chat`, and the Markdown discovery routes. Geistdocs owns those implementations, so it can describe them for you. Add the route adapter and tell `/agents.md` where it lives:
3687
+
3688
+ ```ts title="app/[lang]/openapi.json/route.ts"
3689
+ import { createOpenApiRoute } from "@vercel/geistdocs/routes/openapi";
3690
+ import { config } from "@/lib/geistdocs/config";
3691
+
3692
+ export const { GET, generateStaticParams } = createOpenApiRoute({
3693
+ config,
3694
+ });
3695
+ ```
3696
+
3697
+ ```tsx title="geistdocs.tsx"
3698
+ export const agent = {
3699
+ api: {
3700
+ openApiUrl: "https://api.example.com/openapi.json",
3701
+ siteOpenApiUrl: "/openapi.json",
3702
+ },
3703
+ } satisfies GeistdocsAgentReadinessConfig;
3704
+ ```
3705
+
3706
+ 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.
3707
+
3708
+ 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.
3709
+
3710
+ 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.
3711
+
3712
+ Publishing the document makes `/api/chat` discoverable for programmatic use. That endpoint runs a language model on your account and has no built-in rate limit. Set `endpoints: { chat: false }` if that is not acceptable for your site.
3713
+
3654
3714
  ## Keep it honest
3655
3715
 
3656
3716
  Only list OpenAPI specs, authentication flows, or MCP servers that actually exist. Geistdocs validates new `openApiSpecs` entries and MCP servers rendered by `/.well-known/mcp.json` as absolute `http` or `https` URLs or root-relative paths. Existing `/agents.md` URL fields keep the same URL handling as previous versions. Geistdocs makes product capabilities discoverable, but it does not create APIs or MCP tools for you.
@@ -3796,10 +3856,15 @@ Use eve agent mode when a hosted [eve framework](https://eve.dev) agent should a
3796
3856
 
3797
3857
  ```tsx title="geistdocs.tsx"
3798
3858
  export const ai = {
3799
- eveAgent: { url: "https://help-eve.example.dev" },
3859
+ eveAgent: {
3860
+ url: "https://help-eve.example.dev",
3861
+ prewarm: true,
3862
+ },
3800
3863
  };
3801
3864
  ```
3802
3865
 
3866
+ 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.
3867
+
3803
3868
  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.
3804
3869
 
3805
3870
  Eve agent mode keeps the platform-owned behavior from proxy mode:
@@ -5049,53 +5114,54 @@ source: apps/template/content/docs/webmcp.mdx
5049
5114
 
5050
5115
  # WebMCP
5051
5116
 
5052
- Geistdocs includes experimental WebMCP support. WebMCP is disabled by default. To opt in, add it to the `defineConfig` call in `lib/geistdocs/config.tsx`:
5117
+ 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`:
5053
5118
 
5054
5119
  ```ts
5055
- export const config = defineConfig({
5056
- // ...
5057
- webmcp: { enabled: true },
5058
- });
5120
+ import { createMcpRoute } from "@vercel/geistdocs/routes/mcp";
5121
+ import { config } from "@/lib/geistdocs/config";
5122
+ import { GET as search } from "../search/route";
5123
+
5124
+ const handler = createMcpRoute({ config, search });
5125
+
5126
+ export { handler as GET, handler as POST };
5059
5127
  ```
5060
5128
 
5061
- The provider exposes two read-only tools:
5129
+ The canonical template includes this setup. Existing consumers must add the route themselves: `geistdocs update` does not overwrite local adapters. There is no fallback to the old browser search transport.
5130
+
5131
+ ## Tools
5062
5132
 
5063
5133
  | Tool | Input | Result |
5064
5134
  | --- | --- | --- |
5065
- | `search_docs` | `query`, a nonempty string up to 500 characters | Results from the existing search API in the current language |
5066
- | `read_current_page` | None | The current documentation page as Markdown |
5135
+ | `search_docs` | Nonblank `query` up to 500 characters; optional configured `locale` | MCP result containing search results as JSON text |
5136
+ | `read_current_page` | None | Current page as Markdown |
5067
5137
 
5068
- Search respects the existing search visibility rules. Page reading uses the existing Markdown route and fails if the current page does not serve Markdown. Neither tool sends data to an external model or modifies documentation. Returned documentation is marked as untrusted content.
5138
+ 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`.
5069
5139
 
5070
- WebMCP requires a compatible browser with the experimental API enabled. Unsupported browsers continue to work normally. This feature uses browser-local tools, independently of the site's remote MCP discovery manifest.
5140
+ 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.
5071
5141
 
5072
- ## Verify locally
5142
+ ## Lifecycle and safety
5073
5143
 
5074
- Enable WebMCP testing as described in the [Chrome documentation](https://developer.chrome.com/docs/ai/webmcp). Open a documentation page and inspect its tools:
5144
+ Search follows the upstream bridge contract: MCP result envelopes are returned unchanged, including `isError`; browser-provided cancellation reaches fetch, but there is no additional request deadline. The bridge preserves `readOnlyHint` but does not emit WebMCP's explicit `untrustedContentHint`. Search results are still untrusted documentation, not agent instructions.
5075
5145
 
5076
- ```js
5077
- const tools = await document.modelContext.getTools();
5078
- const search = tools.find((tool) => tool.name === "search_docs");
5079
- await document.modelContext.executeTool(search, JSON.stringify({ query: "configuration" }));
5080
- const read = tools.find((tool) => tool.name === "read_current_page");
5081
- await document.modelContext.executeTool(read, "{}");
5082
- ```
5146
+ Search registration lasts for the document and is not tied to React unmounts. Reload after changing feature configuration. With `webmcp.enabled` disabled, the endpoint returns 404 and new documents do not load the bridge. Unsupported browsers continue to work normally.
5147
+
5148
+ `read_current_page` remains browser-local: it reads the live URL without its query or fragment, requires a Markdown response, and retains its 15-second timeout, cancellation, untrusted-content hint and registration cleanup.
5083
5149
 
5084
- Navigate to another documentation page and read it again. Repeat in a translated route and, when configured, under the site's base path. Disable the feature and verify the provider removes its tools.
5150
+ For protected documentation, authorize the MCP route and supplied search handler. Direct handler reuse does not execute middleware scoped only to `/api/search`. Cross-origin cookie requests are rejected; protocol responses use `Cache-Control: no-store`. Tool allowlists and read-only annotations are not authorization. Never put tokens in client config.
5085
5151
 
5086
- ## agent-browser
5152
+ The remote discovery manifest remains independent; configured external servers are not replaced.
5087
5153
 
5088
- With agent-browser 0.36.0 or newer, WebMCP is enabled by default in managed Chrome sessions:
5154
+ ## Verify locally
5155
+
5156
+ Use a compatible browser with WebMCP enabled. With agent-browser 0.36.0 or newer:
5089
5157
 
5090
5158
  ```bash
5091
5159
  agent-browser --session docs-check open http://localhost:3000/docs
5092
5160
  agent-browser --session docs-check webmcp list
5093
- agent-browser --session docs-check webmcp invoke search_docs --params '{"query":"configuration"}'
5161
+ agent-browser --session docs-check webmcp invoke search_docs --params '{"query":"configuration","locale":"en"}'
5094
5162
  agent-browser --session docs-check webmcp invoke read_current_page --params '{}'
5095
5163
  agent-browser --session docs-check close
5096
5164
  ```
5097
5165
 
5098
- Discovery includes each tool's origin, frame, schema, and read-only annotations. Check the invocation's `status`: a successfully delivered command can still contain a failed tool execution.
5099
-
5100
- Both tools limit network requests to 15 seconds. When the browser supplies an execution signal, cancellation also aborts the request. Some experimental browser versions, including Chrome 152, omit that signal: canceling an invocation in those versions does not immediately abort its underlying fetch, which remains bounded by the request deadline.
5166
+ Check the invocation's `status` and the search result's `isError`, not just command delivery. Navigate to another page and confirm reading follows the new URL; switch language and search with an explicit locale. Repeat under a configured base path. Disable the feature and reload to verify registration and endpoint opt-out.
5101
5167
 
@@ -242,5 +242,5 @@
242
242
  }
243
243
  ],
244
244
  "source": "apps/template/content/docs",
245
- "version": "2.4.2"
245
+ "version": "2.6.0"
246
246
  }
@@ -134,6 +134,36 @@ export const config = defineConfig({
134
134
  });
135
135
  ```
136
136
 
137
+ ## Describe the documentation site's own API
138
+
139
+ `agent.api.openApiUrl` points at your product's API. The documentation site also has HTTP endpoints of its own: `/api/search`, `/api/chat`, and the Markdown discovery routes. Geistdocs owns those implementations, so it can describe them for you. Add the route adapter and tell `/agents.md` where it lives:
140
+
141
+ ```ts title="app/[lang]/openapi.json/route.ts"
142
+ import { createOpenApiRoute } from "@vercel/geistdocs/routes/openapi";
143
+ import { config } from "@/lib/geistdocs/config";
144
+
145
+ export const { GET, generateStaticParams } = createOpenApiRoute({
146
+ config,
147
+ });
148
+ ```
149
+
150
+ ```tsx title="geistdocs.tsx"
151
+ export const agent = {
152
+ api: {
153
+ openApiUrl: "https://api.example.com/openapi.json",
154
+ siteOpenApiUrl: "/openapi.json",
155
+ },
156
+ } satisfies GeistdocsAgentReadinessConfig;
157
+ ```
158
+
159
+ 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.
160
+
161
+ 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.
162
+
163
+ 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.
164
+
165
+ Publishing the document makes `/api/chat` discoverable for programmatic use. That endpoint runs a language model on your account and has no built-in rate limit. Set `endpoints: { chat: false }` if that is not acceptable for your site.
166
+
137
167
  ## Keep it honest
138
168
 
139
169
  Only list OpenAPI specs, authentication flows, or MCP servers that actually exist. Geistdocs validates new `openApiSpecs` entries and MCP servers rendered by `/.well-known/mcp.json` as absolute `http` or `https` URLs or root-relative paths. Existing `/agents.md` URL fields keep the same URL handling as previous versions. Geistdocs makes product capabilities discoverable, but it does not create APIs or MCP tools for you.
@@ -134,10 +134,15 @@ Use eve agent mode when a hosted [eve framework](https://eve.dev) agent should a
134
134
 
135
135
  ```tsx title="geistdocs.tsx"
136
136
  export const ai = {
137
- eveAgent: { url: "https://help-eve.example.dev" },
137
+ eveAgent: {
138
+ url: "https://help-eve.example.dev",
139
+ prewarm: true,
140
+ },
138
141
  };
139
142
  ```
140
143
 
144
+ 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.
145
+
141
146
  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.
142
147
 
143
148
  Eve agent mode keeps the platform-owned behavior from proxy mode:
@@ -37,6 +37,7 @@ Configure Geistdocs through user-owned files in the generated project. Runtime f
37
37
  | `app/[lang]/docs/[[...slug]]/page.tsx` | Configures the package docs page renderer. |
38
38
  | `app/[lang]/agents.md/route.ts` | Configures the agent-readiness entry point. |
39
39
  | `app/[lang]/.well-known/mcp.json/route.ts` | Configures MCP server discovery. |
40
+ | `app/[lang]/openapi.json/route.ts` | Serves an OpenAPI document for the site's own search, chat, and Markdown endpoints. |
40
41
  | `app/[lang]/llms.txt/route.ts` | Configures the all-docs Markdown endpoint. |
41
42
  | `app/[lang]/llms.mdx/[[...slug]]/route.ts` | Configures single-page Markdown responses. |
42
43
  | `proxy.ts` | Configures markdown negotiation, AI-agent rewrites, request tracking, and custom request hooks. |
@@ -199,10 +200,15 @@ The `ai` config accepts `retrieval: "mixedbread"` to use semantic documentation
199
200
  ```tsx title="geistdocs.tsx"
200
201
  export const ai = {
201
202
  retrieval: "mixedbread",
202
- eveAgent: { url: "https://help-eve.example.dev" },
203
+ eveAgent: {
204
+ url: "https://help-eve.example.dev",
205
+ prewarm: true,
206
+ },
203
207
  };
204
208
  ```
205
209
 
210
+ 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.
211
+
206
212
  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.
207
213
 
208
214
  Use [Versioned docs](/docs/versioned-docs) for versioned source setup and [Proxy and markdown routes](/docs/proxy) for route mappings.
@@ -553,6 +553,7 @@ Check these URLs locally:
553
553
  - `/sitemap.md`.
554
554
  - `/agents.md`.
555
555
  - `/.well-known/mcp.json` if `agent.mcp.servers` is configured.
556
+ - `/openapi.json` if the site mounts `createOpenApiRoute`.
556
557
  - A page-level Markdown URL such as `/docs/getting-started.mdx`.
557
558
  - A non-docs route that should not be rewritten as Markdown, such as the homepage.
558
559
 
@@ -62,6 +62,29 @@ Pass the scope here rather than reading a header or a cookie in the route. The s
62
62
  > Note:
63
63
  `createSearchRoute` indexes pages without a `tag` field, and tagged queries match with `containsAll`, so a tag passed to the built-in route matches nothing.
64
64
 
65
+ ### Let readers change the scope
66
+
67
+ `tag` alone fixes the scope: it follows the page and a reader cannot override it. Pass `tags` as well to render the alternatives as pills under the results:
68
+
69
+ ```tsx title="app/layout.tsx"
70
+ <GeistdocsProvider
71
+ config={config}
72
+ search={{
73
+ options: {
74
+ tag: "v5",
75
+ tags: [
76
+ { name: "v4", value: "v4" },
77
+ { name: "v5", value: "v5" },
78
+ ],
79
+ allowClear: true,
80
+ onTagChange: (value) => persist(value),
81
+ },
82
+ }}
83
+ >
84
+ ```
85
+
86
+ The selection starts at `tag` and follows it when the page changes, so navigating still re-scopes the dialog. `allowClear` adds a pill that searches everything, and `onTagChange` reports each pick for sites that remember it across sessions.
87
+
65
88
  ## AI Sidebar
66
89
 
67
90
  When users open the AI chat on desktop, the provider automatically adds padding to prevent content from being hidden behind the sidebar. On mobile, the chat opens as a drawer instead, so no padding is needed.
@@ -7,52 +7,53 @@ source: apps/template/content/docs/webmcp.mdx
7
7
 
8
8
  # WebMCP
9
9
 
10
- Geistdocs includes experimental WebMCP support. WebMCP is disabled by default. To opt in, add it to the `defineConfig` call in `lib/geistdocs/config.tsx`:
10
+ 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`:
11
11
 
12
12
  ```ts
13
- export const config = defineConfig({
14
- // ...
15
- webmcp: { enabled: true },
16
- });
13
+ import { createMcpRoute } from "@vercel/geistdocs/routes/mcp";
14
+ import { config } from "@/lib/geistdocs/config";
15
+ import { GET as search } from "../search/route";
16
+
17
+ const handler = createMcpRoute({ config, search });
18
+
19
+ export { handler as GET, handler as POST };
17
20
  ```
18
21
 
19
- The provider exposes two read-only tools:
22
+ The canonical template includes this setup. Existing consumers must add the route themselves: `geistdocs update` does not overwrite local adapters. There is no fallback to the old browser search transport.
23
+
24
+ ## Tools
20
25
 
21
26
  | Tool | Input | Result |
22
27
  | --- | --- | --- |
23
- | `search_docs` | `query`, a nonempty string up to 500 characters | Results from the existing search API in the current language |
24
- | `read_current_page` | None | The current documentation page as Markdown |
28
+ | `search_docs` | Nonblank `query` up to 500 characters; optional configured `locale` | MCP result containing search results as JSON text |
29
+ | `read_current_page` | None | Current page as Markdown |
25
30
 
26
- Search respects the existing search visibility rules. Page reading uses the existing Markdown route and fails if the current page does not serve Markdown. Neither tool sends data to an external model or modifies documentation. Returned documentation is marked as untrusted content.
31
+ 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`.
27
32
 
28
- WebMCP requires a compatible browser with the experimental API enabled. Unsupported browsers continue to work normally. This feature uses browser-local tools, independently of the site's remote MCP discovery manifest.
33
+ 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.
29
34
 
30
- ## Verify locally
35
+ ## Lifecycle and safety
31
36
 
32
- Enable WebMCP testing as described in the [Chrome documentation](https://developer.chrome.com/docs/ai/webmcp). Open a documentation page and inspect its tools:
37
+ Search follows the upstream bridge contract: MCP result envelopes are returned unchanged, including `isError`; browser-provided cancellation reaches fetch, but there is no additional request deadline. The bridge preserves `readOnlyHint` but does not emit WebMCP's explicit `untrustedContentHint`. Search results are still untrusted documentation, not agent instructions.
33
38
 
34
- ```js
35
- const tools = await document.modelContext.getTools();
36
- const search = tools.find((tool) => tool.name === "search_docs");
37
- await document.modelContext.executeTool(search, JSON.stringify({ query: "configuration" }));
38
- const read = tools.find((tool) => tool.name === "read_current_page");
39
- await document.modelContext.executeTool(read, "{}");
40
- ```
39
+ Search registration lasts for the document and is not tied to React unmounts. Reload after changing feature configuration. With `webmcp.enabled` disabled, the endpoint returns 404 and new documents do not load the bridge. Unsupported browsers continue to work normally.
41
40
 
42
- Navigate to another documentation page and read it again. Repeat in a translated route and, when configured, under the site's base path. Disable the feature and verify the provider removes its tools.
41
+ `read_current_page` remains browser-local: it reads the live URL without its query or fragment, requires a Markdown response, and retains its 15-second timeout, cancellation, untrusted-content hint and registration cleanup.
43
42
 
44
- ## agent-browser
43
+ For protected documentation, authorize the MCP route and supplied search handler. Direct handler reuse does not execute middleware scoped only to `/api/search`. Cross-origin cookie requests are rejected; protocol responses use `Cache-Control: no-store`. Tool allowlists and read-only annotations are not authorization. Never put tokens in client config.
45
44
 
46
- With agent-browser 0.36.0 or newer, WebMCP is enabled by default in managed Chrome sessions:
45
+ The remote discovery manifest remains independent; configured external servers are not replaced.
46
+
47
+ ## Verify locally
48
+
49
+ Use a compatible browser with WebMCP enabled. With agent-browser 0.36.0 or newer:
47
50
 
48
51
  ```bash
49
52
  agent-browser --session docs-check open http://localhost:3000/docs
50
53
  agent-browser --session docs-check webmcp list
51
- agent-browser --session docs-check webmcp invoke search_docs --params '{"query":"configuration"}'
54
+ agent-browser --session docs-check webmcp invoke search_docs --params '{"query":"configuration","locale":"en"}'
52
55
  agent-browser --session docs-check webmcp invoke read_current_page --params '{}'
53
56
  agent-browser --session docs-check close
54
57
  ```
55
58
 
56
- Discovery includes each tool's origin, frame, schema, and read-only annotations. Check the invocation's `status`: a successfully delivered command can still contain a failed tool execution.
57
-
58
- Both tools limit network requests to 15 seconds. When the browser supplies an execution signal, cancellation also aborts the request. Some experimental browser versions, including Chrome 152, omit that signal: canceling an invocation in those versions does not immediately abort its underlying fetch, which remains bounded by the request deadline.
59
+ Check the invocation's `status` and the search result's `isError`, not just command delivery. Navigate to another page and confirm reading follows the new URL; switch language and search with an explicit locale. Repeat under a configured base path. Disable the feature and reload to verify registration and endpoint opt-out.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@vercel/geistdocs",
3
3
  "description": "Runtime and CLI for Geistdocs projects.",
4
- "version": "2.4.2",
4
+ "version": "2.6.0",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
7
7
  "type": "git",
@@ -127,6 +127,10 @@
127
127
  "types": "./dist/routes/mcp.d.ts",
128
128
  "default": "./dist/routes/mcp.js"
129
129
  },
130
+ "./routes/openapi": {
131
+ "types": "./dist/routes/openapi.d.ts",
132
+ "default": "./dist/routes/openapi.js"
133
+ },
130
134
  "./routes/not-found": {
131
135
  "types": "./dist/routes/not-found.d.ts",
132
136
  "default": "./dist/routes/not-found.js"
@@ -255,6 +259,7 @@
255
259
  "dependencies": {
256
260
  "@ai-sdk/react": "^3.0.134",
257
261
  "@clack/prompts": "^0.11.0",
262
+ "@modelcontextprotocol/server": "^2.0.0",
258
263
  "@next/env": "16.3.3",
259
264
  "@orama/tokenizers": "^3.1.16",
260
265
  "@streamdown/cjk": "^1.0.1",
@@ -273,6 +278,7 @@
273
278
  "fumadocs-ui": "16.2.2",
274
279
  "geist": "1.7.1",
275
280
  "glob": "^11.0.0",
281
+ "mcp-handler": "2.2.0",
276
282
  "mermaid": "^11.12.2",
277
283
  "motion": "^12.23.25",
278
284
  "next-themes": "^0.4.6",
@@ -287,14 +293,14 @@
287
293
  "remark-stringify": "^11.0.0",
288
294
  "sonner": "^2.0.7",
289
295
  "streamdown": "^2.1.0",
290
- "ts-morph": "^27.0.2",
291
296
  "tailwind-merge": "^3.4.0",
297
+ "ts-morph": "^27.0.2",
292
298
  "tw-animate-css": "^1.4.0",
293
299
  "unified": "^11.0.5",
294
300
  "unist-util-visit": "^5.1.0",
295
301
  "use-stick-to-bottom": "^1.1.1",
296
302
  "vaul": "^1.1.2",
297
- "zod": "^4.1.13"
303
+ "zod": "^4.6.5"
298
304
  },
299
305
  "peerDependencies": {
300
306
  "next": "^16.3.3",
@@ -35,7 +35,7 @@ Use these instructions when an AI coding agent edits this project.
35
35
  | Configure the Fumadocs source adapter or versioned docs | `lib/geistdocs/source.ts` |
36
36
  | Configure Fumadocs collections and source-safe MDX processing | `source.config.ts` |
37
37
  | Configure the docs page renderer | `app/[lang]/docs/[[...slug]]/page.tsx` |
38
- | Configure AI-readable markdown output and recovery | `app/[lang]/agents.md/route.ts`, `app/[lang]/.well-known/mcp.json/route.ts`, `app/[lang]/llms.txt/route.ts`, `app/[lang]/llms.mdx/[[...slug]]/route.ts`, `app/[lang]/sitemap.md/route.ts` |
38
+ | Configure AI-readable markdown output and recovery | `app/[lang]/agents.md/route.ts`, `app/[lang]/.well-known/mcp.json/route.ts`, `app/[lang]/openapi.json/route.ts`, `app/[lang]/llms.txt/route.ts`, `app/[lang]/llms.mdx/[[...slug]]/route.ts`, `app/[lang]/sitemap.md/route.ts` |
39
39
  | Configure chat or search APIs | `app/api/chat/route.ts`, `app/api/search/route.ts`, `app/api/search/export/route.ts` |
40
40
  | Add request handling before or after Geistdocs routing | `proxy.ts` |
41
41
  | Edit the marketing home page | `app/[lang]/(home)/**` |
@@ -75,7 +75,7 @@ Use these instructions when an AI coding agent edits this project.
75
75
  - Keep `MXBAI_API_KEY` and `MXBAI_STORE_ID` in environment variables. Never put them in `geistdocs.tsx`, because config is available to client components.
76
76
  - Keep `app/api/search/export/route.ts` and the `next build && geistdocs search sync` build script when Mixedbread retrieval is enabled. Production builds incrementally sync chat-visible Markdown; local and preview builds skip remote sync unless `--allow-non-production` is passed.
77
77
  - Mixedbread failures fall back to local Orama retrieval. Keep the local source definitions and `excludeFrom: [chat]` visibility behavior intact.
78
- - Set `ai.eveAgent: { url }` in `geistdocs.tsx` to answer Ask AI with a hosted eve framework agent instead. The URL flows through the config object; the route file needs no changes. Requests authenticate with a per-request Vercel OIDC bearer token by default; pass server-only headers through the `eveAgent` option on `createChatRoute` for custom auth. Never put auth material in `geistdocs.tsx`. Configuring both `proxy` and an eve agent throws at route creation.
78
+ - Set `ai.eveAgent: { url }` in `geistdocs.tsx` to answer Ask AI with a hosted eve framework agent instead. The URL flows through the config object; the route file needs no changes. Set `prewarm: true` for eve 0.59+ responders when the site should prepare an empty durable session as the chat client loads. Requests authenticate with a per-request Vercel OIDC bearer token by default; pass server-only headers through the `eveAgent` option on `createChatRoute` for custom auth. Never put auth material in `geistdocs.tsx`. Configuring both `proxy` and an eve agent throws at route creation.
79
79
  - Geistdocs Ask AI targets AI SDK v6: `ai` v6 and `@ai-sdk/react` v3. Keep those dependencies on the generated package versions unless a `@vercel/geistdocs` release changes them.
80
80
  - If the app uses `ai` or `@ai-sdk/react` for product code outside Geistdocs, migrate that app code separately or let the package manager install separate versions. Do not downgrade Geistdocs Ask AI to match unrelated app code.
81
81
  - Set `GEISTDOCS_CHAT_PROXY_URL` only when Ask AI should route through the central Vertex-backed proxy. The value must include the `/vertex` route, such as `https://<geistdocs-platform-deployment>/vertex`.
@@ -0,0 +1,6 @@
1
+ import { createOpenApiRoute } from "@vercel/geistdocs/routes/openapi";
2
+ import { config } from "@/lib/geistdocs/config";
3
+
4
+ export const { GET, generateStaticParams } = createOpenApiRoute({
5
+ config,
6
+ });
@@ -0,0 +1,7 @@
1
+ import { createMcpRoute } from "@vercel/geistdocs/routes/mcp";
2
+ import { config } from "@/lib/geistdocs/config";
3
+ import { GET as search } from "../search/route";
4
+
5
+ const handler = createMcpRoute({ config, search });
6
+
7
+ export { handler as GET, handler as POST };
@@ -132,6 +132,36 @@ export const config = defineConfig({
132
132
  });
133
133
  ```
134
134
 
135
+ ## Describe the documentation site's own API
136
+
137
+ `agent.api.openApiUrl` points at your product's API. The documentation site also has HTTP endpoints of its own: `/api/search`, `/api/chat`, and the Markdown discovery routes. Geistdocs owns those implementations, so it can describe them for you. Add the route adapter and tell `/agents.md` where it lives:
138
+
139
+ ```ts title="app/[lang]/openapi.json/route.ts"
140
+ import { createOpenApiRoute } from "@vercel/geistdocs/routes/openapi";
141
+ import { config } from "@/lib/geistdocs/config";
142
+
143
+ export const { GET, generateStaticParams } = createOpenApiRoute({
144
+ config,
145
+ });
146
+ ```
147
+
148
+ ```tsx title="geistdocs.tsx"
149
+ export const agent = {
150
+ api: {
151
+ openApiUrl: "https://api.example.com/openapi.json",
152
+ siteOpenApiUrl: "/openapi.json",
153
+ },
154
+ } satisfies GeistdocsAgentReadinessConfig;
155
+ ```
156
+
157
+ 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.
158
+
159
+ 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.
160
+
161
+ 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.
162
+
163
+ Publishing the document makes `/api/chat` discoverable for programmatic use. That endpoint runs a language model on your account and has no built-in rate limit. Set `endpoints: { chat: false }` if that is not acceptable for your site.
164
+
135
165
  ## Keep it honest
136
166
 
137
167
  Only list OpenAPI specs, authentication flows, or MCP servers that actually exist. Geistdocs validates new `openApiSpecs` entries and MCP servers rendered by `/.well-known/mcp.json` as absolute `http` or `https` URLs or root-relative paths. Existing `/agents.md` URL fields keep the same URL handling as previous versions. Geistdocs makes product capabilities discoverable, but it does not create APIs or MCP tools for you.
@@ -132,10 +132,15 @@ Use eve agent mode when a hosted [eve framework](https://eve.dev) agent should a
132
132
 
133
133
  ```tsx title="geistdocs.tsx"
134
134
  export const ai = {
135
- eveAgent: { url: "https://help-eve.example.dev" },
135
+ eveAgent: {
136
+ url: "https://help-eve.example.dev",
137
+ prewarm: true,
138
+ },
136
139
  };
137
140
  ```
138
141
 
142
+ 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.
143
+
139
144
  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.
140
145
 
141
146
  Eve agent mode keeps the platform-owned behavior from proxy mode:
@@ -35,6 +35,7 @@ Configure Geistdocs through user-owned files in the generated project. Runtime f
35
35
  | `app/[lang]/docs/[[...slug]]/page.tsx` | Configures the package docs page renderer. |
36
36
  | `app/[lang]/agents.md/route.ts` | Configures the agent-readiness entry point. |
37
37
  | `app/[lang]/.well-known/mcp.json/route.ts` | Configures MCP server discovery. |
38
+ | `app/[lang]/openapi.json/route.ts` | Serves an OpenAPI document for the site's own search, chat, and Markdown endpoints. |
38
39
  | `app/[lang]/llms.txt/route.ts` | Configures the all-docs Markdown endpoint. |
39
40
  | `app/[lang]/llms.mdx/[[...slug]]/route.ts` | Configures single-page Markdown responses. |
40
41
  | `proxy.ts` | Configures markdown negotiation, AI-agent rewrites, request tracking, and custom request hooks. |
@@ -197,10 +198,15 @@ The `ai` config accepts `retrieval: "mixedbread"` to use semantic documentation
197
198
  ```tsx title="geistdocs.tsx"
198
199
  export const ai = {
199
200
  retrieval: "mixedbread",
200
- eveAgent: { url: "https://help-eve.example.dev" },
201
+ eveAgent: {
202
+ url: "https://help-eve.example.dev",
203
+ prewarm: true,
204
+ },
201
205
  };
202
206
  ```
203
207
 
208
+ 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.
209
+
204
210
  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.
205
211
 
206
212
  Use [Versioned docs](/docs/versioned-docs) for versioned source setup and [Proxy and markdown routes](/docs/proxy) for route mappings.
@@ -552,6 +552,7 @@ Check these URLs locally:
552
552
  - `/sitemap.md`.
553
553
  - `/agents.md`.
554
554
  - `/.well-known/mcp.json` if `agent.mcp.servers` is configured.
555
+ - `/openapi.json` if the site mounts `createOpenApiRoute`.
555
556
  - A page-level Markdown URL such as `/docs/getting-started.mdx`.
556
557
  - A non-docs route that should not be rewritten as Markdown, such as the homepage.
557
558