docs: document multi-agent project structure

apps/docs/lib/geistdocs/llms-index.ts

@@ -25,6 +25,7 @@ Documentation links below point directly to Markdown. Remove the \`.md\` suffix
 
 ## Build
 
+- [Project Structure](${EVE_ORIGIN}/docs/project-structure.md): Organize one or more independently addressed root agents, select them with the CLI, and deploy them together.
 - [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.

apps/docs/lib/geistdocs/redirects.test.ts

@@ -107,8 +107,8 @@ describe("docsRedirects", () => {
     ["/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/getting-started/project-structure", "/docs/project-structure"],
+    ["/docs/getting-started/project-structure.md", "/docs/project-structure.md"],
     ["/docs/reference/http-api", "/docs/channels/eve"],
     ["/docs/project-layout", "/docs/getting-started"],
     ["/docs/reference/project-layout", "/docs/getting-started"],
@@ -135,7 +135,7 @@ describe("rootMarkdownRedirects", () => {
   it.each([
     ["/getting-started.mdx", "/docs/getting-started.mdx"],
     ["/installation.md", "/docs/getting-started.md"],
-    ["/project-structure.mdx", "/docs/getting-started.mdx"],
+    ["/project-structure.mdx", "/docs/project-structure.mdx"],
     ["/tools/overview.md", "/docs/tools.md"],
     ["/channels/eve.mdx", "/docs/channels/eve.mdx"],
   ])("redirects observed root Markdown alias %s to %s", (source, destination) => {

apps/docs/lib/geistdocs/redirects.ts

@@ -47,7 +47,6 @@ 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"),
@@ -71,15 +70,15 @@ export const docsRedirects: DocsRedirect[] = [
   ...createDocsRedirects("/evals", "/evals/overview"),
   ...createDocsRedirects("/advanced/evals", "/evals/overview"),
   ...createDocsRedirects("/getting-started/installation", "/getting-started"),
-  ...createDocsRedirects("/getting-started/project-structure", "/getting-started"),
+  ...createDocsRedirects("/getting-started/project-structure", "/project-structure"),
   ...createDocsRedirects("/getting-started/first-agent", "/tutorial/first-agent"),
 ];
 
 export const rootMarkdownRedirects: DocsRedirect[] = [
   ["/getting-started", "/getting-started"],
   ["/install-integrations", "/install-integrations"],
   ["/installation", "/getting-started"],
-  ["/project-structure", "/getting-started"],
+  ["/project-structure", "/project-structure"],
   ["/instructions", "/instructions"],
   ["/tools/overview", "/tools"],
   ["/skills", "/skills"],

docs/README.md

@@ -14,7 +14,8 @@ Important naming note:
 
 | To do this                                               | Read this                                                                              |
 | -------------------------------------------------------- | -------------------------------------------------------------------------------------- |
-| Create a project, or understand the file layout          | [Getting Started](./getting-started.mdx)                                               |
+| Create your first project                                | [Getting Started](./getting-started.mdx)                                               |
+| Organize one or more peer agents in a project            | [Project Structure](./project-structure.md)                                            |
 | Set the model, reasoning, or other agent-wide config     | [Agents](./agent-config.md)                                                            |
 | Change what the agent does and how it behaves            | [Instructions](./instructions.mdx)                                                     |
 | Give the agent a typed capability it can call            | [Tools](./tools/overview.mdx)                                                          |
@@ -54,24 +55,25 @@ Unless you configure stricter controls, eve agents may operate with permissive s
 For a full picture rather than a single task, read in this order:
 
 1. [Getting Started](./getting-started.mdx)
-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)
+2. [Project Structure](./project-structure.md)
+3. [Tutorial](./tutorial/first-agent.mdx)
+4. [Agents](./agent-config.md)
+5. [TypeScript API Reference](./reference/typescript-api.md)
+6. [Context Control](./concepts/context-control.md)
+7. [Skills](./skills.mdx)
+8. [Tools](./tools/overview.mdx)
+9. [Connections](./connections/overview.mdx)
+10. [Sandboxes](./sandbox.mdx)
+11. [Channels](./channels/overview.mdx)
+12. [Session Context](./guides/session-context.md)
+13. [Sessions and Streaming](./concepts/sessions-runs-and-streaming.md)
+14. [Client SDK](./guides/client/overview.mdx)
+15. [Subagents](./subagents/index.mdx)
+16. [Schedules](./schedules.mdx)
+17. [Evals](./evals/overview.mdx)
+18. [Authentication](./guides/auth-and-route-protection.md)
+19. [Deployment](./guides/deployment/overview.md)
+20. [CLI](./reference/cli.md)
 
 ## The public mental model
 

docs/extensions.md

@@ -197,7 +197,9 @@ The same mount shape works with an npm package, a workspace dependency, or a lin
 
 ### Use an extension in a workspace
 
-A workspace extension is a regular extension package kept in the same monorepo as its consumers. It is useful when several agents need the same capabilities, or when a private capability should evolve alongside the agents that use it.
+A workspace extension is a regular extension package kept in the same package-manager workspace as its consumers. It is useful when several agents need the same capabilities, or when a private capability should evolve alongside the agents that use it.
+
+A package-manager workspace is not necessarily an eve multi-agent project. The example below contains two independently deployable agent packages. For several peer agents deployed together from one eve project, see [Project Structure](./project-structure#multi-agent-project); the extension is still mounted separately by each agent.
 
 For example, a pnpm workspace can keep one extension next to two independently deployable agents:
 

docs/getting-started.mdx

@@ -42,6 +42,14 @@ To initialize the agent with a different AI Gateway model or reasoning effort, p
 npx eve@latest init my-agent --model openai/gpt-5.6-terra --reasoning high
 ```
 
