@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
@@ -0,0 +1,144 @@
1
+ ---
2
+ title: Improve Ask AI answers with Mixedbread
3
+ description: Configure Mixedbread retrieval for a Geistdocs Ask AI chat and sync documentation to a site-specific Store
4
+ type: guide
5
+ summary: Provision a Mixedbread Store for one Geistdocs consumer site, enable semantic retrieval, and sync documentation during production builds.
6
+ url: /docs/mixedbread-retrieval
7
+ source: apps/template/content/docs/mixedbread-retrieval.mdx
8
+ prerequisites:
9
+ - /docs/ask-ai
10
+ - /docs/env
11
+ - /docs/deployment
12
+ related:
13
+ - /docs/configuration
14
+ - /docs/llms-txt
15
+ ---
16
+
17
+ # Improve Ask AI answers with Mixedbread
18
+
19
+ 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.
20
+
21
+ Geistdocs keeps the visible search dialog on its local Orama index. Mixedbread only changes the documentation retrieval used by Ask AI.
22
+
23
+ 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.
24
+
25
+ ## How Mixedbread retrieval works
26
+
27
+ 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.
28
+
29
+ The production build performs an incremental sync:
30
+
31
+ 1. Next.js statically generates `/api/search/export` from the site's configured content sources.
32
+ 2. `geistdocs search sync` uploads new or changed Markdown documents to the site's Mixedbread Store.
33
+ 3. Ask AI queries the Store by `siteId` and locale.
34
+ 4. Geistdocs falls back to the local Orama retriever if Mixedbread is unavailable or its credentials are missing at runtime.
35
+
36
+ Pages with `internal: true` or `excludeFrom: [chat]` are omitted from the export and removed from the Store on the next successful sync.
37
+
38
+ ## Prerequisites
39
+
40
+ Before enabling Mixedbread retrieval, confirm that:
41
+
42
+ - The Mixedbread Marketplace integration is installed on your Vercel team.
43
+ - The consumer site has its own Vercel project.
44
+ - The consumer repository uses a Geistdocs release that includes `geistdocs search sync` and `createSearchExportRoute`.
45
+ - `source.config.ts` enables `includeProcessedMarkdown`, as generated Geistdocs projects do by default.
46
+ - `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.
47
+
48
+ Use one Store per consumer site. Separate Stores isolate deployments and cleanup while keeping the same configuration in every repository.
49
+
50
+ ## Provision a Store from the consumer repository
51
+
52
+ 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.
53
+
54
+ 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:
55
+
56
+ ```bash title="Terminal"
57
+ cd path/to/consumer-site-repository
58
+ vercel link
59
+ vercel integration add mixedbread \
60
+ --name docs-my-product \
61
+ --environment production
62
+ ```
63
+
64
+ 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.
65
+
66
+ The command provisions one Mixedbread Store, connects it to the currently linked Vercel project, and pulls these environment variables:
67
+
68
+ - `MXBAI_API_KEY`: Authenticates server-side Mixedbread API requests.
69
+ - `MXBAI_STORE_ID`: Identifies this consumer site's Store.
70
+
71
+ Vercel prints a resource link after provisioning. Confirm the connection with:
72
+
73
+ ```bash title="Terminal"
74
+ vercel integration list --integration mixedbread
75
+ ```
76
+
77
+ ## Configure the consumer site
78
+
79
+ Set a unique `siteId` and enable Mixedbread in the consumer repository's root `geistdocs.tsx` file:
80
+
81
+ ```tsx title="geistdocs.tsx"
82
+ import type {
83
+ GeistdocsAIConfig,
84
+ } from "@vercel/geistdocs/config";
85
+
86
+ export const siteId = "my-product-docs";
87
+
88
+ export const ai = {
89
+ retrieval: "mixedbread",
90
+ } satisfies GeistdocsAIConfig;
91
+ ```
92
+
93
+ 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.
94
+
95
+ ## Add the export route to an existing site
96
+
97
+ New Geistdocs projects include the export route. For an existing package-backed site, create this adapter:
98
+
99
+ ```ts title="app/api/search/export/route.ts"
100
+ import { createSearchExportRoute } from "@vercel/geistdocs/routes/search-export";
101
+ import { config } from "@/lib/geistdocs/config";
102
+ import { geistdocsSource } from "@/lib/geistdocs/source";
103
+
104
+ export const { GET } = createSearchExportRoute({
105
+ config,
106
+ sources: [geistdocsSource],
107
+ });
108
+ ```
109
+
110
+ Pass every configured source in `sources` when the site has multiple sections or documentation versions.
111
+
112
+ ## Sync after each production build
113
+
114
+ New Geistdocs projects run the sync from their build script. For an existing site, update `package.json`:
115
+
116
+ ```json title="package.json"
117
+ {
118
+ "scripts": {
119
+ "build": "next build && geistdocs search sync"
120
+ }
121
+ }
122
+ ```
123
+
124
+ 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.
125
+
126
+ 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:
127
+
128
+ ```bash title="Terminal"
129
+ pnpm build
130
+ vercel env run --environment production -- \
131
+ pnpm exec geistdocs search sync --allow-non-production
132
+ ```
133
+
134
+ 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.
135
+
136
+ ## Verify retrieval
137
+
138
+ Open the Mixedbread dashboard through Vercel and confirm that the Store contains one file per chat-visible documentation page:
139
+
140
+ ```bash title="Terminal"
141
+ vercel integration open mixedbread
142
+ ```
143
+
144
+ 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.
package/docs/sitemap.md CHANGED
@@ -5,8 +5,8 @@ Use it to choose focused page files from `docs/pages/` before reading the full `
5
5
 
