The Open Framework for Building Agents
docs: clarify getting started (#2361)
Chad Hietala5552b9074f5d
diff --git a/docs/getting-started.mdx b/docs/getting-started.mdxindex 90a3ab7cd..f3c79240f 100644--- a/docs/getting-started.mdx+++ b/docs/getting-started.mdx@@ -24,13 +24,7 @@ Run `eve init` with a project name: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.6-terra --reasoning high-```+The command creates the project, installs dependencies, and initializes Git. After scaffolding, eve offers to start the development server or, if a supported coding agent is installed, to open the project in the coding agent.To add eve to a project that already has a `package.json`, run this command from its root before you create any `agent/` files:@@ -40,15 +34,23 @@ npx eve@latest init .eve adds the missing `eve`, `ai`, and `zod` dependencies without changing files the project already owns.+### Customize initialization++To initialize the agent with a different AI Gateway model or reasoning effort, pass `--model` or `--reasoning`:++```bash+npx eve@latest init my-agent --model openai/gpt-5.6-terra --reasoning high+```+## Run the agent-If the development server is not already running, start it from the project root:+Choose **Start eve dev** after scaffolding, or run this from the project root:```bashnpm run dev```-The TUI sends messages to your agent. Stop the server with `Ctrl+C` when you need your shell for another command.+This starts an interactive session where you can send messages to your agent.## Project layout@@ -56,7 +58,7 @@ eve builds an agent by walking the filesystem under `agent/`. Each directory is### Naming from paths-Identity comes from the path. You never write a `name` or `id` field on a `define*` call.+eve derives names from file paths, so you do not configure them separately.| Path | Resolves to || ------------------------------------- | --------------------- |@@ -65,7 +67,7 @@ Identity comes from the path. You never write a `name` or `id` field on a `defin| `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.+The root agent uses its `package.json` `name`, or its app directory name if none is set. A subagent uses its directory name.### Recommended layout@@ -93,31 +95,29 @@ my-agent/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.+### Agent files and directories++Each path under `agent/` has a specific purpose. Root agents can use every path below. A subagent has its own files and can use only the paths marked **Yes**.++| Path | Use | Available to 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. |++### Files available in the sandbox++Files under `agent/` define your agent; only files in `agent/sandbox/workspace/` are copied to `/workspace/` when a session starts.### Local subagents