docs: align AI guides + ADR-0040 with the ask/build two-agent model (ADR-0063/0064) (#2206)

Follow-up to #2194 — sweeps the remaining docs-site + ADR prose that still
described the superseded ADR-0040 unified-assistant / custom-agent model:

- guides/ai-capabilities.mdx: reframe the "AI Agents" section to the two
  surface-bound platform agents (`ask` OSS/free, `build` cloud/paid). State
  ADR-0063 §2 (you extend via skills, not agents — `*.agent.ts` is
  platform-internal, `allowRuntimeCreate:false`) and ADR-0064 (tools = union
  of surface-compatible skills' tools; `surface:'build'` inert on OSS). Add
  the `surface` field to the AgentSchema table; recontextualize the example
  `defineAgent()` blocks as anatomy, not a tenant-authoring tutorial.
- guides/plugin-chatbot-integration.mdx: code examples use `ask`, not the
  legacy `data_chat` alias.
- adr/0040: add a Superseded-by-ADR-0063 banner + Status line (body kept as
  the historical record).

Generated schema refs (references/ai/agent.mdx, skill.mdx) already carry the
`surface` field — build-docs.ts reruns with no diff. Docs-only.

Refs #2168

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: 3 people

content/docs/guides/ai-capabilities.mdx

@@ -42,27 +42,52 @@ ObjectStack provides a comprehensive AI platform:
 
 ## AI Agents
 
-AI agents are autonomous actors that perform tasks on behalf of users.
-
-### How agents are shaped
-
-An agent is plain metadata validated by `AgentSchema` and created with the
-`defineAgent()` factory. The key fields are:
+Per [ADR-0063](https://github.com/objectstack-ai/framework/blob/main/docs/adr/0063-two-kernel-agents-skills-are-the-extension-primitive.md)
+the kernel ships **exactly two** platform agents, bound by the *surface* the user
+is in — the user never picks from a roster:
+
+| Agent | Surface | Does | Edition |
+|---|---|---|---|
+| **`ask`** | data console | Read / query / explore records + run the business **actions** the app exposes. RLS-bounded. | open-source · free |
+| **`build`** | Studio | Author *metadata* (objects, fields, views, flows) via plan → draft → verify → publish. | cloud · paid |
+
+There is no per-turn intent classifier and no agent dropdown: the surface binds
+the agent (data console → `ask`, Studio → `build`). A `build`-shaped request that
+reaches `ask` is declined and redirected to the Builder, never silently re-routed.
+
+### You extend the platform with **skills**, not agents
+
+`*.agent.ts` is **closed to third parties** — the `agent` metadata type is
+`allowRuntimeCreate:false, allowOrgOverride:false`, reserved for the two platform
+agents and platform-owned subagents (ADR-0063 §2). To give the `ask` agent a new
+capability you author a **skill** (`*.skill.ts`) whose `tools` reference your
+Actions / Flows / queries; it then attaches to `ask`. Every skill declares
+`surface: 'ask' | 'build' | 'both'`, and an agent's tool set is the **union of its
+surface-compatible skills' tools** — there is no global fall-through, so a skill
+reaches an agent only when their surfaces match
+([ADR-0064](https://github.com/objectstack-ai/framework/blob/main/docs/adr/0064-tool-scoping-to-agent.md)).
+`surface:'build'` skills are inert on the open-source framework (the `build` agent
+is cloud-only) — intentional tiering, not a bug.
+
+### The shape of an agent
+
+An agent is metadata validated by `AgentSchema` (the platform's own `ask` / `build`
+records use exactly these fields):
 
 | Field | Meaning |
 |------|---------|
+| `surface` | `'ask'` \| `'build'` — the product surface this agent binds (ADR-0063 §1) |
 | `role` | Free-text **persona** string (e.g. `"Senior Support Engineer"`) — not an enum |
 | `instructions` | System prompt / prime directives |
 | `model` | Provider + model config (`provider`: `openai` \| `azure_openai` \| `anthropic` \| `local`) |
 | `skills` | Skill names to attach (the primary Agent → Skill → Tool capability model) |
 | `tools` | Direct tool **references** `{ type, name, description }` — `type` is `action` \| `flow` \| `query` \| `vector_search`; `name` points at an existing Action/Flow/query |
 | `knowledge` | RAG access: `{ topics: string[], indexes: string[] }` |
 
-There is no `type` field and no fixed agent "type" taxonomy — the way an agent
-behaves comes from its persona, instructions, skills, and tools. Likewise there
-are no `triggers` or `schedule` fields on an agent; drive agents from
-[Flows/Workflows](./automation) or invoke them via the chat endpoint when you
-need event- or time-based behaviour.
+There is no `type` field and no fixed agent "type" taxonomy — behaviour comes from
+persona, instructions, skills, and tools. There are no `triggers` / `schedule`
+fields on an agent; drive agents from [Flows/Workflows](./automation) or invoke
+them via the chat endpoint.
 
 <Callout type="info">
 Agent tools are **references** to existing Actions, Flows, or queries — you do
@@ -71,6 +96,15 @@ not define ad-hoc tool names with inline parameter schemas here. See
 LLM-callable.
 </Callout>
 
+<Callout type="warning">
+The agent definitions below illustrate agent **anatomy** — they show how an
+`AgentSchema` record is shaped, *not* a tenant-authoring tutorial. On today's
+platform you do not ship your own agents (`*.agent.ts` is platform-internal); you
+add capability by authoring a **skill** that attaches to the built-in `ask` agent.
+Read the examples for structure, then express your own capability as a skill plus
+the Actions/Flows its tools reference.
+</Callout>
+
 ### Sales Assistant Agent
 
 ```typescript

content/docs/guides/plugin-chatbot-integration.mdx

@@ -35,7 +35,7 @@ verified in step 3):
 
 ```bash
 curl http://localhost:3000/api/v1/ai/agents
-# → { "agents": [{ "name": "data_chat", ... }, ...] }
+# → { "agents": [{ "name": "ask", ... }, ...] }
 
 curl http://localhost:3000/api/v1/ai/models
 # → { "models": [...] }   ← may be empty until the adapter lists models
@@ -82,7 +82,7 @@ import { useObjectChat } from '@object-ui/plugin-chatbot';
 const chat = useObjectChat({
   api: 'http://localhost:3000/api/v1/ai/assistant/chat',
   headers: { 'X-Environment-Id': 'env_local' },
-  body: { agent: 'data_chat' },
+  body: { agent: 'ask' },
 });
 ```
 

docs/adr/0040-unified-assistant-and-agent-binding.md

@@ -1,6 +1,8 @@
 # ADR-0040: Unified Assistant — the end user never picks an agent
 
-**Status**: Proposed (2026-06-11)
+> **⚠️ Superseded by [ADR-0063](./0063-two-kernel-agents-skills-are-the-extension-primitive.md)** (2026-06-22). Its core decision — a *single* unified assistant carrying all skills, switched by a per-turn intent classifier — was **reversed**: the kernel now ships two agents (`ask` / `build`) bound by *surface*, and `*.agent.ts` is closed to third parties (skills are the extension primitive). The UX win it established (the user never picks from a roster) is kept, re-grounded as surface binding. Kept below as a historical record of the decision and the incident that motivated it.
+
+**Status**: **Superseded by [ADR-0063](./0063-two-kernel-agents-skills-are-the-extension-primitive.md)** — original: Proposed (2026-06-11)
 **Deciders**: ObjectStack Protocol Architects
 **Builds on**: [ADR-0033](./0033-ai-assisted-metadata-authoring.md) (draft-gated authoring tools the assistant drives), [ADR-0038](./0038-build-verification-loop.md) (the verify-fix-reverify discipline carried by skills), ADR-0037 / [framework#1694](https://github.com/objectstack-ai/framework/pull/1694) (Live Canvas — the surface the unified assistant builds into)
 **Consumers**: `@objectstack/spec` (agent/skill types — clarified, not changed), `@objectstack/service-ai` (default agent composition), `../cloud/service-ai-studio` (authoring skills attach to the platform assistant), `../objectui` (chat surfaces drop the agent picker)