6
6
  - [Overview](pages/index.md) | URL: /docs | Type: overview | Summary: Geistdocs is a packaged documentation system for creating Next.js and Fumadocs sites with shared runtime features.
7
7
  - [Getting Started](pages/getting-started.md) | URL: /docs/getting-started | Type: guide | Summary: Create a Geistdocs project, run it locally, and edit your first documentation page.
8
- - [Environment Variables](pages/env.md) | URL: /docs/env | Type: reference | Summary: Environment variables required by Geistdocs for AI chat, proxy mode, and production URL configuration.
9
- - [Deploy to Vercel](pages/deployment.md) | URL: /docs/deployment | Type: guide | Summary: Deploy your Geistdocs site to Vercel from the dashboard with the correct project settings.
8
+ - [Environment Variables](pages/env.md) | URL: /docs/env | Type: reference | Summary: Environment variables required by Geistdocs for AI chat, Mixedbread retrieval, proxy mode, and production URL configuration.
9
+ - [Deploy to Vercel](pages/deployment.md) | URL: /docs/deployment | Type: guide | Summary: Deploy a Geistdocs site to Vercel with the required project settings, environment variables, and private-package access.
10
10
  - [Migration guide](pages/migration.md) | URL: /docs/migration | Type: guide | Summary: Move an existing documentation site to @vercel/geistdocs while keeping local content, routing, middleware behavior, and AI-readable surfaces intact.
11
11
  - [Configuration](pages/configuration.md) | URL: /docs/configuration | Type: reference | Summary: Configure site metadata, navigation, AI features, page actions, translations, and local adapters.
12
12
  - [Syntax](pages/syntax.md) | URL: /docs/syntax | Type: reference | Summary: Supported MDX syntax including text formatting, code blocks, line highlighting, and Mermaid diagrams.
