Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

Harden docs routing and discovery (#1613)

John Phamousbf0475036369
diff --git a/apps/docs/app/[lang]/(home)/components/hero-audience.tsx b/apps/docs/app/[lang]/(home)/components/hero-audience.tsx
index d95a0b083..70ea5583b 100644
--- a/apps/docs/app/[lang]/(home)/components/hero-audience.tsx
+++ b/apps/docs/app/[lang]/(home)/components/hero-audience.tsx
@@ -11,9 +11,7 @@ export function HeroAudience({ tagline }: { tagline: string }) {
<>
<div className="relative z-10 max-w-5xl text-center text-heading-40 md:text-heading-48 lg:text-heading-56">
<EveLogoShader audience={audience} />
- <h1 className="relative text-balance w-full max-w-[10em]">
- The framework for building agents
- </h1>
+ <h1 className="relative text-balance w-full max-w-[10em]">Build durable agents with eve</h1>
</div>
<p className="text-balance pt-[0.35em] relative z-10 w-full text-center text-copy-16 text-gray-900 md:max-w-2xl md:text-copy-18 lg:text-copy-20">
{tagline}
diff --git a/apps/docs/app/[lang]/(home)/components/home-content.tsx b/apps/docs/app/[lang]/(home)/components/home-content.tsx
index c429bc869..0d82018c5 100644
--- a/apps/docs/app/[lang]/(home)/components/home-content.tsx
+++ b/apps/docs/app/[lang]/(home)/components/home-content.tsx
@@ -1,4 +1,6 @@
import type { Metadata } from "next";
+import { canonicalAlternates, canonicalRoutes } from "@/lib/geistdocs/canonical";
+import { pageTitleMetadata, siteTitle } from "@/lib/geistdocs/metadata-title";
import { staticOgImage } from "@/lib/geistdocs/og";
import { ArchitectureDiagram } from "./architecture";
import { CTA } from "./cta";
@@ -7,20 +9,21 @@ import { FileTree } from "./file-tree";
import { HeroAudience } from "./hero-audience";
import { NextjsInterop } from "./nextjs-interop";
-const title = "eve";
const tagline = "Like Next.js for agents. Build durable agents with one folder.";
+const titleMetadata = pageTitleMetadata(siteTitle);
export const homeMetadata: Metadata = {
- title,
+ ...titleMetadata,
description: tagline,
+ alternates: canonicalAlternates(canonicalRoutes.home),
openGraph: {
- title,
+ ...titleMetadata.openGraph,
description: tagline,
images: [staticOgImage],
},
twitter: {
+ ...titleMetadata.twitter,
card: "summary_large_image",
- title,
description: tagline,
images: [staticOgImage],
},
diff --git a/apps/docs/app/[lang]/agents.md/route.ts b/apps/docs/app/[lang]/agents.md/route.ts
index 40492a8c5..85f8267bc 100644
--- a/apps/docs/app/[lang]/agents.md/route.ts
+++ b/apps/docs/app/[lang]/agents.md/route.ts
@@ -1,5 +1,7 @@
import { createAgentsRoute } from "@vercel/geistdocs/routes/agents";
+import { transformAgentsMarkdown } from "@/lib/geistdocs/agents-transform";
import { config } from "@/lib/geistdocs/config";
+import { templateEntries } from "@/lib/templates/data";
// Static, CDN-cacheable. /agents.md surfaces the agent instructions from the
// Geistdocs config and points agents at /llms.txt and individual /llms.mdx
@@ -7,7 +9,14 @@ import { config } from "@/lib/geistdocs/config";
// endpoint crawlers and agents poll repeatedly.
export const revalidate = false;
-const agentsRoute = createAgentsRoute({ config });
+const agentsRoute = createAgentsRoute({
+ config,
+ transform: (markdown, { request }) =>
+ transformAgentsMarkdown(markdown, {
+ origin: request.nextUrl.origin,
+ templates: templateEntries,
+ }),
+});
export const GET = agentsRoute.GET;
export const generateStaticParams = agentsRoute.generateStaticParams;
diff --git a/apps/docs/app/[lang]/docs/[[...slug]]/page.tsx b/apps/docs/app/[lang]/docs/[[...slug]]/page.tsx
index 111195903..23a6204a0 100644
--- a/apps/docs/app/[lang]/docs/[[...slug]]/page.tsx
+++ b/apps/docs/app/[lang]/docs/[[...slug]]/page.tsx
@@ -1,9 +1,12 @@
+import { getPublicPath } from "@vercel/geistdocs/config";
import { MobileDocsBar } from "@vercel/geistdocs/mobile-docs-bar";
import { createDocsPage, createPageActions } from "@vercel/geistdocs/pages/docs";
import type { MDXComponents } from "mdx/types";
import { EditOnGithubAction } from "@/components/geistdocs/edit-on-github";
import { getMDXComponents } from "@/components/geistdocs/mdx-components";
+import { canonicalAlternates } from "@/lib/geistdocs/canonical";
import { config } from "@/lib/geistdocs/config";
+import { pageTitleMetadata } from "@/lib/geistdocs/metadata-title";
import { staticOgImage } from "@/lib/geistdocs/og";
import { resolveDocsPageTitle } from "@/lib/geistdocs/page-title";
import { geistdocsSource } from "@/lib/geistdocs/source";
@@ -21,21 +24,36 @@ const docsPage = createDocsPage({
return getMDXComponents(components);
},
metadata: ({ metadata, page, params }) => {
+ const title = resolveDocsPageTitle({
+ pageTitle: page.data.title,
+ pageUrl: page.url,
+ tree: geistdocsSource.source.getPageTree(params.lang),
+ });
+ if (!title) throw new Error(`Missing title for docs page ${page.url}`);
+ const titleMetadata = pageTitleMetadata(title);
+
return {
...metadata,
- title: resolveDocsPageTitle({
- pageTitle: page.data.title,
- pageUrl: page.url,
- tree: geistdocsSource.source.getPageTree(params.lang),
- }),
+ ...titleMetadata,
metadataBase: new URL(getSiteOrigin()),
+ alternates: canonicalAlternates(
+ getPublicPath(page.url, config.basePath),
+ metadata.alternates,
+ ),
openGraph: {
...metadata.openGraph,
+ ...titleMetadata.openGraph,
// Override with the static OG image for now. To restore dynamic per-page
// OG generation, swap the line below back to:
// images: geistdocsSource.getPageImage(page).url,
images: [staticOgImage],
},
+ twitter: {
+ ...metadata.twitter,
+ ...titleMetadata.twitter,
+ card: "summary_large_image",
+ images: [staticOgImage],
+ },
};
},
source: geistdocsSource,
diff --git a/apps/docs/app/[lang]/integrations/[slug]/page.tsx b/apps/docs/app/[lang]/integrations/[slug]/page.tsx
index 683abe995..10b788da5 100644
--- a/apps/docs/app/[lang]/integrations/[slug]/page.tsx
+++ b/apps/docs/app/[lang]/integrations/[slug]/page.tsx
@@ -3,6 +3,9 @@ import type { Metadata } from "next";
import Link from "next/link";
import { notFound } from "next/navigation";
import { Suspense } from "react";
+import { canonicalAlternates, integrationPath } from "@/lib/geistdocs/canonical";
+import { pageTitleMetadata } from "@/lib/geistdocs/metadata-title";
+import { staticOgImage } from "@/lib/geistdocs/og";
import { buildConnectionInstall, buildConnectionSetup } from "@/lib/integrations/connection-setup";
import {
getIntegration,
@@ -37,9 +40,18 @@ export const generateMetadata = async ({
if (!integration) {
return {};
}
+ const title = `${integration.name} Integration`;
+ const titleMetadata = pageTitleMetadata(title);
return {
- title: `${integration.name} Integration`,
+ ...titleMetadata,
description: integration.tagline,
+ alternates: canonicalAlternates(integrationPath(integration.slug)),
+ openGraph: { ...titleMetadata.openGraph, images: [staticOgImage] },
+ twitter: {
+ ...titleMetadata.twitter,
+ card: "summary_large_image",
+ images: [staticOgImage],
+ },
};
};
diff --git a/apps/docs/app/[lang]/integrations/components/integration-card.tsx b/apps/docs/app/[lang]/integrations/components/integration-card.tsx
index df8bb047e..4078112f6 100644
--- a/apps/docs/app/[lang]/integrations/components/integration-card.tsx
+++ b/apps/docs/app/[lang]/integrations/components/integration-card.tsx
@@ -1,4 +1,5 @@
import Link from "next/link";
+import { integrationPath } from "@/lib/geistdocs/canonical";
import { type Integration, protocolBadgeClassName, protocolLabel } from "@/lib/integrations/data";
import { logos } from "@/lib/integrations/logos";
@@ -19,7 +20,7 @@ export const IntegrationCard = ({ integration }: IntegrationCardProps) => {
return (
<Link
className="group flex flex-col gap-4 rounded-lg border bg-background-100 p-5 transition-colors hover:border-gray-400 hover:bg-gray-100"
- href={`/integrations/${integration.slug}`}
+ href={integrationPath(integration.slug)}
>
<div className="flex flex-wrap items-start justify-between gap-3">
<span className="flex size-10 shrink-0 items-center justify-center rounded-md border bg-background text-gray-1000">
diff --git a/apps/docs/app/[lang]/integrations/page.tsx b/apps/docs/app/[lang]/integrations/page.tsx
index b446a555a..50f0894bd 100644
--- a/apps/docs/app/[lang]/integrations/page.tsx
+++ b/apps/docs/app/[lang]/integrations/page.tsx
@@ -1,4 +1,7 @@
import type { Metadata } from "next";
+import { canonicalAlternates, canonicalRoutes } from "@/lib/geistdocs/canonical";
+import { pageTitleMetadata } from "@/lib/geistdocs/metadata-title";
+import { staticOgImage } from "@/lib/geistdocs/og";
import { integrations } from "@/lib/integrations/data";
import { translations } from "@/geistdocs";
import { Gallery, type GalleryFilter } from "./components/gallery";
@@ -6,10 +9,18 @@ import { Gallery, type GalleryFilter } from "./components/gallery";
const title = "Integrations";
const description =
"Browse the channels, connections, extensions, and instrumentation providers available to an eve agent, each with install, quick start, and configuration steps.";
+const titleMetadata = pageTitleMetadata(title);
export const metadata: Metadata = {
- title,
+ ...titleMetadata,
description,
+ alternates: canonicalAlternates(canonicalRoutes.integrations),
+ openGraph: { ...titleMetadata.openGraph, images: [staticOgImage] },
+ twitter: {
+ ...titleMetadata.twitter,
+ card: "summary_large_image",
+ images: [staticOgImage],
+ },
};
export const generateStaticParams = () => Object.keys(translations).map((lang) => ({ lang }));
diff --git a/apps/docs/app/[lang]/layout.tsx b/apps/docs/app/[lang]/layout.tsx
index df62dff60..eeefafed9 100644
--- a/apps/docs/app/[lang]/layout.tsx
+++ b/apps/docs/app/[lang]/layout.tsx
@@ -2,15 +2,19 @@ import "../global.css";
import { Footer } from "@vercel/geistdocs/footer";
import { Navbar } from "@vercel/geistdocs/navbar";
import type { Metadata } from "next";
+import { notFound } from "next/navigation";
import { GeistdocsProvider } from "@/components/geistdocs/provider";
import { config } from "@/lib/geistdocs/config";
import { mono, sans } from "@/lib/geistdocs/fonts";
import { staticOgImage } from "@/lib/geistdocs/og";
+import { isSupportedLanguage, supportedLanguages } from "@/lib/geistdocs/languages";
+import { rootTitleMetadata } from "@/lib/geistdocs/metadata-title";
import { getSiteOrigin } from "@/lib/geistdocs/url";
import { cn } from "@/lib/utils";
export const metadata: Metadata = {
metadataBase: new URL(getSiteOrigin()),
+ title: rootTitleMetadata,
openGraph: {
images: [staticOgImage],
},
@@ -24,8 +28,12 @@ export const metadata: Metadata = {
},
};
+export const dynamicParams = false;
+export const generateStaticParams = () => supportedLanguages.map((lang) => ({ lang }));
+
const Layout = async ({ children, params }: LayoutProps<"/[lang]">) => {
const { lang } = await params;
+ if (!isSupportedLanguage(lang)) notFound();
return (
<html
diff --git a/apps/docs/app/[lang]/llms.mdx/[[...slug]]/route.ts b/apps/docs/app/[lang]/llms.mdx/[[...slug]]/route.ts
index e1b5a7210..494febfb3 100644
--- a/apps/docs/app/[lang]/llms.mdx/[[...slug]]/route.ts
+++ b/apps/docs/app/[lang]/llms.mdx/[[...slug]]/route.ts
@@ -1,10 +1,12 @@
import { createDocsMarkdownRoute } from "@vercel/geistdocs/routes/llms";
+import { getMarkdownRequestedPath } from "@/lib/geistdocs/markdown-path";
import { geistdocsSource } from "@/lib/geistdocs/source";
import { integrationSource } from "@/lib/integrations/source";
export const revalidate = false;
const markdownRoute = createDocsMarkdownRoute({
+ notFound: { getRequestedPath: getMarkdownRequestedPath },
sources: [geistdocsSource, integrationSource],
});
diff --git a/apps/docs/app/[lang]/sitemap.md/route.ts b/apps/docs/app/[lang]/sitemap.md/route.ts
index a545b86a1..d80340b17 100644
--- a/apps/docs/app/[lang]/sitemap.md/route.ts
+++ b/apps/docs/app/[lang]/sitemap.md/route.ts
@@ -1,7 +1,10 @@
import { createSitemapMarkdownRoute } from "@vercel/geistdocs/routes/sitemap";
import { config } from "@/lib/geistdocs/config";
+import { resolveDocsPageTitle } from "@/lib/geistdocs/page-title";
+import { transformSitemapMarkdown } from "@/lib/geistdocs/sitemap-transform";
import { geistdocsSource } from "@/lib/geistdocs/source";
import { integrationSource } from "@/lib/integrations/source";
+import { templateEntries } from "@/lib/templates/data";
export const revalidate = false;
export const dynamic = "error";
@@ -9,6 +12,16 @@ export const dynamic = "error";
const sitemapRoute = createSitemapMarkdownRoute({
config,
sources: [{ source: geistdocsSource }, { source: integrationSource }],
+ transform: (markdown, { lang }) =>
+ transformSitemapMarkdown(markdown, {
+ resolveTitle: (title, url) =>
+ resolveDocsPageTitle({
+ pageTitle: title,
+ pageUrl: url,
+ tree: geistdocsSource.source.getPageTree(lang),
+ }) ?? title,
+ templates: templateEntries,
+ }),
});
export const GET = sitemapRoute.GET;
diff --git a/apps/docs/app/[lang]/templates/[slug]/page.tsx b/apps/docs/app/[lang]/templates/[slug]/page.tsx
index a7d2dca28..d34f89db4 100644
--- a/apps/docs/app/[lang]/templates/[slug]/page.tsx
+++ b/apps/docs/app/[lang]/templates/[slug]/page.tsx
@@ -7,6 +7,8 @@ import Link from "next/link";
import { notFound } from "next/navigation";
import type { ComponentProps } from "react";
import { translations } from "@/geistdocs";
+import { canonicalAlternates, templatePath } from "@/lib/geistdocs/canonical";
+import { pageTitleMetadata } from "@/lib/geistdocs/metadata-title";
import {
getTemplateEntry,
templateEntries,
@@ -37,9 +39,16 @@ export const generateMetadata = async ({
}): Promise<Metadata> => {
const { slug } = await params;
const entry = getTemplateEntry(slug);
- return entry
- ? { title: `${entry.title} template - eve`, description: entry.description }
- : { title: "Template not found" };
+ if (!entry) return { title: "Template not found" };
+
+ const titleMetadata = pageTitleMetadata(`${entry.title} template - eve`);
+ return {
+ ...titleMetadata,
+ description: entry.description,
+ alternates: canonicalAlternates(templatePath(entry.slug)),
+ openGraph: titleMetadata.openGraph,
+ twitter: { ...titleMetadata.twitter, card: "summary_large_image" },
+ };
};
const TemplateDetailPage = async ({ params }: { params: Promise<PageParams> }) => {
diff --git a/apps/docs/app/[lang]/templates/page.tsx b/apps/docs/app/[lang]/templates/page.tsx
index 842da07ad..6b25c18be 100644
--- a/apps/docs/app/[lang]/templates/page.tsx
+++ b/apps/docs/app/[lang]/templates/page.tsx
@@ -1,4 +1,7 @@
import type { Metadata } from "next";
+import { canonicalAlternates, canonicalRoutes } from "@/lib/geistdocs/canonical";
+import { pageTitleMetadata } from "@/lib/geistdocs/metadata-title";
+import { staticOgImage } from "@/lib/geistdocs/og";
import { translations } from "@/geistdocs";
import { templateEntries } from "@/lib/templates/data";
import { TemplateGallery } from "./template-gallery";
@@ -6,10 +9,18 @@ import { TemplateGallery } from "./template-gallery";
const title = "Templates";
const description =
"Explore agents built on eve. Set one up with a prompt or use its source as a starting point.";
+const titleMetadata = pageTitleMetadata(title);
export const metadata: Metadata = {
- title,
+ ...titleMetadata,
description,
+ alternates: canonicalAlternates(canonicalRoutes.templates),
+ openGraph: { ...titleMetadata.openGraph, images: [staticOgImage] },
+ twitter: {
+ ...titleMetadata.twitter,
+ card: "summary_large_image",
+ images: [staticOgImage],
+ },
};
export const generateStaticParams = () => Object.keys(translations).map((lang) => ({ lang }));
diff --git a/apps/docs/app/[lang]/templates/template-gallery.tsx b/apps/docs/app/[lang]/templates/template-gallery.tsx
index f28c2bfbc..343ebb12a 100644
--- a/apps/docs/app/[lang]/templates/template-gallery.tsx
+++ b/apps/docs/app/[lang]/templates/template-gallery.tsx
@@ -12,6 +12,7 @@ import { Input } from "@vercel/geistdocs/components/input";
import { ChevronDownIcon, SearchIcon } from "lucide-react";
import Link from "next/link";
import { useMemo, useState } from "react";
+import { templatePath } from "@/lib/geistdocs/canonical";
import type { TemplateCategory, TemplateEntry, TemplateIntegration } from "@/lib/templates/data";
import { integrationIcons } from "./integration-icons";
@@ -73,7 +74,7 @@ const TemplateCard = ({ entry }: { entry: TemplateEntry }) => (
<li>
<Link
className="flex min-h-36 flex-col rounded-lg border border-gray-alpha-400 bg-background-100 p-4 no-underline outline-none transition-colors hover:border-gray-alpha-500 hover:bg-gray-alpha-100 focus-visible:border-gray-alpha-600 focus-visible:ring-2 focus-visible:ring-blue-700 focus-visible:ring-offset-2 focus-visible:ring-offset-background-100 motion-reduce:transition-none"
- href={`/templates/${entry.slug}`}
+ href={templatePath(entry.slug)}
>
<h2 className="text-gray-1000 text-heading-16">{entry.title}</h2>
<p className="mt-2 line-clamp-2 max-w-[90%] text-balance text-[14px] leading-[1.3] text-gray-800">
diff --git a/apps/docs/app/global-not-found.tsx b/apps/docs/app/global-not-found.tsx
new file mode 100644
index 000000000..f723b9c47
--- /dev/null
+++ b/apps/docs/app/global-not-found.tsx
@@ -0,0 +1,28 @@
+import type { Metadata } from "next";
+import "./global.css";
+
+export const metadata: Metadata = {
+ title: "Page not found - eve",
+ description: "The requested eve documentation page does not exist.",
+};
+
+const GlobalNotFound = () => (
+ <html lang="en">
+ <body className="flex min-h-screen items-center justify-center bg-background-100 px-6 text-gray-1000">
+ <main className="max-w-md text-center">
+ <h1 className="text-heading-32">Page not found</h1>
+ <p className="mt-3 text-copy-16 text-gray-900">
+ The requested page does not exist. Browse the eve documentation to continue.
+ </p>
+ <a
+ className="mt-6 inline-flex rounded-md border px-4 py-2 text-label-14"
+ href="/docs/getting-started"
+ >
+ Browse documentation
+ </a>
+ </main>
+ </body>
+ </html>
+);
+
+export default GlobalNotFound;
diff --git a/apps/docs/app/sitemap.ts b/apps/docs/app/sitemap.ts
new file mode 100644
index 000000000..62045b3b3
--- /dev/null
+++ b/apps/docs/app/sitemap.ts
@@ -0,0 +1,49 @@
+import { getPublicPath } from "@vercel/geistdocs/config";
+import type { MetadataRoute } from "next";
+import { canonicalRoutes, integrationPath, templatePath } from "@/lib/geistdocs/canonical";
+import { config } from "@/lib/geistdocs/config";
+import { defaultLanguage } from "@/lib/geistdocs/languages";
+import {
+ compatibilityRedirects,
+ docsRedirects,
+ rootMarkdownRedirects,
+} from "@/lib/geistdocs/redirects";
+import { createCanonicalSitemap, type SitemapSourceEntry } from "@/lib/geistdocs/sitemap";
+import { geistdocsSource } from "@/lib/geistdocs/source";
+import { getSiteOrigin } from "@/lib/geistdocs/url";
+import { integrations } from "@/lib/integrations/data";
+import { templateEntries } from "@/lib/templates/data";
+
+const getLastModified = (data: unknown): Date | undefined => {
+ if (!data || typeof data !== "object" || !("lastModified" in data)) return;
+ return data.lastModified instanceof Date ? data.lastModified : undefined;
+};
+
+const redirectPathnames = [
+ "/docs",
+ ...compatibilityRedirects.map(({ source }) => source),
+ ...docsRedirects.map(({ source }) => source),
+ ...rootMarkdownRedirects.map(({ source }) => source),
+].filter((pathname) => !pathname.includes(":"));
+
+export default function sitemap(): MetadataRoute.Sitemap {
+ const docs: SitemapSourceEntry[] = geistdocsSource.source
+ .getPages(defaultLanguage)
+ .map((page) => ({
+ pathname: getPublicPath(page.url, config.basePath),
+ lastModified: getLastModified(page.data),
+ }));
+
+ return createCanonicalSitemap({
+ excludedPathnames: redirectPathnames,
+ origin: getSiteOrigin(),
+ sources: [
+ { pathname: canonicalRoutes.home },
+ ...docs,
+ { pathname: canonicalRoutes.integrations },
+ ...integrations.map(({ slug }) => ({ pathname: integrationPath(slug) })),
+ { pathname: canonicalRoutes.templates },
+ ...templateEntries.map(({ slug }) => ({ pathname: templatePath(slug) })),
+ ],
+ });
+}
diff --git a/apps/docs/geistdocs.tsx b/apps/docs/geistdocs.tsx
index c97f6c707..aa2bbad8e 100644
--- a/apps/docs/geistdocs.tsx
+++ b/apps/docs/geistdocs.tsx
@@ -1,6 +1,8 @@
import { LogoEve } from "@vercel/geistdocs/assets/logos/logo-eve";
import type { GeistdocsGithubConfig } from "@vercel/geistdocs/config";
+export { translations } from "@/lib/geistdocs/languages";
+
export const Logo = () => <LogoEve />;
export const github: GeistdocsGithubConfig = {
@@ -34,13 +36,13 @@ export const agent = {
product: {
name: "eve",
description:
- "A filesystem-first framework for building durable agents on Vercel with markdown instructions, TypeScript tools, and built-in runtime primitives.",
+ "A filesystem-first, Apache-2.0 framework for building durable backend AI agents that run on Vercel or your own infrastructure. eve is currently in beta.",
category: "Agent framework",
- audience: ["developers building AI agents", "Vercel users"],
+ audience: ["developers building AI agents", "teams running agents on any infrastructure"],
useCases: [
"Create durable agents with filesystem conventions",
"Add channels, tools, skills, sandboxes, hooks, and schedules",
- "Deploy agent workloads on Vercel",
+ "Deploy agent workloads on Vercel or self-host them as Node services",
],
},
instructions: [
@@ -49,7 +51,7 @@ export const agent = {
"Verify setup with `eve info --json` and `eve channels list --json` before reporting success.",
"Use /sitemap.md to identify the most relevant documentation pages before answering broad questions.",
"Use /llms.txt when you need the complete documentation corpus as Markdown context.",
- "Fetch individual documentation pages with a .md or .mdx extension for focused page-level context.",
+ "Fetch individual docs or integration pages with a .md or .mdx extension for focused page-level context. Template pages are HTML discovery pages and do not expose this alternate Markdown route.",
"Do not assume API, authentication, OpenAPI, or MCP support unless it is listed in this file.",
],
};
@@ -65,12 +67,6 @@ export const eveAgent = {
url: "https://help-ash.vercel.sh",
};
-export const translations = {
- en: {
- displayName: "English",
- },
-};
-
export const basePath: string | undefined = undefined;
export const siteId: string | undefined = "agent-framework";
diff --git a/apps/docs/lib/geistdocs/agents-transform.test.ts b/apps/docs/lib/geistdocs/agents-transform.test.ts
new file mode 100644
index 000000000..02877e44e
--- /dev/null
+++ b/apps/docs/lib/geistdocs/agents-transform.test.ts
@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { transformAgentsMarkdown } from "./agents-transform";
+
+const input = `# eve
+
+## Documentation Surfaces
+
+- Page-level Markdown: append .md or .mdx to a documentation URL
+
+- To create an agent, get it as Markdown from /llms.mdx/getting-started (or via /llms.txt).
+`;
+
+describe("transformAgentsMarkdown", () => {
+ it("describes canonical HTML and route-specific Markdown accurately", () => {
+ const output = transformAgentsMarkdown(input, { origin: "https://eve.dev", templates: [] });
+
+ expect(output).toContain(
+ "Canonical HTML pages use `/docs/...`, `/integrations/...`, and `/templates/...`",
+ );
+ expect(output).toContain("Docs and integration pages expose alternate Markdown");
+ expect(output).toContain("Template pages are HTML discovery pages");
+ expect(output).toContain("/docs/getting-started.md (or via /llms.txt)");
+ expect(output).not.toContain("/llms.mdx/getting-started");
+ expect(output).not.toContain("append .md or .mdx to a documentation URL");
+ });
+
+ it("adds concise canonical template discovery entries", () => {
+ const output = transformAgentsMarkdown(input, {
+ origin: "https://eve.dev",
+ templates: [{ slug: "chat", title: "Chat", description: "A persisted chat agent." }],
+ });
+
+ expect(output).toContain(
+ "- [Chat template](https://eve.dev/templates/chat): A persisted chat agent.",
+ );
+ });
+
+ it("fails loudly if the upstream generic guidance changes", () => {
+ expect(() =>
+ transformAgentsMarkdown("# eve", { origin: "https://eve.dev", templates: [] }),
+ ).toThrow("Geistdocs agents.md Markdown guidance changed");
+ });
+});
diff --git a/apps/docs/lib/geistdocs/agents-transform.ts b/apps/docs/lib/geistdocs/agents-transform.ts
new file mode 100644
index 000000000..bc18ee1bc
--- /dev/null
+++ b/apps/docs/lib/geistdocs/agents-transform.ts
@@ -0,0 +1,45 @@
+interface TemplateDiscoveryEntry {
+ description: string;
+ slug: string;
+ title: string;
+}
+
+const GENERIC_MARKDOWN_INSTRUCTION =
+ "- Page-level Markdown: append .md or .mdx to a documentation URL";
+const INTERNAL_GETTING_STARTED_INSTRUCTION =
+ "get it as Markdown from /llms.mdx/getting-started (or via /llms.txt)";
+
+const escapeMarkdown = (value: string): string => value.replace(/([\\[\]])/g, "\\$1");
+
+export const transformAgentsMarkdown = (
+ markdown: string,
+ { origin, templates }: { origin: string; templates: TemplateDiscoveryEntry[] },
+): string => {
+ if (
+ !markdown.includes(GENERIC_MARKDOWN_INSTRUCTION) ||
+ !markdown.includes(INTERNAL_GETTING_STARTED_INSTRUCTION)
+ ) {
+ throw new Error("Geistdocs agents.md Markdown guidance changed; update the eve transform.");
+ }
+
+ const corrected = markdown
+ .replace(
+ GENERIC_MARKDOWN_INSTRUCTION,
+ [
+ "- Canonical HTML pages use `/docs/...`, `/integrations/...`, and `/templates/...` URLs.",
+ "- Docs and integration pages expose alternate Markdown by appending `.md` or `.mdx` to their canonical HTML URL.",
+ "- Template pages are HTML discovery pages; use their setup prompt or source link instead of appending a Markdown extension.",
+ ].join("\n"),
+ )
+ .replace(
+ INTERNAL_GETTING_STARTED_INSTRUCTION,
+ "get it as Markdown from /docs/getting-started.md (or via /llms.txt)",
+ );
+
+ const templateLines = templates.map(
+ (template) =>
+ `- [${escapeMarkdown(`${template.title} template`)}](${origin}/templates/${template.slug}): ${template.description}`,
+ );
+
+ return `${corrected.trimEnd()}\n\n## Templates\n\n${templateLines.join("\n")}\n`;
+};
diff --git a/apps/docs/lib/geistdocs/canonical.test.ts b/apps/docs/lib/geistdocs/canonical.test.ts
new file mode 100644
index 000000000..54c5fb57b
--- /dev/null
+++ b/apps/docs/lib/geistdocs/canonical.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import {
+ canonicalAlternates,
+ canonicalPathname,
+ canonicalRoutes,
+ integrationPath,
+ templatePath,
+} from "./canonical";
+
+describe("canonical routes", () => {
+ it("uses one path model for hubs and detail pages", () => {
+ expect(canonicalRoutes).toEqual({
+ home: "/",
+ integrations: "/integrations",
+ templates: "/templates",
+ });
+ expect(integrationPath("slack")).toBe("/integrations/slack");
+ expect(templatePath("eve-chat-template")).toBe("/templates/eve-chat-template");
+ });
+
+ it("removes query and fragment variants from canonical paths", () => {
+ expect(canonicalPathname("/integrations?filter=channel")).toBe("/integrations");
+ expect(canonicalPathname("/docs/channels/overview#which-channel")).toBe(
+ "/docs/channels/overview",
+ );
+ });
+
+ it("preserves alternate representations while setting the HTML canonical", () => {
+ expect(
+ canonicalAlternates("/docs/channels/overview?view=all", {
+ types: { "text/markdown": "/docs/channels/overview.md" },
+ }),
+ ).toEqual({
+ canonical: "/docs/channels/overview",
+ types: { "text/markdown": "/docs/channels/overview.md" },
+ });
+ });
+
+ it.each(["https://other.example/docs", "//other.example/docs"])(
+ "rejects cross-origin canonical value %s",
+ (value) => {
+ expect(() => canonicalPathname(value)).toThrow("Canonical path must be site-relative");
+ },
+ );
+});
diff --git a/apps/docs/lib/geistdocs/canonical.ts b/apps/docs/lib/geistdocs/canonical.ts
new file mode 100644
index 000000000..e2cd7556b
--- /dev/null
+++ b/apps/docs/lib/geistdocs/canonical.ts
@@ -0,0 +1,27 @@
+import type { Metadata } from "next";
+
+export const canonicalRoutes = {
+ home: "/",
+ integrations: "/integrations",
+ templates: "/templates",
+} as const;
+
+export const integrationPath = (slug: string): string => `${canonicalRoutes.integrations}/${slug}`;
+
+export const templatePath = (slug: string): string => `${canonicalRoutes.templates}/${slug}`;
+
+export const canonicalPathname = (value: string): string => {
+ const pathname = value.split(/[?#]/, 1)[0] || canonicalRoutes.home;
+ if (!pathname.startsWith("/") || pathname.startsWith("//")) {
+ throw new Error(`Canonical path must be site-relative: ${value}`);
+ }
+ return pathname;
+};
+
+export const canonicalAlternates = (
+ pathname: string,
+ alternates?: Metadata["alternates"],
+): NonNullable<Metadata["alternates"]> => ({
+ ...alternates,
+ canonical: canonicalPathname(pathname),
+});
diff --git a/apps/docs/lib/geistdocs/config.tsx b/apps/docs/lib/geistdocs/config.tsx
index 96333e69b..419c6844b 100644
--- a/apps/docs/lib/geistdocs/config.tsx
+++ b/apps/docs/lib/geistdocs/config.tsx
@@ -12,11 +12,12 @@ import {
title,
translations,
} from "@/geistdocs";
+import { defaultLanguage } from "./languages";
export const config = defineConfig({
title,
agent,
- defaultLanguage: "en",
+ defaultLanguage,
logo: <Logo />,
github,
nav,
diff --git a/apps/docs/lib/geistdocs/discovery.test.ts b/apps/docs/lib/geistdocs/discovery.test.ts
new file mode 100644
index 000000000..0dd516e26
--- /dev/null
+++ b/apps/docs/lib/geistdocs/discovery.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { integrations } from "../integrations/data";
+import { templateEntries } from "../templates/data";
+import { integrationPath, templatePath } from "./canonical";
+
+describe("authoritative hub discovery paths", () => {
+ it("gives every integration a unique canonical child link", () => {
+ const paths = integrations.map(({ slug }) => integrationPath(slug));
+
+ expect(new Set(paths).size).toBe(integrations.length);
+ expect(paths.every((path) => /^\/integrations\/[^/?#]+$/.test(path))).toBe(true);
+ });
+
+ it("gives every template a unique canonical child link", () => {
+ const paths = templateEntries.map(({ slug }) => templatePath(slug));
+
+ expect(new Set(paths).size).toBe(templateEntries.length);
+ expect(paths.every((path) => /^\/templates\/[^/?#]+$/.test(path))).toBe(true);
+ });
+});
diff --git a/apps/docs/lib/geistdocs/languages.test.ts b/apps/docs/lib/geistdocs/languages.test.ts
new file mode 100644
index 000000000..794af48d4
--- /dev/null
+++ b/apps/docs/lib/geistdocs/languages.test.ts
@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+import { defaultLanguage, isSupportedLanguage, supportedLanguages } from "./languages";
+
+describe("supported languages", () => {
+ it("accepts configured locales", () => {
+ expect(defaultLanguage).toBe("en");
+ expect(supportedLanguages).toEqual(["en"]);
+ expect(isSupportedLanguage("en")).toBe(true);
+ });
+
+ it.each(["api", "apple-touch-icon.png", "llms-full.txt", "unknown.xml"])(
+ "rejects root segment %s as a locale",
+ (language) => {
+ expect(isSupportedLanguage(language)).toBe(false);
+ },
+ );
+});
diff --git a/apps/docs/lib/geistdocs/languages.ts b/apps/docs/lib/geistdocs/languages.ts
new file mode 100644
index 000000000..e212ef2a9
--- /dev/null
+++ b/apps/docs/lib/geistdocs/languages.ts
@@ -0,0 +1,12 @@
+export const defaultLanguage = "en" as const;
+
+export const translations = {
+ [defaultLanguage]: {
+ displayName: "English",
+ },
+};
+
+export const supportedLanguages = Object.freeze(Object.keys(translations));
+
+export const isSupportedLanguage = (language: string): language is keyof typeof translations =>
+ Object.hasOwn(translations, language);
diff --git a/apps/docs/lib/geistdocs/markdown-path.test.ts b/apps/docs/lib/geistdocs/markdown-path.test.ts
new file mode 100644
index 000000000..532655210
--- /dev/null
+++ b/apps/docs/lib/geistdocs/markdown-path.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { getMarkdownRequestedPath } from "./markdown-path";
+
+describe("getMarkdownRequestedPath", () => {
+ it("restores flattened docs paths", () => {
+ expect(getMarkdownRequestedPath({ slug: ["environment-variables"] })).toBe(
+ "/docs/environment-variables",
+ );
+ });
+
+ it("preserves integration paths", () => {
+ expect(getMarkdownRequestedPath({ slug: ["integrations", "vercel"] })).toBe(
+ "/integrations/vercel",
+ );
+ });
+
+ it("maps the shared route root to the docs root", () => {
+ expect(getMarkdownRequestedPath({ slug: [] })).toBe("/docs");
+ });
+});
diff --git a/apps/docs/lib/geistdocs/markdown-path.ts b/apps/docs/lib/geistdocs/markdown-path.ts
new file mode 100644
index 000000000..a1d903eb6
--- /dev/null
+++ b/apps/docs/lib/geistdocs/markdown-path.ts
@@ -0,0 +1,2 @@
+export const getMarkdownRequestedPath = ({ slug }: { slug: string[] }): string =>
+ slug[0] === "integrations" ? `/${slug.join("/")}` : ["/docs", ...slug].join("/");
diff --git a/apps/docs/lib/geistdocs/markdown-routes.test.ts b/apps/docs/lib/geistdocs/markdown-routes.test.ts
new file mode 100644
index 000000000..800ad57fe
--- /dev/null
+++ b/apps/docs/lib/geistdocs/markdown-routes.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { markdownRoutes } from "./markdown-routes";
+
+const integrationsRoute = markdownRoutes.find(({ from }) => from === "/integrations/*path");
+
+const rewriteIntegration = (path: string): string | undefined => {
+ if (!integrationsRoute || typeof integrationsRoute.to !== "string") return;
+ return integrationsRoute.to.replace("[lang]", "en").replace("*path", path);
+};
+
+describe("markdownRoutes", () => {
+ it("maps valid integration Markdown requests to the shared route", () => {
+ expect(rewriteIntegration("slack")).toBe("/en/llms.mdx/integrations/slack");
+ });
+
+ it("maps missing integrations to the smart Markdown handler", () => {
+ expect(rewriteIntegration("slak")).toBe("/en/llms.mdx/integrations/slak");
+ });
+
+ it("keeps docs Markdown routing intact", () => {
+ expect(markdownRoutes).toContainEqual({
+ from: "/docs/*path",
+ to: "/[lang]/llms.mdx/*path",
+ });
+ });
+});
diff --git a/apps/docs/lib/geistdocs/markdown-routes.ts b/apps/docs/lib/geistdocs/markdown-routes.ts
new file mode 100644
index 000000000..7d6fb7e4b
--- /dev/null
+++ b/apps/docs/lib/geistdocs/markdown-routes.ts
@@ -0,0 +1,6 @@
+import type { GeistdocsMarkdownRoute } from "@vercel/geistdocs/proxy";
+
+export const markdownRoutes: GeistdocsMarkdownRoute[] = [
+ { from: "/docs/*path", to: "/[lang]/llms.mdx/*path" },
+ { from: "/integrations/*path", to: "/[lang]/llms.mdx/integrations/*path" },
+];
diff --git a/apps/docs/lib/geistdocs/metadata-title.test.ts b/apps/docs/lib/geistdocs/metadata-title.test.ts
new file mode 100644
index 000000000..0239df63f
--- /dev/null
+++ b/apps/docs/lib/geistdocs/metadata-title.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+import {
+ formatPageTitle,
+ metadataTitle,
+ pageTitleMetadata,
+ rootTitleMetadata,
+ siteTitle,
+} from "./metadata-title";
+
+describe("metadata titles", () => {
+ it("defines normal child title inheritance at the shared layout", () => {
+ expect(rootTitleMetadata).toEqual({
+ default: "eve – durable AI agent framework",
+ template: "%s – eve",
+ });
+ expect(metadataTitle("Integrations")).toBe("Integrations");
+ expect(formatPageTitle("Integrations")).toBe("Integrations – eve");
+ });
+
+ it("keeps the homepage title absolute", () => {
+ expect(metadataTitle(siteTitle)).toEqual({ absolute: siteTitle });
+ expect(pageTitleMetadata(siteTitle)).toEqual({
+ title: { absolute: siteTitle },
+ openGraph: { title: siteTitle },
+ twitter: { title: siteTitle },
+ });
+ });
+
+ it.each(["Self-host eve", "Get started with eve: durable AI agents in TypeScript"])(
+ "does not suffix explicit standalone branding in %s",
+ (title) => {
+ expect(metadataTitle(title)).toEqual({ absolute: title });
+ expect(formatPageTitle(title)).toBe(title);
+ },
+ );
+
+ it("does not treat useEveAgent as standalone branding", () => {
+ const title = "Build an AI agent chat UI with useEveAgent";
+ expect(metadataTitle(title)).toBe(title);
+ expect(formatPageTitle(title)).toBe(`${title} – eve`);
+ });
+});
diff --git a/apps/docs/lib/geistdocs/metadata-title.ts b/apps/docs/lib/geistdocs/metadata-title.ts
new file mode 100644
index 000000000..dbba53715
--- /dev/null
+++ b/apps/docs/lib/geistdocs/metadata-title.ts
@@ -0,0 +1,32 @@
+import type { Metadata } from "next";
+
+export const siteTitle = "eve – durable AI agent framework";
+export const siteTitleTemplate = "%s – eve";
+
+export const rootTitleMetadata = {
+ default: siteTitle,
+ template: siteTitleTemplate,
+} satisfies NonNullable<Metadata["title"]>;
+
+const standaloneBrandPattern = /(?:^|[^a-z0-9])eve(?=$|[^a-z0-9])/i;
+
+export const formatPageTitle = (title: string): string =>
+ standaloneBrandPattern.test(title) ? title : siteTitleTemplate.replace("%s", title);
+
+export const metadataTitle = (title: string): NonNullable<Metadata["title"]> =>
+ standaloneBrandPattern.test(title) ? { absolute: title } : title;
+
+export const pageTitleMetadata = (
+ title: string,
+): {
+ openGraph: { title: string };
+ title: NonNullable<Metadata["title"]>;
+ twitter: { title: string };
+} => {
+ const resolvedTitle = formatPageTitle(title);
+ return {
+ title: metadataTitle(title),
+ openGraph: { title: resolvedTitle },
+ twitter: { title: resolvedTitle },
+ };
+};
diff --git a/apps/docs/lib/geistdocs/page-title.test.ts b/apps/docs/lib/geistdocs/page-title.test.ts
index 86fd6f30a..ae5c85c50 100644
--- a/apps/docs/lib/geistdocs/page-title.test.ts
+++ b/apps/docs/lib/geistdocs/page-title.test.ts
@@ -2,6 +2,37 @@ import { describe, expect, it } from "vitest";
import { resolveDocsPageTitle } from "./page-title";
describe("resolveDocsPageTitle", () => {
+ it.each([
+ ["/docs/agent-config", "Agent configuration (agent.ts)"],
+ ["/docs/concepts/sessions-runs-and-streaming", "Agent sessions, runs, and streaming"],
+ ["/docs/getting-started", "Get started with eve: durable AI agents in TypeScript"],
+ ["/docs/guides/frontend/overview", "Build an AI agent chat UI with useEveAgent"],
+ ["/docs/reference/project-layout", "agent/ directory reference"],
+ ["/docs/reference/typescript-api", "TypeScript API reference"],
+ ["/docs/tutorial/first-agent", "Build your first agent"],
+ ])("uses the explicit SEO title for %s", (pageUrl, expected) => {
+ expect(resolveDocsPageTitle({ pageTitle: "Visible title", pageUrl, tree: {} })).toBe(expected);
+ });
+
+ it("uses an explicit SEO title before resolving an Overview parent", () => {
+ expect(
+ resolveDocsPageTitle({
+ pageTitle: "Overview",
+ pageUrl: "/docs/guides/frontend/overview",
+ tree: {
+ name: "Docs",
+ children: [
+ {
+ type: "folder",
+ name: "Frontend",
+ children: [{ type: "page", name: "Overview", url: "/docs/guides/frontend/overview" }],
+ },
+ ],
+ },
+ }),
+ ).toBe("Build an AI agent chat UI with useEveAgent");
+ });
+
it("uses the sidebar parent title for an Overview page", () => {
const tree = {
name: "Docs",
diff --git a/apps/docs/lib/geistdocs/page-title.ts b/apps/docs/lib/geistdocs/page-title.ts
index 91c288f63..eaf1a8177 100644
--- a/apps/docs/lib/geistdocs/page-title.ts
+++ b/apps/docs/lib/geistdocs/page-title.ts
@@ -14,6 +14,16 @@ interface ResolveDocsPageTitleOptions {
tree: SidebarNode;
}
+const docsSeoTitles: Readonly<Record<string, string>> = {
+ "/docs/agent-config": "Agent configuration (agent.ts)",
+ "/docs/concepts/sessions-runs-and-streaming": "Agent sessions, runs, and streaming",
+ "/docs/getting-started": "Get started with eve: durable AI agents in TypeScript",
+ "/docs/guides/frontend/overview": "Build an AI agent chat UI with useEveAgent",
+ "/docs/reference/project-layout": "agent/ directory reference",
+ "/docs/reference/typescript-api": "TypeScript API reference",
+ "/docs/tutorial/first-agent": "Build your first agent",
+};
+
const findSidebarParentTitle = (node: SidebarNode, url: string): string | undefined => {
if (node.index?.type === "page" && node.index.url === url) {
return typeof node.name === "string" ? node.name : undefined;
@@ -39,6 +49,8 @@ export const resolveDocsPageTitle = ({
pageUrl,
tree,
}: ResolveDocsPageTitleOptions): string | undefined => {
+ const seoTitle = docsSeoTitles[pageUrl];
+ if (seoTitle) return seoTitle;
if (pageTitle !== "Overview") return pageTitle;
return findSidebarParentTitle(tree, pageUrl) ?? pageTitle;
};
diff --git a/apps/docs/lib/geistdocs/redirects.test.ts b/apps/docs/lib/geistdocs/redirects.test.ts
new file mode 100644
index 000000000..ec45d99f1
--- /dev/null
+++ b/apps/docs/lib/geistdocs/redirects.test.ts
@@ -0,0 +1,120 @@
+import { describe, expect, it } from "vitest";
+import {
+ createDocsRedirects,
+ createRootMarkdownRedirects,
+ compatibilityRedirects,
+ docsRedirects,
+ rootMarkdownRedirects,
+} from "./redirects";
+
+describe("createDocsRedirects", () => {
+ it("preserves Markdown negotiation across default and localized paths", () => {
+ expect(createDocsRedirects("/channels", "/channels/overview")).toEqual([
+ {
+ source: "/docs/channels",
+ destination: "/docs/channels/overview",
+ permanent: true,
+ },
+ {
+ source: "/:lang/docs/channels",
+ destination: "/:lang/docs/channels/overview",
+ permanent: true,
+ },
+ {
+ source: "/docs/channels.md",
+ destination: "/docs/channels/overview.md",
+ permanent: true,
+ },
+ {
+ source: "/:lang/docs/channels.md",
+ destination: "/:lang/docs/channels/overview.md",
+ permanent: true,
+ },
+ {
+ source: "/docs/channels.mdx",
+ destination: "/docs/channels/overview.mdx",
+ permanent: true,
+ },
+ {
+ source: "/:lang/docs/channels.mdx",
+ destination: "/:lang/docs/channels/overview.mdx",
+ permanent: true,
+ },
+ ]);
+ });
+});
+
+describe("createRootMarkdownRedirects", () => {
+ it("redirects only explicit Markdown representations into docs", () => {
+ expect(createRootMarkdownRedirects("/installation", "/installation")).toEqual([
+ {
+ source: "/installation.md",
+ destination: "/docs/installation.md",
+ permanent: true,
+ },
+ {
+ source: "/installation.mdx",
+ destination: "/docs/installation.mdx",
+ permanent: true,
+ },
+ ]);
+ });
+});
+
+describe("docsRedirects", () => {
+ it.each([
+ ["/docs/channels", "/docs/channels/overview"],
+ ["/docs/guides/deployment.md", "/docs/guides/deployment/overview.md"],
+ ["/docs/introduction.md", "/docs/getting-started.md"],
+ ["/docs/reference/http-api", "/docs/channels/eve"],
+ ["/docs/project-layout", "/docs/reference/project-layout"],
+ ["/docs/dynamic-capabilities", "/docs/guides/dynamic-capabilities"],
+ ["/docs/dynamic-workflows", "/docs/guides/dynamic-workflows"],
+ ["/docs/sessions", "/docs/concepts/sessions-runs-and-streaming"],
+ ["/docs/agent", "/docs/agent-config"],
+ ["/docs/evals", "/docs/evals/overview"],
+ ])("redirects %s to %s", (source, destination) => {
+ expect(docsRedirects).toContainEqual({ source, destination, permanent: true });
+ });
+});
+
+describe("rootMarkdownRedirects", () => {
+ it.each([
+ ["/getting-started.mdx", "/docs/getting-started.mdx"],
+ ["/tools/overview.md", "/docs/tools.md"],
+ ["/channels/eve.mdx", "/docs/channels/eve.mdx"],
+ ])("redirects observed root Markdown alias %s to %s", (source, destination) => {
+ expect(rootMarkdownRedirects).toContainEqual({ source, destination, permanent: true });
+ });
+
+ it("does not create extensionless root redirects", () => {
+ expect(
+ rootMarkdownRedirects.some(
+ ({ source }) => !source.endsWith(".md") && !source.endsWith(".mdx"),
+ ),
+ ).toBe(false);
+ });
+});
+
+describe("all redirects", () => {
+ const redirects = [...compatibilityRedirects, ...docsRedirects, ...rootMarkdownRedirects];
+
+ it("has no duplicate sources", () => {
+ const sources = redirects.map(({ source }) => source);
+ expect(new Set(sources).size).toBe(sources.length);
+ });
+
+ it("has no redirect loops", () => {
+ const destinations = new Map(redirects.map(({ source, destination }) => [source, destination]));
+
+ for (const { source } of redirects) {
+ const visited = new Set<string>();
+ let current: string | undefined = source;
+ while (current && destinations.has(current)) {
+ expect(visited.has(current), `redirect loop from ${source}`).toBe(false);
+ visited.add(current);
+ current = destinations.get(current);
+ }
+ }
+ });
+});
diff --git a/apps/docs/lib/geistdocs/redirects.ts b/apps/docs/lib/geistdocs/redirects.ts
new file mode 100644
index 000000000..799646931
--- /dev/null
+++ b/apps/docs/lib/geistdocs/redirects.ts
@@ -0,0 +1,93 @@
+interface DocsRedirect {
+ destination: string;
+ permanent: true;
+ source: string;
+}
+
+const extensions = ["", ".md", ".mdx"] as const;
+const markdownExtensions = [".md", ".mdx"] as const;
+
+export const createDocsRedirects = (source: string, destination: string): DocsRedirect[] =>
+ extensions.flatMap((extension) => [
+ {
+ source: `/docs${source}${extension}`,
+ destination: `/docs${destination}${extension}`,
+ permanent: true,
+ },
+ {
+ source: `/:lang/docs${source}${extension}`,
+ destination: `/:lang/docs${destination}${extension}`,
+ permanent: true,
+ },
+ ]);
+
+export const createRootMarkdownRedirects = (source: string, destination: string): DocsRedirect[] =>
+ markdownExtensions.map((extension) => ({
+ source: `${source}${extension}`,
+ destination: `/docs${destination}${extension}`,
+ permanent: true,
+ }));
+
+export const docsRedirects: DocsRedirect[] = [
+ ...createDocsRedirects("/introduction", "/getting-started"),
+ ...createDocsRedirects("/channels", "/channels/overview"),
+ ...createDocsRedirects("/channels/http", "/channels/eve"),
+ ...createDocsRedirects("/reference/http-api", "/channels/eve"),
+ ...createDocsRedirects("/project-layout", "/reference/project-layout"),
+ ...createDocsRedirects("/dynamic-capabilities", "/guides/dynamic-capabilities"),
+ ...createDocsRedirects("/dynamic-workflows", "/guides/dynamic-workflows"),
+ ...createDocsRedirects("/sessions", "/concepts/sessions-runs-and-streaming"),
+ ...createDocsRedirects("/agent", "/agent-config"),
+ ...createDocsRedirects("/guides/deployment", "/guides/deployment/overview"),
+ ...createDocsRedirects("/deployment", "/guides/deployment/overview"),
+ ...createDocsRedirects("/deployment/overview", "/guides/deployment/overview"),
+ ...createDocsRedirects("/deployment/vercel", "/guides/deployment/vercel"),
+ ...createDocsRedirects("/deployment/self-hosting", "/guides/deployment/self-hosting"),
+ ...createDocsRedirects("/self-hosting", "/guides/deployment/self-hosting"),
+ ...createDocsRedirects("/evals", "/evals/overview"),
+ ...createDocsRedirects("/advanced/evals", "/evals/overview"),
+ ...createDocsRedirects("/getting-started/installation", "/installation"),
+ ...createDocsRedirects("/getting-started/project-structure", "/project-structure"),
+ ...createDocsRedirects("/getting-started/first-agent", "/tutorial/first-agent"),
+];
+
+export const rootMarkdownRedirects: DocsRedirect[] = [
+ ["/getting-started", "/getting-started"],
+ ["/install-integrations", "/install-integrations"],
+ ["/installation", "/installation"],
+ ["/project-structure", "/project-structure"],
+ ["/instructions", "/instructions"],
+ ["/tools/overview", "/tools"],
+ ["/skills", "/skills"],
+ ["/channels/eve", "/channels/eve"],
+ ["/channels/overview", "/channels/overview"],
+ ["/channels/slack", "/channels/slack"],
+ ["/channels/discord", "/channels/discord"],
+ ["/channels/teams", "/channels/teams"],
+ ["/channels/telegram", "/channels/telegram"],
+ ["/channels/twilio", "/channels/twilio"],
+ ["/channels/github", "/channels/github"],
+ ["/channels/linear", "/channels/linear"],
+ ["/channels/chat-sdk", "/channels/chat-sdk"],
+].flatMap(([source, destination]) => createRootMarkdownRedirects(source, destination));
+
+export const compatibilityRedirects: DocsRedirect[] = [
+ { source: "/feed", destination: "/rss.xml", permanent: true },
+ { source: "/feed.xml", destination: "/rss.xml", permanent: true },
+ { source: "/guides/hooks", destination: "/docs/guides/hooks", permanent: true },
+ {
+ source: "/apple-touch-icon-precomposed.png",
+ destination: "/apple-touch-icon.png",
+ permanent: true,
+ },
+ {
+ source: "/apple-touch-icon-120x120.png",
+ destination: "/apple-touch-icon.png",
+ permanent: true,
+ },
+ {
+ source: "/apple-touch-icon-120x120-precomposed.png",
+ destination: "/apple-touch-icon.png",
+ permanent: true,
+ },
+];
diff --git a/apps/docs/lib/geistdocs/sitemap-transform.test.ts b/apps/docs/lib/geistdocs/sitemap-transform.test.ts
new file mode 100644
index 000000000..a8fcb9783
--- /dev/null
+++ b/apps/docs/lib/geistdocs/sitemap-transform.test.ts
@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { transformSitemapMarkdown } from "./sitemap-transform";
+
+const transform = (markdown: string) =>
+ transformSitemapMarkdown(markdown, {
+ resolveTitle: (title, url) =>
+ title === "Overview" && url === "/docs/channels/overview" ? "Channels" : title,
+ templates: [{ slug: "chat", title: "Chat", description: "A persisted chat agent." }],
+ });
+
+describe("transformSitemapMarkdown", () => {
+ it("disambiguates Overview titles and adds canonical HTML identity", () => {
+ const output = transform(
+ "- [Overview](/docs/channels/overview) | Type: Conceptual | Summary: Channel docs",
+ );
+
+ expect(output).toContain(
+ "- [Channels](/docs/channels/overview) | Type: Conceptual | Summary: Channel docs | Canonical: /docs/channels/overview",
+ );
+ });
+
+ it.each([
+ ["/docs/guides/hooks", "Guide", "How-to"],
+ ["/docs/tutorial/first-agent", "Conceptual", "How-to"],
+ ["/docs/concepts/context-control", "Conceptual", "Conceptual"],
+ ["/docs/reference/cli", "Reference", "Reference"],
+ ])("classifies %s as %s", (url, inputType, expectedType) => {
+ const output = transform(`- [Page](${url}) | Type: ${inputType} | Summary: Page summary`);
+ expect(output).toContain(`Type: ${expectedType} | Summary:`);
+ });
+
+ it("adds concise template discovery without embedding template source", () => {
+ const output = transform("# Documentation Sitemap");
+
+ expect(output).toContain(
+ "- [Chat template](/templates/chat) | Type: Example | Summary: A persisted chat agent. | Canonical: /templates/chat",
+ );
+ });
+});
diff --git a/apps/docs/lib/geistdocs/sitemap-transform.ts b/apps/docs/lib/geistdocs/sitemap-transform.ts
new file mode 100644
index 000000000..21b17b8bf
--- /dev/null
+++ b/apps/docs/lib/geistdocs/sitemap-transform.ts
@@ -0,0 +1,55 @@
+interface TemplateDiscoveryEntry {
+ description: string;
+ slug: string;
+ title: string;
+}
+
+interface TransformSitemapOptions {
+ resolveTitle: (title: string, url: string) => string;
+ templates: TemplateDiscoveryEntry[];
+}
+
+const SITEMAP_ENTRY_PATTERN = /^(\s*)- \[([^\]]+)\]\(([^)]+)\) \| (.+)$/gm;
+
+const machineTypeFor = (url: string): string | undefined => {
+ if (
+ url === "/docs/getting-started" ||
+ url === "/docs/installation" ||
+ url === "/docs/install-integrations" ||
+ url.startsWith("/docs/guides/") ||
+ url.startsWith("/docs/tutorial/")
+ ) {
+ return "How-to";
+ }
+ if (url.startsWith("/docs/reference/")) return "Reference";
+ if (url.startsWith("/docs/concepts/") || url.startsWith("/docs/patterns/")) {
+ return "Conceptual";
+ }
+};
+
+const replaceType = (metadata: string, type: string | undefined): string =>
+ type ? metadata.replace(/^Type: [^|]+?(?=\s*\||$)/, `Type: ${type}`) : metadata;
+
+const addCanonical = (metadata: string, url: string): string =>
+ metadata.includes("Canonical:") ? metadata : `${metadata} | Canonical: ${url}`;
+
+export const transformSitemapMarkdown = (
+ markdown: string,
+ { resolveTitle, templates }: TransformSitemapOptions,
+): string => {
+ const transformed = markdown.replace(
+ SITEMAP_ENTRY_PATTERN,
+ (_match, indent: string, title: string, url: string, metadata: string) => {
+ const resolvedTitle = resolveTitle(title, url);
+ const typedMetadata = replaceType(metadata, machineTypeFor(url));
+ return `${indent}- [${resolvedTitle}](${url}) | ${addCanonical(typedMetadata, url)}`;
+ },
+ );
+
+ const templateLines = templates.map(
+ (template) =>
+ `- [${template.title} template](/templates/${template.slug}) | Type: Example | Summary: ${template.description} | Canonical: /templates/${template.slug}`,
+ );
+
+ return `${transformed.trimEnd()}\n\n## Templates\n\n${templateLines.join("\n")}\n`;
+};
diff --git a/apps/docs/lib/geistdocs/sitemap.test.ts b/apps/docs/lib/geistdocs/sitemap.test.ts
new file mode 100644
index 000000000..072e48ff0
--- /dev/null
+++ b/apps/docs/lib/geistdocs/sitemap.test.ts
@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import { createCanonicalSitemap } from "./sitemap";
+
+const sourceDate = new Date("2026-07-20T12:00:00.000Z");
+
+const sources = [
+ { pathname: "/" },
+ { pathname: "/docs/getting-started", lastModified: sourceDate },
+ { pathname: "/docs/getting-started", lastModified: new Date("2026-08-01") },
+ { pathname: "/integrations" },
+ { pathname: "/integrations/slack" },
+ { pathname: "/templates" },
+ { pathname: "/templates/eve-chat-template" },
+ { pathname: "/docs/channels" },
+ { pathname: "/docs/getting-started.md" },
+ { pathname: "/integrations?filter=channel" },
+ { pathname: "/en/integrations/slack" },
+ { pathname: "/llms.txt" },
+ { pathname: "/api" },
+ { pathname: "/unknown.xml" },
+];
+
+describe("createCanonicalSitemap", () => {
+ it("includes each canonical public HTML route exactly once", () => {
+ const sitemap = createCanonicalSitemap({
+ excludedPathnames: ["/docs/channels"],
+ origin: "https://eve.dev",
+ sources,
+ });
+
+ expect(sitemap.map(({ url }) => url)).toEqual([
+ "https://eve.dev/",
+ "https://eve.dev/docs/getting-started",
+ "https://eve.dev/integrations",
+ "https://eve.dev/integrations/slack",
+ "https://eve.dev/templates",
+ "https://eve.dev/templates/eve-chat-template",
+ ]);
+ });
+
+ it("excludes redirects, queries, locale aliases, machine routes, and errors", () => {
+ const urls = createCanonicalSitemap({
+ excludedPathnames: ["/docs/channels"],
+ origin: "https://eve.dev",
+ sources,
+ }).map(({ url }) => url);
+
+ expect(urls).not.toEqual(
+ expect.arrayContaining([
+ expect.stringContaining("?"),
+ expect.stringContaining("/en/"),
+ expect.stringMatching(/\.(?:md|mdx|txt|xml)$/),
+ "https://eve.dev/docs/channels",
+ "https://eve.dev/api",
+ ]),
+ );
+ });
+
+ it("uses trustworthy source dates without build-time fallbacks", () => {
+ const first = createCanonicalSitemap({ origin: "https://eve.dev", sources });
+ const second = createCanonicalSitemap({ origin: "https://eve.dev", sources });
+ const docsEntry = first.find(({ url }) => url.endsWith("/docs/getting-started"));
+ const integrationEntry = first.find(({ url }) => url.endsWith("/integrations/slack"));
+
+ expect(docsEntry?.lastModified).toEqual(sourceDate);
+ expect(docsEntry?.lastModified).not.toBe(sourceDate);
+ expect(integrationEntry).not.toHaveProperty("lastModified");
+ expect(second).toEqual(first);
+ });
+
+ it("omits invalid source dates", () => {
+ expect(
+ createCanonicalSitemap({
+ origin: "https://eve.dev",
+ sources: [{ pathname: "/docs/getting-started", lastModified: new Date("invalid") }],
+ }),
+ ).toEqual([{ url: "https://eve.dev/docs/getting-started" }]);
+ });
+});
diff --git a/apps/docs/lib/geistdocs/sitemap.ts b/apps/docs/lib/geistdocs/sitemap.ts
new file mode 100644
index 000000000..a81faaceb
--- /dev/null
+++ b/apps/docs/lib/geistdocs/sitemap.ts
@@ -0,0 +1,55 @@
+import { canonicalPathname } from "./canonical";
+
+export interface SitemapSourceEntry {
+ lastModified?: Date;
+ pathname: string;
+}
+
+export interface CanonicalSitemapEntry {
+ lastModified?: Date;
+ url: string;
+}
+
+interface CreateCanonicalSitemapOptions {
+ excludedPathnames?: Iterable<string>;
+ origin: string;
+ sources: SitemapSourceEntry[];
+}
+
+const alternateRepresentationPattern = /\.(?:md|mdx|txt|xml)$/i;
+
+const isIndexableHtmlPath = (pathname: string): boolean =>
+ pathname === "/" ||
+ pathname === "/integrations" ||
+ pathname === "/templates" ||
+ /^\/docs\/.+/.test(pathname) ||
+ /^\/integrations\/[^/]+$/.test(pathname) ||
+ /^\/templates\/[^/]+$/.test(pathname);
+
+const trustedLastModified = (value: Date | undefined): Date | undefined =>
+ value instanceof Date && Number.isFinite(value.getTime()) ? new Date(value.getTime()) : undefined;
+
+export const createCanonicalSitemap = ({
+ excludedPathnames = [],
+ origin,
+ sources,
+}: CreateCanonicalSitemapOptions): CanonicalSitemapEntry[] => {
+ const excluded = new Set(Array.from(excludedPathnames, canonicalPathname));
+ const entries = new Map<string, CanonicalSitemapEntry>();
+
+ for (const source of sources) {
+ const pathname = canonicalPathname(source.pathname);
+ if (pathname !== source.pathname) continue;
+ if (!isIndexableHtmlPath(pathname)) continue;
+ if (alternateRepresentationPattern.test(pathname)) continue;
+ if (excluded.has(pathname)) continue;
+
+ const url = new URL(pathname, `${origin.replace(/\/$/, "")}/`).toString();
+ if (entries.has(url)) continue;
+
+ const lastModified = trustedLastModified(source.lastModified);
+ entries.set(url, lastModified ? { url, lastModified } : { url });
+ }
+
+ return Array.from(entries.values()).sort((a, b) => a.url.localeCompare(b.url));
+};
diff --git a/apps/docs/next.config.ts b/apps/docs/next.config.ts
index c9f48e1d9..a97a4b9bb 100644
--- a/apps/docs/next.config.ts
+++ b/apps/docs/next.config.ts
@@ -1,6 +1,11 @@
import { createRequire } from "node:module";
import { createMDX } from "fumadocs-mdx/next";
import type { NextConfig } from "next";
+import {
+ compatibilityRedirects,
+ docsRedirects,
+ rootMarkdownRedirects,
+} from "./lib/geistdocs/redirects";
const withMDX = createMDX();
const require = createRequire(import.meta.url);
@@ -20,6 +25,7 @@ const config: NextConfig = {
transpilePackages: ["@eve/catalog"],
experimental: {
+ globalNotFound: true,
turbopackFileSystemCacheForDev: true,
},
@@ -43,15 +49,6 @@ const config: NextConfig = {
],
},
- async rewrites() {
- return [
- {
- source: "/sitemap.xml",
- destination: "https://crawled-sitemap.vercel.sh/eve.dev-.xml",
- },
- ];
- },
-
async redirects() {
return [
{
@@ -64,27 +61,9 @@ const config: NextConfig = {
destination: "/:lang/docs/getting-started",
permanent: true,
},
- {
- source: "/docs/introduction",
- destination: "/docs/getting-started",
- permanent: true,
- },
- {
- source: "/:lang/docs/introduction",
- destination: "/:lang/docs/getting-started",
- permanent: true,
- },
- // Evals moved from a single Advanced page to a top-level section.
- {
- source: "/docs/advanced/evals",
- destination: "/docs/evals/overview",
- permanent: true,
- },
- {
- source: "/:lang/docs/advanced/evals",
- destination: "/:lang/docs/evals/overview",
- permanent: true,
- },
+ ...compatibilityRedirects,
+ ...docsRedirects,
+ ...rootMarkdownRedirects,
];
},
};
diff --git a/apps/docs/package.json b/apps/docs/package.json
index 3920f661b..c5cdfe63b 100644
--- a/apps/docs/package.json
+++ b/apps/docs/package.json
@@ -24,7 +24,7 @@
"@icons-pack/react-simple-icons": "13.13.0",
"@streamdown/code": "1.1.1",
"@vercel/analytics": "2.0.1",
- "@vercel/geistdocs": "1.19.2",
+ "@vercel/geistdocs": "1.19.3",
"@vercel/speed-insights": "2.0.0",
"@vgpu/core": "0.0.7",
"@vgpu/render": "0.0.7",
diff --git a/apps/docs/proxy.ts b/apps/docs/proxy.ts
index 0f8719781..d497bfd29 100644
--- a/apps/docs/proxy.ts
+++ b/apps/docs/proxy.ts
@@ -1,9 +1,11 @@
import { createProxy } from "@vercel/geistdocs/proxy";
import { config as geistdocsConfig } from "@/lib/geistdocs/config";
+import { markdownRoutes } from "@/lib/geistdocs/markdown-routes";
import { trackMdRequest } from "@/lib/geistdocs/md-tracking";
const proxy = createProxy({
config: geistdocsConfig,
+ markdownRoutes,
trackMarkdownRequest: trackMdRequest,
before: () => null,
});
diff --git a/apps/docs/public/apple-touch-icon.png b/apps/docs/public/apple-touch-icon.png
new file mode 100644
index 000000000..e7bc78411
Binary files /dev/null and b/apps/docs/public/apple-touch-icon.png differ
diff --git a/docs/README.md b/docs/README.md
index 0ca1ef89c..cfe9ca7ef 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -47,12 +47,12 @@ Read in this order:
12. [Channels](./channels/overview.mdx)
13. [Session Context](./reference/typescript-api.md)
14. [Sessions And Streaming](./concepts/sessions-runs-and-streaming.md)
-15. [TypeScript SDK](./clients/typescript-sdk/overview.mdx)
+15. [TypeScript SDK](./guides/client/overview.mdx)
16. [Subagents](./subagents.mdx)
17. [Schedules](./schedules.mdx)
18. [Evals](./evals/overview.mdx)
-19. [Auth And Route Protection](./develop/auth-and-route-protection.md)
-20. [Vercel Deployment](./develop/deployment.md)
+19. [Auth And Route Protection](./guides/auth-and-route-protection.md)
+20. [Vercel Deployment](./guides/deployment/overview.md)
21. [CLI, Build, And Debugging](./reference/cli.md)
## The public mental model
@@ -105,5 +105,5 @@ That is why eve exposes two identifiers:
## Good companions in this repo
-- Weather-focused smoke/dev fixture: [`../../apps/fixtures/weather-fixture`](../../apps/fixtures/weather-fixture)
-- Public API source of truth: [`../../packages/eve/src/public/index.ts`](../../packages/eve/src/public/index.ts)
+- Weather-focused smoke/dev fixture: [`../apps/fixtures/weather-agent`](../apps/fixtures/weather-agent)
+- Public API source of truth: [`../packages/eve/src/public/index.ts`](../packages/eve/src/public/index.ts)
diff --git a/docs/channels/overview.mdx b/docs/channels/overview.mdx
index 4d0933c9e..ecea35864 100644
--- a/docs/channels/overview.mdx
+++ b/docs/channels/overview.mdx
@@ -9,7 +9,7 @@ A channel is the edge adapter between a platform and your agent. It does three t
- Owns the `continuationToken`, the resume handle for a conversation on that surface.
- Decides delivery, meaning how, where, and whether a response goes back.
-eve ships a base HTTP channel plus first-class platform channels, and you can author your own. Browse the full set in the [Integrations](/integrations?filter=channel) gallery.
+eve ships a base HTTP channel plus first-class platform channels, and you can author your own. Browse the full set in the [Integrations](/integrations) gallery and choose the Channels filter.
After a channel normalizes input, eve runs the same agent runtime regardless of where the message came from. Tools and instructions do not need channel-specific logic.
@@ -49,15 +49,17 @@ eve does **not** use the Chat SDK's runtime. The `Chat`, `Adapter`, and `Thread`
| You want… | Use |
| ------------------------------------------- | ---------------------------------------------------------- |
| A web app / browser chat UI | eve channel + [`useEveAgent`](../guides/frontend/overview) |
-| Local tooling, SDK clients, `curl` | eve channel (default) |
+| Local tooling, SDK clients, `curl` | [eve HTTP channel](./eve) (default) |
| Slack mentions, DMs, buttons | [Slack](./slack) |
+| iMessage | [Photon](./photon) |
| Discord slash commands, components | [Discord](./discord) |
| Microsoft Teams messages + Adaptive Cards | [Teams](./teams) |
| Telegram bot messages | [Telegram](./telegram) |
| SMS or speech-transcribed phone calls | [Twilio](./twilio) |
| GitHub @mentions, PR review with checkout | [GitHub](./github) |
| Linear issue delegation and Agent Sessions | [Linear](./linear) |
-| Anything else (internal webhook, WebSocket) | Custom channel (`defineChannel`, above) |
+| Another Chat SDK-supported service | [Chat SDK adapters](./chat-sdk) |
+| Anything else (internal webhook, WebSocket) | [Custom channel](./custom) (`defineChannel`, above) |
## Disclaimer
@@ -70,4 +72,4 @@ Where an eve agent communicates with people, you may be required to disclose tha
- [Slack](./slack): the most common platform channel, end to end
- [Custom channels](./custom): build a channel for any surface with `defineChannel`
- [Frontend](../guides/frontend/overview): browser chat on the eve channel with `useEveAgent`
-- [Integrations](/integrations?filter=channel): browse every built-in channel in one gallery
+- [Integrations](/integrations): browse every built-in channel in one gallery using the Channels filter
diff --git a/docs/connections/overview.mdx b/docs/connections/overview.mdx
index 8fcbcd93c..db71c0400 100644
--- a/docs/connections/overview.mdx
+++ b/docs/connections/overview.mdx
@@ -274,6 +274,6 @@ A tool can require both sign-in (`auth`) and a human approval. The model's appro
- [MCP connections](/docs/connections/mcp): connect to remote MCP servers.
- [OpenAPI connections](/docs/connections/openapi): generate tools from OpenAPI operations.
-- [Integrations](/integrations?filter=connection): browse every connection eve ships, in one gallery.
+- [Integrations](/integrations): browse every connection eve ships using the Connections filter.
- [Tools](/docs/tools): authored tools live alongside connection-provided tools; the same approval helpers apply.
- [Security model](/docs/concepts/security-model): how connection credentials stay out of the model's reach.
diff --git a/docs/extensions.md b/docs/extensions.md
index 0716283b5..a3f5c48ba 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -298,7 +298,7 @@ The `crm__` prefix is reserved for this directory mount. A consumer cannot overr
### Use an extension tool result in a hook
-To retain an extension tool's result type in a consumer hook, import its definition from `./tools` and pass it to [`toolResultFrom`](/guides/hooks#narrowing-tool-results):
+To retain an extension tool's result type in a consumer hook, import its definition from `./tools` and pass it to [`toolResultFrom`](/docs/guides/hooks#narrowing-tool-results):
```ts title="agent/hooks/narrow-crm.ts"
import { defineHook } from "eve/hooks";
@@ -323,7 +323,7 @@ At build time, eve checks the extension's generated capability metadata. If the
## What to read next
-- [Extension integrations](/integrations?filter=extension): browse ready-to-install extensions
+- [Integrations](/integrations): browse ready-to-install extensions using the Extensions filter
- [Tools](/docs/tools): static tools, approval, and tool output
- [Dynamic capabilities](/docs/guides/dynamic-capabilities): dynamic tools, skills, and instructions
- [Instructions](/docs/instructions): static and TypeScript instructions
diff --git a/docs/guides/hooks.md b/docs/guides/hooks.md
index 1b6898bbc..a54dbfb48 100644
--- a/docs/guides/hooks.md
+++ b/docs/guides/hooks.md
@@ -3,7 +3,7 @@ title: "Hooks"
description: "Subscribe to runtime stream events from agent/hooks/."
---
-Hooks are eve's authored extension points for the runtime event stream. A hook subscribes to stream events and runs side effects after each event is durably recorded, such as audit logging, metrics and alerting, or persisting every session and message to your own database for analytics. Reach for one to observe what the agent does without writing a tool, a context provider (a value made available across a step), or a channel adapter handler (a handler defined on a channel's adapter; see [Channels](../channels)).
+Hooks are eve's authored extension points for the runtime event stream. A hook subscribes to stream events and runs side effects after each event is durably recorded, such as audit logging, metrics and alerting, or persisting every session and message to your own database for analytics. Reach for one to observe what the agent does without writing a tool, a context provider (a value made available across a step), or a channel adapter handler (a handler defined on a channel's adapter; see [Channels](../channels/overview)).
## Define a hook
diff --git a/docs/guides/state.md b/docs/guides/state.md
index 5236f32b8..539131b92 100644
--- a/docs/guides/state.md
+++ b/docs/guides/state.md
@@ -69,7 +69,7 @@ Every [subagent](../subagents) starts with its own fresh state, whether it's a b
## State vs. connection-side storage
-`defineState` holds conversation-scoped working memory that lives and dies with the session, including counters, the current plan, and what the user has told you this conversation. It is the agent's short-term memory, persisted durably for the life of the session. Anything that has to outlive the session, be shared across sessions or users, or be queried independently of a turn belongs in an external store. Start with a packaged [memory integration](/integrations?filter=memory), a general [connection](../connections), or your own database.
+`defineState` holds conversation-scoped working memory that lives and dies with the session, including counters, the current plan, and what the user has told you this conversation. It is the agent's short-term memory, persisted durably for the life of the session. Anything that has to outlive the session, be shared across sessions or users, or be queried independently of a turn belongs in an external store. Start with a packaged memory provider from the [integration gallery](/integrations) using the Memory filter, a general [connection](../connections), or your own database.
## What to read next
diff --git a/docs/patterns/multi-tenant-memory.md b/docs/patterns/multi-tenant-memory.md
index 57a1b4b80..51fdd8723 100644
--- a/docs/patterns/multi-tenant-memory.md
+++ b/docs/patterns/multi-tenant-memory.md
@@ -3,7 +3,7 @@ title: "Multi-tenant memory"
description: "Compose dynamic instructions, authenticated session context, and ordinary tools into tenant-scoped long-term memory."
---
-You can add long-term memory with a packaged [memory integration](/integrations?filter=memory), or build tenant-aware memory from your own application store by composing three existing eve primitives:
+You can add long-term memory from the [integration gallery](/integrations) using the Memory filter, or build tenant-aware memory from your own application store by composing three existing eve primitives:
1. route auth puts the tenant and user on `ctx.session.auth`;
2. dynamic instructions load that caller's memories before each turn;
diff --git a/docs/reference/meta.json b/docs/reference/meta.json
index c667486ff..95edf9b9e 100644
--- a/docs/reference/meta.json
+++ b/docs/reference/meta.json
@@ -1,4 +1,4 @@
{
"title": "Reference",
- "pages": ["http-api", "typescript-api", "cli", "project-layout"]
+ "pages": ["typescript-api", "cli", "project-layout"]
}
diff --git a/docs/tools/human-in-the-loop.md b/docs/tools/human-in-the-loop.md
index 019be2bc4..a4c9cab13 100644
--- a/docs/tools/human-in-the-loop.md
+++ b/docs/tools/human-in-the-loop.md
@@ -115,7 +115,7 @@ See [Sessions, runs & streaming](/docs/concepts/sessions-runs-and-streaming) for
## Answering from a client or channel
-Channels turn requests into native UI: the Slack adapter renders approvals as buttons and questions as select menus, and writes the user's choice back as the answer. You get this for free on every [channel](/docs/channels).
+Channels turn requests into native UI: the Slack adapter renders approvals as buttons and questions as select menus, and writes the user's choice back as the answer. You get this for free on every [channel](/docs/channels/overview).
From your own frontend, read the pending request off the latest message and answer through the same session — see [Building a frontend](/docs/guides/frontend/overview#human-in-the-loop-prompts) for the client-side reducer and `inputResponses` shape.
diff --git a/packages/eve/README.md b/packages/eve/README.md
index 97ff903b4..da4c30f95 100644
--- a/packages/eve/README.md
+++ b/packages/eve/README.md
@@ -140,7 +140,7 @@ CLI commands:
## Deploying
-eve is built to be durable. The runtime is Nitro + Workflows. Read the [deployment guide](https://eve.dev/docs/guides/deployment) for the deployment path, environment variables, and configuration.
+eve is built to be durable. The runtime is Nitro + Workflows. Read the [deployment guide](https://eve.dev/docs/guides/deployment/overview) for the deployment path, environment variables, and configuration.
## Read Next
@@ -151,7 +151,7 @@ These files ship inside the installed package at `node_modules/eve/docs/`:
- [Project Layout](https://eve.dev/docs/reference/project-layout) — every authored directory in depth
- [`agent.ts`](https://eve.dev/docs/agent-config) — agent config reference
- [TypeScript API](https://eve.dev/docs/reference/typescript-api) — complete `define*` and runtime helper reference
-- [Vercel Deployment](https://eve.dev/docs/guides/deployment) — deploy to production
+- [Vercel Deployment](https://eve.dev/docs/guides/deployment/overview) — deploy to production
By authoring concern: [Tools](https://eve.dev/docs/tools) · [Channels](https://eve.dev/docs/channels/overview) · [Hooks](https://eve.dev/docs/guides/hooks) · [Skills](https://eve.dev/docs/skills) · [Sandbox](https://eve.dev/docs/sandbox) · [Connections](https://eve.dev/docs/connections) · [Subagents](https://eve.dev/docs/subagents) · [Schedules](https://eve.dev/docs/schedules) · [Evals](https://eve.dev/docs/evals/overview)
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d475b857c..daa943fc7 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -153,8 +153,8 @@ importers:
specifier: 2.0.1
'@vercel/geistdocs':
- specifier: 1.19.2
- version: 1.19.2(9e720ded9dcd1bda98eee6f07251de0a)
+ specifier: 1.19.3
+ version: 1.19.3(9e720ded9dcd1bda98eee6f07251de0a)
'@vercel/speed-insights':
specifier: 2.0.0
@@ -7654,8 +7654,8 @@ packages:
'@vercel/[email protected]':
resolution: {integrity: sha512-H1qNhnvyRIhek/esVnVK+RoFsxrSOLl4qiM4iyV2IcjDoqY4H0Ped65tc5ZgZEP/P2KGNYfEDSBEukdBZa+kCg==}
- '@vercel/[email protected]':
- resolution: {integrity: sha512-LOxbVHAVsfWIkBIo98TUNL2pRKBL/XrthAxgGm3eYP57G9xlKSTRsA43mpnZ1k80rUz1IzhLrGFffOIV6UR7oQ==}
+ '@vercel/[email protected]':
+ resolution: {integrity: sha512-mz3Jx+ZwDOFGkqrG83CtT9jDFVrjOzIyZ0Kh14SbcapwByk9Lq08CnoWiuXdr3GB82MRlDAIagKDnjSwHgV66w==}
hasBin: true
peerDependencies:
next: ^16.2.11
@@ -21953,7 +21953,7 @@ snapshots:
etag: 1.8.1
fs-extra: 11.1.0
- '@vercel/[email protected](9e720ded9dcd1bda98eee6f07251de0a)':
+ '@vercel/[email protected](9e720ded9dcd1bda98eee6f07251de0a)':
dependencies:
'@ai-sdk/react': 3.0.193([email protected])([email protected])
'@clack/prompts': 0.11.0
diff --git a/scripts/check-docs.mjs b/scripts/check-docs.mjs
index bc3b02aef..8cd4ba39f 100755
--- a/scripts/check-docs.mjs
+++ b/scripts/check-docs.mjs
@@ -21,8 +21,8 @@
* Files intentionally not part of the site (the top-level engineer-facing
* README.md in each root) are skipped via isExcluded().
*/
-import { readdirSync, readFileSync, statSync } from "node:fs";
-import { relative, resolve } from "node:path";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
import { fileURLToPath } from "node:url";
const ROOTS = [
@@ -200,17 +200,11 @@ function renderedUrl(relPath, source) {
function checkLinks(rootDir) {
const files = walkMarkdown(rootDir);
const renderedUrls = new Set();
- const renderedDirs = new Set();
for (const abs of files) {
const rel = relative(rootDir, abs).split("\\").join("/");
if (isExcluded(rel)) continue;
const source = readFileSync(abs, "utf8");
renderedUrls.add(renderedUrl(rel, source));
- let dir = rel.includes("/") ? rel.slice(0, rel.lastIndexOf("/")) : "";
- while (dir) {
- renderedDirs.add(`/docs/${dir}`);
- dir = dir.includes("/") ? dir.slice(0, dir.lastIndexOf("/")) : "";
- }
}
const linkRe = /\]\((\s*[^)]+?)\s*\)/g;
for (const abs of files) {
@@ -233,7 +227,6 @@ function checkLinks(rootDir) {
.replace(/\.mdx?$/, "");
if (resolvedUrl === "/docs") continue; // docs root / index
if (renderedUrls.has(resolvedUrl)) continue;
- if (renderedDirs.has(resolvedUrl)) continue; // folder link (sidebar group)
failures.push({
root: "docs",
file: rel,
@@ -243,7 +236,90 @@ function checkLinks(rootDir) {
}
}
+function checkMetaReferences(rootDir) {
+ const visit = (dir) => {
+ const meta = loadMetaJson(dir);
+ if (meta && Array.isArray(meta.pages)) {
+ for (const entry of meta.pages) {
+ if (typeof entry !== "string") continue;
+ if (entry === "..." || entry === "z...z" || entry === "---") continue;
+ if (/^---.+---$/.test(entry)) continue;
+ if (entry.startsWith("[")) continue;
+
+ const slug = entry.startsWith("!") ? entry.slice(1) : entry;
+ const candidates = [
+ resolve(dir, slug),
+ resolve(dir, `${slug}.md`),
+ resolve(dir, `${slug}.mdx`),
+ ];
+ if (candidates.some((candidate) => existsSync(candidate))) continue;
+
+ failures.push({
+ root: "docs",
+ file: `${relative(rootDir, dir) || "."}/meta.json`,
+ issue: `meta.json#pages entry \`${entry}\` does not resolve to a page or navigation folder`,
+ });
+ }
+ }
+
+ for (const entry of readdirSync(dir)) {
+ const full = resolve(dir, entry);
+ if (statSync(full).isDirectory()) visit(full);
+ }
+ };
+
+ visit(rootDir);
+}
+
+function checkRepositoryMarkdownLinks(absPath) {
+ const source = readFileSync(absPath, "utf8");
+ const linkRe = /\]\((\s*[^)]+?)\s*\)/g;
+ let match;
+
+ while ((match = linkRe.exec(source)) !== null) {
+ const target = match[1].trim().split("#")[0].split("?")[0];
+ if (!target || target.startsWith("/") || /^[a-z]+:/i.test(target)) continue;
+ if (existsSync(resolve(dirname(absPath), target))) continue;
+
+ failures.push({
+ root: "docs",
+ file: relative(ROOTS[0].dir, absPath),
+ issue: `broken repository link → \`${match[1].trim()}\``,
+ });
+ }
+}
+
+function checkChannelHubLinks(rootDir) {
+ const hubPath = resolve(rootDir, "channels/overview.mdx");
+ const source = readFileSync(hubPath, "utf8");
+ const linkedRoutes = new Set();
+ const linkRe = /\]\((\s*[^)]+?)\s*\)/g;
+ let match;
+
+ while ((match = linkRe.exec(source)) !== null) {
+ const target = match[1].trim().split("#")[0].split("?")[0];
+ if (!target || (!target.startsWith("./") && !target.startsWith("/docs/"))) continue;
+ linkedRoutes.add(new URL(target, "https://eve.dev/docs/channels/overview").pathname);
+ }
+
+ const meta = loadMetaJson(resolve(rootDir, "channels"));
+ for (const slug of meta?.pages ?? []) {
+ if (typeof slug !== "string" || slug === "overview") continue;
+ const expected = `/docs/channels/${slug}`;
+ if (linkedRoutes.has(expected)) continue;
+
+ failures.push({
+ root: "docs",
+ file: "channels/overview.mdx",
+ issue: `channel hub does not link to canonical child route \`${expected}\``,
+ });
+ }
+}
+
checkLinks(ROOTS[0].dir);
+checkMetaReferences(ROOTS[0].dir);
+checkRepositoryMarkdownLinks(resolve(ROOTS[0].dir, "README.md"));
+checkChannelHubLinks(ROOTS[0].dir);
if (failures.length === 0) {
process.stdout.write(