@vercel/geistdocs 1.14.1 → 1.15.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 (37) hide show
  1. package/dist/cli/index.js +1 -1
  2. package/dist/config.d.ts +16 -0
  3. package/dist/config.d.ts.map +1 -1
  4. package/dist/internal/chat/message-metadata.d.ts.map +1 -1
  5. package/dist/internal/chat/message-metadata.js +17 -2
  6. package/dist/internal/chat/shell.d.ts.map +1 -1
  7. package/dist/internal/chat/shell.js +3 -3
  8. package/dist/internal/cn.d.ts.map +1 -1
  9. package/dist/internal/cn.js +45 -1
  10. package/dist/internal/eve-agent.d.ts +76 -0
  11. package/dist/internal/eve-agent.d.ts.map +1 -0
  12. package/dist/internal/eve-agent.js +541 -0
  13. package/dist/internal/last-modified.d.ts +6 -0
  14. package/dist/internal/last-modified.d.ts.map +1 -0
  15. package/dist/internal/last-modified.js +32 -0
  16. package/dist/internal/page-actions-client.js +1 -1
  17. package/dist/internal/sidebar.js +5 -5
  18. package/dist/internal/ui/drawer.d.ts +2 -0
  19. package/dist/internal/ui/drawer.d.ts.map +1 -1
  20. package/dist/internal/ui/drawer.js +6 -0
  21. package/dist/pages/docs.js +2 -2
  22. package/dist/routes/chat.d.ts +20 -3
  23. package/dist/routes/chat.d.ts.map +1 -1
  24. package/dist/routes/chat.js +95 -1
  25. package/dist/source-config.d.ts.map +1 -1
  26. package/dist/source-config.js +5 -1
  27. package/docs/agents.md +1 -1
  28. package/docs/llms.txt +46 -2
  29. package/docs/manifest.json +1 -1
  30. package/docs/pages/ask-ai.md +35 -1
  31. package/docs/pages/configuration.md +10 -0
  32. package/package.json +2 -1
  33. package/template/AGENTS.md +2 -1
  34. package/template/content/docs/ask-ai.mdx +35 -1
  35. package/template/content/docs/configuration.mdx +10 -0
  36. package/template/package.json +1 -1
  37. package/theme.css +35 -15
@@ -19,7 +19,7 @@ export const resolvePageMarkdownUrl = ({ basePath, pageUrl, isRootMountedPage =
19
19
  }
20
20
  return `${normalizedPublicPageUrl}.md`;
21
21
  };
22
- const DocsTitle = ({ className, ...props }) => (_jsx(FumadocsDocsTitle, { className: cn("mb-4 text-balance text-4xl tracking-tight", className), ...props }));
22
+ const DocsTitle = ({ className, ...props }) => (_jsx(FumadocsDocsTitle, { className: cn("mb-4 text-balance", className), ...props }));
23
23
  const DocsDescription = (props) => _jsx(FumadocsDocsDescription, { ...props });
24
24
  const DocsBody = ({ className, ...props }) => (_jsx(FumadocsDocsBody, { className: cn("mx-auto w-full", className), ...props }));
25
25
  const hasTableOfContentsActions = (config, extraActions) => config.pageActions?.scrollTop !== false ||