@@ -19,6 +19,7 @@ Use it to choose focused page files from `docs/pages/` before reading the full `
19
19
  - [Configure sidebar navigation](pages/guides/nested-navigation.md) | URL: /docs/guides/nested-navigation | Type: guide | Summary: Configure sidebar order, section labels, folder landing pages, and deeply nested page trees with meta.json files.
20
20
  - [Edit on GitHub](pages/edit-on-github.md) | URL: /docs/edit-on-github | Type: integration | Summary: A direct link on every documentation page that lets readers propose changes through GitHub pull requests.
21
21
  - [Feedback](pages/feedback.md) | URL: /docs/feedback | Type: integration | Summary: An interactive feedback widget that collects user sentiment and creates structured GitHub Issues automatically.
22
+ - [Improve Ask AI answers with Mixedbread](pages/mixedbread-retrieval.md) | URL: /docs/mixedbread-retrieval | Type: guide | Summary: Provision a Mixedbread Store for one Geistdocs consumer site, enable semantic retrieval, and sync documentation during production builds.
22
23
  - [Internationalization](pages/internationalization.md) | URL: /docs/internationalization | Type: guide | Summary: Serve documentation in multiple languages with automatic translation via the Geistdocs CLI and Fumadocs routing.
23
24
  - [llms.txt](pages/llms-txt.md) | URL: /docs/llms-txt | Type: conceptual | Summary: A single endpoint that returns all documentation as plain Markdown text following the llms.txt standard.
24
25
  - [Open in Chat](pages/open-in-chat.md) | URL: /docs/open-in-chat | Type: conceptual | Summary: Transfer documentation context to AI chat platforms like ChatGPT, Claude, Cursor, and v0 with a single click.
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": "1.25.2",
4
+ "version": "1.26.0",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
7
7
  "type": "git",
@@ -10,13 +10,14 @@
10
10
  },
11
11
  "type": "module",
12
12
  "bin": {
13
- "geistdocs": "dist/cli/index.js"
13
+ "geistdocs": "cli.js"
14
14
  },
15
15
  "sideEffects": [
16
16
  "./styles.css",
17
17
  "./theme.css"
18
18
  ],
19
19
  "files": [
20
+ "cli.js",
20
21
  "dist",
21
22
  "docs",
22
23
  "source-config.js",
@@ -86,6 +87,10 @@
86
87
  "types": "./dist/routes/search.d.ts",
87
88
  "default": "./dist/routes/search.js"
88
89
  },
90
+ "./routes/search-export": {
91
+ "types": "./dist/routes/search-export.d.ts",
92
+ "default": "./dist/routes/search-export.js"
93
+ },
89
94
  "./routes/llms": {
90
95
  "types": "./dist/routes/llms.d.ts",
91
96
  "default": "./dist/routes/llms.js"
@@ -275,9 +280,12 @@
275
280
  "@ai-sdk/react": "^3.0.134",
276
281
  "@clack/prompts": "^0.11.0",
277
282
  "@icons-pack/react-simple-icons": "^13.8.0",
283
+ "@next/env": "16.3.3",
278
284
  "@orama/tokenizers": "^3.1.16",
279
285
  "@streamdown/cjk": "^1.0.1",
280
286
  "@streamdown/code": "^1.0.1",
287
+ "@types/mdx": "^2.0.13",
288
+ "@types/react": "^19.2.7",
281
289
  "@vercel/agent-readability": "^0.6.0",
282
290
  "@vercel/oidc": "^3.4.1",
283
291
  "ai": "^6.0.132",
@@ -321,9 +329,7 @@
321
329
  "@biomejs/biome": "^2.3.8",
322
330
  "@types/glob": "^9.0.0",
323
331
  "@types/mdast": "^4.0.4",
324
- "@types/mdx": "^2.0.13",
325
332
  "@types/node": "^24.10.1",
326
- "@types/react": "^19.2.7",
327
333
  "@types/react-dom": "^19.2.3",
328
334
  "mdast-util-mdx-jsx": "^3.2.0",
329
335
  "next": "16.3.3",
@@ -0,0 +1,19 @@
1
+ # AI Gateway API key for default Ask AI mode.
2
+ # Ask AI does not use this when GEISTDOCS_CHAT_PROXY_URL is set.
3
+ AI_GATEWAY_API_KEY=""
4
+
5
+ # Mixedbread credentials injected by the Vercel Marketplace integration.
6
+ MXBAI_API_KEY=""
7
+ MXBAI_STORE_ID=""
8
+
9
+ # Chat proxy URL for Vertex-backed Ask AI mode.
10
+ # Include the /vertex route, for example: https://<geistdocs-platform-deployment>/vertex
11
+ GEISTDOCS_CHAT_PROXY_URL=""
12
+
13
+ # Chat proxy bearer token.
14
+ # Only set this for a custom proxy that requires Authorization: Bearer <token>.
15
+ # The default Geistdocs platform /vertex proxy uses Vercel OIDC and Trusted Sources.
16
+ GEISTDOCS_CHAT_PROXY_TOKEN=""
17
+
18
+ # Production URL (automatically set on Vercel)
19
+ NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL="localhost:3000"
@@ -7,6 +7,7 @@ Use these instructions when an AI coding agent edits this project.
7
7
  ## Architecture
8
8
 
9
9
  - Runtime features come from `@vercel/geistdocs`, including the docs page renderer, layout helpers, MDX components, search, Ask AI, markdown routes, proxy helpers, and source helpers.
10
+ - Stable Geistdocs exposes shared UI primitives through documented `@vercel/geistdocs/components/*` paths. When explicitly migrating to the Geistcn canary, follow the migration guide before replacing those imports with `@vercel/geistcn` and `@vercel/geistcn-assets`.
10
11
  - `@vercel/geistdocs` owns the Ask AI client, server route behavior, and AI SDK v6 runtime dependencies. Do not fork package internals to fit an older app-level `ai` version.
11
12
  - Local files are user-owned adapters. They should stay thin and call public package exports from `@vercel/geistdocs/*`.
12
13
  - Do not copy package internals into the app to make a customization. Prefer configuring an adapter file or upgrading `@vercel/geistdocs`.
@@ -24,7 +25,7 @@ Use these instructions when an AI coding agent edits this project.
24
25
 
25
26
  | Task | Edit |
26
27
  | --- | --- |
27
- | Configure site title, logo, nav, GitHub links, AI prompt, suggestions, translations, `basePath`, or `siteId` | `geistdocs.tsx` |
28
+ | Configure site title, logo, nav, GitHub links, AI prompt, retrieval, suggestions, translations, `basePath`, or `siteId` | `geistdocs.tsx` |
28
29
  | Add or update documentation pages | `content/docs/**/*.mdx` |
29
30
  | Control sidebar order, groups, and folder labels | `content/docs/meta.json` |
30
31
  | Give a page a shorter navigation label | Set `navTitle` in the page's frontmatter |
@@ -35,7 +36,7 @@ Use these instructions when an AI coding agent edits this project.
35
36
  | Configure Fumadocs collections and source-safe MDX processing | `source.config.ts` |
36
37
  | Configure the docs page renderer | `app/[lang]/docs/[[...slug]]/page.tsx` |
37
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 chat or search APIs | `app/api/chat/route.ts`, `app/api/search/route.ts` |
39
+ | Configure chat or search APIs | `app/api/chat/route.ts`, `app/api/search/route.ts`, `app/api/search/export/route.ts` |
39
40
  | Add request handling before or after Geistdocs routing | `proxy.ts` |
40
41
  | Edit the marketing home page | `app/[lang]/(home)/**` |
41
42
  | Edit shared styles | `app/global.css`, `app/styles/geistdocs.css` |
@@ -68,6 +69,11 @@ Use these instructions when an AI coding agent edits this project.
68
69
  ## Ask AI and Vertex proxy guidelines
69
70
 
70
71
  - Leave `GEISTDOCS_CHAT_PROXY_URL` unset and `ai.eveAgent` unconfigured to use the default AI Gateway path. In that mode, `app/api/chat/route.ts` calls `createChatRoute` without a `proxy` option and uses the local docs search tool during the AI SDK `streamText` loop.
72
+ - Set `ai.retrieval: "mixedbread"` with a unique `siteId` to use Mixedbread semantic retrieval for Ask AI. The visible search dialog continues to use local Orama search.
73
+ - Provision a Mixedbread Store from the root of this consumer site's repository, where Vercel CLI is linked to this site's Vercel project. Never run `vercel integration add mixedbread` from the Geistdocs package repository or another consumer repository.
74
+ - Keep `MXBAI_API_KEY` and `MXBAI_STORE_ID` in environment variables. Never put them in `geistdocs.tsx`, because config is available to client components.
75
+ - 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.
76
+ - Mixedbread failures fall back to local Orama retrieval. Keep the local source definitions and `excludeFrom: [chat]` visibility behavior intact.
71
77
  - 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.
72
78
  - 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.
73
79
  - 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.
@@ -80,18 +86,24 @@ Use these instructions when an AI coding agent edits this project.
80
86
  ## Migration guidelines
81
87
 
82
88
  - When migrating from Fumadocs or a custom Geist docs site, inventory `source.config.ts`, route files, `middleware.ts` or `proxy.ts`, `public/llms.txt`, OG routes, Tailwind CSS setup, and required environment variables before editing.
89
+ - The Geistcn migration is on the `canary` release channel until it is promoted to stable. Pin the tested `@vercel/geistdocs` canary exactly instead of storing the mutable dist-tag or a semver range.
90
+ - The Geistcn canary requires private npm access. Keep `NPM_TOKEN` out of source files; configure it through local npm authentication, Vercel project settings, and GitHub Actions secrets.
91
+ - Declare the `@vercel/geistcn` and `@vercel/geistcn-assets` versions from the matching bundled template as direct dependencies when application files import them.
83
92
  - Inventory direct app usage of `ai` and `@ai-sdk/react`. Package-owned Ask AI uses AI SDK v6; migrate local AI SDK code separately from Geistdocs route adapters.
84
93
  - Import source-config helpers from `@vercel/geistdocs/source-config` in `source.config.ts`. Do not import runtime component entry points from source config.
85
94
  - Move existing `middleware.ts` behavior into `createProxy({ before })` or `createProxy({ after })` hooks.
86
95
  - Delete `public/llms.txt` when using `createLlmsRoute`; otherwise the static file can mask the App Router route.
87
96
  - Set `openGraph.images` in `createDocsPage` only when the app includes the Geistdocs OG route, or override metadata to avoid broken `/og/...` URLs.
88
- - Add Tailwind CSS v4 `@source` entries for `@vercel/geistdocs` and related runtime dependencies when migrating styles.
97
+ - Keep `@vercel/geistcn`, `@vercel/geist-test-utils`, and `@vercel/next-themes` in `transpilePackages`, and keep the Geistcn `modularizeImports` mappings from the bundled template.
98
+ - Apply `geistFontClasses`, `tailwind`, and `tailwind-preflight` to the root `<html>` element.
99
+ - Import the Geistcn Tailwind, base, and marketing typography styles in the template's order, keep `@vercel/geistdocs/theme.css`, and add only the narrow `@vercel/geistcn/src/components/**/*.{ts,tsx}` source scan.
89
100
  - Add local fallbacks for production-only environment variables so migration builds do not require production secrets.
90
101
 
91
102
  ## Package updates
92
103
 
93
104
  - Use `pnpm exec geistdocs update` to update package-based Geistdocs projects.
94
105
  - `geistdocs update` updates the `@vercel/geistdocs` dependency. It does not overwrite local adapter files.
106
+ - On a canary project, `geistdocs update` follows the current `canary` dist-tag. Check and test that version before updating an active migration.
95
107
  - Review dependency changes and run the verification commands before committing an update.
96
108
 
97
109
  ## Commands
@@ -102,10 +114,12 @@ Use these instructions when an AI coding agent edits this project.
102
114
  - Regenerate Fumadocs output after dependency installation: `pnpm postinstall`
103
115
  - Update Geistdocs: `pnpm exec geistdocs update`
104
116
  - Run translations if configured: `pnpm translate`
117
+ - Sync the Mixedbread Store outside production when explicitly needed: `pnpm exec geistdocs search sync --allow-non-production`
105
118
 
106
119
  ## Verification
107
120
 
108
121
  - Run `pnpm build` after changing routes, config, source setup, MDX components, or package versions.
109
122
  - Run `pnpm dev` and open the changed pages when visual layout, navigation, or MDX rendering changes.
110
123
  - Check both `/docs` and AI-readable routes such as `/agents.md`, `/.well-known/mcp.json`, `/llms.txt`, or a page-level `.md` URL when changing content routing or proxy behavior.
124
+ - Confirm `/api/search/export` is statically generated after changing Mixedbread retrieval or source configuration.
111
125
  - Confirm no secrets were added to source files. Use `.env.local` for local values and keep it out of Git.
@@ -0,0 +1,8 @@
1
+ import { createSearchExportRoute } from "@vercel/geistdocs/routes/search-export";
2
+ import { config } from "@/lib/geistdocs/config";
3
+ import { geistdocsSource } from "@/lib/geistdocs/source";
4
+
5
+ export const { GET } = createSearchExportRoute({
6
+ config,
7
+ sources: [geistdocsSource],
8
+ });
@@ -8,6 +8,7 @@ prerequisites:
8
8
  related:
9
9
  - /docs/open-in-chat
10
10
  - /docs/llms-txt
11
+ - /docs/mixedbread-retrieval
11
12
  - /docs/configuration
12
13
  ---
13
14
 
@@ -172,6 +173,8 @@ By default, the AI assistant includes a built-in `search_docs` tool that:
172
173
 
173
174
  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.
174
175
 
176
+ 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.
177
+
175
178
  ### Persistent Chat History
176
179
 
177
180
  Conversations are automatically saved to the browser's IndexedDB, providing:
@@ -114,6 +114,7 @@ On desktop, the group opens as a full-width panel below the navbar, following th
114
114
  import { defineConfig } from "@vercel/geistdocs/config";
115
115
  import {
116
116
  agent,
117
+ ai,
117
118
  basePath,
118
119
  github,
119
120
  Logo,
@@ -138,6 +139,7 @@ export const config = defineConfig({
138
139
  ai: {
139
140
  prompt,
140
141
  suggestions,
142
+ ...ai,
141
143
  },
142
144
  });
143
145
  ```