+To create several independently addressed root agents in one project, pass their names with `--agents`:
+
+```bash
+npx eve@latest init my-project --agents support,billing
+```
+
+This creates `agents/support/agent/` and `agents/billing/agent/` under one project root. See [Project Structure](./project-structure) for agent selection, ownership, routes, and deployment.
+
 ## Run the agent
 
 Choose **Start eve dev** after scaffolding, or run this from the project root:
@@ -54,7 +62,7 @@ This starts an interactive session where you can send messages to your agent.
 
 ## 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.
+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. In a multi-agent project, each peer has the same authored shape under `agents/<name>/agent/`; see [Project Structure](./project-structure) for the project-level layout.
 
 ### Naming from paths
 

docs/guides/deployment/vercel.mdx

@@ -51,7 +51,7 @@ See [Sandbox](../../sandbox) for resource limits, network policy, and lifecycle
 
 ## Deploy the agent
 
-A project containing only several independently addressed root agents can use eve's hostless workspace layout:
+A project containing several independently addressed root agents can use eve's hostless multi-agent layout. Read [Project Structure](../../project-structure) first for the project model, CLI selection, ownership, and route topology:
 
 ```text
 my-project/
@@ -92,11 +92,18 @@ Vercel uses the generated output to configure these services:
 
 ## Verify the deployment
 
-Check the health route and connect the development TUI:
+For a standalone agent, check the health route and connect the development TUI at the deployment origin:
 
 ```bash
-curl https://your_agent.vercel.app/support/eve/v1/health
-eve dev https://your_agent.vercel.app/support
+curl https://your-agent.vercel.app/eve/v1/health
+eve dev https://your-agent.vercel.app
+```
+
+For a hostless multi-agent project, include the member name:
+
+```bash
+curl https://your-project.vercel.app/support/eve/v1/health
+eve dev https://your-project.vercel.app/support
 ```
 
 Set `VERCEL_AUTOMATION_BYPASS_SECRET` locally before connecting if the deployment uses Deployment Protection.

docs/guides/frontend/nextjs.mdx

@@ -45,7 +45,9 @@ export default withEve(nextConfig, {
 });
 ```
 
-Named agents mount under `/eve/agents/<name>/eve/v1/*`. Call the matching agent from React with `agent`:
+Named agents mount under `/eve/agents/<name>/eve/v1/*`. This is a frontend-owned topology, distinct from the hostless multi-agent project whose peers use `/<name>/eve/v1/*`. See [Project Structure](../../project-structure#choose-a-project-shape) for the comparison.
+
+Call the matching agent from React with `agent`:
 
 ```tsx
 const support = useEveAgent({ agent: "support" });

docs/meta.json

@@ -4,6 +4,7 @@
     "getting-started",
     "concepts",
     "---Build---",
+    "project-structure",
     "agent-config",
     "instructions",
     "memory",