diff --git a/content/docs/guides/ai-capabilities.mdx b/content/docs/guides/ai-capabilities.mdx
index dbef98d2b5..4a5355f3c9 100644
--- a/content/docs/guides/ai-capabilities.mdx
+++ b/content/docs/guides/ai-capabilities.mdx
@@ -42,15 +42,41 @@ 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`) |
@@ -58,11 +84,10 @@ An agent is plain metadata validated by `AgentSchema` and created with the
| `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.
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.
+
+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.
+
+
### Sales Assistant Agent
```typescript
diff --git a/content/docs/guides/plugin-chatbot-integration.mdx b/content/docs/guides/plugin-chatbot-integration.mdx
index b6658e03d4..ece7220273 100644
--- a/content/docs/guides/plugin-chatbot-integration.mdx
+++ b/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' },
});
```
diff --git a/docs/adr/0040-unified-assistant-and-agent-binding.md b/docs/adr/0040-unified-assistant-and-agent-binding.md
index 1c4ef3fc8b..44795ba486 100644
--- a/docs/adr/0040-unified-assistant-and-agent-binding.md
+++ b/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)