docs(spec, docs): App.defaultAgent and actions-as-tools name the agent route as the one chat door

.changeset/21968-spec-default-agent-chat-door.md

@@ -0,0 +1,13 @@
+---
+"@objectstack/spec": patch
+---
+
+`App.defaultAgent` docblock: the agent route is the one chat door, and the console is what reads the key.
+
+Clause-②: no
+
+- The docblock no longer says the assistant chat endpoint (`POST /api/v1/ai/assistant/chat`) resolves this agent from `context.appName`. That route, with `GET /api/v1/ai/assistant` and `GET /api/v1/ai/assistant/skills`, was retired in the cloud AI runtime (objectstack-ai/cloud#2621, objectstack-ai/cloud#2651), and no server route reads `defaultAgent`.
+- It now says who does read it. The console's chat dock hands the active app's `defaultAgent` to its one surface-to-agent resolver, which honours only `ask` or `build` (legacy aliases included) and otherwise falls back to the surface default. The resolved agent is then called by name on `POST /api/v1/ai/agents/:agentName/chat`, where the path segment, not this key, selects the agent.
+- The ADR-0063 surface-binding paragraph and the rule that only the two platform agents resolve are unchanged, as is the note that the bare `POST /api/v1/ai/chat` resolves no agent.
+- The docs page `ai/actions-as-tools` lists the agent route as the only in-product chat route.
+- ⛔ No schema, parse, `.describe()`, export, type or accept-set change. The docblock ships in the published package, in the `dist/ui` and `dist/browser` JavaScript bundles and in the shipped `src/ui/app.zod.ts`, which is why this is a patch.

content/docs/ai/actions-as-tools.mdx

@@ -271,10 +271,9 @@ action into AI only when its logic is safe to run on behalf of anyone the
 capability gate admits.
 
 <Callout type="info">
-**ObjectOS** — the in-product chat routes
-(`/api/v1/ai/assistant/chat`, `/api/v1/ai/agents/:agentName/chat`) resolve the
-authenticated principal from `req.user` — both cookie session
-(`better-auth.session_token`) and Bearer token are handled — and forward it to
+**ObjectOS** — the in-product chat route, `/api/v1/ai/agents/:agentName/chat`,
+resolves the authenticated principal from `req.user` — both cookie session
+(`better-auth.session_token`) and Bearer token are handled — and forwards it to
 `aiService.chatWithTools(...)` as
 `toolExecutionContext: { actor, conversationId, environmentId }`. That threads the
 same RLS context through the runtime's built-in data tools and its

packages/spec/src/ui/app.zod.ts

@@ -1655,15 +1655,18 @@ export const AppSchema = lazySchema(() => strictObject(
   /**
    * Default agent for this app's ambient chat surface.
    *
-   * When set, the assistant chat endpoint (`POST /api/v1/ai/assistant/chat`)
-   * resolves this agent for a call carrying `context.appName`, without the
-   * user having to pick from a list — that route is what drives the
-   * resolution chain (explicit agent > `defaultAgent` of the named app >
-   * first active agent).
+   * The console's agent surfaces read this key; no server route does. The
+   * chat dock hands the active app's `defaultAgent` to the console's one
+   * surface→agent resolver (objectui `surfaceAgent.ts`, called from
+   * `ChatDock.tsx`), which honours it only when it names `ask` or `build`
+   * (legacy aliases included) and otherwise falls back to the surface
+   * default. The agent it resolves is then called by name on the agent route,
+   * `POST /api/v1/ai/agents/:agentName/chat` — the one chat door, where the
+   * `:agentName` path segment, not this key, selects the agent.
    *
-   * The bare `POST /api/v1/ai/chat` route is NOT part of that chain: it
-   * resolves no agent and never reads `context.appName`, so this key does not
-   * scope it. Do not read this key as a guarantee over that endpoint.
+   * The bare `POST /api/v1/ai/chat` route resolves no agent at all, so this
+   * key does not scope it either. Do not read this key as a guarantee over
+   * any endpoint.
    *
    * ADR-0063 §1/§2 — this is a SURFACE-BINDING knob, not a custom-agent
    * slot: the resolvable values are the two platform agents (`ask` for a