objectstack-ai · os-zhuang · Jul 5, 2026 · Jul 5, 2026
diff --git a/content/docs/ai/actions-as-tools.mdx b/content/docs/ai/actions-as-tools.mdx
diff --git a/content/docs/ai/agents.mdx b/content/docs/ai/agents.mdx
@@ -5,26 +5,39 @@ description: The two platform agents (ask and build), how skills extend them, an
 
 # AI Agents
 
-Part of the [AI module](/docs/ai) — see the overview for how the cloud / Enterprise in-UI AI runtime differs from the open edition's MCP-only (BYO-AI) approach.
+Part of the [AI module](/docs/ai). In the **open edition**, agents, tools, and
+skills are **typed metadata**: you author them as source with `defineAgent` /
+`defineSkill` / `defineTool` from the open `@objectstack/spec/ai` package, and an
+external AI client (Claude, Cursor, a local model — any MCP client) reaches your
+objects, queries, and business **Actions** through `@objectstack/mcp` (BYO-AI),
+all governed by RLS. This page describes that metadata and the `AgentSchema` it
+validates against.
+
+<Callout type="info">
+**Cloud / Enterprise — the in-product chat runtime.** The authoring format on
+this page is open. The *in-product chat runtime* that runs agents for end users —
+the two platform agents `ask` and `build`, all in-product chat, and the
+`/api/v1/ai/*` chat endpoints — ships only in the cloud / Enterprise distribution
+(`@objectstack/service-ai`, cloud ADR-0025). The open edition uses
+`@objectstack/mcp` (BYO-AI) instead. The next two sections describe that cloud /
+Enterprise runtime.
+</Callout>
 
 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:
+the cloud / Enterprise runtime 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. | cloud · Enterprise |
 | **`build`** | Studio | Author *metadata* (objects, fields, views, flows) via plan → draft → verify → publish. | cloud · Enterprise |
 
-Both agents are part of the **cloud / Enterprise** in-UI AI runtime (cloud ADR-0025).
-The **open edition** ships neither — it uses `@objectstack/mcp` (BYO-AI) for data
-query and source-mode authoring instead (see the callout in the
-[AI Overview](/docs/ai)).
-
-Within the cloud / EE runtime 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.
+Within this cloud / Enterprise runtime 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. (For data query and source-mode authoring,
+the **open edition** ships neither agent and uses `@objectstack/mcp` (BYO-AI)
+instead — see the callout in the [AI Overview](/docs/ai).)
 
 ## You extend the platform with **skills**, not agents
 
@@ -44,8 +57,9 @@ as Actions / Flows and reach it through `@objectstack/mcp` instead.
 
 ## The shape of an agent
 
-An agent is metadata validated by `AgentSchema` (the platform's own `ask` / `build`
-records use exactly these fields):
+An agent is typed metadata validated by `AgentSchema` — exported, together with the
+`defineAgent` factory, from the open `@objectstack/spec/ai` package (the platform's
+own `ask` / `build` records use exactly these fields):
 
 | Field | Meaning |
 |------|---------|
@@ -59,8 +73,10 @@ records use exactly these fields):
 
 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](/docs/automation) or invoke
-them via the chat endpoint.
+fields on an agent; drive agents from [Flows/Workflows](/docs/automation), or — on
+the **cloud / Enterprise** runtime — via the in-product chat endpoint
+(`/api/v1/ai/*`). In the open edition, invoke the underlying Actions/Flows through
+`@objectstack/mcp`.
 
 <Callout type="info">
 Agent tools are **references** to existing Actions, Flows, or queries — you do
@@ -70,12 +86,15 @@ 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.
+The agent definitions below illustrate agent **anatomy** — how an `AgentSchema`
+record is shaped (that schema and the `defineAgent` factory are part of the open
+`@objectstack/spec/ai` package). Note that the `agent` metadata type is
+`allowRuntimeCreate:false` / `allowOrgOverride:false` (ADR-0063 §2): the **cloud /
+Enterprise** in-product runtime honors only the two platform agents `ask` and
+`build`, so you do not ship a custom agent *to that runtime* — you extend it by
+authoring a **skill** (open metadata) that attaches to `ask`. In the open edition,
+express the same capability as Actions / Flows plus the skills/tools its references
+point at, and reach it through `@objectstack/mcp` (BYO-AI).
 </Callout>
 
 ## Sales Assistant Agent

diff --git a/content/docs/ai/chatbot-integration.mdx b/content/docs/ai/chatbot-integration.mdx
diff --git a/content/docs/ai/index.mdx b/content/docs/ai/index.mdx
@@ -7,17 +7,14 @@ description: Complete guide to leveraging AI agents, RAG pipelines, and intellig
 
 AI in ObjectStack is a **cross-protocol capability layer**: agents, tools, and knowledge retrieval sit on top of the same objects, actions, permissions, and automation that power the rest of the platform. This module covers the architecture and each of its moving parts.
 