@@ -107,7 +107,7 @@ export const createDocsPage = ({ config, source, mdx, pageActions = createIntern
107
107
  page,
108
108
  pageUrl,
109
109
  publicPageUrl,
110
- }), _jsxs("div", { className: "flex flex-col-reverse gap-4 sm:flex-row sm:items-end sm:justify-between", children: [_jsx(DocsTitle, { className: "mb-0 min-w-0", children: data.title }), _jsx(GeistdocsPageActions, { config: pageActions.config, page: {
110
+ }), _jsxs("div", { className: "flex flex-col-reverse gap-4 md:flex-row md:items-end md:justify-between", children: [_jsx(DocsTitle, { className: "mb-0 min-w-0", children: data.title }), _jsx(GeistdocsPageActions, { config: pageActions.config, page: {
111
111
  markdownUrl,
112
112
  path: page.path,
113
113
  url: publicPageUrl,
@@ -6,20 +6,37 @@ interface ChatProxyConfig {
6
6
  headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
7
7
  url: string;
8
8
  }
9
+ interface ChatEveAgentOptions {
10
+ /**
11
+ * Extra headers for requests to the eve agent, replacing the default
12
+ * `Authorization: Bearer <Vercel OIDC token>` when an `authorization`
13
+ * header is provided. Accepts an async function for per-request tokens.
14
+ * Server-only: never expose auth material through `geistdocs.tsx`.
15
+ */
16
+ headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
17
+ /** Overrides `config.ai.eveAgent.url` (e.g. for a staging agent). */
18
+ url?: string;
19
+ }
9
20
  interface CreateChatRouteOptions {
10
21
  config: Pick<GeistdocsConfig, "ai" | "basePath" | "defaultLanguage" | "translations">;
22
+ /**
23
+ * Server-side options for the eve agent responder configured through
24
+ * `config.ai.eveAgent`. Mutually exclusive with `proxy`.
25
+ */
26
+ eveAgent?: ChatEveAgentOptions;
11
27
  /**
12
28
  * Model used to answer Ask AI requests in the default AI Gateway mode.
13
29
  * Accepts any AI SDK `LanguageModel`, including AI Gateway model strings
14
- * such as `"xai/grok-4.5"`. Ignored in proxy mode, where the Vertex-backed
15
- * service selects the model. Defaults to `"openai/gpt-4.1-mini"`.
30
+ * such as `"xai/grok-4.5"`. Ignored in proxy and eve agent modes, where
31
+ * the external service selects the model. Defaults to
32
+ * `"openai/gpt-4.1-mini"`.
16
33
  */
17
34
  model?: LanguageModel;
18
35
  proxy?: ChatProxyConfig;
19
36
  source?: SourceBundle;
20
37
  sources?: SourceBundle[];
21
38
  }
22
- export declare const createChatRoute: ({ config, model, proxy, source, sources, }: CreateChatRouteOptions) => {
39
+ export declare const createChatRoute: ({ config, eveAgent, model, proxy, source, sources, }: CreateChatRouteOptions) => {
23
40
  POST: (req: Request) => Promise<Response>;
24
41
  maxDuration: 800;
25
42
  };
@@ -1 +1 @@
1
- {"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../../src/routes/chat.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,aAAa,EAQnB,MAAM,IAAI,CAAC;AAGZ,OAAO,EAAE,KAAK,eAAe,EAAiB,MAAM,WAAW,CAAC;AAEhE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAEvD,KAAK,YAAY,GAAG,qBAAqB,CAAC;AAyB1C,UAAU,eAAe;IACvB,OAAO,CAAC,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;IACnE,GAAG,EAAE,MAAM,CAAC;CACb;AAED,UAAU,sBAAsB;IAC9B,MAAM,EAAE,IAAI,CACV,eAAe,EACf,IAAI,GAAG,UAAU,GAAG,iBAAiB,GAAG,cAAc,CACvD,CAAC;IACF;;;;;OAKG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;CAC1B;AAqrBD,eAAO,MAAM,eAAe,GAAI,4CAM7B,sBAAsB;gBAIE,OAAO;;CA0IjC,CAAC"}
1
+ {"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../../src/routes/chat.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,aAAa,EAQnB,MAAM,IAAI,CAAC;AAGZ,OAAO,EAAE,KAAK,eAAe,EAAiB,MAAM,WAAW,CAAC;AAShE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAEvD,KAAK,YAAY,GAAG,qBAAqB,CAAC;AAyB1C,UAAU,eAAe;IACvB,OAAO,CAAC,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;IACnE,GAAG,EAAE,MAAM,CAAC;CACb;AAED,UAAU,mBAAmB;IAC3B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;IACnE,qEAAqE;IACrE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,UAAU,sBAAsB;IAC9B,MAAM,EAAE,IAAI,CACV,eAAe,EACf,IAAI,GAAG,UAAU,GAAG,iBAAiB,GAAG,cAAc,CACvD,CAAC;IACF;;;OAGG;IACH,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;CAC1B;AAozBD,eAAO,MAAM,eAAe,GAAI,sDAO7B,sBAAsB;gBASE,OAAO;;CA0JjC,CAAC"}
@@ -1,10 +1,13 @@
1
+ import { getVercelOidcToken } from "@vercel/oidc";
1
2
  import { convertToModelMessages, createUIMessageStream, createUIMessageStreamResponse, stepCountIs, streamText, tool, } from "ai";
2
3
  import { initAdvancedSearch } from "fumadocs-core/search/server";
3
4
  import { z } from "zod";
4
5
  import { getPublicPath } from "../config";
6
+ import { buildEveAgentTranscript, capLastUserMessageText, getEveAgentSessionHandle, resolveEveAgentUrl, runEveAgentTurn, } from "../internal/eve-agent";
5
7
  import { isPageVisibleForSurface } from "../internal/page-visibility";
6
8
  const DEFAULT_CHAT_MODEL = "openai/gpt-4.1-mini";
7
9
  const MAX_CONTEXT_CHARS = 1500;
10
+ const MAX_EVE_AGENT_MESSAGE_CHARS = 4000;
8
11
  const MAX_PROXY_RELATED_PAGES = 5;
9
12
  const MAX_TOOL_RESULTS = 8;
10
13
  const TRAILING_SLASH_PATTERN = /\/$/;
@@ -253,6 +256,29 @@ const getProxyRequestHeaders = async ({ proxy, req, }) => {
253
256
  }
254
257
  return headers;
255
258
  };
259
+ const getEveAgentRequestHeaders = async ({ eveAgent, req, }) => {
260
+ const headers = new Headers(await resolveProxyHeaders(eveAgent?.headers));
261
+ const clientJa4 = req.headers.get("x-vercel-ja4-digest");
262
+ const clientIp = req.headers.get("x-forwarded-for");
263
+ headers.set("Content-Type", "application/json");
264
+ if (clientJa4 && !headers.has("x-client-ja4")) {
265
+ headers.set("x-client-ja4", clientJa4);
266
+ }
267
+ if (clientIp && !headers.has("x-client-ip")) {
268
+ headers.set("x-client-ip", clientIp);
269
+ }
270
+ if (!headers.has("authorization")) {
271
+ try {
272
+ const token = await getVercelOidcToken();
273
+ headers.set("authorization", `Bearer ${token}`);
274
+ }
275
+ catch {
276
+ // Not running on Vercel and no OIDC token available. The request
277
+ // proceeds unauthenticated; the agent's own auth policy decides.
278
+ }
279
+ }
280
+ return headers;
281
+ };
256
282
  const parseSseChunk = (event) => {
257
283
  const data = event
258
284
  .split("\n")
@@ -439,6 +465,54 @@ const createTools = (writer, sources, defaultLanguage, basePath) => {
439
465
  search_docs,
440
466
  };
441
467
  };
468
+ const createChatErrorResponse = (error, status) => new Response(JSON.stringify({ error }), {
469
+ status,
470
+ headers: { "Content-Type": "application/json" },
471
+ });
472
+ const createEveAgentResponse = async ({ actualMessages, agentUrl, config, currentRoute, defaultLanguage, eveAgent, languages, messages, pageContext, req, routeSources, }) => {
473
+ const cappedMessages = capLastUserMessageText(actualMessages, MAX_EVE_AGENT_MESSAGE_CHARS);
474
+ const { messages: contextMessages, sourceDocs } = await buildProxyMessages({
475
+ actualMessages: cappedMessages,
476
+ config,
477
+ currentRoute,
478
+ defaultLanguage,
479
+ languages,
480
+ pageContext,
481
+ routeSources,
482
+ });
483
+ const lastMessage = contextMessages.at(-1);
484
+ if (lastMessage?.role !== "user") {
485
+ return createChatErrorResponse("Invalid chat request: expected a user message.", 400);
486
+ }
487
+ const lastMessageText = getMessageText(lastMessage);
488
+ const handle = getEveAgentSessionHandle(cappedMessages);
489
+ // A fresh eve session (no handle, or the handle turned out to be
490
+ // unusable) receives the prior turns inlined so it still sees the
491
+ // conversation so far.
492
+ const transcriptMessage = buildEveAgentTranscript(contextMessages, lastMessageText);
493
+ const outboundMessage = handle ? lastMessageText : transcriptMessage;
494
+ if (!outboundMessage.trim()) {
495
+ return createChatErrorResponse("Invalid chat request: message must not be empty.", 400);
496
+ }
497
+ const headers = await getEveAgentRequestHeaders({ eveAgent, req });
498
+ const stream = createUIMessageStream({
499
+ originalMessages: messages,
500
+ onError: () => "Something went wrong with your query.",
501
+ execute: async ({ writer }) => {
502
+ await runEveAgentTurn({
503
+ agentUrl,
504
+ fallbackMessage: transcriptMessage,
505
+ handle,
506
+ headers,
507
+ initialChunks: createSourceChunks(sourceDocs),
508
+ message: outboundMessage,
509
+ signal: req.signal,
510
+ writer,
511
+ });
512
+ },
513
+ });
514
+ return createUIMessageStreamResponse({ stream });
515
+ };
442
516
  const resolveSources = (source, sources) => {
443
517
  const resolvedSources = sources ?? (source ? [source] : []);
444
518
  if (resolvedSources.length === 0) {
@@ -446,9 +520,14 @@ const resolveSources = (source, sources) => {
446
520
  }
447
521
  return resolvedSources;
448
522
  };
449
- export const createChatRoute = ({ config, model = DEFAULT_CHAT_MODEL, proxy, source, sources, }) => {
523
+ export const createChatRoute = ({ config, eveAgent, model = DEFAULT_CHAT_MODEL, proxy, source, sources, }) => {
450
524
  const { defaultLanguage, languages } = getLanguages(config);
451
525
  const routeSources = resolveSources(source, sources);
526
+ const eveAgentUrl = resolveEveAgentUrl({
527
+ configUrl: config.ai?.eveAgent?.url,
528
+ hasProxy: Boolean(proxy),
529
+ optionUrl: eveAgent?.url,
530
+ });
452
531
  const POST = async (req) => {
453
532
  try {
454
533
  const requestBody = await req.json();
@@ -462,6 +541,21 @@ export const createChatRoute = ({ config, model = DEFAULT_CHAT_MODEL, proxy, sou
462
541
  }
463
542
  const { messages, currentRoute, pageContext } = requestBody;
464
543
  const actualMessages = messages.filter((message) => !isPageContextMessage(message));
544
+ if (eveAgentUrl) {
545
+ return await createEveAgentResponse({
546
+ actualMessages,
547
+ agentUrl: eveAgentUrl,
548
+ config,
549
+ currentRoute,
550
+ defaultLanguage,
551
+ eveAgent,
552
+ languages,
553
+ messages,
554
+ pageContext,
555
+ req,
556
+ routeSources,
557
+ });
558
+ }
465
559
  if (proxy) {
466
560
  const { messages: proxyMessages, sourceDocs } = await buildProxyMessages({
467
561
  actualMessages,
@@ -1 +1 @@
1
- {"version":3,"file":"source-config.d.ts","sourceRoot":"","sources":["../src/source-config.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,iBAAiB,EACtB,YAAY,IAAI,oBAAoB,EAGrC,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,KAAK,mBAAmB,GAAG,WAAW,CACpC,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAC3C,CAAC;AAEF,MAAM,WAAW,4BAA4B;IAC3C,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,OAAO,CAAC,EAAE,mBAAmB,CAAC,SAAS,CAAC,CAAC;CAC1C;AAED,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;CAsG3B,CAAC;AAEF,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsCrC,CAAC;AAEH,eAAO,MAAM,mBAAmB;;;;;;;iBAAa,CAAC;AAE9C,eAAO,MAAM,2BAA2B,GACtC,SAAQ,4BAAiC,+CAoB1C,CAAC"}
1
+ {"version":3,"file":"source-config.d.ts","sourceRoot":"","sources":["../src/source-config.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,iBAAiB,EACtB,YAAY,IAAI,oBAAoB,EAGrC,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,KAAK,mBAAmB,GAAG,WAAW,CACpC,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAC3C,CAAC;AAEF,MAAM,WAAW,4BAA4B;IAC3C,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,OAAO,CAAC,EAAE,mBAAmB,CAAC,SAAS,CAAC,CAAC;CAC1C;AAED,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;CAsG3B,CAAC;AAEF,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsCrC,CAAC;AAEH,eAAO,MAAM,mBAAmB;;;;;;;iBAAa,CAAC;AAE9C,eAAO,MAAM,2BAA2B,GACtC,SAAQ,4BAAiC,+CAuB1C,CAAC"}
@@ -2,6 +2,7 @@ import { remarkMdxMermaid } from "fumadocs-core/mdx-plugins";
2
2
  import { defineConfig as defineFumadocsConfig, frontmatterSchema, metaSchema, } from "fumadocs-mdx/config";
3
3
  import lastModified from "fumadocs-mdx/plugins/last-modified";
4
4
  import { z } from "zod";
5
+ import { getGitLastModified } from "./internal/last-modified.js";
5
6
  export const geistShikiTheme = {
6
7
  name: "geist",
7
8
  type: "dark",
@@ -157,6 +158,9 @@ export const defineGeistdocsSourceConfig = (config = {}) => {
157
158
  defaultColor: "light",
158
159
  },
159
160
  },
160
- plugins: [lastModified(), ...existingPlugins],
161
+ plugins: [
162
+ lastModified({ versionControl: getGitLastModified }),
163
+ ...existingPlugins,
164
+ ],
161
165
  });
162
166
  };
package/docs/agents.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Geistdocs Package Docs
2
2
 
3
- These docs are bundled with `@vercel/geistdocs` 1.14.1 so agents can understand the installed package without web access.
3
+ These docs are bundled with `@vercel/geistdocs` 1.15.0 so agents can understand the installed package without web access.
4
4
  They are generated from `apps/template/content/docs` during the package build.
5
5
 
6
6
  ## How to use these files
package/docs/llms.txt CHANGED
@@ -1,6 +1,6 @@
1
1
  # Geistdocs Package Documentation
2
2
 
3
- These docs are bundled with `@vercel/geistdocs` 1.14.1.
3
+ These docs are bundled with `@vercel/geistdocs` 1.15.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
@@ -910,6 +910,16 @@ export const config = defineConfig({
910
910
  });
911
911
  ```
912
912
 
913
+ The `ai` config also accepts `eveAgent` to answer Ask AI requests with a hosted eve framework agent:
914
+
915
+ ```tsx title="geistdocs.tsx"
916
+ export const ai = {
917
+ eveAgent: { url: "https://help-eve.example.dev" },
918
+ };
919
+ ```
920
+
921
+ See [Ask AI](/docs/ask-ai) for the full eve agent mode behavior, including authentication.
922
+
913
923
  Use [Versioned docs](/docs/versioned-docs) for versioned source setup and [Proxy and markdown routes](/docs/proxy) for route mappings.
914
924
 
915
925
  ## `source.config.ts`
@@ -2401,7 +2411,7 @@ prepareSendMessagesRequest: ({ body, messages }) => ({
2401
2411
 
2402
2412
  ## Choose an AI mode
2403
2413
 
2404
- Ask AI can run in the default AI Gateway mode or through a Vertex-backed proxy.
2414
+ Ask AI can run in the default AI Gateway mode, through a Vertex-backed proxy, or answered by a hosted eve framework agent.
2405
2415
 
2406
2416
  ### Default AI Gateway mode
2407
2417
 
@@ -2449,6 +2459,40 @@ When `GEISTDOCS_CHAT_PROXY_URL` is set, Geistdocs searches local docs on the fir
2449
2459
 
2450
2460
  The platform proxy forwards a Vercel OIDC token to Vertex in the `x-vercel-trusted-oidc-idp-token` header. The Vertex deployment should validate the caller through Trusted Sources; the Geistdocs site does not need a Vertex API key.
2451
2461
 
2462
+ ### Hosted eve agent mode
2463
+
2464
+ Use eve agent mode when a hosted [eve framework](https://eve.dev) agent should answer Ask AI requests. Configure it with a single field in `geistdocs.tsx`:
2465
+
2466
+ ```tsx title="geistdocs.tsx"
2467
+ export const ai = {
2468
+ eveAgent: { url: "https://help-eve.example.dev" },
2469
+ };
2470
+ ```
2471
+
2472
+ 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.
2473
+
2474
+ Eve agent mode keeps the platform-owned behavior from proxy mode:
2475
+
2476
+ - Local docs retrieval runs on the first user message, and the current page plus related docs are inlined into the message the agent receives.
2477
+ - Locally computed source citations are injected into the response stream, and `excludeFrom: [chat]` page visibility is enforced before anything reaches the agent.
2478
+ - The agent's reasoning shows as a "Thinking..." indicator, its tool calls show as activity labels, and stopping a response cancels the in-flight eve turn.
2479
+
2480
+ **Authentication.** Requests carry a Vercel OIDC bearer token minted per request. Eve's default channel auth (`vercelOidc()`) accepts deployments from the same Vercel team out of the box; cross-team agents can allow the site with `vercelSubject`. For agents with custom auth, pass server-only headers through the `eveAgent` option:
2481
+
2482
+ ```ts title="app/api/chat/route.ts"
2483
+ export const { POST, maxDuration } = createChatRoute({
2484
+ config,
2485
+ sources: [geistdocsSource],
2486
+ eveAgent: {
2487
+ headers: async () => ({ authorization: `Bearer ${await mintToken()}` }),
2488
+ },
2489
+ });
2490
+ ```
2491
+
2492
+ Never put authentication material in `geistdocs.tsx` — the config ships to the client bundle. The agent URL is public configuration; tokens are not.
2493
+
2494
+ The `eveAgent` option also accepts a `url` override for pointing staging deployments at a different agent. Configuring both `proxy` and an eve agent throws at route creation.
2495
+
2452
2496
  ## Features
2453
2497
 
2454
2498
  ### Context-Aware Search
@@ -199,5 +199,5 @@
199
199
  }
200
200
  ],
201
201
  "source": "apps/template/content/docs",
202
- "version": "1.14.1"
202
+ "version": "1.15.0"
203
203
  }
@@ -65,7 +65,7 @@ prepareSendMessagesRequest: ({ body, messages }) => ({
65
65
 
66
66
  ## Choose an AI mode
67
67
 
68
- Ask AI can run in the default AI Gateway mode or through a Vertex-backed proxy.
68
+ Ask AI can run in the default AI Gateway mode, through a Vertex-backed proxy, or answered by a hosted eve framework agent.
69
69
 
70
70
  ### Default AI Gateway mode
71
71
 
@@ -113,6 +113,40 @@ When `GEISTDOCS_CHAT_PROXY_URL` is set, Geistdocs searches local docs on the fir
113
113
 
114
114
  The platform proxy forwards a Vercel OIDC token to Vertex in the `x-vercel-trusted-oidc-idp-token` header. The Vertex deployment should validate the caller through Trusted Sources; the Geistdocs site does not need a Vertex API key.
115
115
 
116
+ ### Hosted eve agent mode
117
+
118
+ Use eve agent mode when a hosted [eve framework](https://eve.dev) agent should answer Ask AI requests. Configure it with a single field in `geistdocs.tsx`:
119
+
120
+ ```tsx title="geistdocs.tsx"
121
+ export const ai = {
122
+ eveAgent: { url: "https://help-eve.example.dev" },
123
+ };
124
+ ```
125
+
126
+ 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.
127
+
128
+ Eve agent mode keeps the platform-owned behavior from proxy mode:
129
+
130
+ - Local docs retrieval runs on the first user message, and the current page plus related docs are inlined into the message the agent receives.
131
+ - Locally computed source citations are injected into the response stream, and `excludeFrom: [chat]` page visibility is enforced before anything reaches the agent.
132
+ - The agent's reasoning shows as a "Thinking..." indicator, its tool calls show as activity labels, and stopping a response cancels the in-flight eve turn.
133
+
134
+ **Authentication.** Requests carry a Vercel OIDC bearer token minted per request. Eve's default channel auth (`vercelOidc()`) accepts deployments from the same Vercel team out of the box; cross-team agents can allow the site with `vercelSubject`. For agents with custom auth, pass server-only headers through the `eveAgent` option:
135
+
136
+ ```ts title="app/api/chat/route.ts"
137
+ export const { POST, maxDuration } = createChatRoute({
138
+ config,
139
+ sources: [geistdocsSource],
140
+ eveAgent: {
141
+ headers: async () => ({ authorization: `Bearer ${await mintToken()}` }),
142
+ },
143
+ });
144
+ ```
145
+
146
+ Never put authentication material in `geistdocs.tsx` — the config ships to the client bundle. The agent URL is public configuration; tokens are not.
147
+
148
+ The `eveAgent` option also accepts a `url` override for pointing staging deployments at a different agent. Configuring both `proxy` and an eve agent throws at route creation.
149
+
116
150
  ## Features
117
151
 
118
152
  ### Context-Aware Search
@@ -147,6 +147,16 @@ export const config = defineConfig({
147
147
  });
148
148
  ```
149
149
 
150
+ The `ai` config also accepts `eveAgent` to answer Ask AI requests with a hosted eve framework agent:
151
+
152
+ ```tsx title="geistdocs.tsx"
153
+ export const ai = {
154
+ eveAgent: { url: "https://help-eve.example.dev" },
155
+ };
156
+ ```
157
+
158
+ See [Ask AI](/docs/ask-ai) for the full eve agent mode behavior, including authentication.
159
+
150
160
  Use [Versioned docs](/docs/versioned-docs) for versioned source setup and [Proxy and markdown routes](/docs/proxy) for route mappings.
151
161
 
152
162
  ## `source.config.ts`
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.14.1",
4
+ "version": "1.15.0",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
7
7
  "type": "git",
@@ -259,6 +259,7 @@
259
259
  "@streamdown/cjk": "^1.0.1",
260
260
  "@streamdown/code": "^1.0.1",
261
261
  "@vercel/agent-readability": "^0.2.1",
262
+ "@vercel/oidc": "^3.4.1",
262
263
  "ai": "^6.0.132",
263
264
  "class-variance-authority": "^0.7.1",
264
265
  "clsx": "^2.1.1",
@@ -61,7 +61,8 @@ Use these instructions when an AI coding agent edits this project.
61
61
 
62
62
  ## Ask AI and Vertex proxy guidelines
63
63
 
64
- - Leave `GEISTDOCS_CHAT_PROXY_URL` unset 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.
64
+ - 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.
65
+ - 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.
65
66
  - 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.
66
67
  - 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.
67
68
  - 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`.
@@ -63,7 +63,7 @@ prepareSendMessagesRequest: ({ body, messages }) => ({
63
63
 
64
64
  ## Choose an AI mode
65
65
 
66
- Ask AI can run in the default AI Gateway mode or through a Vertex-backed proxy.
66
+ Ask AI can run in the default AI Gateway mode, through a Vertex-backed proxy, or answered by a hosted eve framework agent.
67
67
 
68
68
  ### Default AI Gateway mode
69
69
 
@@ -111,6 +111,40 @@ When `GEISTDOCS_CHAT_PROXY_URL` is set, Geistdocs searches local docs on the fir
111
111
 
112
112
  The platform proxy forwards a Vercel OIDC token to Vertex in the `x-vercel-trusted-oidc-idp-token` header. The Vertex deployment should validate the caller through Trusted Sources; the Geistdocs site does not need a Vertex API key.
113
113
 
114
+ ### Hosted eve agent mode
115
+
116
+ Use eve agent mode when a hosted [eve framework](https://eve.dev) agent should answer Ask AI requests. Configure it with a single field in `geistdocs.tsx`:
117
+
118
+ ```tsx title="geistdocs.tsx"
119
+ export const ai = {
120
+ eveAgent: { url: "https://help-eve.example.dev" },
121
+ };
122
+ ```
123
+
124
+ 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.
125
+
126
+ Eve agent mode keeps the platform-owned behavior from proxy mode:
127
+
128
+ - Local docs retrieval runs on the first user message, and the current page plus related docs are inlined into the message the agent receives.
129
+ - Locally computed source citations are injected into the response stream, and `excludeFrom: [chat]` page visibility is enforced before anything reaches the agent.
130
+ - The agent's reasoning shows as a "Thinking..." indicator, its tool calls show as activity labels, and stopping a response cancels the in-flight eve turn.
131
+
132
+ **Authentication.** Requests carry a Vercel OIDC bearer token minted per request. Eve's default channel auth (`vercelOidc()`) accepts deployments from the same Vercel team out of the box; cross-team agents can allow the site with `vercelSubject`. For agents with custom auth, pass server-only headers through the `eveAgent` option:
133
+
134
+ ```ts title="app/api/chat/route.ts"
135
+ export const { POST, maxDuration } = createChatRoute({
136
+ config,
137
+ sources: [geistdocsSource],
138
+ eveAgent: {
139
+ headers: async () => ({ authorization: `Bearer ${await mintToken()}` }),
140
+ },
141
+ });
142
+ ```
143
+
144
+ Never put authentication material in `geistdocs.tsx` — the config ships to the client bundle. The agent URL is public configuration; tokens are not.
145
+
146
+ The `eveAgent` option also accepts a `url` override for pointing staging deployments at a different agent. Configuring both `proxy` and an eve agent throws at route creation.
147
+
114
148
  ## Features
115
149
 
116
150
  ### Context-Aware Search
@@ -145,6 +145,16 @@ export const config = defineConfig({
145
145
  });
146
146
  ```
147
147
 
148
+ The `ai` config also accepts `eveAgent` to answer Ask AI requests with a hosted eve framework agent:
149
+
150
+ ```tsx title="geistdocs.tsx"
151
+ export const ai = {
152
+ eveAgent: { url: "https://help-eve.example.dev" },
153
+ };
154
+ ```
155
+
156
+ See [Ask AI](/docs/ask-ai) for the full eve agent mode behavior, including authentication.
157
+
148
158
  Use [Versioned docs](/docs/versioned-docs) for versioned source setup and [Proxy and markdown routes](/docs/proxy) for route mappings.
149
159
 
150
160
  ## `source.config.ts`
@@ -18,7 +18,7 @@
18
18
  "@streamdown/code": "^1.0.1",
19
19
  "@vercel/agent-readability": "^0.2.1",
20
20
  "@vercel/analytics": "^1.6.1",
21
- "@vercel/geistdocs": "1.14.1",
21
+ "@vercel/geistdocs": "1.15.0",
22
22
  "@vercel/speed-insights": "^1.3.1",
23
23
  "ai": "^6.0.132",
24
24
  "class-variance-authority": "^0.7.1",
package/theme.css CHANGED
@@ -544,43 +544,43 @@
544
544
  /* Typography Heading */
545
545
 
546
546
  @utility text-heading-72 {
547
- @apply font-sans font-semibold text-[72px] leading-[72px] tracking-[-4.32px];
547
+ @apply font-sans font-[450] text-[72px] leading-[72px] tracking-[-4.32px];
548
548
  }
549
549
 
550
550
  @utility text-heading-64 {
551
- @apply font-sans font-semibold text-[64px] leading-[64px] tracking-[-3.84px];
551
+ @apply font-sans font-[450] text-[64px] leading-[64px] tracking-[-3.84px];
552
552
  }
553
553
 
554
554
  @utility text-heading-56 {
555
- @apply font-sans font-semibold text-[56px] leading-[56px] tracking-[-3.36px];
555
+ @apply font-sans font-[450] text-[56px] leading-[56px] tracking-[-3.36px];
556
556
  }
557
557
 
558
558
  @utility text-heading-48 {
559
- @apply font-sans font-semibold text-[48px] leading-[56px] tracking-[-2.88px];
559
+ @apply font-sans font-[450] text-[48px] leading-[56px] tracking-[-2.88px];
560
560
  }
561
561
 
562
562
  @utility text-heading-40 {
563
- @apply font-sans font-semibold text-[40px] leading-[48px] tracking-[-2.4px];
563
+ @apply font-sans font-[450] text-[40px] leading-[48px] tracking-[-2.4px];
564
564
  }
565
565
 
566
566
  @utility text-heading-32 {
567
- @apply font-sans font-semibold [&>strong]:font-medium [&>strong]:text-gray-900 text-[32px] leading-[40px] tracking-[-1.28px];
567
+ @apply font-sans font-[450] [&>strong]:font-medium [&>strong]:text-gray-900 text-[32px] leading-[40px] tracking-[-1.28px];
568
568
  }
569
569
 
570
570
  @utility text-heading-24 {
571
- @apply font-sans font-semibold [&>strong]:font-medium [&>strong]:text-gray-900 text-[24px] leading-[32px] tracking-[-0.96px];
571
+ @apply font-sans font-[450] [&>strong]:font-medium [&>strong]:text-gray-900 text-[24px] leading-[32px] tracking-[-0.96px];
572
572
  }
573
573
 
574
574
  @utility text-heading-20 {
575
- @apply font-sans font-semibold [&>strong]:font-medium [&>strong]:text-gray-900 text-[20px] leading-[26px] tracking-[-0.4px];
575
+ @apply font-sans font-[450] [&>strong]:font-medium [&>strong]:text-gray-900 text-[20px] leading-[26px] tracking-[-0.4px];
576
576
  }
577
577
 
578
578
  @utility text-heading-16 {
579
- @apply font-sans font-semibold [&>strong]:font-medium [&>strong]:text-gray-900 text-[16px] leading-[24px] tracking-[-0.32px];
579
+ @apply font-sans font-[450] [&>strong]:font-medium [&>strong]:text-gray-900 text-[16px] leading-[24px] tracking-[-0.32px];
580
580
  }
581
581
 
582
582
  @utility text-heading-14 {
583
- @apply font-sans font-semibold text-[14px] leading-[20px] tracking-[-0.28px];
583
+ @apply font-sans font-[450] text-[14px] leading-[20px] tracking-[-0.28px];
584
584
  }
585
585
 
586
586
  /* Typography Button */
@@ -673,13 +673,33 @@
673
673
  @apply font-mono font-normal text-[13px] leading-[18px];
674
674
  }
675
675
 
676
- .prose h1,
677
- .prose h2,
678
- .prose h3,
679
- .prose h4,
676
+ .prose h1 {
677
+ @apply text-heading-32;
678
+ }
679
+
680
+ .prose h2 {
681
+ @apply text-heading-24;
682
+ }
683
+
684
+ .prose h3 {
685
+ @apply text-heading-20;
686
+ }
687
+
688
+ .prose h4 {
689
+ @apply text-heading-16;
690
+ }
691
+
680
692
  .prose h5,
681
693
  .prose h6 {
682
- @apply tracking-tight;
694
+ @apply text-heading-14;
695
+ }
696
+
697
+ /* Docs page title. Fumadocs' DocsTitle renders it outside .prose and hardcodes
698
+ text-[1.75em] font-semibold via its own class merge, which our cn() can't
699
+ reliably override. Own the Geist heading style here where specificity wins;
700
+ tracking-tighter loosens text-heading-40's dense -2.4px. */
701
+ #nd-page h1:not(:where(.prose *)) {
702
+ @apply text-heading-40 tracking-tighter;
683
703
  }
684
704
 
685
705
  @layer utilities {