@@ -168,15 +170,16 @@ export const config = defineConfig({
168
170
  });
169
171
  ```
170
172
 
171
- The `ai` config also accepts `eveAgent` to answer Ask AI requests with a hosted eve framework agent:
173
+ The `ai` config accepts `retrieval: "mixedbread"` to use semantic documentation retrieval and `eveAgent` to answer Ask AI requests with a hosted eve framework agent:
172
174
 
173
175
  ```tsx title="geistdocs.tsx"
174
176
  export const ai = {
177
+ retrieval: "mixedbread",
175
178
  eveAgent: { url: "https://help-eve.example.dev" },
176
179
  };
177
180
  ```
178
181
 
179
- See [Ask AI](/docs/ask-ai) for the full eve agent mode behavior, including authentication.
182
+ 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.
180
183
 
181
184
  Use [Versioned docs](/docs/versioned-docs) for versioned source setup and [Proxy and markdown routes](/docs/proxy) for route mappings.
182
185
 
@@ -2,7 +2,7 @@
2
2
  title: Deploy to Vercel
3
3
  description: Learn how to deploy your Geistdocs site to Vercel
4
4
  type: guide
5
- summary: Deploy your Geistdocs site to Vercel from the dashboard with the correct project settings.
5
+ summary: Deploy a Geistdocs site to Vercel with the required project settings, environment variables, and private-package access.
6
6
  prerequisites:
7
7
  - /docs/getting-started
8
8
  - /docs/env
@@ -10,10 +10,10 @@ related:
10
10
  - /docs/configuration
11
11
  ---
12
12
 
13
- 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.
13
+ Deploy a Geistdocs site to Vercel as a Next.js app. Configure package access, environment variables, and the production URL before shipping.
14
14
 
15
- <CopyPrompt text="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.">
16
- 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.
15
+ <CopyPrompt text="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.">
16
+ 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.
17
17
  </CopyPrompt>
18
18
 
19
19
  ## Prerequisites
@@ -24,6 +24,31 @@ Before deploying, you need:
24
24
  - A [Vercel account](https://vercel.com) (sign up at [vercel.com](https://vercel.com))
25
25
  - Your Vercel account connected to your GitHub account
26
26
  - Environment variables ready (see [Environment Variables](/docs/env))
27
+ - Access to restricted `@vercel` npm packages if the project uses the Geistcn canary
28
+
29
+ ## Configure private package access
30
+
31
+ The Geistcn canary depends on restricted `@vercel/geistcn` and `@vercel/geistcn-assets` packages. Package installation fails without npm authentication.
32
+
33
+ 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.
34
+
35
+ 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:
36
+
37
+ ```yaml title=".github/workflows/check.yml"
38
+ - uses: pnpm/action-setup@v4
39
+
40
+ - uses: actions/setup-node@v4
41
+ with:
42
+ node-version: 20
43
+ cache: pnpm
44
+ registry-url: https://registry.npmjs.org
45
+
46
+ - run: pnpm install
47
+ env:
48
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
49
+ ```
50
+
51
+ 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.
27
52
 
28
53
  ## Deploy to Vercel
29
54
 
@@ -33,9 +58,9 @@ To deploy from the Vercel dashboard:
33
58
  2. Select your Geistdocs repository
34
59
  3. Configure your project settings:
35
60
  - **Framework Preset**: Next.js (automatically detected)
36
- - **Build Command**: `pnpm build` or `npm run build`
61
+ - **Build Command**: `pnpm build`
37
62
  - **Output Directory**: `.next` (default)
38
- - **Install Command**: `pnpm install` or `npm install`
63
+ - **Install Command**: `pnpm install`
39
64
  4. Add your environment variables (see [Environment Variables](/docs/env))
40
65
  5. Click "Deploy"
41
66
 
@@ -2,7 +2,7 @@
2
2
  title: Environment Variables
3
3
  description: Learn about the environment variables used in Geistdocs
4
4
  type: reference
5
- summary: Environment variables required by Geistdocs for AI chat, proxy mode, and production URL configuration.
5
+ summary: Environment variables required by Geistdocs for AI chat, Mixedbread retrieval, proxy mode, and production URL configuration.
6
6
  prerequisites:
7
7
  - /docs/getting-started
8
8
  related:
@@ -10,10 +10,10 @@ related:
10
10
  - /docs/deployment
11
11
  ---
12
12
 
13
- Geistdocs uses environment variables to configure Ask AI, optional Vertex-backed proxy mode, and production URL behavior.
13
+ Geistdocs uses environment variables to configure Ask AI, optional Mixedbread retrieval, optional Vertex-backed proxy mode, and production URL behavior.
14
14
 
15
- <CopyPrompt text="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.">
16
- 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.
15
+ <CopyPrompt text="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.">
16
+ 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.
17
17
  </CopyPrompt>
18
18
 
19
19
  ## `AI_GATEWAY_API_KEY`
@@ -24,6 +24,16 @@ The API key for the AI Gateway. This is used to power the default local AI chat
24
24
 
25
25
  Leave `GEISTDOCS_CHAT_PROXY_URL` unset to use AI Gateway mode.
26
26
 
27
+ ## `MXBAI_API_KEY`
28
+
29
+ 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.
30
+
31
+ ## `MXBAI_STORE_ID`
32
+
33
+ The Mixedbread Store used by one consumer site. Set `ai.retrieval` to `"mixedbread"` and configure a unique `siteId` before using this value.
34
+
35
+ 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.
36
+
27
37
  ## `GEISTDOCS_CHAT_PROXY_URL`
28
38
 
29
39
  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.
@@ -12,37 +12,57 @@ related:
12
12
 
13
13
  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.
14
14
 
15
- <CopyPrompt text="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.">
16
- 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`.
15
+ <CopyPrompt text="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.">
16
+ 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`.
17
17
  </CopyPrompt>
18
18
 
19
19
  ## Prerequisites
20
20
 
21
21
  Before you begin, install:
22
22
 
23
- - Node.js 18 or later
24
- - pnpm, npm, or another package manager
23
+ - Node.js 20.9 or later
24
+ - pnpm
25
25
  - Git
26
26
 
27
+ The Geistdocs CLI always uses pnpm to install the generated project's dependencies. Running the CLI through `npx` does not remove the pnpm requirement.
28
+
29
+ ## Choose a release channel
30
+
31
+ 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.
32
+
33
+ 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`.
34
+
35
+ ## Authenticate for the Geistcn canary
36
+
37
+ 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`:
38
+
39
+ ```ini title="~/.npmrc"
40
+ @vercel:registry=https://registry.npmjs.org/
41
+ //registry.npmjs.org/:_authToken=${NPM_TOKEN}
42
+ always-auth=true
43
+ ```
44
+
45
+ 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.
46
+
27
47
  ## Create a project
28
48
 
29
- Run the Geistdocs CLI from an empty parent folder:
49
+ Run the Geistdocs CLI from an empty parent folder. For stable Geistdocs, run:
30
50
 
31
51
  ```bash title="Terminal"
