eve 0.10.0 → 0.11.0

package/docs/reference/project-layout.md

@@ -9,14 +9,14 @@ Eve builds an agent by walking the filesystem under `agent/`. Each directory is
 
 Identity comes from the path. You never write a `name` or `id` field on a `define*` call.
 
-| Path                                  | Becomes               |
+| 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`. A subagent takes its name from its directory.
+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
 
@@ -24,38 +24,43 @@ The root agent takes its name from the enclosing `package.json` `name`. A subage
 my-agent/
 ├── package.json
 ├── tsconfig.json
-└── agent/
-    ├── agent.ts
-    ├── instructions.md
-    ├── instrumentation.ts
-    ├── channels/
-    ├── connections/
-    ├── hooks/
-    ├── skills/
-    ├── lib/
-    ├── sandbox/
-    ├── tools/
-    ├── schedules/
-    └── subagents/
+├── 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
 
-| Path                                                    | Holds                                       | Notes                                                                                                                                                                                                                       |
-| ------------------------------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `agent.ts`                                              | Runtime config                              | Model, modelOptions, compaction, build, experimental. See [Agent config](../agent-config).                                                                                                                                  |
-| `instructions.md` / `instructions.ts` / `instructions/` | Base system prompt                          | A flat file, or a directory of `.md` and `.ts` files. Static sources compose at build time. Dynamic sources (`defineDynamic` + `defineInstructions`) resolve at runtime.                                                    |
-| `instrumentation.ts`                                    | Telemetry config                            | OTel exporter and AI SDK span settings; auto-discovered and run before agent code.                                                                                                                                          |
-| `channels/`                                             | HTTP / messaging entrypoints                | Root-only today.                                                                                                                                                                                                            |
-| `connections/`                                          | External service connections (MCP, OpenAPI) | One connection per file; name derived from filename.                                                                                                                                                                        |
-| `hooks/`                                                | Lifecycle and stream-event subscribers      | Module-backed only. Recursive directories supported.                                                                                                                                                                        |
-| `skills/`                                               | On-demand procedures and capability packs   | Flat markdown, module-backed skills, or packaged skills. Seeded into `/workspace/skills/...`.                                                                                                                               |
-| `lib/`                                                  | Shared authored helper code                 | Import-only; not mounted into the workspace.                                                                                                                                                                                |
-| `sandbox.ts` or `sandbox/sandbox.ts`                    | The agent's single sandbox                  | 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. Supported on root and local subagents. |
-| `sandbox/workspace/**`                                  | Files seeded into the sandbox               | Mirrored into `/workspace/...` at session bootstrap.                                                                                                                                                                        |
-| `tools/`                                                | Typed executable integrations               | Module-backed only.                                                                                                                                                                                                         |
-| `schedules/`                                            | Recurring jobs                              | Each schedule is `<name>.ts` (default-exported `defineSchedule`) or `<name>.md` (frontmatter `cron:` + prompt body). Recursive nesting supported. Root-only today.                                                          |
-| `subagents/`                                            | Specialist child agents                     | Each child is its own local package under `subagents/<id>/`.                                                                                                                                                                |
+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 `/workspace/skills/...`.                                                                                                                         |
+| `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 workspace
 
@@ -74,6 +79,7 @@ A local subagent lives under `subagents/<id>/` and uses the same `agent.ts` shap
 agent/subagents/researcher/
 ├── agent.ts
 ├── instructions.md
+├── connections/
 ├── hooks/
 ├── skills/
 ├── lib/
@@ -86,7 +92,8 @@ Rules:
 
 - `agent.ts` is required, and must declare a `description`. 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).
-- `channels/` and `schedules/` are not supported inside local subagents today.
+- `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
@@ -106,7 +113,7 @@ Prefer the nested layout. It keeps the app root separate from the authored surfa
 
 ## 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.
+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
 

package/docs/reference/typescript-api.md

@@ -54,7 +54,7 @@ A few non-`define*` helpers round out the set: `disableTool` and `ExperimentalWo
 
 ## Runtime context (`ctx`)
 
-`ctx` is passed to your tool `execute`, hook handlers, and channel event handlers. It is live only while authored code is actually running, so reaching for it at module top level throws. See [Session context](../guides/session-context) for the full model.
+`ctx` is passed to your tool `execute`, hook handlers, and channel event handlers. It is live only while authored code is running, so reaching for it at module top level throws. See [Session context](../guides/session-context) for the full model.
 
 | Member                     | Use                                                                           |
 | -------------------------- | ----------------------------------------------------------------------------- |

package/docs/sandbox.mdx

@@ -1,11 +1,13 @@
 ---
 title: "Sandbox"
-description: "The agent's isolated bash environment: built-in file tools, a seeded /workspace, backends, lifecycle, and network policy."
+description: "The agent's isolated bash environment, including built-in file tools, a seeded /workspace, backends, lifecycle, and network policy."
 ---
 
 The sandbox is the agent's isolated bash environment: a filesystem rooted at `/workspace` where it can run shell commands, execute scripts, and read or write files without ever touching your app runtime. Every Eve agent has exactly one. The built-in `bash`, `read_file`, `write_file`, `glob`, and `grep` tools already target it, and your authored code can too.
 
-You author nothing for the agent to have a working sandbox; it exists by default. Override it only when you need to add setup, seed files, pick a backend, or lock down the network.
+A working sandbox exists by default, with nothing to author. Override it only to add setup, seed files, pick a backend, or lock down the network.
+
+The default sandbox is not a substitute for configuring network policy, credentials, retention, deletion, or other controls your application requires.
 
 ## Using the sandbox
 
@@ -18,7 +20,7 @@ The model already has shell and file access through the default tools:
 | `glob`                     | find files by pattern               |
 | `grep`                     | search file contents                |
 
-All of them run with `/workspace` as the working directory. Any authored runtime function (a tool, a step, a model callback) can grab a live sandbox handle with `ctx.getSandbox()`.
+All of them run with `/workspace` as the working directory. Any authored runtime function (a tool, a step, a model callback) can get a live sandbox handle with `ctx.getSandbox()`.
 
 ```ts title="agent/tools/run_analysis.ts"
 import { defineTool } from "eve/tools";
@@ -38,7 +40,7 @@ export default defineTool({
 
 `ctx.getSandbox()` takes no arguments, is async, and only works inside authored runtime execution.
 
-`/workspace` is one namespace across every backend, so `/workspace/foo` points at the same file whether the backend is local or Vercel. When you need to interpolate a path into a generated command, `sandbox.resolvePath("repo/build.py")` anchors a relative path to its absolute `/workspace/repo/build.py` form. `readFile`, `writeFile`, and `run` do the same anchoring internally.
+`/workspace` is one namespace across every backend, so `/workspace/foo` points at the same file whether the backend is local or Vercel. When you need to interpolate a path into a generated command, `sandbox.resolvePath("repo/build.py")` anchors a relative path to its absolute `/workspace/repo/build.py` form.
 
 The handle does more than `run` and `writeTextFile`. In every method, relative paths resolve from `/workspace` and absolute paths pass through untouched:
 
@@ -53,7 +55,7 @@ The handle does more than `run` and `writeTextFile`. In every method, relative p
 | `resolvePath(path)`                      | anchor a relative path to its absolute `/workspace/...` form                                    |
 | `setNetworkPolicy(policy)`               | change egress policy mid-turn (backend-dependent; see [Network policy](#network-policy))        |
 
-Since `run` blocks until the command exits, reach for `spawn` when the process should keep running while the agent does other work:
+Since `run` blocks until the command exits, use `spawn` when the process should keep running while the agent does other work:
 
 ```ts
 const sandbox = await ctx.getSandbox();
@@ -66,7 +68,7 @@ A `SandboxProcess` exposes `stdout`/`stderr` byte streams, `wait()` (resolves wi
 
 `sandbox.id` is a stable per-session identifier that persists across reconnects to the same logical session. Use it as the cache key for per-session state that must outlive individual step executions.
 
-The option types (`SandboxSpawnOptions`, `SandboxReadBinaryFileOptions`, `SandboxWriteBinaryFileOptions`, and so on) are named-exported from `eve/sandbox` alongside `SandboxProcess`.
+The option types (`SandboxSpawnOptions`, `SandboxReadBinaryFileOptions`, `SandboxWriteBinaryFileOptions`, and so on) are named exports from `eve/sandbox`, alongside `SandboxProcess`.
 
 ## Seeding `/workspace`
 
@@ -80,7 +82,7 @@ agent/sandbox/
     scripts/run.sh          ← lands at /workspace/scripts/run.sh
 ```
 
-Every file under `workspace/` mirrors into the sandbox cwd with its structure intact, and Eve lists the top-level entries to the model in the prompt automatically. One subtree is off limits: skill discovery already seeds skill files under `/workspace/skills/`, so authoring `agent/sandbox/workspace/skills/...` is rejected. Put those under `agent/skills/` instead.
+Every file under `workspace/` mirrors into the sandbox cwd with its structure intact, and Eve lists the top-level entries to the model in the prompt automatically. One subtree is off limits. Skill discovery already seeds skill files under `/workspace/skills/`, so authoring `agent/sandbox/workspace/skills/...` is rejected; put those under `agent/skills/` instead.
 
 ## Overriding the sandbox
 
@@ -117,14 +119,14 @@ The backend decides where the sandbox runs. Eve ships four pinned factories from
 | `vercel()`         | on [Vercel Sandbox](https://vercel.com/docs/sandbox).                                          |
 | `docker()`         | locally in a Docker container, driven through the `docker` CLI.                                |
 | `microsandbox()`   | locally in a lightweight [microsandbox](https://www.npmjs.com/package/microsandbox) VM.        |
-| `justbash()`       | locally in the pure-JS `just-bash` interpreter — no daemon or VM, but no real binaries either. |
+| `justbash()`       | locally in the pure-JS `just-bash` interpreter (no daemon or VM, but no real binaries either). |
 | `defaultBackend()` | picks the best available: Vercel Sandbox on hosted Vercel → Docker → microsandbox → just-bash. |
 
-Configuring a pinned factory uses that backend unconditionally — `docker()` always requires a reachable Docker daemon, `vercel()` always creates hosted sandboxes (including from local dev, with Vercel credentials).
+Configuring a pinned factory uses that backend unconditionally. `docker()` always requires a reachable Docker daemon, and `vercel()` always creates hosted sandboxes (including from local dev, with Vercel credentials).
 
 With `backend` omitted, Eve uses `defaultBackend()`, which resolves on first use in priority order:
 
-1. **Vercel Sandbox** when deploying on Vercel (`process.env.VERCEL` is set) — local container/VM runtimes can't run there.
+1. **Vercel Sandbox** when deploying on Vercel (`process.env.VERCEL` is set), since local container/VM runtimes can't run there.
 2. **Docker** when a daemon is reachable through a Docker-compatible `docker` CLI (Docker Desktop, OrbStack, Colima, Podman via its docker-compatible CLI; override the binary with `EVE_DOCKER_PATH`).
 3. **microsandbox** when the host supports it: macOS on Apple Silicon, or glibc Linux with KVM enabled.
 4. **just-bash** as the dependency-free fallback.
@@ -145,24 +147,26 @@ export default defineSandbox({
 
 ### Docker
 
-`docker()` drives the Docker CLI directly. The default base image is `ghcr.io/vercel/eve:latest`, Eve's published sandbox runtime image; Eve creates `/workspace` and verifies Bash during framework setup before authored bootstrap code runs. Configure it through `docker({ image, env, pullPolicy, networkPolicy })`; install authored runtime tools in sandbox bootstrap or provide them through a custom image. Templates are committed as local Docker images and reused across sessions when the sandbox source, seed files, `revalidationKey`, and Docker backend options still match; sessions run as long-lived containers whose filesystems persist `/workspace` changes across turns for the same durable session. `eve dev` prunes stale template images in the background.
+`docker()` drives the Docker CLI directly. The default base image is `ghcr.io/vercel/eve:latest`, Eve's published sandbox runtime image. Eve creates `/workspace` and verifies Bash during framework setup, before authored bootstrap code runs. Configure it through `docker({ image, env, pullPolicy, networkPolicy })`, and install authored runtime tools in sandbox bootstrap or provide them through a custom image. Templates are committed as local Docker images and reused across sessions when the sandbox source, seed files, `revalidationKey`, and Docker backend options still match. Sessions run as long-lived containers whose filesystems persist `/workspace` changes across turns for the same durable session. `eve dev` prunes stale template images in the background.
 
 ### microsandbox
 
-`microsandbox()` runs each sandbox in a lightweight local VM with snapshot-backed templates, a `vercel-sandbox` user, and a firewall capable of domain-level network policies and credential brokering — the closest local match to hosted Vercel Sandbox. The default base image is `ghcr.io/vercel/eve:latest`, Eve's published sandbox runtime image; Eve verifies Bash, creates `/workspace`, and creates the sandbox user during framework setup before authored bootstrap code runs. Install authored runtime tools in sandbox bootstrap or provide them through a custom image. Supported hosts: macOS on Apple Silicon, or Linux (glibc) with KVM. The `microsandbox` npm package and its VM runtime are not bundled with Eve: `eve dev` installs both automatically when missing (disable with `setup: { autoInstall: false }`); production processes fail with actionable install errors instead.
+`microsandbox()` runs each sandbox in a lightweight local VM with snapshot-backed templates, a `vercel-sandbox` user, and a firewall capable of domain-level network policies and credential brokering. It is the closest local match to hosted Vercel Sandbox. The default base image is `ghcr.io/vercel/eve:latest`, Eve's published sandbox runtime image. During framework setup, before authored bootstrap code runs, Eve verifies Bash and creates `/workspace` and the sandbox user. Install authored runtime tools in sandbox bootstrap or provide them through a custom image. Supported hosts are macOS on Apple Silicon, or Linux (glibc) with KVM. The `microsandbox` npm package and its VM runtime are not bundled with Eve, so `eve dev` installs both automatically when missing (disable with `setup: { autoInstall: false }`); production processes fail with actionable install errors instead.
 
 ### just-bash
 
-`justbash()` needs no daemon or VM, but commands run in a simulated bash with a virtual filesystem under `.eve/sandbox-cache/` — no real binaries (`git`, `node`, package managers) and no network isolation. The `just-bash` package is an optional peer dependency: `eve dev` installs it into your application automatically when missing (disable with `autoInstall: false`); production processes fail with an actionable install error instead.
+`justbash()` needs no daemon or VM, but commands run in a simulated bash with a virtual filesystem under `.eve/sandbox-cache/`, with no real binaries (`git`, `node`, package managers) and no network isolation. The `just-bash` package is an optional peer dependency, so `eve dev` installs it into your application automatically when missing (disable with `autoInstall: false`); production processes fail with an actionable install error instead.
 
-You can write your own backend too: a `SandboxBackend` is just an object with a `name`, a `create`, and an optional `prewarm`. See the `SandboxBackend*` types on `eve/sandbox`.
+You can also write your own backend. A `SandboxBackend` is an object with a `name`, a `create`, and an optional `prewarm`. See the `SandboxBackend*` types on `eve/sandbox`.
 
 ## Lifecycle
 
 There are two hooks, scoped differently:
 
-- **`bootstrap({ use })`** is template-scoped and runs once when the template is built. Put reusable setup here, the kind every later session inherits: clone a baseline repo, install dependencies, seed files. Call `use()` to get a `SandboxSession`. Only template filesystem state and supported backend metadata carry into later sessions; config like network policy does not. If external inputs affect what bootstrap produces, set `revalidationKey: () => string` so Eve knows when to rebuild the template (authored sandbox source and seed contents are already tracked for you).
-- **`onSession({ use, ctx })`** is durable-session-scoped and runs once per session. This is where per-session setup goes: network policy, resources, timeout, per-user credentials, one-time markers. Because it runs inside the active runtime context, it can read `ctx.session` and derive the current principal without baking credentials into the template. Call `use(opts?)` to get a `SandboxSession`; `opts` flow to the backend's update path after create.
+- **`bootstrap({ use })`** is template-scoped and runs once when the template is built. Put reusable setup here that every later session inherits, such as cloning a baseline repo, installing dependencies, or seeding files. Call `use()` to get a `SandboxSession`. Only template filesystem state and supported backend metadata carry into later sessions; config like network policy does not. If external inputs affect what bootstrap produces, set `revalidationKey: () => string` so Eve knows when to rebuild the template (authored sandbox source and seed contents are already tracked for you).
+- **`onSession({ use, ctx })`** is durable-session-scoped and runs once per session. Put per-session setup here, including network policy, resources, timeout, per-user credentials, and one-time markers. Because it runs inside the active runtime context, it can read `ctx.session` and derive the current principal without baking credentials into the template. Call `use(opts?)` to get a `SandboxSession`; `opts` flow to the backend's update path after create.
+
+If you require a network policy or other configuration for every session, configure it on the backend factory or in `onSession`; do not rely on bootstrap-only configuration.
 
 ```ts
 import { defineSandbox } from "eve/sandbox";
@@ -179,7 +183,7 @@ export default defineSandbox({
 });
 ```
 
-Sessions are persistent. When the VM shuts down (timeout, default 30 minutes), the filesystem is preserved and the sandbox resumes on the next message as if nothing happened, even days later.
+Sessions are persistent, and how the underlying runtime idles out depends on the backend. On the Vercel backend, the VM times out after a period of inactivity (default 30 minutes); Eve preserves the filesystem and resumes the sandbox on the next message as if nothing happened, even days later. The Docker backend keeps a long-lived container per durable session and persists `/workspace` across turns without that timeout, and the just-bash backend stores its virtual filesystem under `.eve/sandbox-cache/`. In every case, `/workspace` survives between turns for the same session.
 
 ## Network policy
 
@@ -195,7 +199,9 @@ networkPolicy: {
 };
 ```
 
-Set it on the factory (`vercel({ networkPolicy: "deny-all" })`) and it applies before authored `bootstrap` code runs; framework-owned base setup may briefly keep egress open to install required packages. Set it in `onSession`'s `use()` to override per-session. The common pattern combines both: leave the factory open so `bootstrap` can `git clone`, then lock down in `onSession`. And to change the policy mid-turn, call `sandbox.setNetworkPolicy(...)` on the live handle.
+Default egress is `allow-all`. For non-public, sensitive, regulated, or production workloads, configure `deny-all` or an explicit allow-list before running untrusted tools or handling sensitive data.
+
+Set it on the factory (`vercel({ networkPolicy: "deny-all" })`) and it applies before authored `bootstrap` code runs; framework-owned base setup may briefly keep egress open to install required packages. Set it in `onSession`'s `use()` to override per-session. The common pattern combines both: leave the factory open so `bootstrap` can `git clone`, then lock down in `onSession`. To change the policy mid-turn, call `sandbox.setNetworkPolicy(...)` on the live handle.
 
 Domain-level allow-lists and credential brokering are supported by `vercel()` and `microsandbox()`. The Docker backend honors only `"allow-all"` and `"deny-all"` (at creation and via `setNetworkPolicy`); the just-bash backend rejects `setNetworkPolicy` entirely.
 
@@ -208,7 +214,7 @@ async onSession({ use }) {
   await use({
     networkPolicy: {
       allow: {
-        "github.com": [{ transform: [{ headers: { authorization: "Basic …" } }] }],
+        "github.com": [{ transform: [{ headers: { authorization: "Basic your_base64_credentials_here" } }] }],
         "*": [],
       },
     },

package/docs/schedules.mdx

@@ -1,9 +1,9 @@
 ---
 title: "Schedules"
-description: "Run an agent on a cron cadence: a fire-and-forget prompt, or a handler that hands work off to a channel."
+description: "Run an agent on a cron cadence, either a fire-and-forget prompt or a handler that hands work off to a channel."
 ---
 
-A schedule is how the agent starts work on its own clock instead of waiting for an inbound message. Daily digests, data syncs, cleanup sweeps, heartbeats: anything that should fire on a cadence. Each one is a single file under `agent/schedules/` carrying a cron expression. Schedules are root-only, so declared subagents cannot have a `schedules/` directory.
+A schedule starts the agent on its own clock instead of waiting for an inbound message. Use one for daily digests, data syncs, cleanup sweeps, heartbeats, or anything that should fire on a cadence. Each one is a single file under `agent/schedules/` carrying a cron expression. Schedules are root-only, so declared subagents cannot have a `schedules/` directory.
 
 The name comes from the path under `schedules/` (`agent/schedules/billing/sweep.ts` → `"billing/sweep"`), and nested directories are fine.
 
@@ -25,11 +25,13 @@ interface ScheduleHandlerArgs {
 }
 ```
 
-`defineSchedule` is just a pass-through for types. The compiler is what enforces the one-of rule.
+`defineSchedule` is a type-level pass-through. The compiler is what enforces the one-of rule.
+
+`cron` is a standard 5-field string (`minute hour day-of-month month day-of-week`) with minute granularity. On Vercel, each schedule becomes a Vercel Cron Job, and Vercel evaluates the expression in UTC, so `"0 9 * * 1-5"` fires at 09:00 UTC on weekdays. `eve dev` never fires schedules on their cron cadence. To trigger one while iterating, use the dispatch route below.
 
 ## Markdown form (fire-and-forget)
 
-This is the minimal schedule. Eve runs the agent on the prompt and throws away the output, though the agent can still call tools, write to backends, and log along the way. We call this task mode. A task-mode session runs to completion or fails; it cannot park to wait for a person or an OAuth sign-in.
+This is the minimal schedule. Eve runs the agent on the prompt and throws away the output, though the agent can still call tools, write to backends, and log along the way. We call this task mode. A task-mode session runs to completion or fails, and cannot park to wait for a person or an OAuth sign-in.
 
 ```ts title="agent/schedules/heartbeat.ts"
 import { defineSchedule } from "eve/schedules";
@@ -54,7 +56,7 @@ Sweep stale workflow state.
 
 ## Handler form (`run`)
 
-Reach for a handler when the schedule needs to deliver to a channel, branch on conditions, or compute its arguments at fire time. The handler is in full control. It has no channel of its own, so it passes the work to one with `receive`.
+Use a handler when the schedule needs to deliver to a channel, branch on conditions, or compute its arguments at fire time. The handler is in full control. It has no channel of its own, so it passes the work to one with `receive`.
 
 ```ts title="agent/schedules/daily-digest.ts"
 import { defineSchedule } from "eve/schedules";
@@ -75,30 +77,30 @@ export default defineSchedule({
 });
 ```
 
-- `receive(channel, { message, target, auth })`: starts a session on another channel. Same contract as a route handler’s `args.receive`.
-- `waitUntil(promise)`: extends the cron task’s lifetime so the parked session and any in-flight fetches settle before the task ends. Wrap the `receive` call in it.
+- `receive(channel, { message, target, auth })`: starts a session on another channel. Same contract as a route handler's `args.receive`.
+- `waitUntil(promise)`: extends the cron task's lifetime so the parked session and any in-flight fetches settle before the task ends. Wrap the `receive` call in it.
 - `appAuth`: the app principal (`{ authenticator: "app", principalId: "eve:app", principalType: "runtime" }`). Pass it as `receive(..., { auth: appAuth })` for work the agent does on its own behalf.
 
-A handler-form session runs on the same durable runtime engine as any other session, so it can park, for instance when the channel handoff is waiting for a Slack reply. Only markdown task mode is barred from waiting.
+A handler-form session runs on the same durable runtime engine as any other session, so it can park (durably suspend), for instance when the channel handoff is waiting for a Slack reply. Only markdown task mode is barred from waiting.
 
 ## Trigger a schedule while iterating
 
-In production the cron cadence is the only thing that fires a schedule, but waiting for the next tick gets old fast while iterating in `eve dev`. So the dev server mounts a one-shot dispatch route: fire a schedule by name, out of band, exactly once.
+The dev server mounts a one-shot dispatch route that fires a schedule by name, out of band, exactly once. Since `eve dev` never runs schedules on their cron cadence, this is how you trigger one without waiting for the next production tick.
 
 ```sh
-curl -X POST http://localhost:2000/eve/v1/dev/schedules/heartbeat
+curl -X POST http://localhost:3000/eve/v1/dev/schedules/heartbeat
 # -> { "scheduleId": "heartbeat", "sessionIds": ["..."] }
 ```
 
-`:scheduleId` is the path-derived schedule name (`agent/schedules/heartbeat.ts` → `heartbeat`; URL-encode the `/` in nested names). It runs the exact dispatch path the production cron handler uses and returns the started session ids as JSON, so you can subscribe to each one’s [stream](./concepts/sessions-runs-and-streaming) at `GET /eve/v1/session/:sessionId/stream`. An unknown id comes back `404` with `availableScheduleIds`, listing the schedules the app actually defines.
+`:scheduleId` is the path-derived schedule name (`agent/schedules/heartbeat.ts` → `heartbeat`; URL-encode the `/` in nested names). It runs the exact dispatch path the production cron handler uses and returns the started session ids as JSON, so you can subscribe to each one's [stream](./concepts/sessions-runs-and-streaming) at `GET /eve/v1/session/:sessionId/stream`. An unknown id comes back `404` with `availableScheduleIds`, listing the schedules the app actually defines.
 
 The route is dev-only. Production builds never mount it, and it needs no auth since the dev server is local-only.
 
 ## On Vercel
 
-Hosted Vercel builds turn every `defineSchedule(...)` into a Vercel Cron Job, with each `cron` written as an entry in `.vercel/output/config.json`. Confirm discovery under Settings → Cron Jobs and watch execution history under Observability → Cron Jobs. Per-run logs land under Observability → Logs.
+Hosted Vercel builds turn every `defineSchedule(...)` into a Vercel Cron Job, with each `cron` written as an entry in `.vercel/output/config.json`. Vercel evaluates these expressions in UTC. Confirm discovery under **Settings → Cron Jobs** and watch execution history under **Observability → Cron Jobs**. Per-run logs land under **Observability → Logs**.
 
 ## What to read next
 
-- Deliver schedule output to users → [Channels](./channels/overview)
-- Inspect a schedule run → [Sessions, runs & streaming](./concepts/sessions-runs-and-streaming)
+- [Channels](./channels/overview): deliver schedule output to users.
+- [Sessions, runs & streaming](./concepts/sessions-runs-and-streaming): inspect a schedule run.

package/docs/skills.mdx

@@ -3,7 +3,7 @@ title: "Skills"
 description: "Author load-on-demand procedures the model pulls into context with load_skill."
 ---
 
-A skill is a model-loadable procedure that follows the `SKILL.md` convention: a markdown document (optionally a packaged directory with supporting files) that the model pulls into context on demand rather than carrying on every turn. Eve advertises each skill's description, and the model loads the full body only when a turn calls for it, the progressive-disclosure model the broader Agent Skills standard uses. A skill authored against that standard ports over as-is.
+A skill is a model-loadable procedure that follows the `SKILL.md` convention. It is a markdown document, optionally a packaged directory with supporting files, that the model pulls into context on demand rather than carrying on every turn. Eve advertises each skill's description, and the model loads the full body only when a turn calls for it. This is progressive disclosure, the same model the broader Agent Skills standard uses, so a skill authored against that standard ports over as-is.
 
 ## How loading works
 
@@ -25,11 +25,11 @@ The smallest skill is a flat markdown file. The content is the procedure, and th
 Use the weather tool before answering forecast or temperature questions.
 ```
 
-A packaged skill is a directory: a `SKILL.md` plus sibling files like `references/`, `assets/`, and `scripts/`. The packaged `SKILL.md` must carry `description` frontmatter. Flat markdown skills may skip it.
+A flat markdown skill can skip the `description` frontmatter. When it does, Eve advertises the first non-empty, non-code-fence line of the body with any leading `#`, `>`, `*`, or `-` marker stripped. If the body has no such line, Eve falls back to the literal `Instructions for the <name> skill.`, which is a weak routing hint, so add a `description` when you want the model to route on intent.
 
-`agent/skills/research/SKILL.md`:
+A packaged skill is a directory with a `SKILL.md` plus sibling files like `references/`, `assets/`, and `scripts/`. The packaged `SKILL.md` must carry `description` frontmatter; it has no filename slug to fall back on.
 
-```md
+```md title="agent/skills/research/SKILL.md"
 ---
 description: Research unfamiliar topics before answering with confidence.
 ---
@@ -55,7 +55,9 @@ export default defineSkill({
 
 Eve generates `SKILL.md` from `markdown`, and each `files` entry becomes a package-relative sibling. Start with plain markdown and move to `defineSkill` only when you hit its limits.
 
-Skills are scoped to the agent that declares them. A [subagent](./subagents)'s `skills/` are invisible to the root agent, and the reverse holds too. There's no shared-skill mechanism, so when you want to share executable helpers, put them in `lib/`.
+## Skills are scoped per agent
+
+Skills are scoped to the agent that declares them. A [subagent](./subagents)'s `skills/` are invisible to the root agent, and the reverse holds too. There's no shared-skill mechanism, so put shared executable helpers in `lib/`.
 
 ## Read skill files at runtime
 
@@ -70,7 +72,7 @@ The handle exposes the skill's `name` and `file(relativePath)`; file content is
 
 ## Dynamic skills
 
-Want a different skill per principal, tenant, or channel, like the caller's own team playbook? Wrap `defineSkill` in a `defineDynamic` resolver keyed on `ctx.session.auth`. See [Dynamic capabilities](./guides/dynamic-capabilities).
+To serve a different skill per principal, tenant, or channel (the caller's own team playbook, say), wrap `defineSkill` in a `defineDynamic` resolver keyed on `ctx.session.auth`. See [Dynamic capabilities](./guides/dynamic-capabilities).
 
 ## What to read next
 

package/docs/subagents.mdx

@@ -1,9 +1,9 @@
 ---
 title: "Subagents"
-description: "Delegate work to child agents: a copy of the agent itself, or declared specialists with their own sandbox and skills."
+description: "Delegate work to child agents, either a copy of the agent itself or declared specialists with their own sandbox and skills."
 ---
 
-A subagent is a child agent that one agent delegates a focused subtask to. Split work out into one when you want it to run in parallel, when the child should see a narrower set of tools, or when a specialist needs its own identity. There are two kinds.
+A subagent is a child agent that one agent delegates a focused subtask to. Split work into one to run it in parallel, to give the child a narrower set of tools, or to give a specialist its own identity. There are two kinds, the built-in `agent` tool (a copy of the agent itself) and declared subagents (specialists with their own directory).
 
 ## The built-in `agent` tool
 
@@ -16,7 +16,9 @@ Every agent gets an `agent` tool by default. The model calls it to delegate a su
 }
 ```
 
-The copy shares the parent's sandbox and tools. A child's file writes are immediately visible to the parent, which is what makes parallel calls natural: fan out a few copies to fix different files at once. The copy inherits auth and connections, but starts with fresh conversation history and fresh state. If a declared subagent calls `agent`, the child is a copy of _that_ subagent, not the root.
+The copy shares the parent's sandbox and tools, and a child's file writes are immediately visible to the parent. That is what makes parallel calls natural: fan out a few copies to fix different files at once. The copy inherits auth and connections, but starts with fresh conversation history and fresh state. If a declared subagent calls `agent`, the child is a copy of _that_ subagent, not the root.
+
+The parent transfers data to the child through the `message` input it gives the subagent. Do not include sensitive data in a subagent request unless that child and its inherited tools, connections, sandbox, and telemetry path are appropriate for that data.
 
 An authored tool at `agent/tools/agent.ts` takes priority over the built-in.
 
@@ -47,30 +49,54 @@ agent/subagents/researcher/
 └── subagents/          # optional, nested subagents
 ```
 
-`schedules/` is not supported inside a declared subagent: schedules are root-only.
+`schedules/` is not supported inside a declared subagent. Schedules are root-only.
 
 ## The isolation boundary
 
-A declared subagent gets its own independent sandbox and its own `skills/` set. Neither crosses the parent boundary:
+A declared subagent inherits nothing from the root's authored slots. Discovery treats its directory as its own agent root, so it has only the instructions, tools, connections, skills, sandbox, hooks, and nested subagents authored under `agent/subagents/<id>/`. An absent slot falls back to the framework default, not to the root's version.
+
+| Slot         | Built-in `agent` tool         | Declared subagent                      |
+| ------------ | ----------------------------- | -------------------------------------- |
+| Instructions | Inherited (copy of the agent) | Own `instructions.{md,ts}`, optional   |
+| Tools        | Inherited                     | Own `tools/`                           |
+| Connections  | Inherited                     | Own `connections/`                     |
+| Skills       | Inherited                     | Own `skills/`                          |
+| Sandbox      | Shared with parent            | Own `sandbox/`, else framework default |
+| Hooks        | Inherited                     | Own `hooks/`                           |
+| State        | Fresh                         | Fresh                                  |
+| Channels     | Root-only                     | Root-only                              |
+| Schedules    | Root-only                     | Root-only                              |
 
-- The child sees only skills authored under `agent/subagents/<id>/skills/`. Root `agent/skills/` stay out of reach during its turns. When two subagents need the same procedure, duplicate the markdown under each, or share typed helpers via `lib/`.
-- The child's sandbox does not inherit from the parent. It falls back to the framework default unless it authors `subagents/<id>/sandbox.ts`, or seeds files via `subagents/<id>/sandbox/workspace/`.
+For a declared subagent this means duplicating anything the child needs. When two subagents need the same procedure, copy the markdown under each `skills/` directory, or share typed helpers via `lib/`. The sandbox does not inherit from the parent; it falls back to the framework default unless the subagent authors `subagents/<id>/sandbox.ts` or seeds files via `subagents/<id>/sandbox/workspace/`.
 
-The built-in `agent` tool is the exception: its children share the parent's sandbox and tools because they are copies of the same agent working on the same files.
+The built-in `agent` tool is the exception. Its children share the parent's sandbox and tools because they are copies of the same agent working on the same files.
 
-`defineState` is never shared, for either kind: each child starts with fresh durable state.
+`defineState` is never shared, for either kind. Each child starts with fresh durable state.
 
 ## What the parent sees
 
-Eve lowers every subagent (built-in copy, declared, or [remote](./guides/remote-agents)) into a model-visible tool with the same `{ message, outputSchema? }` shape. The parent packs `message` with everything the child needs, since the child never sees the parent's history. Set `outputSchema` and the child runs in task mode, returning structured output as the tool result.
+Eve lowers every subagent (built-in copy, declared, or [remote](./guides/remote-agents)) into a model-visible tool with the same `{ message, outputSchema? }` shape. The parent packs `message` with everything the child needs, since the child never sees the parent's history. Set `outputSchema` to run the child in task mode, returning structured output as the tool result.
+
+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__<connection>__<tool>`), it carries no namespace, so the model, approvals, logs, and evals all reference it by that name. Its input schema is:
+
+```ts
+{
+  message: string;       // all context the child needs; it never sees the parent's history
+  outputSchema?: object; // when set, the child runs in task mode and returns structured output
+}
+```
+
+Because the name lives in the same runtime tool namespace as authored tools, a subagent named `researcher` collides with a tool named `researcher`. Eve rejects the build rather than picking a winner, so keep subagent directory names distinct from tool names.
+
+Do not rely on subagent delegation by itself as an approval boundary. Put sensitive tools behind `needsApproval`, connection approval, route/session authorization, or other controls wherever those tools can be called.
 
 Each delegated subagent spins up its own child session and stream. The parent stream carries only the control-plane events `subagent.called` and `subagent.completed`. To follow the child's full progress, read `subagent.called.data.childSessionId` and subscribe at `GET /eve/v1/session/:childSessionId/stream`.
 
 ## When to split
 
-Split out a subagent when the task needs a different prompt or specialist role, a narrower tool surface, or its own runtime context. Don't reach for one when a [skill](./skills) would do: if the agent can keep its identity and just needs an optional procedure, a skill is the lighter choice.
+Split out a subagent when the task needs a different prompt or specialist role, a narrower tool surface, or its own runtime context. Don't reach for one when a [skill](./skills) would do. If the agent can keep its identity and needs only an optional procedure, a skill is the lighter choice.
 
 ## What to read next
 
-- Call another Eve deployment as a subagent → [Remote agents](./guides/remote-agents)
-- Have the model orchestrate its subagents programmatically (fan-out, map-reduce) → [Dynamic workflows](./guides/dynamic-workflows)
+- [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).

package/docs/tools.mdx

@@ -3,7 +3,7 @@ title: "Tools"
 description: "Define typed actions the agent can call, and gate sensitive ones on human approval."
 ---
 
-A tool is a typed action the agent can call: hit an API, run a query, write a file. The action stays in code you control. Tools run in your app runtime (full `process.env`), not the [sandbox](./sandbox).
+A tool is a typed action the agent can call, such as hitting an API, running a query, or writing a file. The action stays in code you control. Tools run in your app runtime with full access to `process.env`, not in the [sandbox](./sandbox).
 
 ## Define a tool
 
@@ -33,7 +33,7 @@ When a tool returns structured data, add an optional `outputSchema`. With Zod or
 
 ### The `ctx` parameter
 
-`execute` gets a `ctx` carrying the runtime accessors you'll reach for:
+`execute` gets a `ctx` carrying the runtime accessors:
 
 - `ctx.session`: session metadata, turn, auth, parent lineage.
 - `ctx.getSandbox()`: the live [sandbox](./sandbox) handle.
@@ -41,13 +41,13 @@ When a tool returns structured data, add an optional `outputSchema`. With Zod or
 
 Running in the app runtime is what lets a tool import shared code from `lib/`, read `process.env`, and take part in Eve’s durable pause/resume model.
 
-Eve never runs authored tools during discovery: the model sees descriptors first, and only what it actually calls gets executed. Re-executing a step from the same input is idempotent, so tool side effects are not duplicated when a turn resumes after a crash.
+Eve never runs authored tools during discovery. The model sees descriptors first, and only what it actually calls gets executed. Completed steps never re-run; Eve replays the recorded result. A step interrupted mid-execution re-runs, so make non-idempotent side effects like charges or emails idempotent, or gate them with approval.
 
 ## Human-in-the-loop
 
-HITL is not a separate system. It is just a tool that pauses for a person before (or instead of) running. Gate one on approval with `needsApproval` and the helpers from `eve/tools/approval`:
+Human-in-the-loop (HITL) approval is a property of a tool that pauses for a person before (or instead of) running. Gate a tool on approval with `needsApproval` and the helpers from `eve/tools/approval`:
 
-```ts
+```ts title="agent/tools/refund_charge.ts"
 import { defineTool } from "eve/tools";
 import { always } from "eve/tools/approval";
 import { z } from "zod";
@@ -68,13 +68,15 @@ export default defineTool({
 | `once()`   | Require approval only the first time the tool runs in a session; auto-allow after. |
 | `always()` | Require approval before every call.                                                |
 
-When the decision depends on the input, pass your own predicate instead of a helper. It receives `{ toolName, toolInput, approvedTools }` and returns a boolean. To require approval only when an amount crosses a threshold:
+By default, omitted `needsApproval` behaves like `never()`, so tool calls may execute without human approval. Require human approval or other safeguards for sensitive, irreversible, regulated, financial, healthcare, employment, housing, legal, safety-impacting, user-impacting, or external side-effecting actions.
+
+When the decision depends on the input, pass your own predicate instead of a helper. It receives `{ toolName, toolInput, approvedTools }` and returns a boolean. `toolInput` can be undefined, so guard the access. To require approval only when an amount crosses a threshold:
 
 ```ts
-needsApproval: ({ toolInput }) => toolInput.amount > 1000,
+needsApproval: ({ toolInput }) => (toolInput?.amount ?? 0) > 1000,
 ```
 
-### The pause and resume
+### How approval pause and resume works
 
 Approvals and questions share one protocol:
 
@@ -97,7 +99,9 @@ toModelOutput(output) {
 },
 ```
 
-It receives the full, typed `execute` return and only affects the model. Channel event handlers and hooks still get the full output on `action.result`, so a channel can render rich platform output (Slack Block Kit, say) the model never sees. Return `{ type: "text", value }` for a summary, or `{ type: "json", value }` for a smaller object.
+`toModelOutput` receives the full, typed `execute` return and only affects the model. Channel event handlers and hooks still get the full output on `action.result`, so a channel can render rich platform output (Slack Block Kit, say) the model never sees. Return `{ type: "text", value }` for a summary, or `{ type: "json", value }` for a smaller object.
+
+Do not return secrets, credentials, unnecessary personal data, or unbounded sensitive content from tools. Filter, minimize, and redact tool outputs before returning them.
 
 ## What to read next