-<Callout type="warning">
-**This guide describes the cloud / Enterprise AI tier. The open edition exposes AI only via MCP (BYO-AI).**
+<Callout type="info">
+**The open framework does AI bring-your-own-AI** — your keys, your models, zero platform AI cost. Everything on this page is part of the open edition unless a section is explicitly marked **cloud / Enterprise**:
 
-Per **cloud ADR-0025** (`service-ai → cloud; open = MCP-only` — [`cloud/docs/adr/0025`](https://github.com/objectstack-ai/cloud/blob/main/docs/adr/0025-service-ai-to-cloud-open-mcp-only.md)), the in-UI AI runtime — `@objectstack/service-ai`: both the **`ask`** data-query assistant and the **`build`** Studio authoring assistant, plus all in-product chat — ships in the **cloud / Enterprise** distribution. It is **not** in the open framework, and no open distribution (cloud free tier, Docker, desktop, on-prem) has a built-in `ask` / `build` chat.
+- **Data & actions → `@objectstack/mcp`** (BYO-AI). Point your own AI — Claude, Cursor, any MCP client, or a local model — at the app's objects, queries, and business **actions**, governed by the same RLS. With a local model, data *and* inference stay inside your boundary.
+- **Knowledge & RAG → the Knowledge Protocol + adapter plugins** (`knowledge-memory`, `knowledge-ragflow`, `embedder-openai`) — permission-aware retrieval over your own objects.
+- **Agents, tools, skills → typed metadata** (`defineAgent` / `defineTool` / `defineSkill`) plus the Model Registry. Author them as source (`*.agent.ts`, `*.tool.ts`, …) with your own AI coding agent (Claude Code, Cursor), aided by the ObjectStack [skills](/docs/ai/skills-reference) and MCP introspection.
 
-The **open edition** does AI two ways instead — both bring-your-own-AI, zero platform AI cost:
-
-- **Data query → `@objectstack/mcp`** (BYO-AI). Point your own AI — Claude, Cursor, any MCP client, or a local model — at the app's objects, queries, and business **actions**, governed by the same RLS. With a local model, data *and* inference stay inside your boundary.
-- **Metadata authoring → source mode.** Author typed metadata as source (`*.object.ts`, `*.flow.ts`, …) with your own AI coding agent (Claude Code, Cursor), aided by the ObjectStack [skills](/docs/ai/skills-reference) and MCP introspection. There is no in-product Builder chat in the open edition.
-
-Everything below (agents, the `ask` / `build` personas, `@objectstack/service-ai` wiring, the `/api/v1/ai/*` routes) therefore describes the **cloud / Enterprise** distribution.
+The **cloud / Enterprise** tier adds an in-product chat *runtime* on top of these same primitives — the `ask` data-query assistant, the `build` Studio authoring assistant, and the `/api/v1/ai/*` chat endpoints (`@objectstack/service-ai`, cloud [ADR-0025](https://github.com/objectstack-ai/cloud/blob/main/docs/adr/0025-service-ai-to-cloud-open-mcp-only.md)). The open edition has no built-in in-product chat.
 </Callout>
 
 ## What's in this module
@@ -28,7 +25,6 @@ Everything below (agents, the `ask` / `build` personas, `@objectstack/service-ai
 - [Natural Language Queries](/docs/ai/natural-language-queries) — the built-in data tools that turn questions into ObjectQL
 - [AI Skills System](/docs/ai/skills) — structured knowledge modules for AI coding assistants
 - [AI Skills Reference](/docs/ai/skills-reference) — the per-skill catalog
-- [Chatbot Integration](/docs/ai/chatbot-integration) — wiring `plugin-chatbot` to the framework AI backend
 - Spec: [Knowledge Protocol](/docs/protocol/knowledge)
 - Schema reference: [AI](/docs/references/ai)
 
@@ -138,10 +134,19 @@ ObjectStack provides a comprehensive AI platform:
 ### Complete Sales AI Workflow
 
 Agents are metadata, not classes — there are no `.enrich()` / `.predict()` /
-`.query()` methods to call. You invoke an agent over HTTP (the REST chat
-endpoint) or, server-side, via `aiService.chatWithTools(...)`. Enrichment,
-scoring, and email drafting are implemented as **Actions/Flows exposed as
-tools**, and the LLM calls them while reasoning over the conversation.
+`.query()` methods to call. Enrichment, scoring, and email drafting are
+implemented as **Actions/Flows exposed as tools**, and the LLM calls them while
+reasoning over the conversation. In the **open edition**, your own AI reaches
+those same tools over MCP (`@objectstack/mcp`), and you drive them on a trigger
+or schedule from a [Flow or Workflow](/docs/automation).
+
+<Callout type="info">
+**Cloud / Enterprise runtime.** The in-product chat invocation shown below — the
+REST chat endpoint (`/api/v1/ai/agents/:agentName/chat`) and the server-side
+`aiService.chatWithTools(...)` — is the `@objectstack/service-ai` chat runtime,
+which ships in the **cloud / Enterprise** tier. The agent, tool, and skill
+*metadata* it consumes is open; only this in-product chat runtime is not.
+</Callout>
 
 ```typescript
 // Invoke an agent over the REST chat endpoint.