eve 0.32.0 → 0.33.0

package/docs/agent-config.md

@@ -17,6 +17,10 @@ export default defineAgent({
 });
 ```
 
+For a static AI Gateway model ID, you can make the same source change from the
+project root with `eve set --model anthropic/claude-opus-4.8` or from the local
+dev TUI with `/model anthropic/claude-opus-4.8`.
+
 The root `agent.ts` can be omitted when no runtime config is needed. In that case, eve defaults
 to `anthropic/claude-sonnet-5`. When `agent.ts` is present, `model` is required.
 
@@ -45,21 +49,23 @@ Model use is subject to the terms, data-processing commitments, retention behavi
 
 ### Choose the model dynamically
 
-`model` also accepts `defineDynamic({ fallback, events })`. `fallback` is the
-compiled static model: it anchors build-time metadata (routing, credentials,
-context window) and serves whenever no dynamic selection is set.
+`model` also accepts `defineDynamic({ events })`. Each matching handler must
+return the concrete model for its scope; a dynamic model has no compiled
+default.
 
 ```ts title="agent/agent.ts"
 import { defineAgent, defineDynamic } from "eve";
 
 export default defineAgent({
   model: defineDynamic({
-    fallback: "anthropic/claude-sonnet-5",
     events: {
-      "session.started": (_event, ctx) =>
-        ctx.session.auth.initiator?.attributes.plan === "enterprise"
-          ? "anthropic/claude-opus-4.8"
-          : null,
+      "session.started": (_event, ctx) => {
+        if (ctx.session.auth.initiator?.attributes.plan === "enterprise") {
+          return "anthropic/claude-opus-4.8";
+        }
+
+        return "anthropic/claude-sonnet-5";
+      },
     },
   }),
 });