32
- pnpm dlx @vercel/geistdocs init --name my-docs
52
+ pnpm dlx @vercel/geistdocs@latest init --name my-docs
33
53
  ```
34
54
 
35
- You can also use npm:
55
+ For the Geistcn canary, run:
36
56
 
37
57
  ```bash title="Terminal"
38
- npx @vercel/geistdocs init --name my-docs
58
+ pnpm dlx @vercel/geistdocs@canary init --name my-docs
39
59
  ```
40
60
 
41
61
  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.
42
62
 
43
63
  ## Understand generated dependencies
44
64
 
45
- 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.
65
+ 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.
46
66
 
47
67
  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.
48
68
 
@@ -107,7 +127,7 @@ Read [Configuration](/docs/configuration) for the full configuration surface.
107
127
 
108
128
  ## Update Geistdocs
109
129
 
110
- For package-based projects, `geistdocs update` updates the `@vercel/geistdocs` package version. It does not overwrite your local content or adapter files.
130
+ 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`.
111
131
 
112
132
  ```bash title="Terminal"
113
133
  pnpm exec geistdocs update
@@ -26,7 +26,7 @@ Geistdocs has three main parts:
26
26
  ```mermaid
27
27
  flowchart TB
28
28
  subgraph Package["@vercel/geistdocs package"]
