@vercel/geistdocs 1.25.2 → 1.26.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 (54) hide show
  1. package/cli.js +8 -0
  2. package/dist/cli/index.js +6 -2
  3. package/dist/config.d.ts +5 -0
  4. package/dist/config.d.ts.map +1 -1
  5. package/dist/internal/chat-retrieval.d.ts +32 -0
  6. package/dist/internal/chat-retrieval.d.ts.map +1 -0
  7. package/dist/internal/chat-retrieval.js +91 -0
  8. package/dist/internal/mixedbread.d.ts +93 -0
  9. package/dist/internal/mixedbread.d.ts.map +1 -0
  10. package/dist/internal/mixedbread.js +286 -0
  11. package/dist/internal/page-actions-client.d.ts.map +1 -1
  12. package/dist/internal/page-actions-client.js +1 -19
  13. package/dist/internal/search-export.d.ts +18 -0
  14. package/dist/internal/search-export.d.ts.map +1 -0
  15. package/dist/internal/search-export.js +1 -0
  16. package/dist/internal/search-sync.d.ts +25 -0
  17. package/dist/internal/search-sync.d.ts.map +1 -0
  18. package/dist/internal/search-sync.js +312 -0
  19. package/dist/routes/chat.d.ts +8 -2
  20. package/dist/routes/chat.d.ts.map +1 -1
  21. package/dist/routes/chat.js +53 -15
  22. package/dist/routes/search-export.d.ts +12 -0
  23. package/dist/routes/search-export.d.ts.map +1 -0
  24. package/dist/routes/search-export.js +44 -0
  25. package/docs/agents.md +4 -3
  26. package/docs/llms.txt +384 -33
  27. package/docs/manifest.json +12 -3
  28. package/docs/pages/ask-ai.md +3 -0
  29. package/docs/pages/configuration.md +5 -2
  30. package/docs/pages/deployment.md +30 -5
  31. package/docs/pages/env.md +13 -3
  32. package/docs/pages/getting-started.md +29 -9
  33. package/docs/pages/index.md +3 -2
  34. package/docs/pages/md.md +1 -1
  35. package/docs/pages/migration.md +148 -8
  36. package/docs/pages/mixedbread-retrieval.md +144 -0
  37. package/docs/sitemap.md +3 -2
  38. package/package.json +10 -4
  39. package/template/.env.example +19 -0
  40. package/template/AGENTS.md +17 -3
  41. package/template/app/api/search/export/route.ts +8 -0
  42. package/template/content/docs/ask-ai.mdx +3 -0
  43. package/template/content/docs/configuration.mdx +5 -2
  44. package/template/content/docs/deployment.mdx +31 -6
  45. package/template/content/docs/env.mdx +14 -4
  46. package/template/content/docs/getting-started.mdx +30 -10
  47. package/template/content/docs/index.mdx +3 -2
  48. package/template/content/docs/md.mdx +1 -1
  49. package/template/content/docs/meta.json +1 -0
  50. package/template/content/docs/migration.mdx +150 -9
  51. package/template/content/docs/mixedbread-retrieval.mdx +142 -0
  52. package/template/geistdocs.tsx +12 -1
  53. package/template/lib/geistdocs/config.tsx +2 -5
  54. package/template/package.json +2 -2
package/docs/llms.txt CHANGED
@@ -1,14 +1,14 @@
1
1
  # Geistdocs Package Documentation
2
2
 
