Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

docs: reorganize navigation and consolidate guides (#1916)

Colton Padden09aa810829c1
diff --git a/.agents/skills/technical-writing/references/content-types.md b/.agents/skills/technical-writing/references/content-types.md
index ad907558d..00636e906 100644
--- a/.agents/skills/technical-writing/references/content-types.md
+++ b/.agents/skills/technical-writing/references/content-types.md
@@ -18,6 +18,16 @@ Document APIs, CLI commands, configuration, limits, or schemas for lookup. Use e
Explain how or why a system works. Define the mental model, boundaries, tradeoffs, and related tasks without turning the page into a procedural guide.
+## Information architecture
+
+Organize navigation for progressive disclosure: a reader should meet the smallest useful surface first and find depth by descending, not by scanning.
+
+- Keep the top-level sidebar lean. `docs/meta.json` sections move from orientation (Introduction) through authoring (Build), connecting (Integrate), and running (Operate) to lookup (Reference).
+- Nest a page under the capability that owns it when the page only matters after the reader knows the parent (for example, Workflow Tool under Subagents, State under Core Concepts).
+- Promote a page to the top level only when readers need it before or independently of any parent capability.
+- Lead every page and section with the common case; push advanced options, edge cases, and internals further down or into a nested page.
+- When moving a published route, update authored links and add permanent redirects for every old HTML and Markdown URL, and keep `llms-index.ts` in step with the sidebar.
+
## Decide whether to create a page
Create a page only when all are true:
diff --git a/apps/docs/components/geistdocs/docs-layout.tsx b/apps/docs/components/geistdocs/docs-layout.tsx
index 560ecf66e..f52eea38e 100644
--- a/apps/docs/components/geistdocs/docs-layout.tsx
+++ b/apps/docs/components/geistdocs/docs-layout.tsx
@@ -13,6 +13,7 @@ export const DocsLayout = ({ tree, children }: DocsLayoutProps) => (
containerProps={{
className: "max-w-[1448px] mx-auto",
}}
+ sidebarMode="tree"
tree={tree}
>
{children}
diff --git a/apps/docs/lib/geistdocs/llms-index.test.ts b/apps/docs/lib/geistdocs/llms-index.test.ts
index be1d56c3e..bafa57c4c 100644
--- a/apps/docs/lib/geistdocs/llms-index.test.ts
+++ b/apps/docs/lib/geistdocs/llms-index.test.ts
@@ -7,6 +7,12 @@ describe("createLlmsIndex", () => {
expect(output).toMatch(/^# eve\n\n> /);
expect(output).not.toMatch(/^---/);
+ expect(output).toContain("## Introduction");
+ expect(output).toContain("## Build");
+ expect(output).toContain("## Integrate");
+ expect(output).toContain("## Operate");
+ expect(output).not.toContain("## Application Integration");
+ expect(output).toContain("## Core Concepts");
expect(output).toContain("## Optional");
});
diff --git a/apps/docs/lib/geistdocs/llms-index.ts b/apps/docs/lib/geistdocs/llms-index.ts
index 87b15fed7..4a82cd53c 100644
--- a/apps/docs/lib/geistdocs/llms-index.ts
+++ b/apps/docs/lib/geistdocs/llms-index.ts
@@ -10,67 +10,83 @@ eve.dev publishes framework documentation. It is not a shared API, authorization
Documentation links below point directly to Markdown. Remove the \`.md\` suffix for the canonical HTML page.
-## Start here
+## Introduction
-- [Getting started](${EVE_ORIGIN}/docs/getting-started.md): Choose the right path for a new or existing eve project.
-- [Installation](${EVE_ORIGIN}/docs/installation.md): Create a project, configure a model credential, and run it locally.
-- [Project structure](${EVE_ORIGIN}/docs/project-structure.md): Learn which files eve discovers and how paths define capabilities.
-- [First-agent tutorial](${EVE_ORIGIN}/docs/tutorial/first-agent.md): Build an agent with tools, durable state, and an interface.
+- [Getting Started](${EVE_ORIGIN}/docs/getting-started.md): Create a project, configure a model, understand its layout, and run it locally.
-## Author an agent
+## Core Concepts
-- [Agent configuration](${EVE_ORIGIN}/docs/agent-config.md): Configure the model, reasoning effort, compaction, and runtime behavior.
+- [Execution Model and Durability](${EVE_ORIGIN}/docs/concepts/execution-model-and-durability.md): Understand sessions, checkpointed steps, and parked work.
+- [Sessions, Runs, and Streaming](${EVE_ORIGIN}/docs/concepts/sessions-runs-and-streaming.md): Understand session IDs, NDJSON events, controls, and reconnecting.
+- [Default Harness](${EVE_ORIGIN}/docs/concepts/default-harness.md): Understand the built-in loop, tools, workspace, and context assembly.
+- [Context Control](${EVE_ORIGIN}/docs/concepts/context-control.md): Choose what the model sees and when.
+- [Security Model](${EVE_ORIGIN}/docs/concepts/security-model.md): Review trust boundaries, secret handling, credentials, and fail-closed behavior.
+
+## Build
+
+- [Agents](${EVE_ORIGIN}/docs/agent-config.md): Configure the model, reasoning effort, compaction, and runtime behavior.
- [Instructions](${EVE_ORIGIN}/docs/instructions.md): Write the agent's always-on system prompt.
- [Tools](${EVE_ORIGIN}/docs/tools.md): Define typed actions and gate sensitive calls on human approval.
-- [Skills](${EVE_ORIGIN}/docs/skills.md): Add procedures that the model loads on demand.
-- [Channels](${EVE_ORIGIN}/docs/channels/overview.md): Expose the agent through HTTP, Slack, Discord, and other messaging surfaces.
- [Connections](${EVE_ORIGIN}/docs/connections.md): Connect external MCP and OpenAPI servers without exposing credentials to the model.
-- [Extensions](${EVE_ORIGIN}/docs/extensions.md): Package and mount reusable eve capabilities.
+- [Channels](${EVE_ORIGIN}/docs/channels/overview.md): Expose the agent through HTTP, Slack, Discord, and other messaging surfaces.
+- [Base eve Channel](${EVE_ORIGIN}/docs/channels/eve.md): Understand the HTTP API exposed by each running eve app.
+- [Skills](${EVE_ORIGIN}/docs/skills.md): Add procedures that the model loads on demand.
- [Sandbox](${EVE_ORIGIN}/docs/sandbox.md): Configure the isolated shell, filesystem, lifecycle, and network policy.
- [Subagents](${EVE_ORIGIN}/docs/subagents.md): Delegate work to copies of the root agent or declared specialists.
-- [Schedules](${EVE_ORIGIN}/docs/schedules.md): Run prompts or handlers on a cron cadence.
- [Evals](${EVE_ORIGIN}/docs/evals/overview.md): Define repeatable scored checks and run them with \`eve eval\`.
+- [Durable State](${EVE_ORIGIN}/docs/concepts/state.md): Persist per-session memory across step boundaries.
+- [Session Context](${EVE_ORIGIN}/docs/guides/session-context.md): Use session metadata and runtime accessors in authored code.
+- [Schedules](${EVE_ORIGIN}/docs/schedules.md): Run prompts or handlers on a cron cadence.
+- [Hooks](${EVE_ORIGIN}/docs/guides/hooks.md): Subscribe to runtime stream events.
+- [Dynamic Capabilities](${EVE_ORIGIN}/docs/guides/dynamic-capabilities.md): Resolve models, tools, skills, subagents, and instructions at runtime.
+- [Workflow Tool](${EVE_ORIGIN}/docs/subagents/workflow-tool.md): Let the model orchestrate subagents through the experimental Workflow tool.
-## Connect clients and interfaces
+## Integrate
-- [Base eve channel](${EVE_ORIGIN}/docs/channels/eve.md): Understand the HTTP API exposed by each running eve app.
-- [Frontend overview](${EVE_ORIGIN}/docs/guides/frontend/overview.md): Build browser chat interfaces with \`useEveAgent\`.
+- [Add Integrations](${EVE_ORIGIN}/docs/install-integrations.md): Discover and add official or third-party integrations.
+- [Extensions](${EVE_ORIGIN}/docs/extensions.md): Package and mount reusable eve capabilities.
+- [Remote Agents](${EVE_ORIGIN}/docs/guides/remote-agents.md): Call another eve deployment as a subagent.
+- [Agent Client Protocol (ACP)](${EVE_ORIGIN}/docs/protocols/acp.md): Use local or deployed eve agents from ACP clients.
+- [Universal Commerce Protocol (UCP)](${EVE_ORIGIN}/docs/protocols/ucp.md): Serve a UCP profile from a custom eve channel.
+- [Frontend Frameworks](${EVE_ORIGIN}/docs/guides/frontend/overview.md): Build browser chat interfaces with \`useEveAgent\`.
- [Next.js](${EVE_ORIGIN}/docs/guides/frontend/nextjs.md): Mount eve routes and use the React client in Next.js.
- [Nuxt](${EVE_ORIGIN}/docs/guides/frontend/nuxt.md): Mount eve routes and use the Vue client in Nuxt.
- [SvelteKit](${EVE_ORIGIN}/docs/guides/frontend/sveltekit.md): Mount eve routes and use the Svelte client in SvelteKit.
-- [TypeScript SDK](${EVE_ORIGIN}/docs/guides/client/overview.md): Call an eve app from scripts, services, tests, or custom UIs.
-- [Sessions, runs, and streaming](${EVE_ORIGIN}/docs/concepts/sessions-runs-and-streaming.md): Understand continuation tokens, stream handles, NDJSON events, and reconnecting.
-- [Authentication and route protection](${EVE_ORIGIN}/docs/guides/auth-and-route-protection.md): Secure a deployed app's routes and connection OAuth.
+- [Client SDK](${EVE_ORIGIN}/docs/guides/client/overview.md): Call an eve app from scripts, services, tests, or custom UIs.
-## Run and operate
+## Operate
-- [Execution model and durability](${EVE_ORIGIN}/docs/concepts/execution-model-and-durability.md): Understand sessions, checkpointed steps, and parked work.
-- [Default harness](${EVE_ORIGIN}/docs/concepts/default-harness.md): Understand the built-in loop, tools, workspace, and context assembly.
-- [Context control](${EVE_ORIGIN}/docs/concepts/context-control.md): Control context growth, compaction, and model-visible history.
-- [Security model](${EVE_ORIGIN}/docs/concepts/security-model.md): Review trust boundaries, secret handling, credentials, and fail-closed behavior.
-- [Deployment overview](${EVE_ORIGIN}/docs/guides/deployment/overview.md): Choose between Vercel and self-hosted infrastructure.
+- [Deployment Overview](${EVE_ORIGIN}/docs/guides/deployment/overview.md): Choose between Vercel and self-hosted infrastructure.
- [Deploy to Vercel](${EVE_ORIGIN}/docs/guides/deployment/vercel.md): Build and deploy with Vercel Workflow and Vercel Sandbox.
-- [Self-hosting](${EVE_ORIGIN}/docs/guides/deployment/self-hosting.md): Run eve as a Node service or container.
-- [Instrumentation](${EVE_ORIGIN}/docs/guides/instrumentation.md): Trace agents with OpenTelemetry and inspect workflow metadata.
-- [Hooks](${EVE_ORIGIN}/docs/guides/hooks.md): Subscribe to runtime stream events.
-- [Durable state](${EVE_ORIGIN}/docs/guides/state.md): Persist per-session memory across step boundaries.
-- [Dynamic capabilities](${EVE_ORIGIN}/docs/guides/dynamic-capabilities.md): Resolve models, tools, skills, subagents, and instructions at runtime.
-- [Remote agents](${EVE_ORIGIN}/docs/guides/remote-agents.md): Call another eve deployment as a subagent.
+- [Self-Hosting](${EVE_ORIGIN}/docs/guides/deployment/self-hosting.md): Run eve as a Node service or container.
+- [Authentication](${EVE_ORIGIN}/docs/guides/auth-and-route-protection.md): Secure an agent's HTTP routes and establish caller identity.
+- [Observability](${EVE_ORIGIN}/docs/guides/instrumentation.md): Trace agents with OpenTelemetry and inspect workflow metadata.
+- [Terminal UI](${EVE_ORIGIN}/docs/guides/dev-tui.md): Work with a local or deployed agent from the interactive terminal UI.
+
+## Tutorial
+
+- [Tutorial](${EVE_ORIGIN}/docs/tutorial/first-agent.md): Build an agent with tools, durable state, and an interface.
+
+## Patterns
+
+- [Multi-Tenant Memory](${EVE_ORIGIN}/docs/patterns/multi-tenant-memory.md): Compose tenant-scoped long-term memory from dynamic instructions and tools.
+- [Dynamic Scheduling](${EVE_ORIGIN}/docs/patterns/dynamic-scheduling.md): Build application-managed schedules from an eve schedule and authored tools.
+- [Multi-Tenant Outbound Auth](${EVE_ORIGIN}/docs/patterns/multi-tenant-auth.md): Select tenant-scoped credentials for tools and connections.
+- [Multi-Tenant Approvals](${EVE_ORIGIN}/docs/patterns/multi-tenant-approvals.md): Apply tenant policy to authored and connection tools.
-## Reference and discovery
+## API Reference and Discovery
-- [TypeScript API](${EVE_ORIGIN}/docs/reference/typescript-api.md): Find public \`define*\` helpers, runtime context, and import paths.
-- [CLI reference](${EVE_ORIGIN}/docs/reference/cli.md): Find every eve command and option.
-- [Project layout reference](${EVE_ORIGIN}/docs/reference/project-layout.md): Look up authored slots and path-derived naming rules.
-- [Install integrations](${EVE_ORIGIN}/docs/install-integrations.md): Discover and add official or third-party integrations.
-- [Documentation map](${EVE_ORIGIN}/sitemap.md): Browse every documentation, integration, and template page with type and summary metadata.
-- [Agent instructions](${EVE_ORIGIN}/agents.md): Read operational guidance for coding agents working with eve.
-- [Full documentation corpus](${EVE_ORIGIN}/llms-full.txt): Load all docs and integration content for offline indexing or a large context window.
+- [TypeScript API Reference](${EVE_ORIGIN}/docs/reference/typescript-api.md): Find public \`define*\` helpers, runtime context, and import paths.
+- [CLI Reference](${EVE_ORIGIN}/docs/reference/cli.md): Find every eve command and option.
+- [Responsible Use](${EVE_ORIGIN}/docs/responsible-use.md): Review deployer responsibilities and safeguards.
+- [Documentation Map](${EVE_ORIGIN}/sitemap.md): Browse every documentation, integration, and template page with type and summary metadata.
+- [Agent Instructions](${EVE_ORIGIN}/agents.md): Read operational guidance for coding agents working with eve.
+- [Full Documentation Corpus](${EVE_ORIGIN}/llms-full.txt): Load all docs and integration content for offline indexing or a large context window.
## Optional
- [Integrations](${EVE_ORIGIN}/integrations): Browse official channels, connections, extensions, and instrumentation providers.
- [Templates](${EVE_ORIGIN}/templates): Browse complete example projects and their source.
-- [Official eve skill](https://github.com/vercel/eve/blob/main/skills/eve/SKILL.md): Install or inspect the coding-agent skill; its guidance defers to version-matched bundled docs.
-- [Source repository](https://github.com/vercel/eve): Read source, releases, issues, and contribution guidance.
+- [Official eve Skill](https://github.com/vercel/eve/blob/main/skills/eve/SKILL.md): Install or inspect the coding-agent skill; its guidance defers to version-matched bundled docs.
+- [Source Repository](https://github.com/vercel/eve): Read source, releases, issues, and contribution guidance.
`;
diff --git a/apps/docs/lib/geistdocs/page-title.test.ts b/apps/docs/lib/geistdocs/page-title.test.ts
index ae5c85c50..85ed3b3cc 100644
--- a/apps/docs/lib/geistdocs/page-title.test.ts
+++ b/apps/docs/lib/geistdocs/page-title.test.ts
@@ -7,7 +7,6 @@ describe("resolveDocsPageTitle", () => {
["/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) => {
diff --git a/apps/docs/lib/geistdocs/page-title.ts b/apps/docs/lib/geistdocs/page-title.ts
index eaf1a8177..b457baaca 100644
--- a/apps/docs/lib/geistdocs/page-title.ts
+++ b/apps/docs/lib/geistdocs/page-title.ts
@@ -19,7 +19,6 @@ const docsSeoTitles: Readonly<Record<string, string>> = {
"/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",
};
diff --git a/apps/docs/lib/geistdocs/redirects.test.ts b/apps/docs/lib/geistdocs/redirects.test.ts
index 2006f1c58..225b20cd5 100644
--- a/apps/docs/lib/geistdocs/redirects.test.ts
+++ b/apps/docs/lib/geistdocs/redirects.test.ts
@@ -48,15 +48,15 @@ describe("createDocsRedirects", () => {
describe("createRootMarkdownRedirects", () => {
it("redirects only explicit Markdown representations into docs", () => {
- expect(createRootMarkdownRedirects("/installation", "/installation")).toEqual([
+ expect(createRootMarkdownRedirects("/installation", "/getting-started")).toEqual([
{
source: "/installation.md",
- destination: "/docs/installation.md",
+ destination: "/docs/getting-started.md",
permanent: true,
},
{
source: "/installation.mdx",
- destination: "/docs/installation.mdx",
+ destination: "/docs/getting-started.mdx",
permanent: true,
},
]);
@@ -105,12 +105,24 @@ describe("docsRedirects", () => {
["/docs/channels", "/docs/channels/overview"],
["/docs/guides/deployment.md", "/docs/guides/deployment/overview.md"],
["/docs/introduction.md", "/docs/getting-started.md"],
+ ["/docs/installation", "/docs/getting-started"],
+ ["/docs/installation.md", "/docs/getting-started.md"],
+ ["/docs/project-structure", "/docs/getting-started"],
+ ["/docs/project-structure.md", "/docs/getting-started.md"],
["/docs/reference/http-api", "/docs/channels/eve"],
- ["/docs/project-layout", "/docs/reference/project-layout"],
+ ["/docs/project-layout", "/docs/getting-started"],
+ ["/docs/reference/project-layout", "/docs/getting-started"],
+ ["/docs/reference/project-layout.md", "/docs/getting-started.md"],
["/docs/dynamic-capabilities", "/docs/guides/dynamic-capabilities"],
- ["/docs/dynamic-workflows", "/docs/guides/dynamic-workflows"],
+ ["/docs/guides/state", "/docs/concepts/state"],
+ ["/docs/dynamic-workflows", "/docs/subagents/workflow-tool"],
+ ["/docs/guides/dynamic-workflows", "/docs/subagents/workflow-tool"],
["/docs/sessions", "/docs/concepts/sessions-runs-and-streaming"],
["/docs/agent", "/docs/agent-config"],
+ ["/docs/guides/acp", "/docs/protocols/acp"],
+ ["/docs/guides/acp.md", "/docs/protocols/acp.md"],
+ ["/docs/guides/ucp", "/docs/protocols/ucp"],
+ ["/docs/guides/ucp.mdx", "/docs/protocols/ucp.mdx"],
["/docs/evals", "/docs/evals/overview"],
])("redirects %s to %s", (source, destination) => {
expect(docsRedirects).toContainEqual({ source, destination, permanent: true });
@@ -120,6 +132,8 @@ describe("docsRedirects", () => {
describe("rootMarkdownRedirects", () => {
it.each([
["/getting-started.mdx", "/docs/getting-started.mdx"],
+ ["/installation.md", "/docs/getting-started.md"],
+ ["/project-structure.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) => {
diff --git a/apps/docs/lib/geistdocs/redirects.ts b/apps/docs/lib/geistdocs/redirects.ts
index b3ec350d8..05099d88e 100644
--- a/apps/docs/lib/geistdocs/redirects.ts
+++ b/apps/docs/lib/geistdocs/redirects.ts
@@ -46,14 +46,21 @@ export const createIntegrationRedirects = (source: string, destination: string):
export const docsRedirects: DocsRedirect[] = [
...createDocsRedirects("/introduction", "/getting-started"),
+ ...createDocsRedirects("/installation", "/getting-started"),
+ ...createDocsRedirects("/project-structure", "/getting-started"),
...createDocsRedirects("/channels", "/channels/overview"),
...createDocsRedirects("/channels/http", "/channels/eve"),
...createDocsRedirects("/reference/http-api", "/channels/eve"),
- ...createDocsRedirects("/project-layout", "/reference/project-layout"),
+ ...createDocsRedirects("/project-layout", "/getting-started"),
+ ...createDocsRedirects("/reference/project-layout", "/getting-started"),
...createDocsRedirects("/dynamic-capabilities", "/guides/dynamic-capabilities"),
- ...createDocsRedirects("/dynamic-workflows", "/guides/dynamic-workflows"),
+ ...createDocsRedirects("/guides/state", "/concepts/state"),
+ ...createDocsRedirects("/dynamic-workflows", "/subagents/workflow-tool"),
+ ...createDocsRedirects("/guides/dynamic-workflows", "/subagents/workflow-tool"),
...createDocsRedirects("/sessions", "/concepts/sessions-runs-and-streaming"),
...createDocsRedirects("/agent", "/agent-config"),
+ ...createDocsRedirects("/guides/acp", "/protocols/acp"),
+ ...createDocsRedirects("/guides/ucp", "/protocols/ucp"),
...createDocsRedirects("/guides/deployment", "/guides/deployment/overview"),
...createDocsRedirects("/deployment", "/guides/deployment/overview"),
...createDocsRedirects("/deployment/overview", "/guides/deployment/overview"),
@@ -62,16 +69,16 @@ export const docsRedirects: DocsRedirect[] = [
...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/installation", "/getting-started"),
+ ...createDocsRedirects("/getting-started/project-structure", "/getting-started"),
...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"],
+ ["/installation", "/getting-started"],
+ ["/project-structure", "/getting-started"],
["/instructions", "/instructions"],
["/tools/overview", "/tools"],
["/skills", "/skills"],
diff --git a/apps/docs/lib/geistdocs/sitemap-transform.test.ts b/apps/docs/lib/geistdocs/sitemap-transform.test.ts
index c1c0183ed..bf577b73c 100644
--- a/apps/docs/lib/geistdocs/sitemap-transform.test.ts
+++ b/apps/docs/lib/geistdocs/sitemap-transform.test.ts
@@ -23,6 +23,7 @@ describe("transformSitemapMarkdown", () => {
it.each([
["/docs/guides/hooks", "Guide", "How-to"],
+ ["/docs/protocols/acp", "Guide", "How-to"],
["/docs/tutorial/first-agent", "Conceptual", "How-to"],
["/docs/concepts/context-control", "Conceptual", "Conceptual"],
["/docs/reference/cli", "Reference", "Reference"],
diff --git a/apps/docs/lib/geistdocs/sitemap-transform.ts b/apps/docs/lib/geistdocs/sitemap-transform.ts
index 2a30dc6e1..8fe7c9896 100644
--- a/apps/docs/lib/geistdocs/sitemap-transform.ts
+++ b/apps/docs/lib/geistdocs/sitemap-transform.ts
@@ -14,9 +14,9 @@ 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/protocols/") ||
url.startsWith("/docs/tutorial/")
) {
return "How-to";
diff --git a/docs/README.md b/docs/README.md
index 194af436a..526616518 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -34,26 +34,24 @@ Casing convention:
Read in this order:
1. [Getting Started](./getting-started.mdx)
-2. [Installation](./installation.mdx)
-3. [Project Structure](./project-structure.mdx)
-4. [Project Layout](./reference/project-layout.md)
-5. [`agent.ts`](./agent-config.md)
-6. [TypeScript API](./reference/typescript-api.md)
-7. [Context Control](./concepts/context-control.md)
-8. [Skills](./skills.mdx)
-9. [Tools](./tools/overview.mdx)
-10. [Connections](./connections/overview.mdx)
-11. [Sandboxes](./sandbox.mdx)
-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](./guides/client/overview.mdx)
-16. [Subagents](./subagents.mdx)
-17. [Schedules](./schedules.mdx)
-18. [Evals](./evals/overview.mdx)
-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)
+2. [Tutorial](./tutorial/first-agent.mdx)
+3. [Agents](./agent-config.md)
+4. [TypeScript API Reference](./reference/typescript-api.md)
+5. [Context Control](./concepts/context-control.md)
+6. [Skills](./skills.mdx)
+7. [Tools](./tools/overview.mdx)
+8. [Connections](./connections/overview.mdx)
+9. [Sandboxes](./sandbox.mdx)
+10. [Channels](./channels/overview.mdx)
+11. [Session Context](./guides/session-context.md)
+12. [Sessions and Streaming](./concepts/sessions-runs-and-streaming.md)
+13. [Client SDK](./guides/client/overview.mdx)
+14. [Subagents](./subagents/index.mdx)
+15. [Schedules](./schedules.mdx)
+16. [Evals](./evals/overview.mdx)
+17. [Authentication](./guides/auth-and-route-protection.md)
+18. [Deployment](./guides/deployment/overview.md)
+19. [CLI](./reference/cli.md)
## The public mental model
diff --git a/docs/agent-config.md b/docs/agent-config.md
index 3faddf5ab..a5d86f9be 100644
--- a/docs/agent-config.md
+++ b/docs/agent-config.md
@@ -1,9 +1,9 @@
---
-title: "agent.ts"
-description: "Set the agent's runtime config in agent.ts with defineAgent, including the model, reasoning effort, and compaction."
+title: "Agents"
+description: "Configure an eve agent's model, reasoning effort, compaction, limits, and runtime behavior in agent.ts."
---
-An agent's `agent.ts` calls `defineAgent` (from `eve`) to set its runtime config.
+An eve app has one root agent assembled from the files under `agent/`. Its optional `agent.ts` calls `defineAgent` (from `eve`) when you need to configure the model or other runtime behavior. Declared [subagents](./subagents) have their own `agent.ts` and capabilities; this page covers the configuration shared by root agents and subagents.
## Set the model
@@ -229,7 +229,7 @@ installed package must stay external in hosted output, list it in
## Other defineAgent fields
-`defineAgent` takes a few more fields, all optional. For the exported types, see the [TypeScript API](./reference/typescript-api).
+`defineAgent` takes a few more fields, all optional. For the exported types, see the [TypeScript API Reference](./reference/typescript-api).
| Field | Type | Default | Description |
| -------------- | --------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -257,5 +257,5 @@ During `eve dev`, ordinary dependencies are bundled into each retained runtime g
## What to read next
- [Default harness](./concepts/default-harness) for the loop and built-in tools this config drives
-- [TypeScript API](./reference/typescript-api) for every `defineAgent` field and type
+- [TypeScript API Reference](./reference/typescript-api) for every `defineAgent` field and type
- [Subagents](./subagents) for the `description` requirement and child-agent config
diff --git a/docs/channels/eve.mdx b/docs/channels/eve.mdx
index 3cdaa0153..6db539183 100644
--- a/docs/channels/eve.mdx
+++ b/docs/channels/eve.mdx
@@ -36,15 +36,13 @@ The session routes use only durable session IDs. Create a session explicitly, th
### Start and continue a session
+Start a session with an initial message, then use the returned `sessionId` for every follow-up and control operation:
+
```bash
curl -X POST https://<deployment>/eve/v1/session \
-H "Content-Type: application/json" \
-d '{"message":"What is the weather in Paris?"}'
# {"ok":true,"sessionId":"wrun_A","status":"accepted"}
-
-curl -X POST https://<deployment>/eve/v1/session/wrun_A \
- -H "Content-Type: application/json" \
- -d '{"message":"How about tomorrow?"}'
```
The first request requires `message`. A follow-up request accepts exactly one of
@@ -65,69 +63,25 @@ creates or follows a replacement session.
### Stream events
-Stream responses are newline-delimited JSON (`application/x-ndjson; charset=utf-8`), one event object per line:
-
-```bash
-curl -N https://<deployment>/eve/v1/session/wrun_A/stream
-# {"type":"turn.started",...}
-# {"type":"message.appended","data":{"messageDelta":"It is ",...}}
-# {"type":"message.completed",...}
-```
+Stream a session as newline-delimited JSON from `GET /eve/v1/session/:sessionId/stream`. The [session protocol](../concepts/sessions-runs-and-streaming#stream-a-session) defines the event set, envelopes, cursors, and reconnection behavior.
### Cancel a turn
-Cancel a session's in-flight turn with an empty body, or scope the cancel to the turn you observed by passing the `turnId` stamped on that turn's stream events:
+Post to `/eve/v1/session/:sessionId/cancel` to request cancellation of the active turn. You can include the observed `turnId` to keep a late request from cancelling a newer turn. Cancellation is asynchronous; confirm it on the stream as `turn.cancelled` followed by `session.waiting`.
-```bash
-curl -X POST https://<deployment>/eve/v1/session/wrun_A/cancel
-# {"ok":true,"sessionId":"wrun_A","status":"accepted"}
-```
-
-Cancellation is asynchronous: `"accepted"` means the live session durably queued the request. Confirm an actual cancellation on the stream as `turn.cancelled` followed by `session.waiting`—never as a failure. Active local and remote subagents are cancelled recursively before the parent settles. Content emitted before cancellation stays on the event stream, while durable model history keeps only content that had already settled. The session accepts the next message normally.
-
-An accepted cancellation returns HTTP `202` with `sessionId`. An inactive target
-returns HTTP `200` with `{"ok":true,"status":"no_active_turn"}`.
-
-A live session also returns `"accepted"` when it is already parked; the driver consumes that late or duplicate cancel as a no-op. An unknown or terminal session returns `"no_active_turn"`. A `turnId` naming any other turn is likewise accepted and consumed as a no-op, so a guarded cancel racing a turn boundary cannot stop a turn the caller never saw.
+See [Cancel the in-flight turn](../concepts/sessions-runs-and-streaming#cancel-the-in-flight-turn) for response statuses, HTTP status codes, subagent cancellation, and race behavior.
### Clear context
-Clear one session's model-message history without replacing the session:
-
-```bash
-curl -X POST https://<deployment>/eve/v1/session/wrun_A/clear
-# {"ok":true,"sessionId":"wrun_A","status":"accepted"}
-```
-
-An accepted clear emits `context.cleared` followed by `session.waiting`. The next message uses the same session without prior model messages; the system prompt, tools, skills, durable state, limits, and session-scoped sandbox remain.
+Post to `/eve/v1/session/:sessionId/clear` to remove model-message history while preserving the session ID, system prompt, tools, skills, durable state, limits, and sandbox. See [Compact, clear, and reset](../concepts/sessions-runs-and-streaming#compact-clear-and-reset).
### Compact context
-Compact one session's context without sending a message:
-
-```bash
-curl -X POST https://<deployment>/eve/v1/session/wrun_A/compact
-# {"ok":true,"sessionId":"wrun_A","status":"accepted"}
-```
-
-Compaction is asynchronous. A successful operation emits `compaction.requested` and `compaction.completed`, then returns through `session.waiting`. When a turn is active, compaction waits for it to settle. If summarization fails, the session still returns to `session.waiting` with its previous history.
+Post to `/eve/v1/session/:sessionId/compact` to summarize context without sending a user message. The operation waits for an active turn to settle and reports its result on the stream. See [Compact, clear, and reset](../concepts/sessions-runs-and-streaming#compact-clear-and-reset).
### Reset a session
-Reset terminally retires the exact session ID:
-
-```bash
-curl -X POST https://<deployment>/eve/v1/session/wrun_A/reset \
- -H "Content-Type: application/json" \
- -d '{"reason":"Start over"}'
-# {"ok":true,"previousSessionId":"wrun_A","status":"reset"}
-```
-
-After reset, the old ID cannot accept another message. Start a replacement explicitly with `POST /eve/v1/session`.
-
-The control routes never create sessions. `compact`, `clear`, and `reset` return `"no_active_session"` when the ID is already inactive. Session message and control request/response bodies do not accept or return continuation tokens. For compatibility, the streamed `session.waiting` event retains `data.continuationToken`: it is the channel-local token for a channel-addressed session and the immutable session ID for an ID-only session. New clients should continue through their fixed session handle instead of reading this field.
-
-See [Sessions, runs & streaming](../concepts/sessions-runs-and-streaming) for the complete event set, operation results, and cursor behavior.
+Post to `/eve/v1/session/:sessionId/reset` to terminally retire that session. Reset never replaces the ID automatically; create a new session explicitly for a fresh conversation. See [Compact, clear, and reset](../concepts/sessions-runs-and-streaming#compact-clear-and-reset).
## CORS
@@ -199,11 +153,11 @@ always dispatches and therefore always produces or continues a session.
The browser side of this API lives in the [Frontend](../guides/frontend/overview) docs, where `useEveAgent` drives the eve channel from React UI.
-For scripts, server-to-server calls, evals, tests, and custom clients, use the [TypeScript SDK](../guides/client/overview). It wraps the ID-addressed session routes, stream cursor, and reconnect loop.
+For scripts, server-to-server calls, evals, tests, and custom clients, use the [Client SDK](../guides/client/overview). It wraps the ID-addressed session routes, stream cursor, and reconnect loop.
## What to read next
- [Frontend](../guides/frontend/overview): drive the eve channel from browser UI with `useEveAgent`
-- [TypeScript SDK](../guides/client/overview): call the eve channel from TypeScript
+- [Client SDK](../guides/client/overview): call the eve channel from TypeScript
- [Auth & route protection](../guides/auth-and-route-protection): the route auth policy
- [Sessions, runs & streaming](../concepts/sessions-runs-and-streaming): the routes this channel exposes
diff --git a/docs/channels/meta.json b/docs/channels/meta.json
index c8119fbce..b18f444fc 100644
--- a/docs/channels/meta.json
+++ b/docs/channels/meta.json
@@ -1,5 +1,6 @@
{
"title": "Channels",
+ "defaultOpen": false,
"pages": [
"overview",
"eve",
diff --git a/docs/concepts/context-control.md b/docs/concepts/context-control.md
index 482bfddeb..cfe514eb3 100644
--- a/docs/concepts/context-control.md
+++ b/docs/concepts/context-control.md
@@ -1,92 +1,63 @@
---
title: "Context Control"
-description: "Control what an eve agent's model sees and when, across instructions, skills, the workspace, and subagents."
+description: "Choose what an eve agent's model sees and when, across instructions, skills, tools, the workspace, and subagents."
---
-eve gives you a few levers for controlling what the model sees and when. `instructions.md` (or `instructions.ts`) is always on, `skills/` are available but loaded on demand, and the workspace and sandbox are visible through tools rather than pasted into the prompt.
+Control context by putting information in the narrowest surface that needs it. Keep permanent rules in instructions, load optional procedures as skills, let the model inspect runtime files through sandbox tools, and delegate specialist work to a subagent.
-## Base identity with `instructions.md`
-
-Use `instructions.md` for the core contract of the agent.
-
-```md
-You are a careful support assistant. Be concise, verify facts before replying, and explain when you
-used a tool.
-```
-
-Keep this file focused on stable behavior that should apply on every turn.
+## Recommended context layout
-## Compose instructions in TypeScript with `instructions.ts`
+| Need | Use | What the model sees |
+| ---------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| Permanent identity, rules, or constraints | [`instructions.md` or `instructions.ts`](../instructions) | The instructions on every model call |
+| A procedure needed only for some tasks | A [skill](../skills) | Its description until the model loads the full skill |
+| A typed action or external operation | A [tool](../tools) or [connection](../connections) | The callable schema and the result of each call |
+| Files or command execution | The [sandbox workspace](../sandbox) | A workspace hint, then files and command output the model requests through tools |
+| A specialist with a separate prompt and capabilities | A [subagent](../subagents) | Only the subagent's final result in the parent context |
+| Instructions or capabilities that vary by caller | A [dynamic capability](../guides/dynamic-capabilities) | The values resolved for the active session |
-To build the instructions prompt from typed helpers, lib code, or environment-derived values, author it as a module instead of markdown.
+## Base identity with `instructions.md`
-```ts title="agent/instructions.ts"
-import { defineInstructions } from "eve/instructions";
-import { buildInstructionsPrompt } from "./lib/prompts";
+Use instructions for stable behavior that should apply throughout a session, such as the agent's role, tone, and standing constraints. Markdown is the default. Keep instructions short enough to justify including them on every model call.
-export default defineInstructions({
- markdown: buildInstructionsPrompt(),
-});
-```
+### Compose instructions in TypeScript with `instructions.ts`
-Module-backed instructions run once at build time. eve captures the resulting markdown into the compiled manifest, so the runtime serves the same prompt every session without re-running the module.
+Use `instructions.ts` when you need typed helpers or build-time composition. See [Instructions](../instructions) for both formats, directory composition, and runtime resolution.
## Load procedures on demand with `skills/`
-Skills stay out of the always-on prompt by default, which keeps rich procedures available without bloating every turn. eve advertises the available skills and adds a framework-owned `load_skill` tool. When the request clearly matches a skill description, or the user names a skill explicitly, the model activates that skill, and eve appends the skill's markdown to the active instructions for later turn work.
+Use skills for optional procedures that would otherwise make the always-on prompt unnecessarily large. eve advertises each skill's description and loads the full instructions only when the model calls `load_skill`.
### Flat skill
-```md title="agent/skills/get-weather.md"
-Use the weather tool before answering forecast or temperature questions.
-```
+Use a markdown file for a self-contained procedure.
### Packaged skill
-```md title="agent/skills/research/SKILL.md"
----
-description: Research unfamiliar topics before answering with confidence.
----
-
-When the task is novel or ambiguous, gather evidence first, then answer with the key facts and the
-remaining uncertainty.
-```
-
-Packaged skills are useful when you also want sibling files such as `references/`, `assets/`, or `scripts/` under the same skill directory. Those files are available under the runtime skill root, normally `$HOME/.agents/skills/<skill>/`. Relative references inside a `SKILL.md` resolve from that specific skill directory, so `references/checklist.md` means `$HOME/.agents/skills/<skill>/references/checklist.md` unless eve has fallen back to `/workspace/skills/<skill>/`.
-
-See [Skills](../skills) for the full authoring model and install notes.
+Use a directory with `SKILL.md` when the procedure also needs references, assets, or scripts. See [Skills](../skills) for both formats, installation, runtime files, and dynamic skills.
## Put runtime files in the workspace, not the prompt
-eve does not inline the entire authored surface into the prompt. Instead, it gives the model a shallow workspace hint, a separate skill-root hint, and runtime tools to inspect deeper when needed. Skill package files are outside `/workspace` in the normal case, and the model inspects them with the shared `bash` tool, which keeps prompts smaller and makes file and command work explicit.
+Do not paste a file tree or large working dataset into the prompt. Seed files into the sandbox workspace and let the model inspect them through `bash`, `read_file`, `glob`, and the other sandbox-backed tools. Skill package files use a separate runtime skill directory.
-See [Sandbox](../sandbox) for the workspace and sandbox model.
+See [Sandbox](../sandbox) for workspace seeding, runtime access, backends, and lifecycle behavior.
## Delegate to a specialist with a subagent
-If a task deserves its own prompt and tool surface, use a local subagent instead of overloading the root agent. Subagents are a context-control lever too. They get their own `instructions.md`, tools, and sandbox, and they run inside their own delegated context instead of extending the root agent inline.
+Use a subagent when work needs its own instructions, tools, skills, state, or sandbox. The child runs in a separate context instead of adding its working history to the parent. The parent receives the result of the delegation.
-See [Subagents](../subagents).
+See [Subagents](../subagents) for the distinction between root-agent copies and declared specialists, including their isolation boundaries.
## Dynamic context with `defineDynamic`
-The levers above are static, authored once and the same on every session. When the right context depends on who is calling (their team, tenant, plan, or feature flags), resolve it at runtime instead. `defineDynamic` in `agent/instructions/` returns the per-session system prompt, and `defineDynamic` in `agent/skills/` returns the set of skills a caller can load. Both read `ctx.session.auth` or channel metadata, so a caller on the billing team gets the billing instructions and playbook while no one else sees them. See [Dynamic capabilities](../guides/dynamic-capabilities) for the resolver API and when each event fires.
-
-## Recommended context layout
-
-Pick the lever by what the context is for:
+Use `defineDynamic` when instructions, skills, tools, subagents, or the model depend on the active principal, tenant, channel, or feature state. Dynamic resolvers can read session auth and channel metadata before returning the capabilities available to that session.
-- `instructions.md` for the agent's permanent identity. Keep it short and stable.
-- `instructions.ts` when you need to compose the prompt from typed helpers at build time.
-- `skills/` for optional procedures that should load only when needed. Move long procedures here instead of into the always-on prompt.
-- `tools/` to expose typed integrations.
-- a subagent when the task needs a different specialist surface; use one only for real specialization boundaries.
-- the workspace or sandbox when the model should inspect files or run commands instead of relying on pasted instructions.
+See [Dynamic capabilities](../guides/dynamic-capabilities) for the resolver API, supported slots, and execution order.
## What to read next
-- [Tools](../tools): expose typed integrations the model can call.
-- [Skills](../skills): the full authoring model for on-demand procedures.
-- [Subagents](../subagents): delegate to a specialist with its own prompt and tools.
-- [Dynamic capabilities](../guides/dynamic-capabilities): resolve per-session instructions and skills with `defineDynamic`.
-- [Hooks](../guides/hooks): run code on session events to update the channel state that dynamic resolvers read.
+- [Instructions](../instructions): author the always-on system prompt.
+- [Skills](../skills): provide procedures that load on demand.
+- [Sandbox](../sandbox): give the model files and command execution.
+- [Subagents](../subagents): isolate specialist work.
+- [Dynamic capabilities](../guides/dynamic-capabilities): vary context and capabilities by session.
diff --git a/docs/concepts/default-harness.md b/docs/concepts/default-harness.md
index 42455d098..71e9e3451 100644
--- a/docs/concepts/default-harness.md
+++ b/docs/concepts/default-harness.md
@@ -57,7 +57,7 @@ The model-facing file tools accept absolute paths and paths beginning with `$HOM
Notes:
-- **`agent`** is available only in the root session. Its child uses the root's instructions, tools, connections, and sandbox, but starts with fresh conversation history and fresh [state](../guides/state). The child receives neither `agent` nor `Workflow`; declared subagents do not receive the built-in `agent` either. See [Subagents](../subagents).
+- **`agent`** is available only in the root session. Its child uses the root's instructions, tools, connections, and sandbox, but starts with fresh conversation history and fresh [state](./state). The child receives neither `agent` nor `Workflow`; declared subagents do not receive the built-in `agent` either. See [Subagents](../subagents).
- **`load_skill`** only pulls instructions into context. It adds no new execution surface, because behavior still comes from the tools the agent already has.
- **`connection_search`** surfaces a connection's tools by their qualified name (e.g. `linear__list_issues`), which the model can then call directly. It's registered only when the agent has connections.
- **`web_search`** has no local executor; the provider runs it. AI Gateway models use Exa by default. To use Parallel instead, export `webSearch({ provider: "parallel" })` from `agent/tools/web_search.ts`. Direct provider models continue to use their native search implementation. To supply your own implementation, override it with `defineTool()`.
@@ -125,7 +125,7 @@ import { experimental_workflow } from "eve/tools";
export default experimental_workflow({ maxSubagents: 100 });
```
-With it on, the model can orchestrate the agent's own subagents from model-authored JavaScript, all as one durable step. The tool is root-only — delegated subagent sessions never see it — and one program may dispatch at most the configured `maxSubagents` calls (default 100). See [Dynamic workflows](../guides/dynamic-workflows).
+With it on, the model can orchestrate the agent's own subagents from model-authored JavaScript, all as one durable step. The tool is root-only — delegated subagent sessions never see it — and one program may dispatch at most the configured `maxSubagents` calls (default 100). See [Workflow Tool](../subagents/workflow-tool).
## The opt-in `sleep` tool
diff --git a/docs/concepts/execution-model-and-durability.mdx b/docs/concepts/execution-model-and-durability.mdx
index 4e88e2370..5fc6ce3e5 100644
--- a/docs/concepts/execution-model-and-durability.mdx
+++ b/docs/concepts/execution-model-and-durability.mdx
@@ -60,7 +60,7 @@ Crash the process, hit a timeout, or redeploy mid-turn, and the run picks up fro
There's nothing to configure. eve owns the workflow lifecycle, and sessions are durable by default.
-You don't write workflow code directly. Workflow primitives (`start()`, `resumeHook()`, etc.) are an implementation detail of eve's runtime layer; channels, tools, and hooks never touch them. Two surfaces give your own code session data: tools read the current session's metadata (id, turn, auth, parent lineage) via `ctx.session`, and [`defineState`](../guides/state) reads or writes session-scoped durable state. See [State](../guides/state) for the read/write model.
+You don't write workflow code directly. Workflow primitives (`start()`, `resumeHook()`, etc.) are an implementation detail of eve's runtime layer; channels, tools, and hooks never touch them. Two surfaces give your own code session data: tools read the current session's metadata (id, turn, auth, parent lineage) via `ctx.session`, and [`defineState`](./state) reads or writes session-scoped durable state. See [State](./state) for the read/write model.
## Parked work
@@ -97,4 +97,4 @@ Conversation history within a session is append-only. Turns land in order, and t
- [Sessions and streaming](./sessions-runs-and-streaming): the handles you hold and the event stream you watch.
- [Security model](./security-model): the trust boundaries the runtime enforces.
-- [State](../guides/state): durable per-session memory that persists across step boundaries.
+- [State](./state): durable per-session memory that persists across step boundaries.
diff --git a/docs/concepts/meta.json b/docs/concepts/meta.json
index bbd5e2cef..685aad11c 100644
--- a/docs/concepts/meta.json
+++ b/docs/concepts/meta.json
@@ -1,8 +1,10 @@
{
- "title": "Concepts",
+ "title": "Core Concepts",
+ "defaultOpen": false,
"pages": [
"execution-model-and-durability",
"sessions-runs-and-streaming",
+ "state",
"default-harness",
"context-control",
"security-model"
diff --git a/docs/concepts/sessions-runs-and-streaming.md b/docs/concepts/sessions-runs-and-streaming.md
index c87eb7a05..8f895d56d 100644
--- a/docs/concepts/sessions-runs-and-streaming.md
+++ b/docs/concepts/sessions-runs-and-streaming.md
@@ -14,7 +14,7 @@ or creates a replacement implicitly.
Authored channels also have channel-local continuation tokens. A token addresses
whichever session currently owns a platform conversation, such as a Slack thread.
That identity stays behind the channel boundary and is never accepted or returned
-by the eve HTTP session API. See [Custom channels](../channels/custom#address-and-session-handles).
+by the eve HTTP session API. See [Custom channels](../channels/custom#channel-operations-and-session-handles).
Sessions last 30 days by default; configure `limits.sessionTimeoutMs` in
`agent.ts`, or set it to `false` to disable the deadline. At expiration, eve
@@ -148,7 +148,15 @@ curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId> \
-d '{"message":"Now send the short version."}'
```
-The follow-up reuses the same durable session: same history, same state. Message sends default to cancellation-backed `"steer"`; if a turn is active, eve buffers the follow-up, cancels that turn, and starts the message under a new turn ID. Channels and TypeScript `Session.send(...)` calls can select `turnPolicy: "queue"` when active work should finish first. Structured `inputResponses` never steer.
+The follow-up reuses the same durable session: same history, same state. A follow-up accepts exactly one of `message` or `inputResponses`. Use structured responses to answer one or more pending human-input requests by ID:
+
+```bash
+curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId> \
+ -H 'content-type: application/json' \
+ -d '{"inputResponses":[{"requestId":"req_A","optionId":"approve"}]}'
+```
+
+Message sends default to cancellation-backed `"steer"`; if a turn is active, eve buffers the follow-up, cancels that turn, and starts the message under a new turn ID. Channels and TypeScript `Session.send(...)` calls can select `turnPolicy: "queue"` when active work should finish first. Structured `inputResponses` never steer.
If one pending batch is waiting on a human-in-the-loop approval, a matching text reply such as `approve` or `cancel` answers it. Unrelated text starts an ordinary turn immediately without denying the tool call; the approval stays pending and answerable. A later structured `inputResponses` answer keyed by its `requestId` still resumes the original tool call, even after intervening turns.
@@ -190,9 +198,11 @@ curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/reset \
-d '{"reason":"Start over"}'
```
-Compaction summarizes context, clear removes model-message history in place,
-and reset terminally retires the session. A reset ID never becomes a new session;
-create another session explicitly for a fresh conversation.
+Compaction summarizes context without adding a user message. If a turn is active, eve queues the request until that turn settles. A successful compaction emits `compaction.requested` and `compaction.completed`, followed by `session.waiting`; if summarization fails, the session returns to waiting with its previous history.
+
+Clear removes model-message history in place while preserving the session identity, system prompt, tools, skills, durable state, limits, and sandbox. It emits `context.cleared` followed by `session.waiting`.
+
+Reset terminally retires the exact session ID. A reset ID never becomes a new session; create another session explicitly for a fresh conversation. Compact, clear, and reset return `"no_active_session"` when the target is already inactive.
## Reconnect and rewind
@@ -227,7 +237,7 @@ The lookup is opt-in; requests without the parameter get no header. The TypeScri
For scripts, server-to-server calls, tests, evals, and custom UIs, `eve/client` wraps these routes in a typed client so you don't hand-roll the POST and NDJSON stream loop.
-Start with the [TypeScript SDK](../guides/client/overview) guide. It covers basic usage, sending messages, session state, streaming, and per-turn `outputSchema` results.
+Start with the [Client SDK](../guides/client/overview) guide. It covers basic usage, sending messages, session state, streaming, and per-turn `outputSchema` results.
## Inspect the agent over HTTP
@@ -254,5 +264,5 @@ The order is structural, not incidental. By the time a resolver or hook reads ch
- [Execution model & durability](./execution-model-and-durability): what makes a session durable and how parked work resumes.
- [Channels](../channels/overview): how platform addresses map to durable sessions.
-- [TypeScript SDK](../guides/client/overview): call these routes from scripts and server-side code.
+- [Client SDK](../guides/client/overview): call these routes from scripts and server-side code.
- [Frontend](../guides/frontend/overview): `useEveAgent` instead of raw routes.
diff --git a/docs/guides/state.md b/docs/concepts/state.md
similarity index 96%
rename from docs/guides/state.md
rename to docs/concepts/state.md
index a58ef5f45..7b30914c2 100644
--- a/docs/guides/state.md
+++ b/docs/concepts/state.md
@@ -46,7 +46,7 @@ export default defineTool({
## Reset state between turns
-State is durable by default and does not reset between turns. If you want a clean slate every turn, overwrite it from a lifecycle [hook](./hooks) on `turn.started`:
+State is durable by default and does not reset between turns. If you want a clean slate every turn, overwrite it from a lifecycle [hook](../guides/hooks) on `turn.started`:
```ts title="agent/hooks/reset-budget.ts"
import { defineHook } from "eve/hooks";
@@ -73,7 +73,7 @@ Every [subagent](../subagents) starts with its own fresh state, whether it's a b
## What to read next
-- Read state inside dynamic resolvers → [Dynamic capabilities](./dynamic-capabilities)
+- Read state inside dynamic resolvers → [Dynamic capabilities](../guides/dynamic-capabilities)
- How step durability works → [Execution model & durability](../concepts/execution-model-and-durability)
-- The `ctx` accessors available alongside state → [TypeScript API](../reference/typescript-api)
+- The `ctx` accessors available alongside state → [TypeScript API Reference](../reference/typescript-api)
- Tenant-scoped long-term memory in your own store → [Multi-tenant memory](../patterns/multi-tenant-memory)
diff --git a/docs/connections/mcp.mdx b/docs/connections/mcp.mdx
index d76b83bfb..754f7c3f9 100644
--- a/docs/connections/mcp.mdx
+++ b/docs/connections/mcp.mdx
@@ -26,68 +26,13 @@ The `url` must speak Streamable HTTP or SSE. Write the `description` for the mod
## Use Vercel Connect for OAuth
-For OAuth-backed MCP servers, prefer [Vercel Connect](https://vercel.com/docs/connect). Connect owns the browser consent flow, encrypted token storage, refresh, and project access. The `connect()` helper from `@vercel/connect/eve` plugs that lifecycle into eve's connection auth, so credentials never land in model context or conversation history.
+For OAuth-backed MCP servers, use the shared [Vercel Connect flow](../connections#interactive-oauth-via-vercel-connect), then pass the returned connector UID to `connect()`. Keep the MCP runtime URL and Connect service identifier distinct. For example, Linear uses `https://mcp.linear.app/mcp` as the MCP endpoint and `mcp.linear.app` when creating the connector.
-From the Vercel project or agent app that will run the connection:
-
-```bash
-npm install @vercel/connect
-vercel link
-vercel connect create mcp.linear.app --name linear
-vercel connect attach <connector-uid> --yes
-vercel env pull
-```
-
-Use the connector UID returned by the CLI in `connect("<connector-uid>")`. For Linear, the MCP runtime endpoint is `https://mcp.linear.app/mcp`, while the managed Connect service identifier is `mcp.linear.app`; those are related but not interchangeable.
-
-By default, `connect("...")` is user-scoped. The first tool call for a new user emits an `authorization.required` event with a URL to visit, parks the turn, and resumes after the callback completes. The active eve session must already have a user principal from route auth or from a platform channel. If there is no authenticated user, the connection fails with `reason: "principal_required"`.
-
-If the MCP server should act as the agent itself instead of the signed-in user, make the connector app-scoped:
-
-```ts title="agent/connections/linear.ts"
-import { connect } from "@vercel/connect/eve";
-import { defineMcpClientConnection } from "eve/connections";
-
-export default defineMcpClientConnection({
- url: "https://mcp.linear.app/mcp",
- description: "Linear workspace: issues, projects, cycles, and comments.",
- auth: connect({ connector: "mcp.linear.app/linear", principalType: "app" }),
-});
-```
-
-App-scoped Connect auth is non-interactive. eve asks Connect for one shared app token; if the connector is missing or cannot issue an app token, the tool call fails terminally so an operator can fix setup.
+`connect("...")` is user-scoped by default and requires an authenticated user on the active eve session. Use `connect({ connector, principalType: "app" })` when the server should act as the agent instead. The connections overview covers connector setup, session requirements, app and user scope, callback behavior, and troubleshooting.
## Static tokens and headers
-Use `auth.getToken` when you already have a bearer token, API key, service account token, or out-of-band OAuth flow. eve sends the returned token as `Authorization: Bearer <token>`.
-
-```ts title="agent/connections/linear.ts"
-import { defineMcpClientConnection } from "eve/connections";
-
-export default defineMcpClientConnection({
- url: "https://mcp.linear.app/mcp",
- description: "Linear workspace: issues, projects, cycles, and comments.",
- auth: {
- getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }),
- },
-});
-```
-
-Use `headers` for non-Bearer auth schemes or extra server configuration:
-
-```ts title="agent/connections/private-docs.ts"
-import { defineMcpClientConnection } from "eve/connections";
-
-export default defineMcpClientConnection({
- url: "https://docs.example.com/mcp",
- description: "Internal docs: search pages, owners, and recent changes.",
- headers: {
- "X-Api-Key": process.env.DOCS_API_KEY!,
- },
-});
-```
-
-`auth` and `headers` can also be functions that receive the active session context. Use that when credentials, tenants, or routing depend on the caller.
+MCP connections accept the shared connection `auth` and `headers` options. Use `auth.getToken` for a bearer token, `headers` for another scheme, and resolver functions when credentials or routing depend on the caller. See [Static-token auth](../connections#static-token-auth), [Headers](../connections#headers), and [Per-caller auth and headers](../connections#per-caller-auth-and-headers) for the canonical examples and token-lifecycle behavior.
## Application-provided tool arguments
@@ -119,18 +64,7 @@ eve treats configured keys as application-owned: it removes them from every remo
## No auth
-Omit `auth` and `headers` only for intentionally public or local-only servers:
-
-```ts title="agent/connections/local.ts"
-import { defineMcpClientConnection } from "eve/connections";
-
-export default defineMcpClientConnection({
- url: "http://localhost:3001/mcp",
- description: "Local dev MCP server.",
-});
-```
-
-Do not use a no-auth connection for sensitive third-party services unless another layer protects the endpoint.
+Omit `auth` and `headers` only for an intentionally public or loopback MCP server. See [No auth](../connections#no-auth) for the shared connection behavior and security boundary.
## Tool filters
@@ -152,24 +86,7 @@ Prefer `allow` for the smallest safe surface, especially when the server exposes
## Approval gates
-For MCP tools that can create, modify, delete, message, transmit, purchase, or access sensitive data, add a human approval gate:
-
-```ts title="agent/connections/linear.ts"
-import { connect } from "@vercel/connect/eve";
-import { defineMcpClientConnection } from "eve/connections";
-import { once } from "eve/tools/approval";
-
-export default defineMcpClientConnection({
- url: "https://mcp.linear.app/mcp",
- description: "Linear workspace.",
- auth: connect("mcp.linear.app/linear"),
- approval: once(),
-});
-```
-
-`once()` asks the first time in a session, `always()` asks on every tool call, and `never()` allows calls without approval. Authorization and approval work together: eve records approval before an OAuth park, then resumes without asking again for the same approved call.
-
-The `once()`, `always()`, and `never()` helpers from `eve/tools/approval` gate every tool the connection serves the same way. See [Connections](/docs/connections#per-connection-approval) for those, and [Human-in-the-loop](/docs/human-in-the-loop) for the full pause-and-resume contract.
+Use the shared `approval` option to gate every tool served by an MCP connection. The [connections overview](../connections#per-connection-approval) defines the `never()`, `once()`, and `always()` helpers; [Human-in-the-loop](../human-in-the-loop#approvals) defines the pause-and-resume contract.
### Gate specific tools by name or input
@@ -233,5 +150,5 @@ When a remote tool returns more data than the model needs, narrow the result at
- [Connections](../connections): shared auth, headers, approval, and per-caller patterns.
- [OpenAPI connections](./openapi): generate tools from OpenAPI operations.
-- [Auth & route protection](../guides/auth-and-route-protection): route auth and the full interactive OAuth lifecycle.
+- [Authentication](../guides/auth-and-route-protection): establish the caller identity required by user-scoped auth.
- [Security model](../concepts/security-model): how connection credentials stay out of the model's reach.
diff --git a/docs/connections/meta.json b/docs/connections/meta.json
index d1a8c1ea3..76ff828a9 100644
--- a/docs/connections/meta.json
+++ b/docs/connections/meta.json
@@ -1,4 +1,5 @@
{
"title": "Connections",
+ "defaultOpen": false,
"pages": ["overview", "mcp", "openapi"]
}
diff --git a/docs/connections/openapi.mdx b/docs/connections/openapi.mdx
index 861356556..87f6171c8 100644
--- a/docs/connections/openapi.mdx
+++ b/docs/connections/openapi.mdx
@@ -48,19 +48,7 @@ export default defineOpenAPIConnection({
## Use Vercel Connect for OAuth
-For OAuth-backed APIs, prefer [Vercel Connect](https://vercel.com/docs/connect). Connect owns browser consent, encrypted token storage, refresh, and project access. The `connect()` helper from `@vercel/connect/eve` plugs that lifecycle into eve's connection auth, so tokens never reach model context or conversation history.
-
-Create or attach a connector for the API provider from the Vercel project or agent app that will run the connection:
-
-```bash
-npm install @vercel/connect
-vercel link
-vercel connect create github --name github
-vercel connect attach <connector-uid> --yes
-vercel env pull
-```
-
-Then use the connector UID returned by the CLI:
+For an OAuth-backed API, follow the shared [Vercel Connect setup](../connections#interactive-oauth-via-vercel-connect), then attach the returned connector UID to the OpenAPI connection:
```ts title="agent/connections/github.ts"
import { connect } from "@vercel/connect/eve";
@@ -74,48 +62,11 @@ export default defineOpenAPIConnection({
});
```
-By default, `connect("...")` is user-scoped. The active eve session must have a user principal from route auth or from a platform channel before the first operation call. If the API should act as the agent itself, make the connector app-scoped:
-
-```ts
-auth: connect({ connector: "github/github", principalType: "app" });
-```
-
-Use `tokenParams` on `connect(...)` when the provider requires explicit OAuth scopes, audiences, resource indicators, or authorization details.
+`connect("...")` is user-scoped by default and requires an authenticated user on the active session. Use `connect({ connector, principalType: "app" })` when the API should act as the agent instead. Configure provider-specific scopes, audiences, or authorization details through `tokenParams` on `connect(...)`.
## Static tokens and headers
-Use `auth.getToken` when you already have a bearer token, API key, service account token, or out-of-band OAuth flow. eve sends the returned token as `Authorization: Bearer <token>`.
-
-```ts title="agent/connections/crm.ts"
-import { defineOpenAPIConnection } from "eve/connections";
-
-export default defineOpenAPIConnection({
- spec: "https://api.example.com/openapi.json",
- baseUrl: "https://api.example.com",
- description: "CRM accounts, contacts, and opportunities.",
- auth: {
- getToken: async () => ({ token: process.env.CRM_TOKEN! }),
- },
-});
-```
-
-Use `headers` for non-Bearer auth schemes, version headers, or tenant routing:
-
-```ts title="agent/connections/notion.ts"
-import { defineOpenAPIConnection } from "eve/connections";
-
-export default defineOpenAPIConnection({
- spec: "https://developers.notion.com/openapi.json",
- baseUrl: "https://api.notion.com",
- description: "Notion pages, databases, comments, and users.",
- headers: {
- Authorization: `Bearer ${process.env.NOTION_API_KEY!}`,
- "Notion-Version": "2022-06-28",
- },
-});
-```
-
-`auth` and `headers` can also be functions that receive the active session context. Use that when credentials, tenants, or routing depend on the caller.
+OpenAPI connections accept the shared connection `auth` and `headers` options. Use `auth.getToken` for a bearer token, `headers` for another scheme or API version, and resolver functions when credentials or routing depend on the caller. See [Static-token auth](../connections#static-token-auth), [Headers](../connections#headers), and [Per-caller auth and headers](../connections#per-caller-auth-and-headers) for the canonical examples and token-lifecycle behavior.
## Application-provided operation arguments
@@ -201,26 +152,11 @@ The parameter `name` must exactly match the placeholder inside the path. If the
## Approval gates
-Generated operation tools can mutate state just like authored tools. Add an approval gate when operations can create, modify, delete, message, transmit, purchase, or access sensitive data:
-
-```ts title="agent/connections/crm.ts"
-import { defineOpenAPIConnection } from "eve/connections";
-import { once } from "eve/tools/approval";
-
-export default defineOpenAPIConnection({
- spec: "https://api.example.com/openapi.json",
- baseUrl: "https://api.example.com",
- description: "CRM accounts, contacts, and opportunities.",
- auth: { getToken: async () => ({ token: process.env.CRM_TOKEN! }) },
- approval: once(),
-});
-```
-
-Combine `approval` with `operations.allow` for the smallest practical surface.
+Generated operations can mutate state like authored tools. Use the shared connection `approval` option for human approval, and combine it with `operations.allow` for the smallest practical surface. See [Per-connection approval](../connections#per-connection-approval) for the helpers and [Human-in-the-loop](../human-in-the-loop#approvals) for policy behavior.
## What to read next
- [Connections](../connections): shared auth, headers, approval, and per-caller patterns.
- [MCP connections](./mcp): connect to remote MCP servers.
-- [Auth & route protection](../guides/auth-and-route-protection): route auth and the full interactive OAuth lifecycle.
+- [Authentication](../guides/auth-and-route-protection): establish the caller identity required by user-scoped auth.
- [Security model](../concepts/security-model): how connection credentials stay out of the model's reach.
diff --git a/docs/connections/overview.mdx b/docs/connections/overview.mdx
index db71c0400..4a7d2a401 100644
--- a/docs/connections/overview.mdx
+++ b/docs/connections/overview.mdx
@@ -22,7 +22,21 @@ Read [OpenAPI connections](/docs/connections/openapi) for `defineOpenAPIConnecti
## Static-token auth
-`getToken` returns a `TokenResult` (`{ token, expiresAt? }`), and eve sends it as `Authorization: Bearer <token>` on every request. Because it runs on each connection attempt, you can mint a fresh token from wherever you keep secrets, including an env var, a secrets manager, an internal vault, or your own OAuth exchange. If the token has a known TTL, set `expiresAt` (milliseconds since epoch) and eve refreshes ahead of time rather than waiting for a `401`.
+`getToken` returns a `TokenResult` (`{ token, expiresAt? }`), and eve sends it as `Authorization: Bearer <token>` on every request. Because it runs on each connection attempt, you can mint a fresh token from wherever you keep secrets, including an env var, a secrets manager, an internal vault, or your own OAuth exchange:
+
+```ts title="agent/connections/linear.ts"
+import { defineMcpClientConnection } from "eve/connections";
+
+export default defineMcpClientConnection({
+ url: "https://mcp.linear.app/mcp",
+ description: "Linear workspace.",
+ auth: {
+ getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }),
+ },
+});
+```
+
+If the token has a known TTL, set `expiresAt` (milliseconds since epoch) and eve refreshes ahead of time rather than waiting for a `401`.
When `getToken` is the only auth, `principalType` defaults to `"app"`: one shared credential keyed across all sessions. Switch to `principalType: "user"` when each end-user carries their own token.
@@ -123,7 +137,19 @@ For connection tools that can create, modify, delete, transmit, purchase, messag
## Interactive OAuth via Vercel Connect
-When the server uses OAuth and you want each end-user to sign in through their own browser, turn on interactive authorization with [Vercel Connect](https://vercel.com/docs/connect). The `connect()` helper from `@vercel/connect/eve` handles consent, encrypted token storage, and refresh, then hooks all of that into eve's authorization flow:
+When the server uses OAuth and you want each end-user to sign in through their own browser, turn on interactive authorization with [Vercel Connect](https://vercel.com/docs/connect). The `connect()` helper from `@vercel/connect/eve` handles consent, encrypted token storage, and refresh, then hooks all of that into eve's authorization flow.
+
+Create and attach the connector from the Vercel project or agent app that will use it:
+
+```bash
+npm install @vercel/connect
+vercel link
+vercel connect create <service> --name <name>
+vercel connect attach <connector-uid> --yes
+vercel env pull
+```
+
+Use the connector UID returned by the CLI in `connect("<connector-uid>")`. The service identifier accepted by `vercel connect create` depends on the provider; it is not necessarily the same as an MCP runtime URL or OpenAPI base URL.
```ts title="agent/connections/linear.ts"
import { connect } from "@vercel/connect/eve";
@@ -155,7 +181,7 @@ export default defineMcpClientConnection({
});
```
-App-scoped Connect auth is non-interactive. eve asks Vercel Connect for an app token and does not emit a browser consent challenge; if the connector is not installed or cannot issue an app token, the tool call fails terminally so an operator can fix the connector setup. The full setup (Connect client provisioning, project linking, the runtime consent flow) lives in [Auth & route protection](/docs/guides/auth-and-route-protection).
+App-scoped Connect auth is non-interactive. eve asks Vercel Connect for an app token and does not emit a browser consent challenge; if the connector is not installed or cannot issue an app token, the tool call fails terminally so an operator can fix the connector setup. See [Authentication](/docs/guides/auth-and-route-protection) when a user-scoped connection needs your HTTP channel to establish the caller's identity.
### Troubleshooting Vercel Connect auth
diff --git a/docs/evals/meta.json b/docs/evals/meta.json
index 91a4a95a2..68d3c12be 100644
--- a/docs/evals/meta.json
+++ b/docs/evals/meta.json
@@ -1,4 +1,5 @@
{
"title": "Evals",
+ "defaultOpen": false,
"pages": ["overview", "cases", "assertions", "judge", "targets", "reporters", "running"]
}
diff --git a/docs/extensions.md b/docs/extensions.md
index a3f5c48ba..bcb9b39fa 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -5,7 +5,7 @@ description: "Package reusable eve capabilities and mount them from npm or a mon
Extensions package eve tools, connections, skills, instruction fragments, and hooks. An author builds an extension package; each agent that uses it declares the package as a dependency and mounts it. The package can be published to a package registry or kept private inside a monorepo workspace.
-Ready-made extensions can also be distributed through an eve integration registry. See [Install Integrations](./install-integrations) to discover and add one with `eve add`; this page explains how extension packages are authored, mounted, configured, and overridden.
+Ready-made extensions can also be distributed through an eve integration registry. See [Add Integrations](./install-integrations) to discover and add one with `eve add`; this page explains how extension packages are authored, mounted, configured, and overridden.
This enables sharing many different capability sets. A browser extension might include several tools for navigating a site. A memory extension could use hooks to capture context and tools to recall it. A self-improving extension could pair hooks with dynamic instructions.
diff --git a/docs/getting-started.mdx b/docs/getting-started.mdx
index 4f3c2390c..abf0d6560 100644
--- a/docs/getting-started.mdx
+++ b/docs/getting-started.mdx
@@ -1,23 +1,185 @@
---
title: "Getting Started"
-description: "Create an eve project, learn its filesystem layout, and start adding capabilities."
-contentType: "Landing"
+description: "Create an eve project, configure a model, understand its filesystem layout, and run your first agent."
+contentType: "How-to"
---
-eve agents are TypeScript projects. You describe an agent with files under `agent/`, then eve runs it as a durable service.
+## Prerequisites
-## Start in order
-
-1. [Install eve](/docs/installation): create a project, configure a model credential, and run it locally
-2. [Learn the project structure](/docs/project-structure): see which files eve discovers and where each capability belongs
-3. [Build your first agent](/docs/tutorial/first-agent): add tools, state, and an interface for a useful workflow
-
-## What you need
+You need:
- Node.js 24 or newer
- npm, which Node.js includes
-- A model credential for the model your agent uses
+- A credential for the model your agent uses
+
+The default scaffolded model routes through the Vercel AI Gateway. Set `AI_GATEWAY_API_KEY`, or link a Vercel project to use `VERCEL_OIDC_TOKEN`. To use a model provider directly, install its AI SDK provider package and set the provider's API key.
+
+Choose a model, provider, and channel that meet your data-processing and compliance requirements.
+
+## Create a project
+
+Run `eve init` with a project name:
+
+```bash
+npx eve@latest init my-agent
+```
+
+The command creates the project, installs dependencies, and initializes Git. If a supported coding-agent REPL is available, eve offers to start the development server, open the REPL, or exit after scaffolding.
+
+Pass an AI Gateway model ID or reasoning effort when you do not want the defaults:
+
+```bash
+npx eve@latest init my-agent --model openai/gpt-5.5 --reasoning high
+```
+
+To add eve to a project that already has a `package.json`, run this command from its root before you create any `agent/` files:
+
+```bash
+npx eve@latest init .
+```
+
+eve adds the missing `eve`, `ai`, and `zod` dependencies without changing files the project already owns.
+
+## Run the agent
+
+If the development server is not already running, start it from the project root:
+
+```bash
+npm run dev
+```
+
+The TUI sends messages to your agent. Stop the server with `Ctrl+C` when you need your shell for another command.
+
+## Project layout
+
+eve builds an agent by walking the filesystem under `agent/`. Each directory is an authored slot, and the slot a file lands in determines how eve loads it.
+
+### Naming from paths
+
+Identity comes from the path. You never write a `name` or `id` field on a `define*` call.
+
+| Path | Resolves to |
+| ------------------------------------- | --------------------- |
+| `agent/tools/get_weather.ts` | tool `get_weather` |
+| `agent/connections/linear.ts` | connection `linear` |
+| `agent/skills/summarize.md` | skill `summarize` |
+| `agent/subagents/researcher/agent.ts` | subagent `researcher` |
+
+The root agent takes its name from the enclosing `package.json` `name`, falling back to the app-root directory name when `package.json` has no `name`. A subagent takes its name from its directory.
+
+### Recommended layout
+
+A minimal agent needs `instructions.md`; `agent.ts` is optional when the defaults are sufficient. Add other slots as the agent needs them:
+
+```text
+my-agent/
+├── package.json
+├── tsconfig.json
+├── agent/
+│ ├── agent.ts
+│ ├── instructions.md
+│ ├── instrumentation.ts
+│ ├── channels/
+│ ├── connections/
+│ ├── hooks/
+│ ├── skills/
+│ ├── lib/
+│ ├── sandbox/
+│ ├── tools/
+│ ├── schedules/
+│ └── subagents/
+└── evals/
+```
+
+Evals live beside `agent/`, not inside it.
+
+### Authored slots
+
+The Subagents column states whether a local subagent (`subagents/<id>/`) can author the slot. A declared subagent inherits nothing from the root; it discovers its own slots.
+
+| Path | Description | Subagents | Notes |
+| ------------------------------------------------------- | ----------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agent.ts` | Runtime config | Yes | Model, model options, compaction, build, and experimental settings. See [Agents](./agent-config). |
+| `instructions.md` / `instructions.ts` / `instructions/` | Base system prompt | Optional | A flat file or directory of `.md` and `.ts` files. Static sources compose at build time. Dynamic sources resolve at runtime. Required on the root, optional on subagents. |
+| `instrumentation.ts` | Telemetry config | No | OTel exporter and AI SDK span settings, auto-discovered and run before agent code. Root-only. |
+| `channels/` | HTTP and messaging entry points | No | Root-only. |
+| `connections/` | External MCP and OpenAPI services | Yes | One connection per file; its name comes from the filename. |
+| `hooks/` | Lifecycle and stream-event subscribers | Yes | Module-backed only. Recursive directories are supported. |
+| `skills/` | On-demand procedures and capability packs | Yes | Flat markdown, module-backed skills, or packaged skills. Runtime files are seeded under `$HOME/.agents/skills/`, with `/workspace/skills/` as a fallback. |
+| `lib/` | Shared authored helper code | Yes | Import-only; not mounted into the workspace. |
+| `sandbox.ts` or `sandbox/sandbox.ts` | The agent's single sandbox | Yes | Use `sandbox.ts` for a definition-only override; use `sandbox/sandbox.ts` with `sandbox/workspace/**` to also seed files. The framework default applies when neither is authored. |
+| `sandbox/workspace/**` | Files seeded into the sandbox | Yes | Mirrored into `/workspace/` when a session starts. |
+| `tools/` | Typed executable integrations | Yes | Module-backed only. |
+| `schedules/` | Recurring jobs | No | Each schedule is a default-exported `defineSchedule` module or a markdown prompt with `cron` frontmatter. Recursive nesting is supported. Root-only. |
+| `subagents/` | Specialist child agents | Yes | Each child is a local package under `subagents/<id>/`. Nested subagents are supported. |
+
+### Runtime files and source files
+
+eve does not mount the whole authored tree into the runtime sandbox. Files under `agent/sandbox/workspace/**` land in `/workspace/` when a session starts.
+
+Skill package files land outside the workspace under `$HOME/.agents/skills/`, with `/workspace/skills/` as a fallback when `$HOME` is unavailable. Everything in `lib/` remains import-only source code.
+
+### Local subagents
+
+A local subagent uses the same `agent.ts` shape as the root:
+
+```text
+agent/subagents/researcher/
+├── agent.ts
+├── instructions.md
+├── connections/
+├── hooks/
+├── skills/
+├── lib/
+├── sandbox/
+├── tools/
+└── subagents/
+```
+
+A subagent's `agent.ts` is required and must provide a description, while its instructions are optional. Connections, hooks, skills, shared code, sandboxes, tools, and nested subagents are supported. Channels and schedules remain root-only. See [Subagents](./subagents) for inheritance and isolation behavior.
+
+### Flat layout
+
+When the app root is also the agent root, eve supports this layout:
+
+```text
+my-agent/
+├── package.json
+├── agent.ts
+├── instructions.md
+├── tools/
+└── skills/
+```
+
+Prefer the nested layout because it keeps application files separate from the authored agent surface.
+
+### Debug file discovery
+
+Run `eve info` when eve does not discover a file. It lists the discovered surface and diagnostics so you can check the authored slot and root-versus-subagent boundary. eve also writes inspectable artifacts under `.eve/`; see [Observability](./guides/instrumentation) and the [CLI](./reference/cli) reference.
+
+## Install manually
+
+If you do not want to use the scaffold, install the runtime dependencies:
+
+```bash
+npm install eve@latest ai zod
+```
+
+Declare Node.js 24 in `package.json`, then create `agent/instructions.md` and, when you need runtime configuration, `agent/agent.ts`.
+
+## Continue with the tutorial
+
+The [Tutorial](/docs/tutorial/first-agent) builds a data analytics agent step by step. It adds tools, state, sandboxed analysis, reusable skills, and human approval before deploying the result.
+
+After the tutorial, continue with the task you need:
-## Choose your next step
+| Goal | Read |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Give the model an action it can call | [Tools](/docs/tools) |
+| Connect an MCP server or OpenAPI service | [Connections](/docs/connections) |
+| Reach users through Slack, Discord, or another platform | [Channels](/docs/channels/overview) |
+| Build a browser interface | [Frontend Frameworks](/docs/guides/frontend/overview) |
+| Test agent behavior | [Evals](/docs/evals/overview) |
+| Secure and deploy the agent | [Authentication](/docs/guides/auth-and-route-protection), then [Deployment](/docs/guides/deployment/overview) |
-Start with [Installation](/docs/installation) when you need a new project. Read [Project structure](/docs/project-structure) when you already have an eve project or want to add a capability.
+Read [Execution Model and Durability](/docs/concepts/execution-model-and-durability) for the mental model behind sessions, turns, durable steps, and parked work.
diff --git a/docs/guides/auth-and-route-protection.md b/docs/guides/auth-and-route-protection.md
index d7975bb71..8720cfc19 100644
--- a/docs/guides/auth-and-route-protection.md
+++ b/docs/guides/auth-and-route-protection.md
@@ -1,5 +1,5 @@
---
-title: "Auth & Route Protection"
+title: "Authentication"
description: "Secure your agent's HTTP routes with an ordered auth walk, verifier helpers, and connection OAuth via Vercel Connect."
---
@@ -12,7 +12,7 @@ Start with route auth.
## Route auth
-The route-auth policy lives on the HTTP channel factory (`agent/channels/eve.ts`) and guards three routes:
+The route-auth policy lives on the HTTP channel factory (`agent/channels/eve.ts`) and guards these route groups:
- `POST /eve/v1/session`
- `POST /eve/v1/session/:sessionId`
@@ -307,22 +307,7 @@ Built-in platform channels that identify a human sender, such as Slack, Discord,
### On a connection
-Attach `connect()` from `@vercel/connect/eve` to the connection:
-
-```ts title="agent/connections/linear.ts"
-import { connect } from "@vercel/connect/eve";
-import { defineMcpClientConnection } from "eve/connections";
-import { once } from "eve/tools/approval";
-
-export default defineMcpClientConnection({
- url: "https://mcp.linear.app/mcp",
- description: "Linear: project management, issue tracking, and team workflows.",
- auth: connect("linear/myagent"),
- approval: once(),
-});
-```
-
-The first call that needs a user-scoped connection kicks off an OAuth sign-in, surfaced as an authorization challenge (a URL the caller visits). [Vercel Connect](https://vercel.com/docs/connect) brokers the flow and holds the credentials, which are resolved and cached per workflow step, never serialized into history, and never shown to the model. For non-interactive connections, pass a static token or `connect({ connector, principalType: "app" })` in place of user-scoped `connect()`. [Connections](../connections) covers both shapes.
+Set `auth` on an MCP or OpenAPI connection when the external service supplies a family of remote tools. The [connections overview](../connections) owns the shared `connect()` setup, static-token providers, app and user scope, approval interaction, and self-hosted OAuth flow.
### On a single tool
diff --git a/docs/guides/client/meta.json b/docs/guides/client/meta.json
index dbb0041cd..347c5fd05 100644
--- a/docs/guides/client/meta.json
+++ b/docs/guides/client/meta.json
@@ -1,4 +1,5 @@
{
- "title": "TypeScript SDK",
+ "title": "Client SDK",
+ "defaultOpen": false,
"pages": ["overview", "messages", "continuations", "streaming", "output-schema"]
}
diff --git a/docs/guides/client/output-schema.mdx b/docs/guides/client/output-schema.mdx
index 5253a0e47..a80024132 100644
--- a/docs/guides/client/output-schema.mdx
+++ b/docs/guides/client/output-schema.mdx
@@ -119,10 +119,10 @@ const followUp = await followUpResponse.result();
console.log(followUp.data); // undefined unless this turn also requested a schema
```
-For task-mode output that belongs to the agent or subagent definition itself, see [`agent.ts`](../../agent-config#outputschema) and [Subagents](../../subagents).
+For task-mode output that belongs to the agent or subagent definition itself, see [`agent.ts`](../../agent-config#other-defineagent-fields) and [Subagents](../../subagents).
## What to read next
- [Messages](./messages): send turns with `send()`
- [Streaming](./streaming): handle `result.completed` live
-- [`agent.ts`](../../agent-config#outputschema): configured task-mode output
+- [`agent.ts`](../../agent-config#other-defineagent-fields): configured task-mode output
diff --git a/docs/guides/client/overview.mdx b/docs/guides/client/overview.mdx
index 5683233b1..dd30b08ee 100644
--- a/docs/guides/client/overview.mdx
+++ b/docs/guides/client/overview.mdx
@@ -1,5 +1,5 @@
---
-title: "TypeScript SDK Overview"
+title: "Client SDK"
description: "Call an eve agent from TypeScript with Client, sessions, auth, and health checks."
---
diff --git a/docs/guides/deployment/meta.json b/docs/guides/deployment/meta.json
index 75483dedf..5c5975069 100644
--- a/docs/guides/deployment/meta.json
+++ b/docs/guides/deployment/meta.json
@@ -1,4 +1,5 @@
{
"title": "Deployment",
+ "defaultOpen": false,
"pages": ["overview", "vercel", "self-hosting"]
}
diff --git a/docs/guides/deployment/overview.md b/docs/guides/deployment/overview.md
index 30b65cba2..2fa675a76 100644
--- a/docs/guides/deployment/overview.md
+++ b/docs/guides/deployment/overview.md
@@ -34,7 +34,7 @@ Keep credentials in your deployment environment or secret manager. Don’t inclu
Your model configuration determines the required credential. A string model ID uses the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway) and requires Vercel project OpenID Connect (OIDC) or `AI_GATEWAY_API_KEY`. A provider-authored model uses that provider’s package and API key. See [Agent configuration](../../agent-config#set-the-model) for both forms.
-Configure production route authentication separately from model access. The default policy rejects browser traffic in production. See [Auth and route protection](../auth-and-route-protection) for the available policies and secret requirements.
+Configure production route authentication separately from model access. The default policy rejects browser traffic in production. See [Authentication](../auth-and-route-protection) for the available policies and secret requirements.
## Verify the deployment
diff --git a/docs/guides/deployment/self-hosting.md b/docs/guides/deployment/self-hosting.md
index c470f57ee..fad0f11bb 100644
--- a/docs/guides/deployment/self-hosting.md
+++ b/docs/guides/deployment/self-hosting.md
@@ -1,5 +1,5 @@
---
-title: "Self-host eve"
+title: "Self-Host eve"
description: "Run an eve agent as a Node service with your own workflow storage, sandbox backend, and routing."
---
@@ -22,7 +22,7 @@ Run this process under the same process manager or container platform you use fo
Set `AI_GATEWAY_API_KEY` to use a string model ID through the Vercel AI Gateway from a non-Vercel host. To call a provider directly, install its [AI SDK provider package](https://ai-sdk.dev/docs/foundations/providers-and-models). Then pass its model object in `agent.ts` and set its API key. See [Agent configuration](../../agent-config#set-the-model) for examples.
-Don’t rely on `vercelOidc()` as the only production authenticator outside Vercel. Configure Basic auth, JSON Web Token (JWT) verification, generic OpenID Connect (OIDC), or a custom verifier that your host can validate. See [Auth and route protection](../auth-and-route-protection).
+Don’t rely on `vercelOidc()` as the only production authenticator outside Vercel. Configure Basic auth, JSON Web Token (JWT) verification, generic OpenID Connect (OIDC), or a custom verifier that your host can validate. See [Authentication](../auth-and-route-protection).
## Persist workflow state
@@ -83,6 +83,6 @@ eve dev https://your_agent.example.com
Use these guides to secure and observe the deployed agent:
-- [Auth and route protection](../auth-and-route-protection): configure the host’s route policy
+- [Authentication](../auth-and-route-protection): configure the host’s route policy
- [Observability](../instrumentation): export traces and diagnose runtime failures
- [Sandbox](../../sandbox): select and secure a sandbox backend
diff --git a/docs/guides/deployment/vercel.mdx b/docs/guides/deployment/vercel.mdx
index 38023de39..ad001baf4 100644
--- a/docs/guides/deployment/vercel.mdx
+++ b/docs/guides/deployment/vercel.mdx
@@ -85,6 +85,6 @@ The Agent Runs tab requires enablement for your Vercel team. Contact your Vercel
Use these guides to secure and observe the deployed agent:
-- [Auth and route protection](../auth-and-route-protection): configure who can call the deployed agent
+- [Authentication](../auth-and-route-protection): configure who can call the deployed agent
- [Observability](../instrumentation): export traces and diagnose runtime failures
- [Sandbox](../../sandbox): configure resources, isolation, and network access
diff --git a/docs/guides/dev-tui.md b/docs/guides/dev-tui.md
index 5ed52b05a..bae62f884 100644
--- a/docs/guides/dev-tui.md
+++ b/docs/guides/dev-tui.md
@@ -1,5 +1,5 @@
---
-title: "Dev TUI"
+title: "Terminal UI"
description: "Use eve locally or connect to a deployed agent from an interactive terminal UI."
---
@@ -57,23 +57,13 @@ Use `/traces` to inspect traces recorded during local development. See [Instrume
## Display options
-Use `eve dev` flags to control how much detail the UI renders:
+Use `eve dev` flags to control tool calls, reasoning, subagents, connection authorization, response statistics, context usage, and logs:
```bash
eve dev --tools full --reasoning collapsed --logs all
```
-| Flag | Values | Description |
-| ---------------------------- | ----------------------------------------------- | -------------------------------------------------- |
-| `--tools` | `full`, `collapsed`, `auto-collapsed`, `hidden` | Tool-call display. |
-| `--reasoning` | `full`, `collapsed`, `auto-collapsed`, `hidden` | Reasoning display. |
-| `--subagents` | `full`, `collapsed`, `auto-collapsed`, `hidden` | Subagent display. |
-| `--connection-auth` | `full`, `collapsed`, `auto-collapsed`, `hidden` | Connection-authorization display. |
-| `--assistant-response-stats` | `tokens`, `tokensPerSecond` | Assistant response statistic. |
-| `--context-size` | Token count | Model context-window size for the usage indicator. |
-| `--logs` | `all`, `stderr`, `sandbox`, `none` | Initial log display mode. |
-
-Use `--host` and `--port` to bind the local server, or `--no-ui` to run without the terminal UI. See the [CLI reference](../reference/cli#eve-dev) for all options.
+Use `--host` and `--port` to bind the local server, or `--no-ui` to run without the terminal UI. See the [`eve dev` CLI reference](../reference/cli#eve-dev) for the complete option list, accepted values, and defaults.
## Connect to a deployment
diff --git a/docs/guides/dynamic-capabilities.md b/docs/guides/dynamic-capabilities.md
index daa013d73..cb2822324 100644
--- a/docs/guides/dynamic-capabilities.md
+++ b/docs/guides/dynamic-capabilities.md
@@ -237,4 +237,4 @@ Both resolve before the prompt is assembled, so the model sees the right instruc
- The static tool basics this builds on → [Tools](../tools)
- The built-in tools and how to override them → [Default harness](../concepts/default-harness)
- Authenticate a tool or connection to an external service → [Auth & route protection](./auth-and-route-protection)
-- Durable per-session memory for resolvers to read → [State](./state)
+- Durable per-session memory for resolvers to read → [State](../concepts/state)
diff --git a/docs/guides/frontend/meta.json b/docs/guides/frontend/meta.json
index 436c9f3b5..b212c7d8f 100644
--- a/docs/guides/frontend/meta.json
+++ b/docs/guides/frontend/meta.json
@@ -1,4 +1,5 @@
{
- "title": "Frontend",
+ "title": "Frontend Frameworks",
+ "defaultOpen": false,
"pages": ["overview", "nextjs", "nuxt", "sveltekit", "use-eve-agent-vue", "use-eve-agent-svelte"]
}
diff --git a/docs/guides/frontend/nextjs.mdx b/docs/guides/frontend/nextjs.mdx
index 8bce5fdef..97905b4ca 100644
--- a/docs/guides/frontend/nextjs.mdx
+++ b/docs/guides/frontend/nextjs.mdx
@@ -88,16 +88,7 @@ const agent = useEveAgent({
});
```
-The default eve channel is fail-closed. With no `agent/channels/eve.ts` authored, eve registers `eveChannel({ auth: [vercelOidc(), localDev(), placeholderAuth()] })`: `vercelOidc()` gets the first chance to resolve a Vercel caller, `localDev()` authenticates while the process is an `eve dev` or `vercel dev` server, and everything else gets a `401`. To run your app's own auth policy, add `agent/channels/eve.ts`:
-
-```ts title="agent/channels/eve.ts"
-import { eveChannel } from "eve/channels/eve";
-import { localDev, vercelOidc } from "eve/channels/auth";
-
-export default eveChannel({ auth: [vercelOidc(), localDev()] });
-```
-
-For a public demo, use `none()` (also from `eve/channels/auth`) to skip authentication. See [Channels](../../channels/overview) and [Auth & route protection](../auth-and-route-protection).
+The browser still needs a production authentication policy. See [Authenticate browser requests](./overview#authenticate-browser-requests) for the default fail-closed behavior and channel configuration.
## Dev vs deploy topology
diff --git a/docs/guides/frontend/nuxt.mdx b/docs/guides/frontend/nuxt.mdx
index 725e4f9ab..d2595adad 100644
--- a/docs/guides/frontend/nuxt.mdx
+++ b/docs/guides/frontend/nuxt.mdx
@@ -60,16 +60,7 @@ async function handleSubmit() {
</template>
```
-The default eve channel is fail-closed. With no `agent/channels/eve.ts` authored, eve registers `eveChannel({ auth: [vercelOidc(), localDev(), placeholderAuth()] })`: `vercelOidc()` gets the first chance to resolve a Vercel caller, `localDev()` authenticates while the process is an `eve dev` or `vercel dev` server, and everything else gets a `401`. To run your own auth policy, add `agent/channels/eve.ts`:
-
-```ts title="agent/channels/eve.ts"
-import { eveChannel } from "eve/channels/eve";
-import { localDev, vercelOidc } from "eve/channels/auth";
-
-export default eveChannel({ auth: [vercelOidc(), localDev()] });
-```
-
-For a public demo, use `none()` (also from `eve/channels/auth`) to skip authentication. See [Channels](../../channels/overview) and [Auth & route protection](../auth-and-route-protection).
+The browser still needs a production authentication policy. See [Authenticate browser requests](./overview#authenticate-browser-requests) for the default fail-closed behavior and channel configuration.
## Dev vs deploy topology
diff --git a/docs/guides/frontend/overview.mdx b/docs/guides/frontend/overview.mdx
index 156867d2a..0b2fff9dd 100644
--- a/docs/guides/frontend/overview.mdx
+++ b/docs/guides/frontend/overview.mdx
@@ -14,7 +14,15 @@ A browser UI is a client of the agent's HTTP routes (the [eve channel](../../cha
The per-framework pages below walk through the wiring step by step: [Next.js](./nextjs), [Nuxt](./nuxt), and [SvelteKit](./sveltekit).
-For scripts, server-to-server calls, evals, tests, or custom clients that do not need framework UI state, use the [TypeScript SDK](../client/overview) directly.
+For scripts, server-to-server calls, evals, tests, or custom clients that do not need framework UI state, use the [Client SDK](../client/overview) directly.
+
+## Authenticate browser requests
+
+A same-origin framework integration sends your application cookies with every eve request. For bearer tokens or another non-cookie scheme, pass `auth` or `headers` to `useEveAgent`.
+
+The default eve channel fails closed. Without an authored `agent/channels/eve.ts`, production browser traffic receives `401` from the default `[vercelOidc(), localDev(), placeholderAuth()]` policy. Add the channel file with an `AuthFn` that verifies your application session or token.
+
+For a public demo, use `none()` from `eve/channels/auth` to admit anonymous requests explicitly. Do not use `none()` for an agent that handles private or production data. See [Authentication](../auth-and-route-protection) for application-session examples, token verifiers, and the default policy.
## Basic chat (React)
@@ -204,11 +212,12 @@ const agent = useEveAgent({
## Lifecycle callbacks
-On top of `onSessionChange`, the hook takes a few per-turn callbacks:
+The hook accepts these lifecycle callbacks:
- `onEvent(event)`: fires for each eve stream event as it arrives.
- `onError(error)`: fires with the last `Error` when a turn fails.
- `onFinish(snapshot)`: fires with the final `{ data, status, session, ... }` snapshot once a turn settles.
+- `onSessionChange(session)`: fires when the session cursor advances. Persist it to resume across reloads.
```tsx
const agent = useEveAgent({
@@ -320,5 +329,5 @@ const support = useEveAgent({ agent: "support" });
- [Sessions, runs & streaming](../../concepts/sessions-runs-and-streaming): the event stream and session cursor
- [Channels](../../channels/overview): the HTTP routes the hook talks to
-- [TypeScript SDK](../client/overview): the lower-level client underneath the frontend hooks
+- [Client SDK](../client/overview): the lower-level client underneath the frontend hooks
- [Next.js](./nextjs): step-by-step setup for wiring eve into a Next.js app
diff --git a/docs/guides/frontend/sveltekit.mdx b/docs/guides/frontend/sveltekit.mdx
index 1805240d3..2bee15a91 100644
--- a/docs/guides/frontend/sveltekit.mdx
+++ b/docs/guides/frontend/sveltekit.mdx
@@ -69,16 +69,7 @@ With the plugin in `vite.config.ts`, components call [`useEveAgent`](./use-eve-a
</form>
```
-The default eve channel is fail-closed. With no `agent/channels/eve.ts` authored, eve registers `eveChannel({ auth: [vercelOidc(), localDev(), placeholderAuth()] })`: `vercelOidc()` gets the first chance to resolve a Vercel caller, `localDev()` authenticates while the process is an `eve dev` or `vercel dev` server, and everything else gets a `401`. To set your own auth policy, add `agent/channels/eve.ts`:
-
-```ts title="agent/channels/eve.ts"
-import { eveChannel } from "eve/channels/eve";
-import { localDev, vercelOidc } from "eve/channels/auth";
-
-export default eveChannel({ auth: [vercelOidc(), localDev()] });
-```
-
-For a public demo, use `none()` (also from `eve/channels/auth`) to skip authentication. See [Channels](../../channels/overview) and [Auth & route protection](../auth-and-route-protection).
+The browser still needs a production authentication policy. See [Authenticate browser requests](./overview#authenticate-browser-requests) for the default fail-closed behavior and channel configuration.
## Dev vs deploy topology
diff --git a/docs/guides/frontend/use-eve-agent-svelte.mdx b/docs/guides/frontend/use-eve-agent-svelte.mdx
index f73a972e2..606918bdb 100644
--- a/docs/guides/frontend/use-eve-agent-svelte.mdx
+++ b/docs/guides/frontend/use-eve-agent-svelte.mdx
@@ -1,43 +1,15 @@
---
title: "useEveAgent (Svelte)"
-description: "Svelte 5 binding that drives an eve agent session from the browser."
+description: "Use the eve Svelte binding and its Svelte-specific reactive interface."
---
-`useEveAgent()` from `eve/svelte` is the browser side of an eve session in a Svelte 5 app. Call it once for a long-lived session you can send turns to, with every stream event projected into rune-friendly reactive data. On SvelteKit, the [Vite plugin](./sveltekit) wires up the routes. The [frontend overview](./overview) covers the model shared across frameworks.
+`useEveAgent()` from `eve/svelte` exposes the shared eve frontend client through Svelte 5 reactive getters and methods. Read the [frontend overview](./overview) for session behavior, messages, human input, authorization, callbacks, reducers, and persistence. This page covers the Svelte-specific interface.
-## Basic usage
-
-Import from `eve/svelte` and read the reactive getters directly. No `$` prefix:
-
-```svelte
-<script lang="ts">
- import { useEveAgent } from "eve/svelte";
-
- const agent = useEveAgent();
-</script>
-
-{#each agent.data.messages as message}
- <p>{message.role}: {JSON.stringify(message.parts)}</p>
-{/each}
-```
-
-## What it returns
+On SvelteKit, register the [`eveSvelteKit` Vite plugin](./sveltekit) to mount the agent routes on the application origin.
-| Property | Type | Description |
-| --------- | --------------------------------------------- | ------------------------------------------------------------------------- |
-| `data` | `TData` | Projected state. With the default reducer, `EveMessageData` (`messages`). |
-| `status` | `UseEveAgentStatus` | `"ready"`, `"submitted"`, `"streaming"`, or `"error"`. |
-| `error` | `Error \| undefined` | Last transport-level error. |
-| `events` | `readonly MessageStreamEvent[]` | Raw server events for this session. |
-| `session` | `ClientSessionState \| undefined` | Fixed session ID and stream cursor. |
-| `send` | `(message, options?) => Promise<void>` | Send text or a multi-part message. |
-| `respond` | `(inputResponses, options?) => Promise<void>` | Answer pending HITL input requests. |
-| `stop` | `() => void` | Abort the client's in-flight stream. |
-| `reset` | `() => void` | Clear state and start a new session. |
-
-These state fields are reactive getters, so read them straight from templates, `$derived`, or `$effect`. They are not stores, so don't prefix them with `$`.
+## Basic usage
-## Send a message
+Call the binding once for a conversation and read its reactive getters directly. The returned object is not a Svelte store, so its fields do not use the `$` prefix:
```svelte
<script lang="ts">
@@ -45,39 +17,51 @@ These state fields are reactive getters, so read them straight from templates, `
const agent = useEveAgent();
let message = $state("");
+ let isBusy = $derived(agent.status === "submitted" || agent.status === "streaming");
async function handleSubmit() {
const text = message.trim();
- if (!text) return;
+ if (!text || isBusy) return;
message = "";
await agent.send(text);
}
</script>
+{#each agent.data.messages as item}
+ <p>{item.role}: {JSON.stringify(item.parts)}</p>
+{/each}
+
<form onsubmit={(event) => {
event.preventDefault();
void handleSubmit();
}}>
- <input bind:value={message} placeholder="Type a message..." />
- <button type="submit">Send</button>
+ <input bind:value={message} disabled={isBusy} />
+ <button type="submit" disabled={isBusy}>Send</button>
</form>
```
-When a turn is more than plain text, reach for `send()`. Attachments follow the AI SDK `UserContent` format. Send file data as a base64 `data:` URL so it survives the JSON transport:
+## What it returns
-```ts
-const bytes = new Uint8Array(await file.arrayBuffer());
-const base64 = btoa(String.fromCodePoint(...bytes));
+The state fields are reactive getters; the commands are ordinary methods:
-await agent.send([
- { type: "text", text: "Describe this image." },
- { type: "file", data: `data:${file.type};base64,${base64}`, mediaType: file.type },
-]);
-```
+| Property | Svelte shape |
+| ---------------------------------- | --------------------------------- |
+| `data` | `TData` |
+| `status` | `UseEveAgentStatus` |
+| `error` | `Error \| undefined` |
+| `events` | `readonly MessageStreamEvent[]` |
+| `session` | `ClientSessionState \| undefined` |
+| `send`, `respond`, `stop`, `reset` | Methods |
+
+Read the getters directly in templates, `$derived`, or `$effect`. The [shared returned-state reference](./overview#returned-state) describes what each value and command does.
+
+## Send a message
+
+Call `agent.send(text)` for text or pass content parts for attachments. The API and transport behavior match the [shared sending guide](./overview#sending-and-streaming); only reactive access differs in Svelte.
## Human-in-the-loop prompts
-A tool opts into approval with `approval` ([Tools](../../tools)). When one fires, the pending request rides along on a `dynamic-tool` part at `part.toolMetadata?.eve?.inputRequest`. Scan every message because an unrelated turn can add newer messages while the approval stays open, then answer through the same session with `agent.respond(inputResponses)`:
+Pending requests appear in `agent.data.messages`. Use the Svelte exports when narrowing message parts, then answer through `agent.respond()`:
```svelte
<script lang="ts">
@@ -118,101 +102,30 @@ A tool opts into approval with `approval` ([Tools](../../tools)). When one fires
{/each}
```
-For a question with `allowFreeform`, bind a text input and send `{ requestId, text }`. The [React hook reference](./overview) covers the shared behavior.
+See [Human-in-the-loop prompts](./overview#human-in-the-loop-prompts) for request semantics and rendering guidance.
## Stop, reset, and resume
-`stop()` aborts the in-flight stream; the server-side turn keeps running and remains attachable — to stop the turn itself, POST the session's [cancel route](../../channels/eve#routes). `reset()` wipes state and starts a fresh session. To resume across reloads, hand `initialSession` the state you saved earlier and use `onSessionChange` to persist the cursor as it advances:
-
-```ts
-const agent = useEveAgent({
- initialSession: savedSessionState,
- initialEvents: savedEvents,
- onSessionChange: (session) => {
- localStorage.setItem("eve-session", JSON.stringify(session));
- },
-});
-```
+Call `agent.stop()` to detach the browser stream without cancelling server-side work, and `agent.reset()` to clear local state and start a new session. Pass `initialSession` and `initialEvents` to restore a saved conversation. See [Resumable sessions](./overview#resumable-sessions) for the persistence contract and [Sending and streaming](./overview#sending-and-streaming) for cancellation behavior.
## Custom host and credentials
-Point `host` at an eve server on a different origin, and pass credentials through `auth` or `headers`. When you supply a function, it re-resolves before every request:
-
-```ts
-const agent = useEveAgent({
- host: "https://agent.example.com",
- headers: async () => ({
- authorization: `Bearer ${await getAccessToken()}`,
- }),
-});
-```
+Pass `host`, `auth`, or `headers` to the binding using the same options as the other frontend bindings. See [Custom hosts and headers](./overview#custom-hosts-and-headers).
## Attach page context per turn
-`clientContext` adds ephemeral context for the next model call and nothing more. Strings (or an array of strings) become user-role context messages; an object is JSON-serialized into one. It rides along with a message or HITL response, never dispatches a turn on its own, and never lands in durable session history. Pass it to `send()`:
-
-```ts
-await agent.send("What should I do on this screen?", {
- clientContext: { route: "/billing", plan: "pro", seatsUsed: 4 },
-});
-```
-
-To attach the same context to every turn without threading it through each call site, pass `prepareSend`. It runs right before each send and returns the (possibly augmented) turn:
-
-```ts
-const agent = useEveAgent({
- prepareSend: (input) => ({
- ...input,
- clientContext: { route: location.pathname },
- }),
-});
-```
+Pass `clientContext` to `send()` or `respond()`, or use `prepareSend` to add context before every turn. See [Attach page context per turn](./overview#attach-page-context-per-turn).
## Lifecycle callbacks
-The binding takes a few per-turn callbacks:
-
-- `onEvent(event)`: fires for each eve stream event as it arrives.
-- `onError(error)`: fires with the last `Error` when a turn fails.
-- `onFinish(snapshot)`: fires with the final snapshot once a turn settles.
-- `onSessionChange(session)`: fires when the session cursor advances. Persist it to resume across reloads.
-
-```ts
-const agent = useEveAgent({
- onEvent: (event) => console.debug(event.type),
- onError: (error) => console.error(error.message),
- onFinish: (snapshot) => console.log(snapshot.status),
-});
-```
-
-The `optimistic` option (default `true`) projects submitted user messages into `data` before eve confirms them with a `message.received` event. These are reducer-facing projection events only; `events` stays the authoritative eve stream.
+Pass `onEvent`, `onError`, `onFinish`, or `onSessionChange` when the application needs lifecycle notifications. See [Lifecycle callbacks](./overview#lifecycle-callbacks) for callback timing and optimistic projection behavior.
## Custom reducer
-The default reducer projects events into `{ messages }` (`EveMessageData`). To shape `data` differently, pass a `reducer` implementing `EveAgentReducer<TData>`:
-
-```ts
-import { useEveAgent } from "eve/svelte";
-import type { EveAgentReducer } from "eve/svelte";
-
-interface ToolLog {
- readonly toolCalls: number;
-}
-
-const toolCounter: EveAgentReducer<ToolLog> = {
- initial: () => ({ toolCalls: 0 }),
- reduce: (data, event) =>
- event.type === "actions.requested" ? { toolCalls: data.toolCalls + 1 } : data,
-};
-
-const agent = useEveAgent({ reducer: toolCounter });
-// agent.data is ToolLog
-```
-
-`reduce(data, event)` receives both authoritative eve stream events and client projection events (`client.message.submitted`, `client.message.failed`, `client.input.responded`). Handle the client events too if you want optimistic and HITL state in your projection. Otherwise, return `data` unchanged for them.
+Import `EveAgentReducer` from `eve/svelte` when projecting events into application-specific state. The resulting `agent.data` uses the reducer's `TData` type. See [Custom reducer](./overview#custom-reducer) for the reducer contract and client projection events.
## What to read next
-- [SvelteKit](./sveltekit): Vite plugin setup
-- [Frontend overview](./overview): the shared integration model
-- [Sessions, runs & streaming](../../concepts/sessions-runs-and-streaming)
+- [SvelteKit](./sveltekit): register the Vite plugin and mount the eve runtime.
+- [Frontend overview](./overview): use the shared frontend API.
+- [Sessions, runs, and streaming](../../concepts/sessions-runs-and-streaming): understand the underlying session protocol.
diff --git a/docs/guides/frontend/use-eve-agent-vue.mdx b/docs/guides/frontend/use-eve-agent-vue.mdx
index 1b3553610..c3ef32786 100644
--- a/docs/guides/frontend/use-eve-agent-vue.mdx
+++ b/docs/guides/frontend/use-eve-agent-vue.mdx
@@ -1,94 +1,66 @@
---
title: "useEveAgent (Vue)"
-description: "Vue composable that drives an eve agent session from the browser."
+description: "Use the eve Vue composable and its Vue-specific reactive interface."
---
-`useEveAgent()` from `eve/vue` is how a Vue app talks to an eve session. It opens a long-lived session, sends turns, and folds every stream event into reactive data you can bind in a template. Nuxt auto-imports it through the [module](./nuxt), and the [frontend overview](./overview) covers the shared model.
+`useEveAgent()` from `eve/vue` exposes the shared eve frontend client as Vue computed refs and methods. Read the [frontend overview](./overview) for session behavior, messages, human input, authorization, callbacks, reducers, and persistence. This page covers the Vue-specific interface.
-## Basic usage
-
-Import the composable from `eve/vue`. Its state is exposed as `ComputedRef`s, so you read it unwrapped in templates:
-
-```vue
-<script setup lang="ts">
-import { useEveAgent } from "eve/vue";
-
-const { data } = useEveAgent();
-</script>
-
-<template>
- <div v-for="message in data.messages" :key="message.id">
- <p>{{ message.role }}: {{ message.parts }}</p>
- </div>
-</template>
-```
+Nuxt users normally receive the composable as an auto-import after registering the [`eve/nuxt` module](./nuxt).
-## What it returns
-
-| Property | Type | Description |
-| --------- | ---------------------------------------------- | ------------------------------------------------------------------------- |
-| `data` | `ComputedRef<TData>` | Projected state. With the default reducer, `EveMessageData` (`messages`). |
-| `status` | `ComputedRef<UseEveAgentStatus>` | `"ready"`, `"submitted"`, `"streaming"`, or `"error"`. |
-| `error` | `ComputedRef<Error \| undefined>` | Last transport-level error. |
-| `events` | `ComputedRef<readonly MessageStreamEvent[]>` | Raw server events for this session. |
-| `session` | `ComputedRef<ClientSessionState \| undefined>` | Fixed session ID and stream cursor. |
-| `send` | `(message, options?) => Promise<void>` | Send text or a multi-part message. |
-| `respond` | `(inputResponses, options?) => Promise<void>` | Answer pending HITL input requests. |
-| `stop` | `() => void` | Abort the client's in-flight stream. |
-| `reset` | `() => void` | Clear state and start a new session. |
+## Basic usage
-The first five are `ComputedRef`s; the rest are methods. Destructure whatever you need, since refs keep their reactivity through destructuring. Read them with `.value` in `<script>`, and unwrapped in `<template>`.
-
-## Send a message
+Import the composable from `eve/vue`. Its state is exposed as `ComputedRef`s, so templates unwrap it automatically:
```vue
<script setup lang="ts">
-import { ref } from "vue";
import { useEveAgent } from "eve/vue";
+import { computed, ref } from "vue";
-const { send } = useEveAgent();
+const { data, status, send } = useEveAgent();
const message = ref("");
+const isBusy = computed(() => status.value === "submitted" || status.value === "streaming");
async function handleSubmit() {
const text = message.value.trim();
- if (!text) return;
+ if (!text || isBusy.value) return;
message.value = "";
await send(text);
}
</script>
<template>
+ <div v-for="item in data.messages" :key="item.id">
+ <p>{{ item.role }}: {{ item.parts }}</p>
+ </div>
<form @submit.prevent="handleSubmit">
- <input v-model="message" placeholder="Type a message..." />
- <button type="submit">Send</button>
+ <input v-model="message" :disabled="isBusy" />
+ <button type="submit" :disabled="isBusy">Send</button>
</form>
</template>
```
-For anything beyond plain text, reach for `send()`. Attachments follow the AI SDK `UserContent` format. Send file data as a base64 `data:` URL so it survives the JSON transport:
+## What it returns
-```vue
-<script setup lang="ts">
-import { useEveAgent } from "eve/vue";
+The state fields are computed refs; the commands are ordinary methods:
-const { send } = useEveAgent();
-
-async function onFileChange(event: Event) {
- const file = (event.target as HTMLInputElement).files?.[0];
- if (!file) return;
- const bytes = new Uint8Array(await file.arrayBuffer());
- const base64 = btoa(String.fromCodePoint(...bytes));
- await send([
- { type: "text", text: "Describe this image." },
- { type: "file", data: `data:${file.type};base64,${base64}`, mediaType: file.type },
- ]);
-}
-</script>
-```
+| Property | Vue shape |
+| ---------------------------------- | ---------------------------------------------- |
+| `data` | `ComputedRef<TData>` |
+| `status` | `ComputedRef<UseEveAgentStatus>` |
+| `error` | `ComputedRef<Error \| undefined>` |
+| `events` | `ComputedRef<readonly MessageStreamEvent[]>` |
+| `session` | `ComputedRef<ClientSessionState \| undefined>` |
+| `send`, `respond`, `stop`, `reset` | Methods |
+
+Destructuring preserves reactivity because each state value remains a ref. Read refs with `.value` in `<script>` and without `.value` in a template. The [shared returned-state reference](./overview#returned-state) describes what each value and command does.
+
+## Send a message
+
+Call `send(text)` for text or pass content parts for attachments. The API and transport behavior match the [shared sending guide](./overview#sending-and-streaming); only reactive access differs in Vue.
## Human-in-the-loop prompts
-A tool opts into approval with `approval` ([Tools](../../tools)). When it triggers, the pending request shows up on a `dynamic-tool` part at `part.toolMetadata?.eve?.inputRequest`. Scan every message because an unrelated turn can add newer messages while the approval stays open, then answer through the same session with `respond(inputResponses)`:
+Pending requests appear in `data.value.messages`. Use the Vue exports when narrowing message parts, then answer through `respond()`:
```vue
<script setup lang="ts">
@@ -132,101 +104,30 @@ const pendingRequests = computed(() =>
</template>
```
-For a question with `allowFreeform`, bind a text input and send `{ requestId, text }`. The [React hook reference](./overview) covers the shared behavior.
+See [Human-in-the-loop prompts](./overview#human-in-the-loop-prompts) for request semantics and rendering guidance.
## Stop, reset, and resume
-`stop()` aborts the in-flight stream; the server-side turn keeps running and remains attachable — to stop the turn itself, POST the session's [cancel route](../../channels/eve#routes). `reset()` wipes state and starts a fresh session. To survive a reload, pass `initialSession` to restore a saved session and `onSessionChange` to persist the cursor as it moves:
-
-```ts
-const agent = useEveAgent({
- initialSession: savedSessionState,
- initialEvents: savedEvents,
- onSessionChange: (session) => {
- localStorage.setItem("eve-session", JSON.stringify(session));
- },
-});
-```
+Call `stop()` to detach the browser stream without cancelling server-side work, and `reset()` to clear local state and start a new session. Pass `initialSession` and `initialEvents` to restore a saved conversation. See [Resumable sessions](./overview#resumable-sessions) for the persistence contract and [Sending and streaming](./overview#sending-and-streaming) for cancellation behavior.
## Custom host and credentials
-When your eve server lives somewhere other than the same origin, point at it with `host` and attach credentials through `auth` or `headers`. Pass a function and it re-resolves before each request:
-
-```ts
-const agent = useEveAgent({
- host: "https://agent.example.com",
- headers: async () => ({
- authorization: `Bearer ${await getAccessToken()}`,
- }),
-});
-```
+Pass `host`, `auth`, or `headers` to the composable using the same options as the other frontend bindings. See [Custom hosts and headers](./overview#custom-hosts-and-headers).
## Attach page context per turn
-`clientContext` adds ephemeral context for the next model call and nothing more. Strings (or an array of strings) become user-role context messages; an object is JSON-serialized into one. It rides along with a message or HITL response, never dispatches a turn on its own, and never lands in durable session history. Pass it in the second argument to `send()` or `respond()`:
-
-```ts
-await send("What should I do on this screen?", {
- clientContext: { route: "/billing", plan: "pro", seatsUsed: 4 },
-});
-```
-
-To attach the same context to every turn without threading it through each call site, pass `prepareSend`. It runs right before each send and returns the (possibly augmented) turn:
-
-```ts
-const agent = useEveAgent({
- prepareSend: (input) => ({
- ...input,
- clientContext: { route: location.pathname },
- }),
-});
-```
+Pass `clientContext` to `send()` or `respond()`, or use `prepareSend` to add context before every turn. See [Attach page context per turn](./overview#attach-page-context-per-turn).
## Lifecycle callbacks
-The composable takes a few per-turn callbacks:
-
-- `onEvent(event)`: fires for each eve stream event as it arrives.
-- `onError(error)`: fires with the last `Error` when a turn fails.
-- `onFinish(snapshot)`: fires with the final snapshot once a turn settles.
-- `onSessionChange(session)`: fires when the session cursor advances. Persist it to resume across reloads.
-
-```ts
-const agent = useEveAgent({
- onEvent: (event) => console.debug(event.type),
- onError: (error) => console.error(error.message),
- onFinish: (snapshot) => console.log(snapshot.status),
-});
-```
-
-The `optimistic` option (default `true`) projects submitted user messages into `data` before eve confirms them with a `message.received` event. These are reducer-facing projection events only; `events` stays the authoritative eve stream.
+Pass `onEvent`, `onError`, `onFinish`, or `onSessionChange` when the application needs lifecycle notifications. See [Lifecycle callbacks](./overview#lifecycle-callbacks) for callback timing and optimistic projection behavior.
## Custom reducer
-The default reducer projects events into `{ messages }` (`EveMessageData`). To shape `data` differently, pass a `reducer` implementing `EveAgentReducer<TData>`:
-
-```ts
-import { useEveAgent } from "eve/vue";
-import type { EveAgentReducer } from "eve/vue";
-
-interface ToolLog {
- readonly toolCalls: number;
-}
-
-const toolCounter: EveAgentReducer<ToolLog> = {
- initial: () => ({ toolCalls: 0 }),
- reduce: (data, event) =>
- event.type === "actions.requested" ? { toolCalls: data.toolCalls + 1 } : data,
-};
-
-const agent = useEveAgent({ reducer: toolCounter });
-// agent.data.value is ToolLog
-```
-
-`reduce(data, event)` receives both authoritative eve stream events and client projection events (`client.message.submitted`, `client.message.failed`, `client.input.responded`). Handle the client events too if you want optimistic and HITL state in your projection. Otherwise, return `data` unchanged for them.
+Import `EveAgentReducer` from `eve/vue` when projecting events into application-specific state. The resulting `data` remains a `ComputedRef<TData>`. See [Custom reducer](./overview#custom-reducer) for the reducer contract and client projection events.
## What to read next
-- [Nuxt](./nuxt): module setup
-- [Frontend overview](./overview): the shared integration model
-- [Sessions, runs & streaming](../../concepts/sessions-runs-and-streaming)
+- [Nuxt](./nuxt): register the module and mount the eve runtime.
+- [Frontend overview](./overview): use the shared frontend API.
+- [Sessions, runs, and streaming](../../concepts/sessions-runs-and-streaming): understand the underlying session protocol.
diff --git a/docs/guides/instrumentation.md b/docs/guides/instrumentation.md
index 63ba41822..20cdfd8ba 100644
--- a/docs/guides/instrumentation.md
+++ b/docs/guides/instrumentation.md
@@ -1,5 +1,5 @@
---
-title: "instrumentation.ts"
+title: "Observability"
description: "Trace an agent with OpenTelemetry in instrumentation.ts, read the workflow run tags eve emits, and debug discovery with eve info and the common-failures table."
---
@@ -179,7 +179,7 @@ Note: By default, telemetry records full message history and model outputs You m
Without an `instrumentation.ts`, `eve dev` records spans to disk — one trace per session, with turns, model steps, and tool calls. Read them two ways:
-- [`/traces`](dev-tui#inspect-traces) in the dev TUI: a live viewer that replays the trace as a conversation.
+- [`/traces`](dev-tui#logs-and-traces) in the dev TUI: a live viewer that replays the trace as a conversation.
- [`eve traces`](../reference/cli#eve-traces): a span tree in the terminal, `eve traces ls` to list. Works after `eve dev` exits.
Writing `instrumentation.ts` replaces this: your `setup` takes over and nothing is recorded locally. For span attributes, retention, and the `EVE_TRACES*` variables, see [`eve traces`](../reference/cli#eve-traces).
@@ -199,13 +199,13 @@ When `eve build` fails on discovery errors, the CLI prints the full diagnostics
### Common failures
-| Symptom | Likely cause and fix |
-| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Tool not discovered (the model never sees it) | Run `eve info`. Confirm the file is in the right slot (`agent/tools/<name>.ts`) and default-exports `defineTool(...)`, and check `.eve/diagnostics.json` for shape errors. `schedules/` are root-only. |
-| Model won't call a tool it should | Tighten the tool `description` and `inputSchema`; put procedural guidance in a [skill](../skills), not the description. Confirm it's in the active set with `eve info`. |
-| Stuck on `session.waiting` | The turn is parked for input. Answer the pending approval or question, or POST a follow-up to `/eve/v1/session/:sessionId`. |
-| 401 on production routes | Expected: auth fails closed. Replace `placeholderAuth()` with your route policy. Use `vercelOidc()` only for Vercel-issued tokens; otherwise configure `httpBasic()`, JWT/OIDC helpers, or a custom `AuthFn`. See [Auth and route protection](./auth-and-route-protection). |
-| Build fails with discovery errors | Read the printed diagnostics and `.eve/diagnostics.json`; confirm the root-vs-subagent boundary is valid and secrets come from env vars. |
+| Symptom | Likely cause and fix |
+| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Tool not discovered (the model never sees it) | Run `eve info`. Confirm the file is in the right slot (`agent/tools/<name>.ts`) and default-exports `defineTool(...)`, and check `.eve/diagnostics.json` for shape errors. `schedules/` are root-only. |
+| Model won't call a tool it should | Tighten the tool `description` and `inputSchema`; put procedural guidance in a [skill](../skills), not the description. Confirm it's in the active set with `eve info`. |
+| Stuck on `session.waiting` | The turn is parked for input. Answer the pending approval or question, or POST a follow-up to `/eve/v1/session/:sessionId`. |
+| 401 on production routes | Expected: auth fails closed. Replace `placeholderAuth()` with your route policy. Use `vercelOidc()` only for Vercel-issued tokens; otherwise configure `httpBasic()`, JWT/OIDC helpers, or a custom `AuthFn`. See [Authentication](./auth-and-route-protection). |
+| Build fails with discovery errors | Read the printed diagnostics and `.eve/diagnostics.json`; confirm the root-vs-subagent boundary is valid and secrets come from env vars. |
## What to read next
diff --git a/docs/guides/meta.json b/docs/guides/meta.json
index 9baa03415..e725d4d3a 100644
--- a/docs/guides/meta.json
+++ b/docs/guides/meta.json
@@ -6,14 +6,10 @@
"instrumentation",
"hooks",
"session-context",
- "state",
"dynamic-capabilities",
- "dynamic-workflows",
"remote-agents",
"dev-tui",
- "acp",
"frontend",
- "client",
- "ucp"
+ "client"
]
}
diff --git a/docs/guides/remote-agents.md b/docs/guides/remote-agents.md
index a9d17513a..bad40707c 100644
--- a/docs/guides/remote-agents.md
+++ b/docs/guides/remote-agents.md
@@ -20,14 +20,14 @@ export default defineRemoteAgent({
`defineRemoteAgent` accepts:
-| Parameter | Type | Required | Default | Description |
-| ------------------ | --------------------------------------------- | -------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `url` | `string \| (() => string \| Promise<string>)` | Yes | n/a | Base URL of the remote eve deployment to call. A string is baked at compile time; a function is resolved at runtime (see [Runtime URLs](#runtime-urls)). |
-| `description` | `string` | Yes | n/a | Model-visible delegation description. |
-| `auth` | `OutboundAuthFn` | No | none | Outbound auth hook from `eve/agents/auth`. |
-| `forwardPrincipal` | `boolean` | No | `false` | Forward the dispatching turn's session principal to the remote deployment (see [Forwarding the caller identity](#forwarding-the-caller-identity)). |
-| `headers` | `HeadersValue` | No | none | Static or lazily resolved request headers. |
-| `path` | `string` | No | `/eve/v1/session` | Route appended to `url` for the create-session request. |
+| Parameter | Type | Required | Default | Description |
+| ------------------ | --------------------------------------------- | -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `url` | `string \| (() => string \| Promise<string>)` | Yes | n/a | Base URL of the remote eve deployment to call. A string is baked at compile time; a function is resolved at runtime (see [Runtime URLs](#runtime-urls)). |
+| `description` | `string` | Yes | n/a | Model-visible delegation description. |
+| `auth` | `OutboundAuthFn` | No | none | Outbound auth hook from `eve/agents/auth`. |
+| `forwardPrincipal` | `boolean` | No | `false` | Forward the dispatching turn's session principal to the remote deployment (see [Forwarding the caller identity](#forwarding-the-caller-identity)). |
+| `headers` | `HeadersValue` | No | none | Static or lazily resolved request headers. |
+| `path` | `string` | No | `/eve/v1/session` | Route appended to `url` for the create-session request. |
| `outputSchema` | `StandardSchema \| JSON Schema` | No | none | Structured return type the caller requires. Enforced by the remote agent like any task-mode output schema. Set it on the definition to apply to every call, or override it per call. |
## Dynamic remote agents
@@ -135,5 +135,5 @@ Both failure paths surface to the parent as a failed tool result, so the caller
## What to read next
- Local delegation and the isolation boundary → [Subagents](../subagents)
-- Have the model orchestrate remote agents programmatically → [Dynamic workflows](./dynamic-workflows)
+- Have the model orchestrate remote agents programmatically → [Workflow Tool](../subagents/workflow-tool)
- Securing the receiving deployment → [Auth & route protection](./auth-and-route-protection)
diff --git a/docs/guides/session-context.md b/docs/guides/session-context.md
index af88515e5..d39fc94e9 100644
--- a/docs/guides/session-context.md
+++ b/docs/guides/session-context.md
@@ -1,20 +1,22 @@
---
title: "Session Context"
-description: "Runtime helpers: ctx.session, ctx.getSandbox, ctx.getSkill, and defineState."
+description: "Use ctx.session and runtime accessors inside eve-managed execution."
---
-eve exposes runtime state through the `ctx` parameter passed to tool `execute`, hook handlers, channel event handlers, and connection auth/header resolvers:
+eve passes a runtime `ctx` to tool executors, hook handlers, channel event handlers, and connection auth and header resolvers. Use it to inspect the active session and reach resources bound to that execution.
-- `ctx.session`: session metadata, turn, auth, and parent lineage
-- `ctx.getSandbox()`: live sandbox handle for the current agent
-- `ctx.getSkill(identifier)`: handle for a named skill visible to the current agent
-- `defineState(name, initial)`: typed durable state with `get()` and `update()` (imported from `eve/context`)
+| Accessor | Provides | Full guide |
+| ---------------------------- | --------------------------------------------------------- | ----------------------------------------------- |
+| `ctx.session` | Session identity, turn metadata, auth, and parent lineage | This page |
+| `ctx.getSandbox()` | The current agent's live sandbox handle | [Sandbox](../sandbox) |
+| `ctx.getSkill(identifier)` | A handle for a skill visible to the current agent | [Skills](../skills#read-skill-files-at-runtime) |
+| `defineState(name, initial)` | Durable typed state shared by runtime code in one session | [State](../concepts/state) |
-These APIs work only inside active authored runtime execution, including tools, channel event handlers, and authored hooks. They throw when called outside a managed context.
+These APIs work only during eve-managed runtime execution. Calling them during module evaluation, discovery, or a build throws.
## `ctx.session`
-`ctx.session` exposes durable runtime metadata about the current execution.
+`ctx.session` describes the durable session and active turn:
```ts title="agent/tools/who_called_me.ts"
import { defineTool } from "eve/tools";
@@ -37,132 +39,61 @@ export default defineTool({
});
```
-Public session fields:
+Public fields include:
-- `auth.current`
-- `auth.initiator`
-- `id`
-- `turn.id`
-- `turn.sequence`
-- optional `parent`
+- `id`: the durable session ID.
+- `turn.id`: the current turn ID.
+- `turn.sequence`: the turn's position in the session.
+- `auth.current`: the caller for the active inbound turn.
+- `auth.initiator`: the caller that started the session.
+- `parent`: the parent call, session, root session, and turn for a child subagent session.
-Behavior:
-
-- `auth.current` is the caller for the active inbound turn.
-- `auth.initiator` is the caller that started the durable session.
-- Unprotected agents expose both as `null`.
-- Top-level schedule sessions expose the framework app principal (`principalId: "eve:app"`, `principalType: "runtime"`).
-- `parent` is present for child subagent sessions and includes the parent `callId`, `sessionId`, `rootSessionId`, and `turn`.
+Unprotected agents expose `auth.current` and `auth.initiator` as `null`. Top-level schedule sessions use the framework app principal (`principalId: "eve:app"`, `principalType: "runtime"`). See [Authentication](./auth-and-route-protection#what-reaches-ctxsessionauth) for how inbound identity becomes session auth.
## `ctx.getSandbox()`
-`ctx.getSandbox()` returns a live handle for the current agent's sandbox.
+Call `ctx.getSandbox()` when authored runtime code needs filesystem or process access in the current agent's sandbox:
```ts
const sandbox = await ctx.getSandbox();
const result = await sandbox.run({ command: "npm test" });
```
-Behavior:
-
-- It takes no arguments. Each agent has exactly one sandbox.
-- It is async because eve binds or restores sandbox state lazily.
-- It only works when sandbox access is attached to the active runtime path.
-- Visibility is node-local. A subagent sees its own sandbox, not the parent's.
-- The returned `RuntimeSandboxSession` extends the ordinary sandbox I/O surface
- with `stop()`. It is exported from `eve/sandbox`.
-
-Call `stop()` to release sandbox compute while preserving the durable session
-and its filesystem:
-
-```ts
-const sandbox = await ctx.getSandbox();
-await sandbox.stop();
-```
-
-Each backend implements this with its native lifecycle operation. Treat the
-stop as the end of sandbox work in the current callback; a later callback calls
-`ctx.getSandbox()` normally and eve reopens the same durable session. Vercel
-also supports using the same handle again: its next command or file operation
-automatically resumes the sandbox, just as it would after an inactivity
-timeout. No separate eve reconnect state is created, and provider failures
-reject the returned promise.
-
-`SandboxSession` also exposes `resolvePath(path)`, which returns the live backend-native path for a logical `/workspace/...` location. Use it when authored code needs that path before passing it to shell code or a child process.
-
-See [Sandbox](../sandbox) for lifecycle details.
+The accessor is asynchronous because eve may need to bind or restore the sandbox. A subagent sees its own sandbox, not its parent's. The returned runtime handle can also stop compute while preserving the durable sandbox state. See [Sandbox](../sandbox#using-the-sandbox) for the I/O API and lifecycle.
## `ctx.getSkill(identifier)`
-`ctx.getSkill(identifier)` returns a handle for a named skill visible to the current agent.
+Call `ctx.getSkill(identifier)` to read a packaged skill's supporting files:
```ts
const skill = ctx.getSkill("research");
const notes = await skill.file("references/checklist.md").text();
```
-Behavior:
-
-- It is synchronous. File content is read lazily from the active sandbox.
-- It only works when sandbox access is attached to the active runtime path.
-- `identifier` is the path-derived skill id.
-- Visibility follows the current agent's sandbox.
-- A missing skill surfaces when a file accessor reads a missing sandbox path.
-- The returned handle exposes `name` and `file(relativePath)`.
-
-See [Skills](../skills) for the full authoring model.
+The accessor is synchronous; file content is read lazily from the active sandbox. Visibility follows the current agent. See [Skills](../skills#read-skill-files-at-runtime) for the complete handle behavior.
## Custom state with `defineState`
-Use `defineState` when your agent needs durable typed state that tools, hooks, and channel handlers can share. State survives workflow step boundaries. Declare the handle at module scope so every importer shares it:
-
-```ts title="agent/lib/budget.ts"
-import { defineState } from "eve/context";
-
-interface BudgetState {
- readonly count: number;
- readonly cap: number;
-}
-
-export const budget = defineState<BudgetState>("myapp.budget", () => ({
- count: 0,
- cap: 25,
-}));
-```
-
-`get()` reads the current value (returning `initial()` on first access), and `update(fn)` applies a function to it. Both throw outside a managed scope. See [State](./state) for the full read/write model and examples from tools and hooks.
+Use `defineState` for durable per-session values that tools, hooks, and channel handlers share. Unlike the `ctx` accessors, import it from `eve/context` and declare the handle at module scope. Its `get()` and `update()` methods still require active eve execution. See [State](../concepts/state) for the read, update, reset, and subagent-isolation model.
## Where these APIs work
-Safe places:
-
-- inside `defineTool(...).execute(input, ctx)`
-- inside connection `auth: (ctx) => provider` and `headers: (ctx) => values` resolvers
-- inside authored callbacks eve runs inside the runtime
-- after asynchronous boundaries inside the same authored execution chain
-
-Unsafe places:
+Runtime context is available:
-- top-level module evaluation
-- build scripts
-- discovery-time code paths
+- inside `defineTool(...).execute(input, ctx)`;
+- inside connection `auth` and `headers` resolvers;
+- inside channel and hook callbacks that receive `ctx`;
+- after asynchronous boundaries within the same authored execution chain.
-If you call them outside an active eve runtime context, they throw immediately with a message explaining the required scope.
+Runtime context is not available during top-level module evaluation, build scripts, or discovery. Declare reusable definitions and state handles at module scope, but call their context-dependent methods only from an eve-managed callback.
## How it works
-The framework sets up a context container before invoking authored code:
-
-1. The runtime populates durable seed values (auth, session id, compiled bundle).
-2. Before each step, the framework derives step-local values (session metadata, sandbox access, skill access) from the durable state.
-3. Authored code runs inside the managed scope, so `ctx` and `defineState` accessors resolve automatically.
-4. After the step, the framework commits mutable state (for example sandbox changes) back to the durable session.
-
-The framework manages this lifecycle. Authored code only uses `ctx` and the public accessors.
+eve establishes the managed context before invoking authored runtime code and keeps it available across asynchronous work in that execution chain. The framework binds durable session data and step-local resources, then commits mutable state at the step boundary. Authored code uses the public accessors rather than managing this lifecycle.
## What to read next
-- [State](./state)
-- [Sessions, runs & streaming](../concepts/sessions-runs-and-streaming)
-- [Subagents](../subagents)
-- [Skills](../skills)
+- [State](../concepts/state): durable typed values scoped to one session.
+- [Sandbox](../sandbox): runtime filesystem and process access.
+- [Skills](../skills): load procedures and read packaged skill files.
+- [Sessions, runs, and streaming](../concepts/sessions-runs-and-streaming): the durable session and event contract.
diff --git a/docs/install-integrations.mdx b/docs/install-integrations.mdx
index 2400971e2..7ef6d556d 100644
--- a/docs/install-integrations.mdx
+++ b/docs/install-integrations.mdx
@@ -1,5 +1,5 @@
---
-title: "Install Integrations"
+title: "Add Integrations"
description: "Discover and install extensions and other integrations from eve and third-party sources."
contentType: "How-to"
---
diff --git a/docs/installation.mdx b/docs/installation.mdx
deleted file mode 100644
index 847ad0f94..000000000
--- a/docs/installation.mdx
+++ /dev/null
@@ -1,66 +0,0 @@
----
-title: "Installation"
-description: "Create an eve project, configure a model credential, and run it locally."
-contentType: "How-to"
----
-
-Create an eve project with `eve init`. The scaffold installs dependencies, creates the agent files, and starts the local development server.
-
-## Configure a model credential
-
-The default scaffolded model routes through the Vercel AI Gateway. Set `AI_GATEWAY_API_KEY`, or link a Vercel project to use `VERCEL_OIDC_TOKEN`.
-
-You can also use a direct provider model. Install its AI SDK provider package and set that provider's API key before you run the agent.
-
-Choose a model, provider, and channel that meet your data-processing and compliance requirements.
-
-## Create a project
-
-Run `eve init` with a project name:
-
-```bash
-npx eve@latest init my-agent
-```
-
-The command creates `my-agent/`, installs dependencies, and initializes Git. If a supported coding-agent REPL is available, eve offers to start the development server, open the REPL, or exit after scaffolding.
-
-Pass an AI Gateway model ID or reasoning effort when you do not want the defaults:
-
-```bash
-npx eve@latest init my-agent --model openai/gpt-5.5 --reasoning high
-```
-
-## Run the agent
-
-From the project root, run the generated development command:
-
-```bash
-cd my-agent
-npm run dev
-```
-
-The terminal UI sends messages to your agent. Stop the server with Ctrl+C when you need your shell for another command.
-
-## Add eve to an existing project
-
-Run `eve init .` from a project with a `package.json` and no existing `agent/` files:
-
-```bash
-npx eve@latest init .
-```
-
-eve adds the missing `eve`, `ai`, and `zod` dependencies without changing files the project already owns.
-
-## Install manually
-
-Install the runtime dependencies when you do not want to use the scaffold:
-
-```bash
-npm install eve@latest ai zod
-```
-
-Declare Node.js 24 in `package.json`, then create `agent/agent.ts` and `agent/instructions.md`. [Project structure](/docs/project-structure) shows the required layout, and [`agent.ts`](./agent-config) documents the runtime configuration.
-
-## Continue building
-
-Read [Project structure](/docs/project-structure) before adding instructions, tools, connections, or channels.
diff --git a/docs/meta.json b/docs/meta.json
index 91ce3852c..fa5dba5ce 100644
--- a/docs/meta.json
+++ b/docs/meta.json
@@ -1,27 +1,38 @@
{
"pages": [
- "---Getting Started---",
+ "---Introduction---",
"getting-started",
- "installation",
- "project-structure",
- "install-integrations",
- "---Build Your Agent---",
+ "concepts",
+ "---Build---",
"agent-config",
"instructions",
"tools",
- "skills",
- "channels",
"connections",
- "extensions",
+ "channels",
+ "skills",
"sandbox",
"subagents",
- "schedules",
"evals",
- "---Learn More---",
+ "guides/session-context",
+ "schedules",
+ "guides/hooks",
+ "guides/dynamic-capabilities",
+ "---Integrate---",
+ "install-integrations",
+ "extensions",
+ "guides/remote-agents",
+ "protocols",
+ "guides/frontend",
+ "guides/client",
+ "---Operate---",
+ "guides/deployment",
+ "guides/auth-and-route-protection",
+ "guides/instrumentation",
+ "guides/dev-tui",
+ "---Reference---",
"tutorial",
- "guides",
- "concepts",
"patterns",
- "reference"
+ "...reference",
+ "responsible-use"
]
}
diff --git a/docs/patterns/dynamic-scheduling.md b/docs/patterns/dynamic-scheduling.md
index ab208edfb..9946069ff 100644
--- a/docs/patterns/dynamic-scheduling.md
+++ b/docs/patterns/dynamic-scheduling.md
@@ -1,5 +1,5 @@
---
-title: "Dynamic scheduling"
+title: "Dynamic Scheduling"
description: "Compose one minute-level eve schedule, proactive channel handoff, and CRUD tools into application-managed schedules."
---
diff --git a/docs/patterns/meta.json b/docs/patterns/meta.json
index 99e60ff49..5f257b873 100644
--- a/docs/patterns/meta.json
+++ b/docs/patterns/meta.json
@@ -1,5 +1,6 @@
{
"title": "Patterns",
+ "defaultOpen": false,
"pages": [
"multi-tenant-memory",
"dynamic-scheduling",
diff --git a/docs/patterns/multi-tenant-approvals.md b/docs/patterns/multi-tenant-approvals.md
index ad25afa8f..b91ceebc3 100644
--- a/docs/patterns/multi-tenant-approvals.md
+++ b/docs/patterns/multi-tenant-approvals.md
@@ -1,5 +1,5 @@
---
-title: "Multi-tenant approvals"
+title: "Multi-Tenant Approvals"
description: "Resolve tenant policy asynchronously for authored tools, OpenAPI operations, and MCP tools."
---
diff --git a/docs/patterns/multi-tenant-auth.md b/docs/patterns/multi-tenant-auth.md
index f43db80f9..cbaffc258 100644
--- a/docs/patterns/multi-tenant-auth.md
+++ b/docs/patterns/multi-tenant-auth.md
@@ -1,5 +1,5 @@
---
-title: "Multi-tenant outbound auth"
+title: "Multi-Tenant Outbound Auth"
description: "Select tenant-scoped credentials inside authored tools, OpenAPI connections, and MCP connections from the active turn context."
---
diff --git a/docs/patterns/multi-tenant-memory.md b/docs/patterns/multi-tenant-memory.md
index 51fdd8723..60ce39f38 100644
--- a/docs/patterns/multi-tenant-memory.md
+++ b/docs/patterns/multi-tenant-memory.md
@@ -1,5 +1,5 @@
---
-title: "Multi-tenant memory"
+title: "Multi-Tenant Memory"
description: "Compose dynamic instructions, authenticated session context, and ordinary tools into tenant-scoped long-term memory."
---
diff --git a/docs/project-structure.mdx b/docs/project-structure.mdx
deleted file mode 100644
index e7f73d185..000000000
--- a/docs/project-structure.mdx
+++ /dev/null
@@ -1,53 +0,0 @@
----
-title: "Project Structure"
-description: "Learn the files eve discovers and how their paths define agent capabilities."
-contentType: "Conceptual"
----
-
-eve builds an agent from files under `agent/`. A file's location determines what eve loads, and most paths also determine the capability's name.
-
-## Start with two files
-
-A minimal agent needs an instructions file and optional runtime configuration:
-
-```text
-my-agent/
-├── package.json
-├── agent/
-│ ├── agent.ts
-│ └── instructions.md
-└── evals/
-```
-
-`agent/instructions.md` is the agent's always-on system prompt. `agent/agent.ts` selects the model and configures runtime behavior. Omit `agent.ts` when the defaults are sufficient.
-
-## Add capabilities as directories
-
-Add a directory when the agent needs that capability:
-
-| Path | Purpose |
-| ----------------------------------- | --------------------------------------------- |
-| [`tools/`](./tools) | Typed functions the model can call |
-| [`skills/`](./skills) | Procedures the model loads when useful |
-| [`channels/`](./channels/overview) | HTTP and messaging entry points |
-| [`connections/`](/docs/connections) | MCP and OpenAPI services |
-| [`sandbox/`](./sandbox) | Controlled workspace files and commands |
-| [`subagents/`](./subagents) | Specialist agents the root agent delegates to |
-| [`schedules/`](./schedules) | Recurring work |
-| `lib/` | Shared code imported by agent files |
-
-The `evals/` directory sits beside `agent/`. It holds the checks that measure whether the agent completes its tasks. See [Evals](./evals/overview).
-
-## Let paths name capabilities
-
-The path supplies the name. This tool file becomes the `get_weather` tool:
-
-```text
-agent/tools/get_weather.ts
-```
-
-The same rule applies to connections, skills, and subagents. You do not add a duplicate `name` or `id` field to the definition.
-
-## Use the full layout reference
-
-[Project layout](./reference/project-layout) lists every supported slot, the root and subagent boundaries, and the file-discovery rules.
diff --git a/docs/guides/acp.md b/docs/protocols/acp.md
similarity index 99%
rename from docs/guides/acp.md
rename to docs/protocols/acp.md
index 392dc07b7..19756d5a7 100644
--- a/docs/guides/acp.md
+++ b/docs/protocols/acp.md
@@ -1,5 +1,5 @@
---
-title: "Use eve through ACP"
+title: "Agent Client Protocol (ACP)"
description: "Use local or deployed eve agents from Agent Client Protocol clients."
---
diff --git a/docs/protocols/meta.json b/docs/protocols/meta.json
new file mode 100644
index 000000000..2e05f7710
--- /dev/null
+++ b/docs/protocols/meta.json
@@ -0,0 +1,5 @@
+{
+ "title": "Protocols",
+ "defaultOpen": false,
+ "pages": ["acp", "ucp"]
+}
diff --git a/docs/guides/ucp.mdx b/docs/protocols/ucp.mdx
similarity index 100%
rename from docs/guides/ucp.mdx
rename to docs/protocols/ucp.mdx
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index 857e45f1c..a355515a8 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -215,7 +215,7 @@ Pass a bare URL and the UI connects to that server instead of booting a local on
| `--context-size <tokens>` | number | none | Model context window size, shown as a usage percentage |
| `--logs <mode>` | enum | `stderr` | Server/agent logs to show: `all` \| `stderr` \| `sandbox` \| `none` |
-`eve acp` reserves stdin and stdout for newline-delimited JSON-RPC and sends diagnostics to stderr. Without a URL, it supervises an isolated local development server. With a URL, it bridges ACP to that server's existing eve HTTP API and accepts the same URL credentials and request headers as `eve dev <url>`. Pass `--scope <team>` when the active Vercel scope does not own the deployment; `EVE_VERCEL_SCOPE` provides the same value for managed harnesses. See [Use eve through ACP](../guides/acp) for client configuration and capability limits.
+`eve acp` reserves stdin and stdout for newline-delimited JSON-RPC and sends diagnostics to stderr. Without a URL, it supervises an isolated local development server. With a URL, it bridges ACP to that server's existing eve HTTP API and accepts the same URL credentials and request headers as `eve dev <url>`. Pass `--scope <team>` when the active Vercel scope does not own the deployment; `EVE_VERCEL_SCOPE` provides the same value for managed harnesses. See [Agent Client Protocol (ACP)](../protocols/acp) for client configuration and capability limits.
A fresh `eve init` passes `--input /model`. That bare local input starts onboarding: the TUI installs the Vercel CLI if needed, asks you to log in if needed, opens `/model`, then offers categorized registry next steps before the first prompt. Other input stays editable in the prompt.
@@ -376,10 +376,10 @@ Lists the user-authored channels in the current project.
4. `eve build` before shipping.
5. `eve start` to smoke-test the built output locally.
-Related: [Project layout](./project-layout) · [instrumentation.ts](../guides/instrumentation).
+Related: [Project layout](../getting-started#project-layout) · [instrumentation.ts](../guides/instrumentation).
## What to read next
-- [Project layout](./project-layout): what `eve info` discovers
+- [Project layout](../getting-started#project-layout): what `eve info` discovers
- [instrumentation.ts](../guides/instrumentation): tracing and the error catalog
- [Deployment](../guides/deployment/overview): `eve build` and `eve start` in production
diff --git a/docs/reference/meta.json b/docs/reference/meta.json
index 95edf9b9e..8aff34420 100644
--- a/docs/reference/meta.json
+++ b/docs/reference/meta.json
@@ -1,4 +1,4 @@
{
"title": "Reference",
- "pages": ["typescript-api", "cli", "project-layout"]
+ "pages": ["typescript-api", "cli"]
}
diff --git a/docs/reference/project-layout.md b/docs/reference/project-layout.md
deleted file mode 100644
index 1ceb6ce70..000000000
--- a/docs/reference/project-layout.md
+++ /dev/null
@@ -1,123 +0,0 @@
----
-title: "Project Layout"
-description: "Authored slots under agent/ and the path-derived naming rule."
----
-
-eve builds an agent by walking the filesystem under `agent/`. Each directory is an authored slot, and the slot a file lands in determines how eve loads it.
-
-## Naming rule
-
-Identity comes from the path. You never write a `name` or `id` field on a `define*` call.
-
-| Path | Resolves to |
-| ------------------------------------- | --------------------- |
-| `agent/tools/get_weather.ts` | tool `get_weather` |
-| `agent/connections/linear.ts` | connection `linear` |
-| `agent/skills/summarize.md` | skill `summarize` |
-| `agent/subagents/researcher/agent.ts` | subagent `researcher` |
-
-The root agent takes its name from the enclosing `package.json` `name`, falling back to the app-root directory name when `package.json` has no `name`. A subagent takes its name from its directory.
-
-## Recommended layout
-
-```text
-my-agent/
-├── package.json
-├── tsconfig.json
-├── agent/
-│ ├── agent.ts
-│ ├── instructions.md
-│ ├── instrumentation.ts
-│ ├── channels/
-│ ├── connections/
-│ ├── hooks/
-│ ├── skills/
-│ ├── lib/
-│ ├── sandbox/
-│ ├── tools/
-│ ├── schedules/
-│ └── subagents/
-└── evals/
-```
-
-Evals live in `evals/` at the app root, a sibling of `agent/`, not inside it. See [Evals](../evals/overview).
-
-## Slot table
-
-The Subagents column states whether a local subagent (`subagents/<id>/`) can author the slot. A declared subagent inherits nothing from the root; it discovers its own slots. See [Subagents](../subagents).
-
-| Path | Description | Subagents | Notes |
-| ------------------------------------------------------- | ------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `agent.ts` | Runtime config | Yes | Model, modelOptions, compaction, build, experimental. See [Agent config](../agent-config). |
-| `instructions.md` / `instructions.ts` / `instructions/` | Base system prompt | Optional | A flat file, or a directory of `.md` and `.ts` files. Static sources compose at build time. Dynamic sources (`defineDynamic` + `defineInstructions`) resolve at runtime. Required on the root, optional on subagents. |
-| `instrumentation.ts` | Telemetry config | No | OTel exporter and AI SDK span settings, auto-discovered and run before agent code. Root-only. |
-| `channels/` | HTTP / messaging entrypoints | No | Root-only. |
-| `connections/` | External service connections (MCP, OpenAPI) | Yes | One connection per file; name derived from filename. |
-| `hooks/` | Lifecycle and stream-event subscribers | Yes | Module-backed only. Recursive directories supported. |
-| `skills/` | On-demand procedures and capability packs | Yes | Flat markdown, module-backed skills, or packaged skills. Seeded into `$HOME/.agents/skills/...`, with `/workspace/skills/...` as a fallback if `$HOME` is unavailable. |
-| `lib/` | Shared authored helper code | Yes | Import-only; not mounted into the workspace. |
-| `sandbox.ts` or `sandbox/sandbox.ts` | The agent's single sandbox | Yes | Use top-level `sandbox.ts` for a definition-only override; use `sandbox/sandbox.ts` + `sandbox/workspace/**` to also seed files. Framework default applies when neither is authored. |
-| `sandbox/workspace/**` | Files seeded into the sandbox | Yes | Mirrored into `/workspace/...` at session bootstrap. |
-| `tools/` | Typed executable integrations | Yes | Module-backed only. |
-| `schedules/` | Recurring jobs | No | Each schedule is `<name>.ts` (default-exported `defineSchedule`) or `<name>.md` (frontmatter `cron:` + prompt body). Recursive nesting supported. Root-only. |
-| `subagents/` | Specialist child agents | Yes | Each child is its own local package under `subagents/<id>/`. Nested subagents are supported. |
-
-## What reaches the runtime sandbox
-
-eve does not mount the whole tree. Authored workspace files land in the sandbox workspace:
-
-- `agent/sandbox/workspace/**` → `/workspace/...` at session bootstrap
-
-Skill files land outside the workspace, under `$HOME/.agents/skills/...`. If `$HOME` is unavailable, eve falls back to `/workspace/skills/...`. Packaged skill references such as `references/checklist.md` resolve relative to the directory containing that skill's `SKILL.md`.
-
-Everything in `lib/` stays import-only source code and never reaches the workspace.
-
-## Local subagent layout
-
-A local subagent lives under `subagents/<id>/` and uses the same `agent.ts` shape as the root.
-
-```text
-agent/subagents/researcher/
-├── agent.ts
-├── instructions.md
-├── connections/
-├── hooks/
-├── skills/
-├── lib/
-├── sandbox/
-├── tools/
-└── subagents/
-```
-
-Rules:
-
-- `agent.ts` is required. A static subagent's definition must declare a `description`; a dynamic subagent's resolver must return a definition with one. The parent reads it on the lowered subagent tool to decide when to delegate.
-- `instructions.md` / `instructions.ts` is optional (unlike the root agent, where it is required).
-- `connections/`, `hooks/`, `skills/`, `lib/`, `sandbox/`, and `tools/` are all supported, discovered from the subagent's own directory.
-- `channels/` and `schedules/` are not supported inside local subagents.
-- Nested subagents are supported.
-
-## Flat layout
-
-Supported when the app root is also the agent root:
-
-```text
-my-agent/
-├── package.json
-├── agent.ts
-├── instructions.md
-├── tools/
-└── skills/
-```
-
-Prefer the nested layout. It keeps the app root separate from the authored surface.
-
-## Why didn't eve discover my file?
-
-Run `eve info`. It lists the discovered surface and prints discovery diagnostics. From there, check that the file sits in the right authored slot (per the slot table above) and that the root-vs-subagent boundary is valid. eve also writes inspectable artifacts under `.eve/`. See the debugging artifacts in [instrumentation.ts](../guides/instrumentation) and the [CLI](./cli) reference.
-
-## What to read next
-
-- [`agent.ts`](../agent-config): the runtime config at the root
-- [Tools](../tools): the most common authored slot
-- [TypeScript API](./typescript-api): the define\* helpers and where they import from
diff --git a/docs/reference/typescript-api.md b/docs/reference/typescript-api.md
index 2d2ee26aa..d77d73d7b 100644
--- a/docs/reference/typescript-api.md
+++ b/docs/reference/typescript-api.md
@@ -1,5 +1,5 @@
---
-title: "TypeScript API"
+title: "TypeScript API Reference"
description: "The define* helpers, the runtime ctx, and where each one is imported from."
---
@@ -118,4 +118,4 @@ Pass another bare OpenAI model slug to override the default. The helper reads cr
- [`agent.ts`](../agent-config): the agent config these helpers configure
- [Tools](../tools): `defineTool`, the most-used helper
-- [Project layout](./project-layout): where each define\* lives on disk
+- [Project layout](../getting-started#project-layout): where each define\* lives on disk
diff --git a/docs/subagents.mdx b/docs/subagents/index.mdx
similarity index 98%
rename from docs/subagents.mdx
rename to docs/subagents/index.mdx
index c50656a9c..c8609f95f 100644
--- a/docs/subagents.mdx
+++ b/docs/subagents/index.mdx
@@ -151,7 +151,7 @@ eve lowers every subagent visible to the current agent (the root built-in copy,
Declared subagents can call nested subagents defined under their own directories. eve does not apply a separate depth limit; nesting ends where the authored directory tree ends. The built-in `agent` follows the stricter root-only rule above, so `limits.maxSubagentDepth` no longer exists.
-`Workflow` is also root-only. Child sessions can still call their own declared or remote subagents, but they receive neither `Workflow` nor the built-in `agent`. The Workflow tool's `maxSubagents` option caps the number of calls made by one program (default 100); see [Dynamic workflows](./guides/dynamic-workflows).
+`Workflow` is also root-only. Child sessions can still call their own declared or remote subagents, but they receive neither `Workflow` nor the built-in `agent`. The Workflow tool's `maxSubagents` option caps the number of calls made by one program (default 100); see [Workflow Tool](./subagents/workflow-tool).
A declared subagent's tool name is the bare path-derived name, with no prefix. `agent/subagents/researcher/` registers as the tool `researcher`. Unlike connection tools (`<connection>__<tool>`), it carries no namespace, so the model, approvals, logs, and evals all reference it by that name. Its input schema is:
@@ -203,4 +203,4 @@ Split out a subagent when the task needs a different prompt or specialist role,
## What to read next
- [Remote agents](./guides/remote-agents): call another eve deployment as a subagent.
-- [Dynamic workflows](./guides/dynamic-workflows): have the model orchestrate its subagents programmatically (fan-out, map-reduce).
+- [Workflow Tool](./subagents/workflow-tool): have the model orchestrate its subagents programmatically (fan-out, map-reduce).
diff --git a/docs/subagents/meta.json b/docs/subagents/meta.json
new file mode 100644
index 000000000..40d6bd018
--- /dev/null
+++ b/docs/subagents/meta.json
@@ -0,0 +1,5 @@
+{
+ "title": "Subagents",
+ "defaultOpen": false,
+ "pages": ["index", "workflow-tool"]
+}
diff --git a/docs/guides/dynamic-workflows.md b/docs/subagents/workflow-tool.md
similarity index 90%
rename from docs/guides/dynamic-workflows.md
rename to docs/subagents/workflow-tool.md
index d0b974366..d0fb57265 100644
--- a/docs/guides/dynamic-workflows.md
+++ b/docs/subagents/workflow-tool.md
@@ -1,5 +1,5 @@
---
-title: "Dynamic Workflows"
+title: "Workflow Tool"
description: "The experimental Workflow tool: let the model orchestrate its own subagents from model-authored JavaScript as one durable step."
---
@@ -7,7 +7,7 @@ The experimental `Workflow` tool lets the model write JavaScript that coordinate
A single turn can already call several subagents, and parallel tool calls dispatch concurrently. What a workflow adds is _programmatic_ coordination. The program decides how many subagents to run based on an earlier result, which output feeds which call, and how to combine everything. That is logic the model cannot express as a few one-off calls.
-`Workflow` is a model-facing tool, not an API for authored tools, hooks, or application code. Authored code cannot submit a Workflow program or use `Workflow` to start an arbitrary user-authored Vercel Workflow. Use the [client SDK](./client/overview) when application code needs to start or continue an eve session; use ordinary application APIs for other deterministic orchestration.
+`Workflow` is a model-facing tool, not an API for authored tools, hooks, or application code. Authored code cannot submit a Workflow program or use `Workflow` to start an arbitrary user-authored Vercel Workflow. Use the [client SDK](../guides/client/overview) when application code needs to start or continue an eve session; use ordinary application APIs for other deterministic orchestration.
## Enable the Workflow tool
@@ -53,7 +53,7 @@ Each `tools.analyst(...)` call dispatches a child subagent, so the parent stream
## What a workflow can orchestrate
-A workflow reaches only this agent's own agents: the built-in `agent` (a copy of itself), declared [subagents](../subagents), and [remote agents](./remote-agents). That is the whole list. No files, network, shell, skills, or connections. A workflow is a coordination layer over subagents, not a place to do other work. Each call can still request structured output via `outputSchema`, exactly like a direct subagent delegation.
+A workflow reaches only this agent's own agents: the built-in `agent` (a copy of itself), declared [subagents](./), and [remote agents](../guides/remote-agents). That is the whole list. No files, network, shell, skills, or connections. A workflow is a coordination layer over subagents, not a place to do other work. Each call can still request structured output via `outputSchema`, exactly like a direct subagent delegation.
## Caps on workflow-spawned subagents
@@ -67,7 +67,7 @@ import { experimental_workflow } from "eve/tools";
export default experimental_workflow({ maxSubagents: 4 });
```
-**Root-only orchestration.** Only the root session receives `Workflow`. Children started by a workflow receive neither `Workflow` nor the built-in `agent`, so Workflow programs cannot recurse. A declared child can still call subagents defined in its own directory (see [Subagents](../subagents)).
+**Root-only orchestration.** Only the root session receives `Workflow`. Children started by a workflow receive neither `Workflow` nor the built-in `agent`, so Workflow programs cannot recurse. A declared child can still call subagents defined in its own directory (see [Subagents](./)).
## Where the JavaScript runs
@@ -83,6 +83,6 @@ That is an allowlist, not a denylist. The sandbox cannot read files, open a sock
## What to read next
-- Declare the subagents a workflow orchestrates → [Subagents](../subagents)
-- Call another deployment as one of those agents → [Remote agents](./remote-agents)
+- Declare the subagents a workflow orchestrates → [Subagents](./)
+- Call another deployment as one of those agents → [Remote agents](../guides/remote-agents)
- The `agent/tools/` opt-in mechanism → [Default harness](../concepts/default-harness)
diff --git a/docs/tools/human-in-the-loop.md b/docs/tools/human-in-the-loop.md
index b33c92ed9..738ecdb24 100644
--- a/docs/tools/human-in-the-loop.md
+++ b/docs/tools/human-in-the-loop.md
@@ -1,5 +1,5 @@
---
-title: "Human-in-the-loop"
+title: "Human-in-the-Loop"
description: "Pause a run for a person — gate a tool on approval or have the agent ask a question — and resume durably when they answer."
url: /human-in-the-loop
---
diff --git a/docs/tools/meta.json b/docs/tools/meta.json
index d1d3d7c10..981a49cdc 100644
--- a/docs/tools/meta.json
+++ b/docs/tools/meta.json
@@ -1,4 +1,5 @@
{
"title": "Tools",
+ "defaultOpen": false,
"pages": ["overview", "human-in-the-loop"]
}
diff --git a/docs/tools/overview.mdx b/docs/tools/overview.mdx
index b1896c15b..6960065b1 100644
--- a/docs/tools/overview.mdx
+++ b/docs/tools/overview.mdx
@@ -143,4 +143,4 @@ Do not return secrets, credentials, unnecessary personal data, or unbounded sens
- [Skills](/docs/skills): on-demand procedures the model loads when relevant
- [Default harness](/docs/concepts/default-harness): the built-in tools and how to override or disable them
- [Dynamic capabilities](/docs/guides/dynamic-capabilities): tools whose set is resolved per session with `defineDynamic`
-- [Auth & route protection](/docs/guides/auth-and-route-protection): authenticate a tool to an external service
+- [Authentication](/docs/guides/auth-and-route-protection): authenticate a tool to an external service
diff --git a/docs/tutorial/connect-a-warehouse.mdx b/docs/tutorial/connect-a-warehouse.mdx
index debb38103..837405894 100644
--- a/docs/tutorial/connect-a-warehouse.mdx
+++ b/docs/tutorial/connect-a-warehouse.mdx
@@ -55,4 +55,4 @@ If you want more control, gate the connection behind approval (`approval: once()
→ Next: [Run analysis](./run-analysis)
-Learn more: [MCP connections](../connections/mcp) · [Auth and route protection](../guides/auth-and-route-protection)
+Learn more: [MCP connections](../connections/mcp) · [Authentication](../guides/auth-and-route-protection)
diff --git a/docs/tutorial/meta.json b/docs/tutorial/meta.json
index 4d874fb0f..fec035e61 100644
--- a/docs/tutorial/meta.json
+++ b/docs/tutorial/meta.json
@@ -1,5 +1,6 @@
{
"title": "Tutorial",
+ "defaultOpen": false,
"pages": [
"first-agent",
"how-it-runs",
diff --git a/docs/tutorial/remember-definitions.mdx b/docs/tutorial/remember-definitions.mdx
index e93cccc50..9752ed20a 100644
--- a/docs/tutorial/remember-definitions.mdx
+++ b/docs/tutorial/remember-definitions.mdx
@@ -65,8 +65,8 @@ export default defineTool({
The second turn is a separate turn in the same session, yet the definition is still there. State checkpoints at step boundaries, so it's the same durability from [Step 2](./how-it-runs), now applied to your own data.
-State is scoped to a session and isolated per agent, so a subagent starts with fresh state and never sees the parent's. Need to reset something each turn? Call `update(() => fresh)` in a lifecycle hook. More in [State](../guides/state).
+State is scoped to a session and isolated per agent, so a subagent starts with fresh state and never sees the parent's. Need to reset something each turn? Call `update(() => fresh)` in a lifecycle hook. More in [State](../concepts/state).
→ Next: [Team playbooks](./team-playbooks)
-Learn more: [State](../guides/state)
+Learn more: [State](../concepts/state)
diff --git a/docs/tutorial/ship-it.mdx b/docs/tutorial/ship-it.mdx
index 26b7dd706..db65d529a 100644
--- a/docs/tutorial/ship-it.mdx
+++ b/docs/tutorial/ship-it.mdx
@@ -151,6 +151,6 @@ Across the nine steps you built and shipped one agent, and along the way you use
- [MCP connections](../connections/mcp) for tool allowlists and per-connection approval.
- [Sandbox](../sandbox) for backends, lifecycle, and network policy.
- [Dynamic capabilities](../guides/dynamic-capabilities) for schema-derived dynamic tools, a read-only analyst subagent, and model-authored report workflows on this same example.
-- [Auth and route protection](../guides/auth-and-route-protection) for production auth patterns.
+- [Authentication](../guides/auth-and-route-protection) for production auth patterns.
-Learn more: [Frontend](../guides/frontend/overview) · [Auth and route protection](../guides/auth-and-route-protection) · [Deployment](../guides/deployment/overview)
+Learn more: [Frontend](../guides/frontend/overview) · [Authentication](../guides/auth-and-route-protection) · [Deployment](../guides/deployment/overview)
diff --git a/packages/eve/README.md b/packages/eve/README.md
index 23f51637e..89ab4e1ee 100644
--- a/packages/eve/README.md
+++ b/packages/eve/README.md
@@ -75,7 +75,7 @@ Runtime accessors live on the subpath that owns the concern:
- `getSkill(identifier)` — handle for a named skill visible to the current agent (`eve/skills`)
- `getContext(key)`, `requireContext(key)`, `hasContext(key)`, `setContext(key)`, `ensureContext(key, factory)` — unified context helpers (`eve/context`)
-The complete API reference, including types and lower-level runtime primitives, is in the [TypeScript API documentation](https://eve.dev/docs/reference/typescript-api).
+The complete API reference, including types and lower-level runtime primitives, is in the [TypeScript API Reference](https://eve.dev/docs/reference/typescript-api).
## Tiny Example
@@ -152,9 +152,9 @@ These files ship inside the installed package at `node_modules/eve/docs/`:
- [Full docs index](https://eve.dev/docs) — recommended entry point
- [Getting Started](https://eve.dev/docs/getting-started) — install, scaffold, and run locally
-- [Project Layout](https://eve.dev/docs/reference/project-layout) — every authored directory in depth
+- [Project Layout](https://eve.dev/docs/getting-started#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
+- [TypeScript API Reference](https://eve.dev/docs/reference/typescript-api) — complete `define*` and runtime helper reference
- [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/scripts/check-docs.mjs b/scripts/check-docs.mjs
index 8cd4ba39f..fb109fd2a 100755
--- a/scripts/check-docs.mjs
+++ b/scripts/check-docs.mjs
@@ -99,7 +99,11 @@ function collectNavReferences(rootDir) {
if (entry === "---") continue;
if (/^---.+---$/.test(entry)) continue; // labeled separator: ---Group name---
if (entry.startsWith("[")) continue; // [Title](url) custom link
- const slug = entry.startsWith("!") ? entry.slice(1) : entry;
+ const slug = entry.startsWith("!")
+ ? entry.slice(1)
+ : entry.startsWith("...")
+ ? entry.slice(3)
+ : entry;
const key = relDir ? `${relDir}/${slug}` : slug;
result.explicit.add(key);
}
@@ -246,7 +250,11 @@ function checkMetaReferences(rootDir) {
if (/^---.+---$/.test(entry)) continue;
if (entry.startsWith("[")) continue;
- const slug = entry.startsWith("!") ? entry.slice(1) : entry;
+ const slug = entry.startsWith("!")
+ ? entry.slice(1)
+ : entry.startsWith("...")
+ ? entry.slice(3)
+ : entry;
const candidates = [
resolve(dir, slug),
resolve(dir, `${slug}.md`),