29
- cli["CLI: init, update, translate"]
29
+ cli["CLI: init, update, translate, search sync"]
30
30
  runtime["Runtime: layout, routes, MDX, controls"]
31
31
  bundledTemplate["Bundled template snapshot"]
32
32
  end
@@ -76,6 +76,7 @@ Advanced projects can use package APIs for versioned docs, multiple content sour
76
76
  - MDX documentation with custom components
77
77
  - Local content in `content/docs`
78
78
  - Search and Ask AI
79
+ - Optional Mixedbread semantic retrieval for Ask AI
79
80
  - Page actions, including feedback, copy page, open in chat, and edit on GitHub
80
81
  - Agent-readiness metadata with `/agents.md` and `/.well-known/mcp.json`
81
82
  - Raw Markdown routes for AI tools
@@ -85,7 +86,7 @@ Advanced projects can use package APIs for versioned docs, multiple content sour
85
86
  - RSS feed
86
87
  - Theme-aware images
87
88
  - Internationalized routes
88
- - CLI commands for init, update, and translation
89
+ - CLI commands for init, update, translation, and Mixedbread search sync
89
90
 
90
91
  ## Next steps
91
92
 
@@ -37,7 +37,7 @@ The `.mdx` version returns:
37
37
 
38
38
  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`.
39
39
 
40
- 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.
40
+ 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.
41
41
 
42
42
  ## Use cases
43
43
 
@@ -21,6 +21,7 @@
21
21
  "open-in-chat",
22
22
  "agent-readiness",
23
23
  "llms-txt",
24
+ "mixedbread-retrieval",
24
25
  "ask-ai"
25
26
  ]
26
27
  }