3
- These docs are bundled with `@vercel/geistdocs` 1.25.2.
3
+ These docs are bundled with `@vercel/geistdocs` 1.26.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, proxy mode, and production URL configuration.
11
- - [Deploy to Vercel](pages/deployment.md): Deploy your Geistdocs site to Vercel from the dashboard with the correct project settings.
10
+ - [Environment Variables](pages/env.md): Environment variables required by Geistdocs for AI chat, Mixedbread retrieval, proxy mode, and production URL configuration.
11
+ - [Deploy to Vercel](pages/deployment.md): Deploy a Geistdocs site to Vercel with the required project settings, environment variables, and private-package access.
12
12
  - [Migration guide](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
  - [Configuration](pages/configuration.md): Configure site metadata, navigation, AI features, page actions, translations, and local adapters.
14
14
  - [Syntax](pages/syntax.md): Supported MDX syntax including text formatting, code blocks, line highlighting, and Mermaid diagrams.
@@ -21,6 +21,7 @@ They describe how to build package-backed Geistdocs sites and how to use the pac
21
21
  - [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.
22
22
  - [Edit on GitHub](pages/edit-on-github.md): A direct link on every documentation page that lets readers propose changes through GitHub pull requests.
23
23
  - [Feedback](pages/feedback.md): An interactive feedback widget that collects user sentiment and creates structured GitHub Issues automatically.
24
+ - [Improve Ask AI answers with Mixedbread](pages/mixedbread-retrieval.md): Provision a Mixedbread Store for one Geistdocs consumer site, enable semantic retrieval, and sync documentation during production builds.
24
25
  - [Internationalization](pages/internationalization.md): Serve documentation in multiple languages with automatic translation via the Geistdocs CLI and Fumadocs routing.
25
26
  - [llms.txt](pages/llms-txt.md): A single endpoint that returns all documentation as plain Markdown text following the llms.txt standard.
26
27
  - [Open in Chat](pages/open-in-chat.md): Transfer documentation context to AI chat platforms like ChatGPT, Claude, Cursor, and v0 with a single click.
@@ -60,7 +61,7 @@ Geistdocs has three main parts:
60
61
  ```mermaid
61
62
  flowchart TB
62
63
  subgraph Package["@vercel/geistdocs package"]
63
- cli["CLI: init, update, translate"]
64
+ cli["CLI: init, update, translate, search sync"]
64
65
  runtime["Runtime: layout, routes, MDX, controls"]
65
66
  bundledTemplate["Bundled template snapshot"]
66
67
  end
@@ -110,6 +111,7 @@ Advanced projects can use package APIs for versioned docs, multiple content sour
110
111
  - MDX documentation with custom components
111
112
  - Local content in `content/docs`
112
113
  - Search and Ask AI
114
+ - Optional Mixedbread semantic retrieval for Ask AI
113
115
  - Page actions, including feedback, copy page, open in chat, and edit on GitHub
114
116
  - Agent-readiness metadata with `/agents.md` and `/.well-known/mcp.json`
115
117
  - Raw Markdown routes for AI tools
@@ -119,7 +121,7 @@ Advanced projects can use package APIs for versioned docs, multiple content sour
119
121
  - RSS feed
120
122
  - Theme-aware images
121
123
  - Internationalized routes
122
- - CLI commands for init, update, and translation
124
+ - CLI commands for init, update, translation, and Mixedbread search sync
123
125
 
124
126
  ## Next steps
125
127
 
@@ -151,35 +153,55 @@ related:
151
153
 
152
154
  Create a Geistdocs site with the package CLI, then edit the generated content and configuration files. If you already have a Fumadocs or custom Geist docs site, read [Migration guide](/docs/migration) before moving route adapters and middleware behavior.
153
155
 
154
- Create a Geistdocs project with `pnpm dlx @vercel/geistdocs init --name my-docs`. Then open `my-docs`, run `pnpm dev`, and explain which files I should edit first: `geistdocs.tsx`, `content/docs`, `content/docs/meta.json`, and `components/geistdocs/mdx-components.tsx`.
156
+ Help me create a Geistdocs project. Use `@vercel/geistdocs@latest` for the stable release or `@vercel/geistdocs@canary` when I specifically need the Geistcn migration. Then run `pnpm dev` and explain which files I should edit first: `geistdocs.tsx`, `content/docs`, `content/docs/meta.json`, and `components/geistdocs/mdx-components.tsx`.
155
157
 
156
158
  ## Prerequisites
157
159
 
158
160
  Before you begin, install:
159
161
 
160
- - Node.js 18 or later
161
- - pnpm, npm, or another package manager
162
+ - Node.js 20.9 or later
163
+ - pnpm
162
164
  - Git
163
165
 
166
+ The Geistdocs CLI always uses pnpm to install the generated project's dependencies. Running the CLI through `npx` does not remove the pnpm requirement.
167
+
168
+ ## Choose a release channel
169
+
170
+ Use `@vercel/geistdocs@latest` for the current stable package-backed release. Use `@vercel/geistdocs@canary` only when you need changes being evaluated on the `canary` branch, including the current Geistcn migration.
171
+
172
+ The canary dist-tag can move several times in one day. The CLI resolves the tag once and writes that exact version to the generated `package.json`.
173
+
174
+ ## Authenticate for the Geistcn canary
175
+
176
+ The Geistcn canary depends on restricted `@vercel/geistcn` and `@vercel/geistcn-assets` packages. Configure npm authentication before running the canary CLI. Add this configuration to your user-level `~/.npmrc`:
177
+
178
+ ```ini title="~/.npmrc"
179
+ @vercel:registry=https://registry.npmjs.org/
180
+ //registry.npmjs.org/:_authToken=${NPM_TOKEN}
181
+ always-auth=true
182
+ ```
183
+
184
+ Set `NPM_TOKEN` from an approved internal source and keep its value out of files and Git. Stable Geistdocs does not currently require these restricted packages. Read [Deploy to Vercel](/docs/deployment) before configuring automated installs.
185
+
164
186
  ## Create a project
165
187
 
166
- Run the Geistdocs CLI from an empty parent folder:
188
+ Run the Geistdocs CLI from an empty parent folder. For stable Geistdocs, run:
167
189
 
168
190
  ```bash title="Terminal"
169
- pnpm dlx @vercel/geistdocs init --name my-docs
191
+ pnpm dlx @vercel/geistdocs@latest init --name my-docs
170
192
  ```
171
193
 
172
- You can also use npm:
194
+ For the Geistcn canary, run:
173
195
 
174
196
  ```bash title="Terminal"
175
- npx @vercel/geistdocs init --name my-docs
197
+ pnpm dlx @vercel/geistdocs@canary init --name my-docs
176
198
  ```
177
199
 
178
200
  The CLI copies the template bundled in the package, rewrites the generated app to depend on the same `@vercel/geistdocs` version, installs dependencies, copies `.env.example` to `.env.local`, and initializes Git.
179
201
 
180
202
  ## Understand generated dependencies
181
203
 
182
- Generated projects include `@vercel/geistdocs`, `ai` v6, and `@ai-sdk/react` v3. Geistdocs uses those AI SDK packages for Ask AI, including the chat client transport and `createChatRoute` server behavior.
204
+ Generated projects include `@vercel/geistdocs`, `ai` v6, and `@ai-sdk/react` v3. Geistdocs uses those AI SDK packages for Ask AI, including the chat client transport and `createChatRoute` server behavior. Canary projects also declare the matching `@vercel/geistcn` and `@vercel/geistcn-assets` versions directly because generated application files import them.
183
205
 
184
206
  Update Ask AI by updating `@vercel/geistdocs`, not by copying package chat internals into the app. If your project uses the AI SDK directly for separate product features, keep that code compatible with the app's installed AI SDK version; package-owned Ask AI does not need to match another consumer project's `ai` version.
185
207
 
@@ -244,7 +266,7 @@ Read [Configuration](/docs/configuration) for the full configuration surface.
244
266
 
245
267
  ## Update Geistdocs
246
268
 
247
- For package-based projects, `geistdocs update` updates the `@vercel/geistdocs` package version. It does not overwrite your local content or adapter files.
269
+ For package-based projects, `geistdocs update` updates the `@vercel/geistdocs` package version. It does not overwrite your local content or adapter files. Projects already using a canary version continue to follow the `canary` dist-tag; stable projects follow `latest`.
248
270
 
249
271
  ```bash title="Terminal"
250
272
  pnpm exec geistdocs update
@@ -259,7 +281,7 @@ Review and test dependency changes before committing.
259
281
  title: Environment Variables
260
282
  description: Learn about the environment variables used in Geistdocs
261
283
  type: reference
262
- summary: Environment variables required by Geistdocs for AI chat, proxy mode, and production URL configuration.
284
+ summary: Environment variables required by Geistdocs for AI chat, Mixedbread retrieval, proxy mode, and production URL configuration.
263
285
  url: /docs/env
264
286
  source: apps/template/content/docs/env.mdx
265
287
  prerequisites:
@@ -271,9 +293,9 @@ related:
271
293
 
272
294
  # Environment Variables
273
295
 
274
- Geistdocs uses environment variables to configure Ask AI, optional Vertex-backed proxy mode, and production URL behavior.
296
+ Geistdocs uses environment variables to configure Ask AI, optional Mixedbread retrieval, optional Vertex-backed proxy mode, and production URL behavior.
275
297
 
276
- Review this Geistdocs project and help me configure the required environment variables. Check whether `AI_GATEWAY_API_KEY`, `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.
298
+ 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.
277
299
 
278
300
  ## `AI_GATEWAY_API_KEY`
279
301
 
@@ -283,6 +305,16 @@ The API key for the AI Gateway. This is used to power the default local AI chat
283
305
 
284
306
  Leave `GEISTDOCS_CHAT_PROXY_URL` unset to use AI Gateway mode.
285
307
 
308
+ ## `MXBAI_API_KEY`
309
+
310
+ The server-only API key for Mixedbread retrieval. The Mixedbread Vercel Marketplace integration injects this value when you provision a Store and connect it to the consumer site's Vercel project.
311
+
312
+ ## `MXBAI_STORE_ID`
313
+
314
+ The Mixedbread Store used by one consumer site. Set `ai.retrieval` to `"mixedbread"` and configure a unique `siteId` before using this value.
315
+
316
+ Provision the Store by running `vercel integration add mixedbread` from the root of the consumer site's repository, where Vercel CLI is linked to that site's project. Do not run the provisioning command from the Geistdocs package repository. Read [Improve Ask AI answers with Mixedbread](/docs/mixedbread-retrieval) for the complete setup.
317
+
286
318
  ## `GEISTDOCS_CHAT_PROXY_URL`
287
319
 
288
320
  An optional URL for a chat proxy. When set, Geistdocs searches the local documentation on the first user message, injects the current page and related docs as context, and forwards the request to this proxy.
@@ -325,7 +357,7 @@ Set this variable explicitly when deploying outside Vercel. Use a hostname such
325
357
  title: Deploy to Vercel
326
358
  description: Learn how to deploy your Geistdocs site to Vercel
327
359
  type: guide
328
- summary: Deploy your Geistdocs site to Vercel from the dashboard with the correct project settings.
360
+ summary: Deploy a Geistdocs site to Vercel with the required project settings, environment variables, and private-package access.
329
361
  url: /docs/deployment
330
362
  source: apps/template/content/docs/deployment.mdx
331
363
  prerequisites:
@@ -337,9 +369,9 @@ related:
337
369
 
338
370
  # Deploy to Vercel
339
371
 
340
- Deploy a Geistdocs site to Vercel as a Next.js app. Make sure your package dependency, environment variables, and production URL are configured before shipping.
372
+ Deploy a Geistdocs site to Vercel as a Next.js app. Configure package access, environment variables, and the production URL before shipping.
341
373
 
342
- Help me deploy this Geistdocs project to Vercel. Check the package scripts, required environment variables, and Vercel project settings, then give me a deploy checklist for production.
374
+ Help me deploy this Geistdocs project to Vercel. Check whether it uses the Geistcn canary and therefore needs private npm access, then review the package scripts, environment variables, GitHub Actions authentication, and Vercel project settings.
343
375
 
344
376
  ## Prerequisites
345
377
 
@@ -349,6 +381,31 @@ Before deploying, you need:
349
381
  - A [Vercel account](https://vercel.com) (sign up at [vercel.com](https://vercel.com))
350
382
  - Your Vercel account connected to your GitHub account
351
383
  - Environment variables ready (see [Environment Variables](/docs/env))
384
+ - Access to restricted `@vercel` npm packages if the project uses the Geistcn canary
385
+
386
+ ## Configure private package access
387
+
388
+ The Geistcn canary depends on restricted `@vercel/geistcn` and `@vercel/geistcn-assets` packages. Package installation fails without npm authentication.
389
+
390
+ For a Vercel deployment, ask `#help-core-platform` to add your Vercel project to the shared `NPM_TOKEN` environment variable list. Include the project link and the environments that need access. When `NPM_TOKEN` is available, Vercel creates the npm authentication configuration before installing dependencies. Do not copy the shared token into your repository or project documentation.
391
+
392
+ For GitHub Actions, ask `#help-it` to add your repository to the allowlist for the `NPM_TOKEN` organization secret. Pass that secret to npm authentication during the install job:
393
+
394
+ ```yaml title=".github/workflows/check.yml"
395
+ - uses: pnpm/action-setup@v4
396
+
397
+ - uses: actions/setup-node@v4
398
+ with:
399
+ node-version: 20
400
+ cache: pnpm
401
+ registry-url: https://registry.npmjs.org
402
+
403
+ - run: pnpm install
404
+ env:
405
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
406
+ ```
407
+
408
+ Read [How do I use private dependencies with Vercel?](https://vercel.com/kb/guide/using-private-dependencies-with-vercel) for the platform's npm authentication behavior.
352
409
 
353
410
  ## Deploy to Vercel
354
411
 
@@ -358,9 +415,9 @@ To deploy from the Vercel dashboard:
358
415
  2. Select your Geistdocs repository
359
416
  3. Configure your project settings:
360
417
  - **Framework Preset**: Next.js (automatically detected)
361
- - **Build Command**: `pnpm build` or `npm run build`
418
+ - **Build Command**: `pnpm build`
362
419
  - **Output Directory**: `.next` (default)
363
- - **Install Command**: `pnpm install` or `npm install`
420
+ - **Install Command**: `pnpm install`
364
421
  4. Add your environment variables (see [Environment Variables](/docs/env))
365
422
  5. Click "Deploy"
366
423
 
@@ -398,7 +455,10 @@ related:
398
455
 
399
456
  Migrate an existing Fumadocs or custom Geist documentation site to `@vercel/geistdocs` by moving shared behavior into package APIs and keeping site-specific adapters local. The safest migration keeps content, routing decisions, and product-specific UI in your app while replacing copied runtime code with thin package-backed adapters.
400
457
 
401
- Help me migrate this existing docs site to package-backed Geistdocs. Inspect `source.config.ts`, `lib/geistdocs/source.ts`, app route files, `proxy.ts` or `middleware.ts`, `public/llms.txt`, Open Graph routes, Tailwind CSS setup, `package.json` AI SDK dependencies, and environment variables. Then produce a step-by-step migration plan using `@vercel/geistdocs` package APIs without copying package internals.
458
+ > Note:
459
+ The current Geistcn migration is available from the `canary` dist-tag, not `latest`. The canary depends on restricted `@vercel/geistcn` packages and is intended for Vercel-internal projects while the migration is evaluated.
460
+
461
+ Help me migrate this existing docs site to package-backed Geistdocs. First determine whether I should use the stable release or the Geistcn canary. Inspect `source.config.ts`, `lib/geistdocs/source.ts`, app route files, `proxy.ts` or `middleware.ts`, `public/llms.txt`, Open Graph routes, Tailwind CSS setup, `package.json` AI SDK dependencies, and environment variables. For the Geistcn canary, also inspect package authentication, `@vercel/geistdocs` component and asset imports, root HTML classes, and Next.js configuration. Pin the selected version and use package APIs without copying package internals.
402
462
 
403
463
  ## Before you migrate
404
464
 
@@ -410,6 +470,7 @@ Create a working branch and inventory the current site before replacing code:
410
470
  - Static files that overlap package routes, such as `public/llms.txt`.
411
471
  - Search, chat, `llms.txt`, page-level Markdown, `sitemap.md`, `agents.md`, `/.well-known/mcp.json`, RSS, and Open Graph routes.
412
472
  - Tailwind CSS version and custom plugins.
473
+ - Imports from `@vercel/geistdocs/components/*` or `@vercel/geistdocs/assets/*` that the Geistcn canary removes.
413
474
  - Direct app usage of `ai` or `@ai-sdk/react` outside Geistdocs.
414
475
  - Environment variables required by the homepage, docs routes, or API routes.
415
476
 
@@ -424,20 +485,76 @@ Fix unrelated build failures first. A migration is safer when the starting point
424
485
 
425
486
  ## Install Geistdocs
426
487
 
427
- Add `@vercel/geistdocs` and align the supported Fumadocs and Next.js dependencies for the package version you are adopting. Geistdocs requires Next.js 16.3.3 or later within 16.x. Earlier 16.3 releases can retain an optional catch-all route's index content after a client navigation to a child page when Cache Components and Partial Prefetching are enabled.
488
+ For the current stable package-backed release, install `latest` and record the exact resolved version:
489
+
490
+ ```bash title="Terminal"
491
+ pnpm add --save-exact @vercel/geistdocs@latest
492
+ ```
493
+
494
+ Geistdocs requires Node.js 20.9 or later and Next.js 16.3.3 or later within 16.x. Earlier 16.3 releases can retain an optional catch-all route's index content after a client navigation to a child page when Cache Components and Partial Prefetching are enabled.
495
+
496
+ If you are starting from a generated stable Geistdocs project and moving content into it, run the CLI from an empty parent folder:
497
+
498
+ ```bash title="Terminal"
499
+ pnpm dlx @vercel/geistdocs@latest init --name my-docs
500
+ ```
501
+
502
+ ### Install the Geistcn canary
428
503
 
429
- For an existing project, use your package manager directly:
504
+ The Geistcn canary requires npm access to restricted `@vercel` packages. Configure your user-level npm authentication before installation:
505
+
506
+ ```ini title="~/.npmrc"
507
+ @vercel:registry=https://registry.npmjs.org/
508
+ //registry.npmjs.org/:_authToken=${NPM_TOKEN}
509
+ always-auth=true
510
+ ```
511
+
512
+ Set `NPM_TOKEN` from an approved internal source and keep its value out of files and Git. Read [Deploy to Vercel](/docs/deployment#configure-private-package-access) for Vercel and GitHub Actions access.
513
+
514
+ For an existing standalone project, install the canary and the direct Geistcn dependencies used by application files. The current canary template uses `@vercel/geistcn` 1.0.3 and `@vercel/geistcn-assets` 2.0.1:
430
515
 
431
516
  ```bash title="Terminal"
432
- pnpm add @vercel/geistdocs
517
+ pnpm add --save-exact \
518
+ @vercel/geistdocs@canary \
519
+ @vercel/geistcn@1.0.3 \
520
+ @vercel/geistcn-assets@2.0.1
433
521
  ```
434
522
 
435
- If you are starting from a generated Geistdocs project and moving content into it, use the CLI:
523
+ `--save-exact` records the canary resolved at install time instead of a range. Before upgrading later, check the next canary and test that exact version:
436
524
 
437
525
  ```bash title="Terminal"
438
- pnpm dlx @vercel/geistdocs init --name my-docs
526
+ npm view @vercel/geistdocs dist-tags.canary
439
527
  ```
440
528
 
529
+ In a monorepo that owns the Geistcn packages, such as `vercel/front`, keep their existing `workspace:*` dependency specifications and pin only `@vercel/geistdocs` to the tested canary.
530
+
531
+ If you are starting from a generated Geistdocs project and moving content into it, run the canary CLI from an empty parent folder:
532
+
533
+ ```bash title="Terminal"
534
+ pnpm dlx @vercel/geistdocs@canary init --name my-docs
535
+ ```
536
+
537
+ ## Replace imports for the Geistcn canary
538
+
539
+ The Geistcn canary removes generic design-system components and assets from the Geistdocs public API. Search for affected imports before upgrading:
540
+
541
+ ```bash title="Terminal"
542
+ rg '@vercel/geistdocs/(components|assets)' .
543
+ ```
544
+
545
+ Replace imports according to this table:
546
+
547
+ | Previous Geistdocs import | Replacement |
548
+ | --- | --- |
549
+ | `components/badge`, `components/button`, `components/dialog`, `components/drawer`, `components/input`, `components/kbd`, `components/separator`, `components/sheet`, `components/spinner`, `components/textarea`, `components/theme-switcher`, or `components/tooltip` | Import the matching component directly from `@vercel/geistcn/components/<name>`. |
550
+ | `components/switch` | Import toggle controls from `@vercel/geistcn/components/toggle`. |
551
+ | `components/sonner` | Use `Toasts` and `useToasts` from `@vercel/geistcn/components/toasts`. |
552
+ | `components/theme-aware-image` | Use `Image` from `@vercel/geistcn/components/image` with `srcLight` and `srcDark`. |
553
+ | `assets/icons`, `assets/icons/*`, `assets/logos`, or `assets/logos/*` | Import from `@vercel/geistcn-assets/icons`, `@vercel/geistcn-assets/icons/*`, `@vercel/geistcn-assets/logos`, or `@vercel/geistcn-assets/logos/*`. |
554
+ | `components/button-group`, `components/card`, or `components/input-group` | Use an appropriate Geistcn component or keep an application-owned composition. There is no direct Geistcn replacement with the same API. |
555
+
556
+ Keep documentation-specific composites such as `Callout`, `CodeBlock`, `CodeBlockTabs`, `CommandPrompt`, `CopyPrompt`, and `Mermaid` imported from `@vercel/geistdocs/components/*`.
557
+
441
558
  ## Configure Next.js
442
559
 
443
560
  The Geistdocs Next.js integration composes Fumadocs MDX, enables automatic app-route discovery for agent-readable 404s, and preserves your Next.js configuration. Enable Cache Components in the same file:
@@ -456,6 +573,39 @@ const config: NextConfig = {
456
573
  export default withGeistdocs(config);
457
574
  ```
458
575
 
576
+ ### Configure Next.js for the Geistcn canary
577
+
578
+ Geistcn publishes TypeScript source from supporting packages. A project using the Geistcn canary also needs the matching transpilation and modular import settings:
579
+
580
+ ```ts title="next.config.ts"
581
+ import { createGeistdocs } from "@vercel/geistdocs/next";
582
+ import type { NextConfig } from "next";
583
+
584
+ const withGeistdocs = createGeistdocs();
585
+
586
+ const config: NextConfig = {
587
+ modularizeImports: {
588
+ "@vercel/geistcn/components": {
589
+ skipDefaultConversion: true,
590
+ transform: "@vercel/geistcn/components/{{ kebabCase member }}",
591
+ },
592
+ "@vercel/geistcn/core": {
593
+ skipDefaultConversion: true,
594
+ transform: "@vercel/geistcn/core",
595
+ },
596
+ },
597
+ transpilePackages: [
598
+ "@vercel/geistcn",
599
+ "@vercel/geist-test-utils",
600
+ "@vercel/next-themes",
601
+ ],
602
+ cacheComponents: true,
603
+ partialPrefetching: true,
604
+ };
605
+
606
+ export default withGeistdocs(config);
607
+ ```
608
+
459
609
  Restart `next dev` after adding, deleting, or renaming an App Router page or route. Production builds always regenerate the route manifest.
460
610
 
461
611
  Every root dynamic parameter needs at least one value from `generateStaticParams`. For a site with a `[lang]` root segment, return every configured language from the root layout:
@@ -484,6 +634,33 @@ Keep `partialPrefetching` enabled so links reuse each route's static and cached
484
634
 
485
635
  For unknown HTML pages, browsers can receive the docs loading shell with a `200` response before the page resolves to the not-found UI. Crawlers wait for the complete response and receive `404`. Machine-readable Markdown routes keep their configured status behavior.
486
636
 
637
+ ## Configure the root layout for the Geistcn canary
638
+
639
+ Geistcn provides the fonts, theme classes, and Tailwind preflight used by the package UI. Apply them to the root `<html>` element:
640
+
641
+ ```tsx title="app/[lang]/layout.tsx"
642
+ import { geistFontClasses } from "@vercel/geistcn/core";
643
+ import { cn } from "@vercel/geistcn/utils";
644
+ import type { ReactNode } from "react";
645
+
646
+ export default function RootLayout({ children }: { children: ReactNode }) {
647
+ return (
648
+ <html
649
+ className={cn(
650
+ geistFontClasses,
651
+ "tailwind tailwind-preflight antialiased"
652
+ )}
653
+ lang="en"
654
+ suppressHydrationWarning
655
+ >
656
+ <body>{children}</body>
657
+ </html>
658
+ );
659
+ }
660
+ ```
661
+
662
+ Keep the site's existing providers and metadata inside this structure. If the route has a `[lang]` parameter, use the active language instead of the hardcoded `en` value.
663
+
487
664
  ## Align Ask AI dependencies
488
665
 
489
666
  Geistdocs Ask AI uses AI SDK v6. Generated projects install `ai` v6 and `@ai-sdk/react` v3 so package-owned chat components and route helpers use the supported AI SDK APIs.
@@ -754,7 +931,7 @@ For a base-path application whose root page is documentation, add `"/"` to the s
754
931
 
755
932
  ## Configure Tailwind CSS
756
933
 
757
- Tailwind CSS v4 requires `@source` entries for package components and related dependencies.
934
+ Stable Geistdocs uses Tailwind CSS v4 with source entries for package components and related dependencies:
758
935
 
759
936
  ```css title="app/styles/geistdocs.css"
760
937
  @import "tailwindcss";
@@ -768,6 +945,23 @@ Tailwind CSS v4 requires `@source` entries for package components and related de
768
945
 
769
946
  Move Tailwind CSS v3 plugin utilities into CSS-first v4 utilities or theme variables. Keep custom token names stable while you migrate components.
770
947
 
948
+ ### Configure Tailwind CSS for the Geistcn canary
949
+
950
+ For the Geistcn canary, use the import order and narrow Geistcn source scan from the canary template:
951
+
952
+ ```css title="app/styles/geistdocs.css"
953
+ @import "@vercel/geistcn/tailwind.css";
954
+ @import "fumadocs-ui/css/shadcn.css";
955
+ @import "fumadocs-ui/css/preset.css";
956
+ @import "@vercel/geistdocs/theme.css";
957
+ @import "@vercel/geistcn/styles.css";
958
+ @import "@vercel/geistcn/marketing-typography.css";
959
+
960
+ @source "../../node_modules/@vercel/geistcn/src/components/**/*.{ts,tsx}";
961
+ ```
962
+
963
+ Geistcn owns the Geist tokens, theme, typography, preflight, and animation utilities. The Geistdocs theme entry point contains documentation and Fumadocs integration rules and sources the compiled Geistdocs runtime. Do not scan all of `@vercel/geistcn/src`; font internals in the published package can reference paths outside the application root and cause Turbopack to fail.
964
+
771
965
  ## Handle environment variables
772
966
 
773
967
  Do not require production secrets for local migration builds. If a homepage or API route depends on a production-only secret, add a local fallback or disable that integration in development.
@@ -778,7 +972,7 @@ export const flagsSecret =
778
972
  (process.env.NODE_ENV === "development" ? "local-development-secret" : undefined);
779
973
  ```
780
974
 
781
- Keep real secrets in `.env.local` and out of Git.
975
+ Keep real application secrets in `.env.local` and out of Git. `NPM_TOKEN` is an install-time credential, not an application environment variable. Keep it in your shell, Vercel project settings, or GitHub Actions secrets, and never prefix it with `NEXT_PUBLIC_`.
782
976
 
783
977
  ## Verify the migration
784
978
 
@@ -786,10 +980,13 @@ Run the same checks after each routing or source change:
786
980
 
787
981
  ```bash title="Terminal"
788
982
  pnpm postinstall
983
+ pnpm list @vercel/geistdocs
789
984
  pnpm build
790
985
  pnpm dev
791
986
  ```
792
987
 
988
+ For the Geistcn canary, also run `pnpm list @vercel/geistcn @vercel/geistcn-assets` and confirm the versions match the selected canary template.
989
+
793
990
  Check these URLs locally:
794
991
 
795
992
  - `/docs` or the migrated docs root.
@@ -927,6 +1124,7 @@ On desktop, the group opens as a full-width panel below the navbar, following th
927
1124
  import { defineConfig } from "@vercel/geistdocs/config";
928
1125
  import {
929
1126
  agent,
1127
+ ai,
930
1128
  basePath,
931
1129
  github,
932
1130
  Logo,
@@ -951,6 +1149,7 @@ export const config = defineConfig({
951
1149
  ai: {
952
1150
  prompt,
953
1151
  suggestions,
1152
+ ...ai,
954
1153
  },
955
1154
  });
956
1155
  ```
@@ -981,15 +1180,16 @@ export const config = defineConfig({
981
1180
  });
982
1181
  ```
983
1182
 
984
- The `ai` config also accepts `eveAgent` to answer Ask AI requests with a hosted eve framework agent:
1183
+ The `ai` config accepts `retrieval: "mixedbread"` to use semantic documentation retrieval and `eveAgent` to answer Ask AI requests with a hosted eve framework agent:
985
1184
 
986
1185
  ```tsx title="geistdocs.tsx"
987
1186
  export const ai = {
1187
+ retrieval: "mixedbread",
988
1188
  eveAgent: { url: "https://help-eve.example.dev" },
989
1189
  };
990
1190
  ```
991
1191
 
992
- See [Ask AI](/docs/ask-ai) for the full eve agent mode behavior, including authentication.
1192
+ 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.
993
1193
 
994
1194
  Use [Versioned docs](/docs/versioned-docs) for versioned source setup and [Proxy and markdown routes](/docs/proxy) for route mappings.
995
1195
 
@@ -2279,7 +2479,7 @@ The `.mdx` version returns:
2279
2479
 
2280
2480
  For a docs section mounted at `/docs`, the section root remains `/docs.md`. For a source mounted at the app root with `baseUrl: "/"`, Geistdocs uses `/index.md` for the root page. If Next.js has `basePath: "/docs"`, that public root Markdown URL is `/docs/index.md`.
2281
2481
 
2282
- Copy Page, View as Markdown, and the `text/markdown` metadata alternate all use the same package resolver. Use `createDocsPage({ getMarkdownUrl })` only when the deployment needs a different public contract.
2482
+ Copy Page, View as Markdown, and the `text/markdown` metadata alternate all use the same package resolver. View as Markdown opens the resolved `.md` URL in a new tab from a button, which keeps the URL shareable without adding an anchor to the page. Use `createDocsPage({ getMarkdownUrl })` only when the deployment needs a different public contract.
2283
2483
 
2284
2484
  ## Use cases
2285
2485
 
@@ -2528,6 +2728,7 @@ prerequisites:
2528
2728
  related:
2529
2729
  - /docs/open-in-chat
2530
2730
  - /docs/llms-txt
2731
+ - /docs/mixedbread-retrieval
2531
2732
  - /docs/configuration
2532
2733
  ---
2533
2734
 
@@ -2692,6 +2893,8 @@ By default, the AI assistant includes a built-in `search_docs` tool that:
2692
2893
 
2693
2894
  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.
2694
2895
 
2896
+ 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.
2897
+
2695
2898
  ### Persistent Chat History
2696
2899
 
2697
2900
  Conversations are automatically saved to the browser's IndexedDB, providing:
@@ -3118,6 +3321,154 @@ Pass any additional fields in the request body, and they are captured as metadat
3118
3321
  - Custom tracking data
3119
3322
 
3120
3323
 
3324
+ ---
3325
+
3326
+ ---
3327
+ title: Improve Ask AI answers with Mixedbread
3328
+ description: Configure Mixedbread retrieval for a Geistdocs Ask AI chat and sync documentation to a site-specific Store
3329
+ type: guide
3330
+ summary: Provision a Mixedbread Store for one Geistdocs consumer site, enable semantic retrieval, and sync documentation during production builds.
3331
+ url: /docs/mixedbread-retrieval
3332
+ source: apps/template/content/docs/mixedbread-retrieval.mdx
3333
+ prerequisites:
3334
+ - /docs/ask-ai
3335
+ - /docs/env
3336
+ - /docs/deployment
3337
+ related:
3338
+ - /docs/configuration
3339
+ - /docs/llms-txt
3340
+ ---
3341
+
3342
+ # Improve Ask AI answers with Mixedbread
3343
+
3344
+ Mixedbread retrieval gives Ask AI the documentation passages that best match a user's question. The AI model stays the same, while semantic retrieval improves the evidence included with each question.
3345
+
3346
+ Geistdocs keeps the visible search dialog on its local Orama index. Mixedbread only changes the documentation retrieval used by Ask AI.
3347
+
3348
+ Help me enable Mixedbread retrieval for this Geistdocs consumer site. Confirm that I am in this site's own repository and linked to the correct Vercel project before provisioning a Store. Then verify `siteId`, `ai.retrieval`, the search export route, the build script, and the `MXBAI` environment variables.
3349
+
3350
+ ## How Mixedbread retrieval works
3351
+
3352
+ Ask AI searches documentation before sending a question to the configured AI model. The default local retriever matches keywords with Orama. Mixedbread adds semantic matching and returns the relevant content chunk instead of the start of a matching page.
3353
+
3354
+ The production build performs an incremental sync:
3355
+
3356
+ 1. Next.js statically generates `/api/search/export` from the site's configured content sources.
3357
+ 2. `geistdocs search sync` uploads new or changed Markdown documents to the site's Mixedbread Store.
3358
+ 3. Ask AI queries the Store by `siteId` and locale.
3359
+ 4. Geistdocs falls back to the local Orama retriever if Mixedbread is unavailable or its credentials are missing at runtime.
3360
+
3361
+ Pages with `internal: true` or `excludeFrom: [chat]` are omitted from the export and removed from the Store on the next successful sync.
3362
+
3363
+ ## Prerequisites
3364
+
3365
+ Before enabling Mixedbread retrieval, confirm that:
3366
+
3367
+ - The Mixedbread Marketplace integration is installed on your Vercel team.
3368
+ - The consumer site has its own Vercel project.
3369
+ - The consumer repository uses a Geistdocs release that includes `geistdocs search sync` and `createSearchExportRoute`.
3370
+ - `source.config.ts` enables `includeProcessedMarkdown`, as generated Geistdocs projects do by default.
3371
+ - `next.config.ts` enables `cacheComponents`, as generated Geistdocs projects do by default. Next.js must statically prerender `/api/search/export` before the sync command runs.
3372
+
3373
+ Use one Store per consumer site. Separate Stores isolate deployments and cleanup while keeping the same configuration in every repository.
3374
+
3375
+ ## Provision a Store from the consumer repository
3376
+
3377
+ Run the Vercel integration command from the root of the **consumer site's repository**. Do not run it from the `geistdocs` package repository or from another docs site's repository.
3378
+
3379
+ The current directory must be linked to the Vercel project that deploys this consumer site. Check `.vercel/project.json`, or run `vercel link` and select the correct project before provisioning the Store:
3380
+
3381
+ ```bash title="Terminal"
3382
+ cd path/to/consumer-site-repository
3383
+ vercel link
3384
+ vercel integration add mixedbread \
3385
+ --name docs-my-product \
3386
+ --environment production
3387
+ ```
3388
+
3389
+ If the repository is a monorepo, run the command from the directory where you link the target Vercel project. The Vercel project's configured Root Directory can still point to the Geistdocs application inside that repository.
3390
+
3391
+ The command provisions one Mixedbread Store, connects it to the currently linked Vercel project, and pulls these environment variables:
3392
+
3393
+ - `MXBAI_API_KEY`: Authenticates server-side Mixedbread API requests.
3394
+ - `MXBAI_STORE_ID`: Identifies this consumer site's Store.
3395
+
3396
+ Vercel prints a resource link after provisioning. Confirm the connection with:
3397
+
3398
+ ```bash title="Terminal"
3399
+ vercel integration list --integration mixedbread
3400
+ ```
3401
+
3402
+ ## Configure the consumer site
3403
+
3404
+ Set a unique `siteId` and enable Mixedbread in the consumer repository's root `geistdocs.tsx` file:
3405
+
3406
+ ```tsx title="geistdocs.tsx"
3407
+ import type {
3408
+ GeistdocsAIConfig,
3409
+ } from "@vercel/geistdocs/config";
3410
+
3411
+ export const siteId = "my-product-docs";
3412
+
3413
+ export const ai = {
3414
+ retrieval: "mixedbread",
3415
+ } satisfies GeistdocsAIConfig;
3416
+ ```
3417
+
3418
+ The generated `lib/geistdocs/config.tsx` spreads `ai` into the package config. Keep `MXBAI_API_KEY` and `MXBAI_STORE_ID` out of `geistdocs.tsx` because that config is available to client components.
3419
+
3420
+ ## Add the export route to an existing site
3421
+
3422
+ New Geistdocs projects include the export route. For an existing package-backed site, create this adapter:
3423
+
3424
+ ```ts title="app/api/search/export/route.ts"
3425
+ import { createSearchExportRoute } from "@vercel/geistdocs/routes/search-export";
3426
+ import { config } from "@/lib/geistdocs/config";
3427
+ import { geistdocsSource } from "@/lib/geistdocs/source";
3428
+
3429
+ export const { GET } = createSearchExportRoute({
3430
+ config,
3431
+ sources: [geistdocsSource],
3432
+ });
3433
+ ```
3434
+
3435
+ Pass every configured source in `sources` when the site has multiple sections or documentation versions.
3436
+
3437
+ ## Sync after each production build
3438
+
3439
+ New Geistdocs projects run the sync from their build script. For an existing site, update `package.json`:
3440
+
3441
+ ```json title="package.json"
3442
+ {
3443
+ "scripts": {
3444
+ "build": "next build && geistdocs search sync"
3445
+ }
3446
+ }
3447
+ ```
3448
+
3449
+ Deploy the site to production. The first production build uploads every chat-visible page. Later builds upload changed pages and remove stale pages while leaving unrelated Store files untouched.
3450
+
3451
+ Local and preview builds skip the remote sync. To test a sync outside a production Vercel build, build the site and run the sync with the linked project's production environment variables:
3452
+
3453
+ ```bash title="Terminal"
3454
+ pnpm build
3455
+ vercel env run --environment production -- \
3456
+ pnpm exec geistdocs search sync --allow-non-production
3457
+ ```
3458
+
3459
+ The sync command fails when Mixedbread retrieval is enabled for a production build but the Store environment variables are missing. The error prints the provisioning command and reminds you to run it from the correct consumer repository.
3460
+
3461
+ ## Verify retrieval
3462
+
3463
+ Open the Mixedbread dashboard through Vercel and confirm that the Store contains one file per chat-visible documentation page:
3464
+
3465
+ ```bash title="Terminal"
3466
+ vercel integration open mixedbread
3467
+ ```
3468
+
3469
+ Ask a question that uses different words from the page title. Ask AI should cite the relevant page and answer from the matching section. If Mixedbread returns an error or exceeds the request timeout, Geistdocs logs a warning and retries the question with local Orama retrieval.
3470
+
3471
+
3121
3472
  ---
3122
3473
 
3123
3474
  ---