@@ -68,24 +74,28 @@ export default defineAgent({
 Handlers receive the shared [dynamic resolver
 context](./guides/dynamic-capabilities) (`ctx.session`, `ctx.channel`,
 `ctx.messages`) and return a gateway model id, an AI SDK `LanguageModel`, a
-selection object, or `null` to leave the scope unset.
+selection object. Returning `null` or `undefined` fails the turn.
 
 - **Scopes.** `session.started` (once per session), `turn.started` (once per
   turn), `step.started` (every model step). Precedence: step > turn >
-  session > `fallback`. Prefer `session.started`: prompt caches are per
-  model, so every switch re-ingests the conversation at uncached prices.
-- **Failures degrade, never fail the turn.** A resolver that throws or
-  returns an invalid selection logs an error and leaves its scope unset.
-  Build-time validation covers only `fallback`; a selected model without
-  credentials fails at request time.
+  session. Prefer `session.started`: prompt caches are per model, so every
+  switch re-ingests the conversation at uncached prices. If no active
+  selection exists before model-dependent work begins, the turn fails.
+- **Failures stop the turn.** A resolver that throws, returns no model, or
+  returns an invalid selection fails before the provider call. A selected
+  model without valid credentials fails at request time.
 - **Serialization.** Session/turn selections must be model id strings; return
   live `LanguageModel` objects only from `step.started`.
 - **Selection object.** `{ model, modelContextWindowTokens?, modelOptions? }`.
-  Set `modelContextWindowTokens` when the selected model's window differs
-  from the fallback's — it is never inherited. Omitted `modelOptions` reuses
-  the agent-level `modelOptions`.
+  When `modelContextWindowTokens` is omitted, eve resolves it from the AI
+  Gateway catalog and caches successful metadata in durable session state for
+  24 hours. Set it explicitly for an unlisted or custom model. Dynamic agents
+  cannot set sibling `modelContextWindowTokens` or `modelOptions` fields;
+  return per-model values from the handler.
 
-Runtime identity reports a dynamic agent's model as `dynamic:<fallback id>`.
+The `session.started` runtime identity does not include a model id for a
+dynamic agent. Each public `step.started` event reports the concrete `modelId`
+selected for that model call.
 
 ## Reasoning effort
 
@@ -103,6 +113,7 @@ Supported values are `"provider-default"`, `"none"`, `"minimal"`, `"low"`,
 `"medium"`, `"high"`, and `"xhigh"`. The selected model and provider determine
 which levels are available and how they map to provider-native settings. Use
 `modelOptions.providerOptions` when you need provider-specific reasoning controls.
+Run `eve set --reasoning high` to update this field from the command line.
 
 ## Compaction
 

package/docs/channels/chat-sdk.mdx

@@ -99,22 +99,22 @@ bot.onNewMention(async (thread, message) => {
 
 `options` accepts `{ thread, auth?, title?, mode?, callback?, adapterName?, turnPolicy? }`. `title` sets the eve session's display title without changing the model message; `auth` attaches an authenticated principal to the turn.
 
-### Experimental steering
+### Steering
 
-By default, a message sent while an eve turn is active waits for the next turn. Pass `turnPolicy: "experimental-steer"` to cancel the active turn before sending the new message:
+Messages default to `turnPolicy: "steer"`: a message sent while an eve turn is active is durably buffered, then cancels that turn and starts as its replacement. Set `turnPolicy: "queue"` when the active turn should finish first:
 
 ```ts
 bot.onSubscribedMessage(async (thread, message) => {
   await send(message.text, {
     thread,
-    turnPolicy: "experimental-steer",
+    turnPolicy: "queue",
   });
 });
 ```
 
-This is cancellation-backed steering: the interrupted turn emits `turn.cancelled`, and the replacement message starts a new turn with a new turn ID. Partial output and completed side effects from the interrupted turn are not rolled back. If no turn is active, the message is sent normally. Use the default `turnPolicy: "queue"` when every turn should finish in order.
+Cancellation-backed steering emits `turn.cancelled`, and the replacement message starts a new turn with a new turn ID. Partial output and completed side effects from the interrupted turn are not rolled back. If no turn is active, the message is sent normally. You can set the policy once on `chatSdkChannel({ turnPolicy })` or override it per `send(...)`.
 
-This policy controls overlapping eve turns. Chat SDK's separate `concurrency` option controls overlapping webhook handlers; use `concurrency: "concurrent"` when each inbound message should reach the experimental steering path immediately.
+This policy controls overlapping eve turns. Chat SDK's separate `concurrency` option controls overlapping webhook handlers; use `concurrency: "concurrent"` when each inbound message should reach the steering path immediately.
 
 ### Delivery
 

package/docs/channels/custom.mdx

@@ -109,6 +109,26 @@ await session.reset({ reason: "Retire this session" });
 await session.getEventStream({ startIndex: 12 });
 ```
 
+Message sends use the channel's `turnPolicy`, which defaults to `"steer"`. An accepted message arriving during an active turn is durably buffered before eve cancels that turn and starts the message as a replacement turn. Configure `turnPolicy: "queue"` on `defineChannel(...)` when active turns should finish in order, or override one send:
+
+```ts
+export default defineChannel({
+  turnPolicy: "queue",
+  routes: [
+    POST("/messages", async (request, { from }) => {
+      const body = await request.json();
+      await from(body.threadId).send(body.message, {
+        auth: null,
+        turnPolicy: "steer",
+      });
+      return new Response(null, { status: 202 });
+    }),
+  ],
+});
+```
+
+The same override is available on fixed `Session.send(...)` and cross-channel `to(...).send(...)`. `respond(...)` never steers: it delivers only addressed input responses. Use `cancel()` when you need to stop work without a replacement message.
+
 Attaching does no lookup. The first operation reports whether the ID is active.
 Call `resolveSession(address)` only when you explicitly need to snapshot an
 address's current owner as a fixed handle.

package/docs/channels/discord.mdx

@@ -16,6 +16,7 @@ pnpm eve add channel/discord
 
 The setup guides you through creating a Discord application and bot, then:
 
+- signs you in to Vercel and creates or links a project when needed;
 - validates the bot token;
 - creates a Vercel Connect client and attaches `/eve/v1/discord` as its trigger destination;
 - registers an application command with a required `message` option;

package/docs/channels/eve.mdx

@@ -56,6 +56,8 @@ curl -X POST https://<deployment>/eve/v1/session/wrun_A \
   -d '{"inputResponses":[{"requestId":"req_A","optionId":"approve"}]}'
 ```
 
+Follow-up messages use `turnPolicy: "steer"` by default. If a turn is active, eve buffers the message before cooperatively cancelling that turn, then starts the follow-up as a replacement turn with a new turn ID. Set `turnPolicy: "queue"` on `eveChannel(...)` when follow-ups should wait for active turns to finish. `inputResponses` never steer.
+
 Sending a message to an unknown or terminal session ID returns `409` with
 `{"code":"session_not_active","error":"The session is no longer active.","ok":false}`.
 TypeScript clients expose the stable code as `ClientError.code`. The route never

package/docs/channels/github.mdx

@@ -14,7 +14,7 @@ Run the registry setup from the agent directory:
 eve add channel/github
 ```
 
-The flow checks that the Vercel CLI is authenticated, creates or links a Vercel project when needed, provisions an app-scoped GitHub Connect client, and registers `/eve/v1/github` as a trigger destination. It then installs `@vercel/connect` and writes `agent/channels/github.ts` with the connector UID.
+The flow signs you in to Vercel when needed, creates or links a Vercel project, provisions an app-scoped GitHub Connect client, and registers `/eve/v1/github` as a trigger destination. It then installs `@vercel/connect` and writes `agent/channels/github.ts` with the connector UID.
 
 Vercel Connect creates the GitHub App, receives and verifies its webhooks, and forwards them to the deployed agent. After deploying, open the GitHub App in the Connect dashboard and install it in the organization or account where you want to use it. Add the generated invocation token (for example, `@my-agent`) to a new issue, pull request, or review comment to start a conversation. GitHub may not autocomplete the token or render it as a linked mention.
 

package/docs/channels/linear.mdx

@@ -16,7 +16,7 @@ eve add linear
 
 Select **Linear Channel** in the component checklist. **Linear MCP** is also selected by default if you want the agent to search and update Linear through MCP. Run `eve add channel/linear-agent` instead to install only the channel directly.
 
-The flow checks that the Vercel CLI is authenticated, creates or links a Vercel project when needed, reuses a compatible existing connector when available or provisions an app-scoped Linear Connect client, and registers `/eve/v1/linear` as a trigger destination. It then installs `@vercel/connect` and writes `agent/channels/linear.ts` with the connector UID.
+The flow signs you in to Vercel when needed, creates or links a Vercel project, reuses a compatible existing connector when available or provisions an app-scoped Linear Connect client, and registers `/eve/v1/linear` as a trigger destination. It then installs `@vercel/connect` and writes `agent/channels/linear.ts` with the connector UID.
 
 Vercel Connect creates the Linear app with the `app:assignable` and `app:mentionable` scopes required for Agent Sessions, receives and verifies `AgentSessionEvent` webhooks, and forwards them to the deployed agent. After deploying, open the Linear app in the Connect dashboard and install it in the workspace where you want to delegate work. Then delegate an issue or mention the agent in a Linear Agent Session.
 

package/docs/channels/overview.mdx

@@ -13,6 +13,25 @@ eve ships a base HTTP channel plus first-class platform channels, and you can au
 
 After a channel normalizes input, eve runs the same agent runtime regardless of where the message came from. Tools and instructions do not need channel-specific logic.
 
+## Overlapping messages
+
+Channels default to `turnPolicy: "steer"`. When an accepted message arrives while a turn is active, eve first durably buffers the message, then cooperatively cancels the active turn and starts a replacement turn. The cancelled turn emits `turn.cancelled` followed by `session.waiting`; the replacement starts with a new turn ID. Output already streamed and completed side effects are not rolled back.
+
+Set `turnPolicy: "queue"` on any built-in or custom channel when each turn must finish before the next message starts:
+
+```ts
+export default defineChannel({
+  turnPolicy: "queue",
+  routes: [
+    // ...
+  ],
+});
+```
+
+`from(address).send(...)`, fixed `Session.send(...)`, cross-channel sends, and Chat SDK bridge sends also accept a per-send `turnPolicy` override. Pure `inputResponses` deliveries answer their pending request without steering. Explicit `cancel()` remains the stop-without-replacement operation.
+
+Channel admission still runs first. Ignored mentions, rejected signatures, duplicates, and any other dropped platform events never affect the active turn.
+
 Each channel has its own provider terms, data flow, auth model, and user-consent expectations. Before sending non-public, sensitive, regulated, or production data through a channel, confirm that the channel provider and your configured scopes, signature checks, route auth, and delivery behavior are appropriate for your use case.
 
 ## Where channels live

package/docs/channels/photon.mdx

@@ -7,8 +7,9 @@ Use `photonIMessageChannel` to receive and reply to iMessages through a Photon p
 
 Run `eve add channel/photon-imessage` to create or use a Photon project and register
 your phone number. It then asks whether to configure Vercel Connect or portable
-credentials. With Vercel Connect, eve creates the connector and configures
-Photon’s webhook through Connect. The channel resolves credentials lazily when
+credentials. With Vercel Connect, eve signs you in and creates or links a Vercel
+project when needed, then creates the connector and configures Photon’s webhook
+through Connect. The channel resolves credentials lazily when
 the adapter first initializes:
 
 ```ts title="agent/channels/photon.ts"
@@ -26,6 +27,8 @@ read, and continues the same eve session for every message in an iMessage
 conversation. A new accepted message cooperatively cancels an active turn and
 steers its replacement turn.
 
+Set `turnPolicy: "queue"` when every response should finish before Photon starts the next message.
+
 Customize inbound dispatch with `onMessage`. Return `null` to ignore a message:
 
 ```ts

package/docs/channels/slack.mdx

@@ -18,7 +18,7 @@ The command recommends Vercel Connect, then scaffolds `agent/channels/slack.ts`
 
 ### Recommended: use Vercel Connect
 
-Vercel Connect setup requires an authenticated Vercel CLI and a linked Vercel project. The guided flow creates or reuses a Slack connector, waits for you to install it in a workspace, and registers `/eve/v1/slack` as a trigger destination before writing the channel file.
+Vercel Connect setup requires the Vercel CLI. The guided flow signs you in when needed, creates or links a Vercel project, creates or reuses a Slack connector, waits for you to install it in a workspace, and registers `/eve/v1/slack` as a trigger destination before writing the channel file.
 
 The generated channel resolves credentials at runtime:
 
@@ -236,24 +236,18 @@ export default slackChannel({
 
 `threadContext` requires the matching Slack history scope. Thread helpers reuse messages already loaded within the same inbound handler, and overlapping refreshes share one `conversations.replies` request. Omit it when the agent should see only direct mentions. `loadThreadContextMessages` remains available when you need custom filtering or non-model processing of the raw thread messages.
 
-#### Cancel an active turn
+#### Control overlapping turns
 
-Message hooks (`onMessage`, `onAppMention`, and `onDirectMessage`) receive thread-bound session operations directly on `ctx`. Call `ctx.cancel({ turnId? })` before returning `{ auth }` to stop the current turn and queue the new Slack message as replacement input, producing a debounce-like experience:
+Accepted Slack messages use cancellation-backed steering by default: eve buffers the new message, cancels the active turn, and starts a replacement turn. Admission happens first, so ignored mentions and messages rejected by your hooks never cancel work. Set `turnPolicy: "queue"` when every active turn should finish:
 
 ```ts title="agent/channels/slack.ts"
 export default slackChannel({
   credentials: connectSlackCredentials("slack/my-agent"),
-  async onMessage(ctx, message) {
-    const shouldHandle = ctx.isBotMentioned() || (await ctx.isSubscribed());
-    if (!shouldHandle || message.author?.isBot) return null;
-
-    await ctx.cancel();
-    return { auth: null };
-  },
+  turnPolicy: "queue",
 });
 ```
 
-`"accepted"` means the live thread session durably queued the cancellation request. A parked session consumes it as a no-op; `"no_active_turn"` means the thread has no active session owner. Both are successful outcomes, so the hook can still return `{ auth }` to deliver the replacement message. Cancellation never sends input itself. A custom `onInteraction` handler receives the same flat operations, which is useful for a Stop button that should cancel without replacement input.
+Message hooks (`onMessage`, `onAppMention`, and `onDirectMessage`) also receive thread-bound session operations directly on `ctx`. `ctx.cancel({ turnId? })` remains useful for a Stop button: it cancels without sending replacement input. `"accepted"` means the live thread session durably queued that request; a parked session consumes it as a no-op, and `"no_active_turn"` means the thread has no active session owner.
 
 Message and interaction hooks expose every current-owner operation directly on `ctx`:
 

package/docs/concepts/execution-model-and-durability.mdx

@@ -66,7 +66,7 @@ You don't write workflow code directly. Workflow primitives (`start()`, `resumeH
 
 Some work has to wait, including a human approving a [tool](../tools), an interactive OAuth sign-in for a [connection](../connections), or a long-running [subagent](../subagents). At those points the turn parks durably. The workflow suspends and holds no compute until the input it's waiting on arrives (a click, a callback, a child completing), even if that's much later. When it does, the conversation picks up exactly where it left off.
 
-## Message delivery and queueing
+## Message delivery and steering
 
 eve does not maintain a durable FIFO queue of user messages for a session. An
 ID-addressed HTTP delivery and a channel-address delivery both target the
@@ -79,14 +79,11 @@ channel alias. Rekeying replaces only that channel alias. An HTTP-created
 session has the stable ID alias and no channel continuation token. Competing
 channel input is not forwarded to the owner.
 
-When a session is waiting, a delivery through its ID or current channel address
-wakes the session and starts the next turn. When a turn is already active, the
-inbox may accept additional deliveries, but the runtime only drains them at
-specific workflow boundaries. If more than one delivery is ready when the driver
-checks, eve may fold them into the next turn; that drain is best-effort and
-depends on workflow and transport timing.
+When a session is waiting, a delivery through its ID or current channel address wakes it and starts the next turn. Message sends default to `turnPolicy: "steer"`: while a turn is active, the session driver durably buffers the replacement before requesting cooperative cancellation. The interrupted turn emits `turn.cancelled` followed by `session.waiting`, then the replacement starts with a new turn ID. Partial output and completed side effects are not rolled back.
 
-So don't rely on concurrent sends to the same session behaving like a typical ordered chat queue. For deterministic behavior, send one user turn at a time and wait for `session.waiting` before sending the next message to the same session. If your channel can receive bursts while the agent is working, keep your own per-session queue in the channel or app layer, then deliver the next message after the session parks again. Separate sessions still run independently.
+`turnPolicy: "queue"` preserves the message until the active turn settles. If several deliveries are ready when the driver checks, eve may fold adjacent messages into the next turn while preserving their arrival order. Pure `inputResponses` deliveries do not steer; they remain available to the pending request they address.
+
+Every built-in and custom channel accepts a default `turnPolicy`, and imperative message sends can override it. The policy is part of the same durable delivery command as the message, so concurrent senders cannot separate replacement ownership from cancellation intent. Separate sessions still run independently.
 
 ## Subagents
 

package/docs/concepts/sessions-runs-and-streaming.md

@@ -148,7 +148,7 @@ 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.
+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.
 
 If the session is waiting on a human-in-the-loop approval, a matching text reply such as `approve` or `cancel` answers the approval. Other follow-up text is held until the approval is answered, so an unrelated message does not implicitly deny the pending tool call.
 
@@ -158,7 +158,7 @@ A response is stale when its request is no longer pending: the question or appro
 
 Responses match pending requests by request ID, so a response to an older request stays a plain user message even while a different question or approval is pending. Like any follow-up message, a stale response clears a pending question and is held while an approval is pending.
 
-For deterministic ordering, send one follow-up at a time and wait for the next `session.waiting` event before sending another message to the same session. See [message delivery and queueing](./execution-model-and-durability#message-delivery-and-queueing) for the current runtime contract.
+Multiple replacement messages retain their durable arrival order and may be folded into the same replacement turn when they arrive before cancellation settles. See [message delivery and steering](./execution-model-and-durability#message-delivery-and-steering) for the current runtime contract.
 
 ## Cancel the in-flight turn
 

package/docs/guides/dynamic-capabilities.md

@@ -7,26 +7,26 @@ description: "Resolve models, subagents, tools, skills, and instructions at runt
 
 ## Dynamic models
 
-The `model` field in `agent.ts` accepts `defineDynamic({ fallback, events })`.
-Resolvers run at `session.started`, `turn.started`, or `step.started`
-(precedence: step > turn > session > `fallback`); `null` leaves a scope unset
-and failures degrade to the next scope. Prefer `session.started` — prompt
-caches are per model, so switching mid-session re-ingests the conversation at
-uncached prices. See
+The `model` field in `agent.ts` accepts `defineDynamic({ events })`. Resolvers
+run at `session.started`, `turn.started`, or `step.started` (precedence: step >
+turn > session). Every matching handler must return a concrete model. A
+missing, invalid, or throwing selection fails the turn before model-dependent
+work begins. Prefer `session.started` — prompt caches are per model, so
+switching mid-session re-ingests the conversation at uncached prices. See
 [agent configuration](../agent-config#choose-the-model-dynamically) for the
 full contract.
 
-The agent always needs exactly one model, so the compiled fallback anchors
-build-time metadata. Tools, skills, instructions, and subagents default by
-authoring a static entry (or returning `null`), so `fallback` on their
-`defineDynamic` export is a build error.
+Dynamic models do not compile a default model or model metadata. When a
+resolver first selects a model, eve normalizes the selection and resolves any
+omitted context-window metadata from the AI Gateway catalog. Dynamic tools,
+skills, instructions, and subagents may return `null` to omit a capability.
 
 ## Dynamic subagents
 
 Wrap a declared subagent's own `agent.ts` in `defineDynamic` when its
 availability depends on the caller, tenant, environment, or a feature flag.
-Return the child definition to configure and expose it. Return `null` or
-`undefined` to omit it from the parent's model-visible tools.
+Return the child definition to configure and expose it. Return `null` to omit
+it from the parent's model-visible tools.
 
 ```ts title="agent/subagents/finance/agent.ts"
 import { defineAgent, defineDynamic } from "eve";
@@ -44,15 +44,19 @@ export default defineDynamic({
 });
 ```
 
-eve always compiles the subagent's filesystem manifest, including its
-instructions, tools, skills, connections, sandbox, and nested subagents. When
-the resolver selects it, eve injects the returned agent configuration into that
-compiled manifest. Each resolution can return a different model or other
-runtime agent settings. Runtime-selected models must use string model IDs;
-build and Workflow-world configuration cannot be selected at runtime.
+eve always compiles the subagent's filesystem resources, including its
+instructions, tools, skills, connections, sandbox, and nested subagents. It
+does not compile an agent config or placeholder model for a dynamic subagent.
+When the resolver selects the subagent, eve combines the returned config with
+those resources before starting the child session. Each resolution can return
+a different model or other runtime agent settings. A returned local config
+must use a static model; it cannot contain another `defineDynamic` model.
+Runtime-selected models must use string model IDs. Put build configuration on
+the outer `defineDynamic` definition; build and Workflow-world configuration
+cannot be selected in a handler result.
 
 A single-file remote subagent uses the same lifecycle. Return
-`defineRemoteAgent(...)` to expose the selected deployment, or nil to omit it:
+`defineRemoteAgent(...)` to expose the selected deployment, or `null` to omit it:
 
 ```ts title="agent/subagents/finance.ts"
 import { defineDynamic, defineRemoteAgent } from "eve";
@@ -77,7 +81,7 @@ outbound request without entering durable workflow state.
 
 Dynamic subagents support `session.started` and `turn.started`. A turn selection
 shadows the session selection for that turn, including when the turn handler
-returns nil. If a resolver throws or returns an invalid definition, eve logs the
+returns `null`. If a resolver throws or returns an invalid definition, eve logs the
 failure and omits the subagent.
 
 The resolved set applies to local and remote direct delegation and the

package/docs/installation.mdx

@@ -22,7 +22,13 @@ Run `eve init` with a project name:
 npx eve@latest init my-agent
 ```
 
-The command creates `my-agent/`, installs dependencies, initializes Git, and starts eve's development server. If a supported coding-agent REPL is available, eve offers to open it instead.
+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
 

package/docs/reference/cli.md

@@ -1,6 +1,6 @@
 ---
 title: "CLI"
-description: "Reference for every eve CLI command: init, info, build, start, dev, logs, trace, link, deploy, eval, channels, and extension."
+description: "Reference for every eve CLI command: init, set, info, build, start, dev, logs, trace, link, deploy, eval, channels, and extension."
 ---
 
 The `eve` binary (`bin: eve`) runs from your app root, and every command first loads `.env`/`.env.local` from that root. Running `eve` with no command runs `eve dev`.
@@ -26,6 +26,7 @@ The `eve` binary (`bin: eve`) runs from your app root, and every command first l
 | `eve channels list`           | List user-authored channels                                                                                                                           |
 | `eve extension init [target]` | Create a new extension package                                                                                                                        |
 | `eve extension build`         | Build the current package as an extension                                                                                                             |
+| `eve set`                     | Change the root agent's model and reasoning effort                                                                                                    |
 | `eve add <item>`              | Install an item from the official or a configured shadcn registry                                                                                     |
 | `eve registry <command>`      | Add sources and list, search, or view registry catalog items                                                                                          |
 
@@ -34,7 +35,7 @@ When `eve build` fails on discovery errors, it prints the full diagnostics repor
 ## `eve init`
 
 ```bash
-eve init [target] [--channel-web-nextjs]
+eve init [target] [--model <provider/model-id>] [--reasoning <effort>] [--channel-web-nextjs]
 ```
 
 Creates a new agent app or adds an agent to an existing app. Always installs dependencies. New directories also initialize Git.
@@ -45,11 +46,13 @@ Creates a new agent app or adds an agent to an existing app. Always installs dep
 | `eve init .` (or an existing project dir) | Adds `agent/` plus missing `eve`, `ai`, and `zod` deps. Needs a `package.json` and no `agent/` files yet                                                 |
 | `eve init` with no target                 | Same as `eve init .`, except coding agents (Claude Code, Cursor, and similar) get a setup guide instead of scaffolding — they have not chosen a name yet |
 
-After scaffolding, a human terminal usually continues into `eve dev` (or a coding-agent REPL if one is on `PATH` and you pick it). Coding-agent launches print the next steps instead of opening the TUI, so the session does not get stuck. Fresh projects use the parent workspace's package manager when there is one; otherwise they use the manager that launched `eve init`.
+After scaffolding, a human terminal usually continues into `eve dev`. If a coding-agent REPL is on `PATH`, the handoff menu can open it instead or exit without starting either process. Coding-agent launches print the next steps instead of opening the TUI, so the session does not get stuck. Fresh projects use the parent workspace's package manager when there is one; otherwise they use the manager that launched `eve init`.
 
-| Flag                   | Type | Default | Description                                                                                          |
-| ---------------------- | ---- | ------- | ---------------------------------------------------------------------------------------------------- |
-| `--channel-web-nextjs` | flag | off     | Add the Web Chat app (Next.js). Not for existing projects — run `eve add channel/web` there instead. |
+| Flag                   | Type   | Default                     | Description                                                                                                              |
+| ---------------------- | ------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `--model <model>`      | string | `anthropic/claude-sonnet-5` | Set the root agent's AI Gateway model ID.                                                                                |
+| `--reasoning <effort>` | enum   | provider default            | Set reasoning to `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. `provider-default` leaves the field unauthored. |
+| `--channel-web-nextjs` | flag   | off                         | Add the Web Chat app (Next.js). Not for existing projects — run `eve add channel/web` there instead.                     |
 
 ## `eve extension`
 
@@ -81,6 +84,28 @@ eve extension build
 
 Builds the complete agent-shaped extension tree into its configured dist root, emits declarations and compatibility metadata, and fills the package `exports` map. The original TypeScript source is not required in the published package.
 
+## Set model settings
+
+Change the root agent's AI Gateway model and reasoning effort without opening the dev TUI:
+
+```bash
+eve set \
+  --model openai/gpt-5.6-sol \
+  --reasoning high
+```
+
+Pass either flag by itself to change one setting. When you pass both, eve writes
+them to `agent/agent.ts` in one source edit. `--reasoning` accepts
+`provider-default`, `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`;
+`provider-default` removes the authored `reasoning` field.
+
+The command uses the same model ID validation and source editor as `/model` in
+the local dev TUI. It does not configure model credentials. The `--model` flag
+cannot rewrite models defined with `defineDynamic`, an environment expression,
+or a provider-authored SDK model; change those models in `agent.ts`.
+`--reasoning` can still update an editable root config when its model comes from
+an SDK call.
+
 ## Registry items
 
 Commands for installing and discovering [shadcn registry](https://ui.shadcn.com/docs/registry) items. Official registry items use a kind and slug (for example, `extension/agent-browser`); URLs and configured registry addresses are also supported.
@@ -98,7 +123,7 @@ eve registry view @acme/my-extension
 eve add @acme/my-extension
 ```
 
-`eve add` asks before running setup declared by an official item and runs multiple declared flows in declaration order. Product-level packages can offer independently installable components: `eve add linear` lets you select the Linear Channel, Linear MCP, or both, with both selected by default. `--yes` installs a package's default components and accepts detected or recommended setup answers.
+`eve add` asks before running setup declared by an official item and runs multiple declared flows in declaration order. Product-level packages can offer independently installable components: `eve add linear` lets you select the Linear Channel, Linear MCP, or both, with both selected by default. Interactive Vercel-backed setup signs in and creates or links a project when needed instead of stopping with a prerequisite. `--yes` installs a package's default components and accepts detected or recommended setup answers.
 
 Coding agents should use `eve add <item> --non-interactive`, adding `--yes` to accept recommended setup values and reduce setup round trips. Explicit `--answer` values take precedence. This mode never opens an eve prompt. When a component or setup decision is missing, the NDJSON terminal event includes a stable question key and a safe continuation command; add the requested answer to that command. Supply answers with repeatable `--answer 'key=<JSON value>'` options. Follow a reported `eve link` prerequisite before retrying Vercel Connect setup. Do not put secrets in command-line answers; use the integration's documented environment variable or secret store.
 
@@ -305,7 +330,7 @@ Links the current directory to a Vercel project. After selecting a team, you can
 eve deploy
 ```
 
-Deploys the agent to Vercel production (`vercel deploy --prod`), installing dependencies first and pulling environment variables after. An already-linked project deploys with or without a TTY (non-interactive runs pass the non-interactive `vercel` flags). An unlinked directory walks the `eve link` pickers when a terminal is present, and exits with guidance otherwise.
+Deploys the agent to Vercel production (`vercel deploy --prod`), installing dependencies first and pulling environment variables after. An already-linked project deploys with or without a TTY (non-interactive runs pass the non-interactive `vercel` flags). When a terminal is present, an unlinked deployment signs in to Vercel if needed and then walks the `eve link` pickers; otherwise, it exits with guidance.
 
 ## `eve eval`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "private": false,
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [