docs: align AI docs with open=MCP-only / in-UI AI=cloud (cloud ADR-0025) (#2337)

os-zhuang · claude · web-flow · commit 44bb97133065 · 2026-06-26T13:32:10.000+08:00
Propagate framework #2325 (service-ai removed from the open framework) across the remaining docs. Canonical decision: cloud ADR-0025 (service-ai -> cloud; open = MCP-only). Disambiguates the cross-repo "ADR-0025" reference, since framework ADR-0025 is plugin-distribution and unrelated. New model documented everywhere: - Open edition (cloud free tier / Docker / desktop / on-prem): no in-product ask/build chat. Data query via @objectstack/mcp (BYO-AI); metadata authoring via source mode + an AI coding agent. - Cloud / Enterprise: in-UI AI runtime (ask + build + in-product chat + /api/v1/ai/*), governed ask, managed/metered AI. User-facing: ai-capabilities (ask edition open->cloud, fixed the ambiguous ADR-0025 ref, added the open-edition two-path callout), plugin-chatbot-integration, environment-variables, knowledge, implementation-status, README (AI bullet -> MCP; drop the dead service-ai Services row), both objectstack-* skills. ADRs: cloud-owned banners on 0033/0038/0040/0063/0064 per cloud ADR-0025 (banners only; ADR bodies preserved as historical record). Left as historical/unaffected: docs/audits/2026-06-*, RELEASE_NOTES.md, ARCHITECTURE.md (spec/ai schemas stay open), apps/docs/app/llms* (generated route handlers), other ADRs' incidental service-ai mentions. Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
diff --git a/README.md b/README.md
@@ -84,7 +84,7 @@ Prefer clicking? Author the same metadata visually in **Studio** — objects, re
 - **AI-native, not retrofitted** — Objects, permissions, flows, APIs, and UI are declarative typed metadata, small enough for an agent to load end-to-end. That metadata generates an automatic tool surface — REST APIs, client SDKs, UI views, and an [MCP](packages/mcp) server — so agents inspect and act through the same contracts you defined.
 - **Protocol-first runtime** — Every definition starts as a Zod schema (`z.infer<>` types), compiles into versioned, self-describing JSON artifacts, and runs on a microkernel plugin system (DI container, EventBus, `init → start → destroy` lifecycle).
 - **Data & framework reach** — In-memory, PostgreSQL, MySQL, SQLite, and MongoDB drivers; 7 framework adapters (Express, Fastify, Hono, NestJS, Next.js, Nuxt, SvelteKit); a client SDK with React hooks (`useQuery` / `useMutation` / `usePagination`).
-- **Governance & built-ins** — better-auth, RBAC / RLS / FLS, a DAG-based automation engine, an AI service (Agent / Tool / Skill on the Vercel AI SDK), the ObjectUI Console, and a full CLI (`os init` / `dev` / `compile` / `validate` / …).
+- **Governance & built-ins** — better-auth, RBAC / RLS / FLS, a DAG-based automation engine, an [MCP](packages/mcp) server that exposes the app to your own AI (BYO-AI), the ObjectUI Console, and a full CLI (`os init` / `dev` / `compile` / `validate` / …).
 
 ## Why AI-native?
 
@@ -252,7 +252,6 @@ For the browser, the typed client SDK and React hooks (`useQuery` / `useMutation
 
 | Package | Description |
 | :--- | :--- |
-| [`@objectstack/service-ai`](packages/services/service-ai) | AI service — Agent, Tool, Skill, Vercel AI SDK integration |
 | [`@objectstack/service-analytics`](packages/services/service-analytics) | Analytics — aggregations, time series, funnels, dashboards |
 | [`@objectstack/service-automation`](packages/services/service-automation) | Automation engine — flows, triggers, and workflow state machines |
 | [`@objectstack/service-cache`](packages/services/service-cache) | Cache — in-memory, Redis, multi-tier |
diff --git a/content/docs/concepts/implementation-status.mdx b/content/docs/concepts/implementation-status.mdx
@@ -294,6 +294,15 @@ The `auth` service in `CoreServiceName` covers both **authentication** (identity
 
 ## AI Layer
 
+<Callout type="warning">
+The in-UI AI **runtime** below (`@objectstack/service-ai`) moved to the **cloud /
+Enterprise** distribution — see cloud ADR-0025 (`service-ai → cloud; open =
+MCP-only`). The agent / skill / tool **schemas** stay open in `@objectstack/spec/ai`;
+the **open edition** exposes AI via [`@objectstack/mcp`](../guides/ai-capabilities)
+(BYO-AI). The Implementation / Status columns describe the runtime as it ships in
+cloud / EE.
+</Callout>
+
 | Protocol | @objectstack/spec | Implementation | Status |
 |:---------|:-----------------:|:-------------:|:------:|
 | **Agent** | ✅ | @objectstack/service-ai | ✅ Agent runtime (`agent-runtime.ts`, `agents/`) |
diff --git a/content/docs/guides/ai-capabilities.mdx b/content/docs/guides/ai-capabilities.mdx
@@ -7,7 +7,18 @@ description: "Complete guide to leveraging AI agents, RAG pipelines, and intelli
 
 Complete guide to leveraging AI agents, knowledge retrieval, and intelligent automation in ObjectStack.
 
-> **Note — the open edition exposes AI via MCP (BYO-AI).** Per ADR-0025, the in-UI AI runtime (`@objectstack/service-ai`: agents, the `ask`/`build` assistants, in-product chat) ships in the **cloud / Enterprise** distribution, not the open framework. A self-hosted **open** runtime instead exposes its objects, queries, and business actions to *your own* AI — Claude, Cursor, any MCP client, or a local model — through **`@objectstack/mcp`** (bring-your-own-AI, zero platform AI cost). The `@objectstack/service-ai` examples below therefore describe the cloud/EE distribution.
+<Callout type="warning">
+**This guide describes the cloud / Enterprise AI tier. The open edition exposes AI only via MCP (BYO-AI).**
+
+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.
+
+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](./skills) 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.
+</Callout>
 
 ## Table of Contents
 
@@ -50,12 +61,17 @@ 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 |
+| **`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 note above).
 
-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 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.
 
 ### You extend the platform with **skills**, not agents
 
@@ -68,8 +84,10 @@ Actions / Flows / queries; it then attaches to `ask`. Every skill declares
 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.
+Both `surface:'ask'` and `surface:'build'` skills run only where the in-UI AI
+runtime exists — the **cloud / Enterprise** distribution. On the open framework
+there is no in-product agent to attach them to (cloud ADR-0025); author capability
+as Actions / Flows and reach it through `@objectstack/mcp` instead.
 
 ### The shape of an agent
 
diff --git a/content/docs/guides/environment-variables.mdx b/content/docs/guides/environment-variables.mdx
@@ -125,6 +125,15 @@ Auth settings precedence:
 
 ## AI
 
+<Callout type="warning">
+These variables configure the **cloud / Enterprise** in-UI AI runtime
+(`@objectstack/service-ai`), which moved out of the open framework — see cloud
+ADR-0025 (`service-ai → cloud; open = MCP-only`). The **open edition** has no
+in-UI AI runtime to configure: it exposes AI through `@objectstack/mcp` (BYO-AI),
+where the model and provider are configured in your own MCP client (Claude,
+Cursor, a local model, …). See the [AI Capabilities guide](./ai-capabilities).
+</Callout>
+
 | Variable | Type | Default | Description |
 |:---|:---|:---|:---|
 | `AI_GATEWAY_MODEL` | string | — | Vercel AI Gateway model id (for example `openai/gpt-4.1-mini` or `anthropic/claude-sonnet-4-5`). When set, the AI service boots with the gateway adapter before trying direct providers. |
diff --git a/content/docs/guides/plugin-chatbot-integration.mdx b/content/docs/guides/plugin-chatbot-integration.mdx
@@ -5,6 +5,17 @@ description: Wire @object-ui/plugin-chatbot in Console (or any frontend) to the
 
 # Connecting plugin-chatbot to a framework AI backend
 
+<Callout type="warning">
+**Cloud / Enterprise tier.** The in-UI AI backend this guide wires up — the
+`/api/v1/ai/*` routes, the `ask` / `build` assistants, the models picker, and the
+HITL inbox (`@objectstack/service-ai`) — ships in the **cloud / Enterprise**
+distribution, not the open framework (cloud ADR-0025: `service-ai → cloud; open =
+MCP-only`). On the **open edition** there is no in-product chat backend; expose
+the app to your own AI through `@objectstack/mcp` (BYO-AI) instead — see the
+[AI Capabilities guide](./ai-capabilities). Follow this guide when you run against
+a cloud / EE host (or a dev server with the AI tier mounted).
+</Callout>
+
 `@object-ui/plugin-chatbot` (a React component shipped from the `objectui`
 monorepo) is the canonical chat UI for ObjectStack Console. It speaks the
 Vercel AI Data Stream protocol, so it pairs natively with the AI routes
diff --git a/content/docs/protocol/knowledge.mdx b/content/docs/protocol/knowledge.mdx
@@ -17,6 +17,15 @@ service that orchestrates them — and ships individual adapters as
 `IDataEngine` / driver plugins (`driver-sql`, `driver-turso`,
 `driver-memory`) and `IStorageService` / S3 + local FS adapters.
 
+<Callout type="info">
+The Knowledge Protocol contract and the `service-knowledge` orchestrator are open
+framework mechanisms. The AI **consumer** that wires the `search_knowledge` tool
+into an in-product chat loop (`@objectstack/service-ai`, shown below) ships in the
+**cloud / Enterprise** distribution — see cloud ADR-0025 (`service-ai → cloud;
+open = MCP-only`). On the open edition, reach your data through `@objectstack/mcp`
+(BYO-AI) instead.
+</Callout>
+
 This document describes the **why**, the **contract**, the **plugin
 model**, and the **MVP scope** that ships in Phase 1.
 
diff --git a/docs/adr/0033-ai-assisted-metadata-authoring.md b/docs/adr/0033-ai-assisted-metadata-authoring.md
@@ -1,5 +1,7 @@
 # ADR-0033: AI-assisted metadata authoring — one agent brain, draft-gated review, type-agnostic apply, open-core boundary
 
+> **🔶 Cloud-owned — superseded in part by cloud ADR-0025 (2026-06-25).** The in-UI AI runtime and the `ask` / `build` agents described here moved to the **cloud / Enterprise** distribution (`@objectstack/service-ai` → `cloud/packages/service-ai`, closed); the open framework exposes AI only via `@objectstack/mcp` (BYO-AI) and ships no in-product `ask` / `build` chat. Retained as historical design context, now **cloud-owned** — see [`cloud/docs/adr/0025-service-ai-to-cloud-open-mcp-only`](https://github.com/objectstack-ai/cloud/blob/main/docs/adr/0025-service-ai-to-cloud-open-mcp-only.md).
+
 **Status**: Accepted (2026-06-02)
 **Deciders**: ObjectStack Protocol Architects
 **Builds on**: [ADR-0005](./0005-metadata-customization-overlay.md) (one Zod source per type + org overlay), [ADR-0010 (protection)](./0010-metadata-protection-model.md) (L1/L2/L3 protection), [ADR-0010 (NL→flow)](./0010-nl-to-flow-authoring.md) + [ADR-0011](./0011-actions-as-ai-tools.md) (AI authoring of metadata / actions-as-tools — **the design center**), [ADR-0019](./0019-approval-as-flow-node.md) (approvals as a flow node), [ADR-0027](./0027-metadata-authoring-lifecycle.md) (**staged authoring · draft · publish · promote** — *this ADR routes every AI write through its draft workspace*), [ADR-0032](./0032-unified-expression-layer.md) (validate-by-default, AI-authored expressions)
diff --git a/docs/adr/0038-build-verification-loop.md b/docs/adr/0038-build-verification-loop.md
@@ -1,5 +1,7 @@
 # ADR-0038: Build Verification Loop — the agent builds, verifies, and corrects itself
 
+> **🔶 Cloud-owned — superseded in part by cloud ADR-0025 (2026-06-25).** The in-UI AI runtime and the `ask` / `build` agents described here moved to the **cloud / Enterprise** distribution (`@objectstack/service-ai` → `cloud/packages/service-ai`, closed); the open framework exposes AI only via `@objectstack/mcp` (BYO-AI) and ships no in-product `ask` / `build` chat. Retained as historical design context, now **cloud-owned** — see [`cloud/docs/adr/0025-service-ai-to-cloud-open-mcp-only`](https://github.com/objectstack-ai/cloud/blob/main/docs/adr/0025-service-ai-to-cloud-open-mcp-only.md).
+
 **Status**: Proposed (2026-06-11)
 **Deciders**: ObjectStack Protocol Architects
 **Builds on**: [ADR-0033](./0033-ai-assisted-metadata-authoring.md) (drafts as the staging layer — this ADR **replaces its human-approval assumption for AI builds** with a machine gate; HITL stays for destructive actions), [ADR-0021](./0021-analytics-dataset-semantic-layer.md) (datasets — what most verification probes exercise), ADR-0037 / [framework#1694](https://github.com/objectstack-ai/framework/pull/1694) (Live Canvas — the *human-visibility* complement to this ADR's *machine-verification*)
diff --git a/docs/adr/0040-unified-assistant-and-agent-binding.md b/docs/adr/0040-unified-assistant-and-agent-binding.md
@@ -1,5 +1,7 @@
 # ADR-0040: Unified Assistant — the end user never picks an agent
 
+> **🔶 Cloud-owned — superseded in part by cloud ADR-0025 (2026-06-25).** The in-UI AI runtime and the `ask` / `build` agents described here moved to the **cloud / Enterprise** distribution (`@objectstack/service-ai` → `cloud/packages/service-ai`, closed); the open framework exposes AI only via `@objectstack/mcp` (BYO-AI) and ships no in-product `ask` / `build` chat. Retained as historical design context, now **cloud-owned** — see [`cloud/docs/adr/0025-service-ai-to-cloud-open-mcp-only`](https://github.com/objectstack-ai/cloud/blob/main/docs/adr/0025-service-ai-to-cloud-open-mcp-only.md).
+
 > **⚠️ 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)
diff --git a/docs/adr/0063-two-kernel-agents-skills-are-the-extension-primitive.md b/docs/adr/0063-two-kernel-agents-skills-are-the-extension-primitive.md
@@ -1,5 +1,7 @@
 # ADR-0063: Two agents (`ask` / `build`), bound by surface; skills are the only third-party extension primitive
 
+> **🔶 Cloud-owned — superseded in part by cloud ADR-0025 (2026-06-25).** The in-UI AI runtime and the `ask` / `build` agents described here moved to the **cloud / Enterprise** distribution (`@objectstack/service-ai` → `cloud/packages/service-ai`, closed); the open framework exposes AI only via `@objectstack/mcp` (BYO-AI) and ships no in-product `ask` / `build` chat. Retained as historical design context, now **cloud-owned** — see [`cloud/docs/adr/0025-service-ai-to-cloud-open-mcp-only`](https://github.com/objectstack-ai/cloud/blob/main/docs/adr/0025-service-ai-to-cloud-open-mcp-only.md).
+
 **Status**: Proposed (2026-06-22)
 **Deciders**: ObjectStack Protocol Architects
 **Supersedes**: [ADR-0040](./0040-unified-assistant-and-agent-binding.md) — its core decision (a *single* unified assistant selected by *per-turn intent classification*) is **reversed**. ADR-0040's UX win ("the end user never picks from a roster") is **kept** but re-grounded: the *surface* binds the agent, not a classifier and not a dropdown. §3 (custom tenant agents) is withdrawn; §4 (tool-scoping) is handed to [ADR-0064](./0064-tool-scoping-to-agent.md).
diff --git a/docs/adr/0064-tool-scoping-to-agent.md b/docs/adr/0064-tool-scoping-to-agent.md
@@ -1,5 +1,7 @@
 # ADR-0064: Tool scoping — an agent's tools are exactly its skills' tools
 
+> **🔶 Cloud-owned — superseded in part by cloud ADR-0025 (2026-06-25).** The in-UI AI runtime and the `ask` / `build` agents described here moved to the **cloud / Enterprise** distribution (`@objectstack/service-ai` → `cloud/packages/service-ai`, closed); the open framework exposes AI only via `@objectstack/mcp` (BYO-AI) and ships no in-product `ask` / `build` chat. Retained as historical design context, now **cloud-owned** — see [`cloud/docs/adr/0025-service-ai-to-cloud-open-mcp-only`](https://github.com/objectstack-ai/cloud/blob/main/docs/adr/0025-service-ai-to-cloud-open-mcp-only.md).
+
 **Status**: Proposed (2026-06-22)
 **Deciders**: ObjectStack Protocol Architects
 **Builds on**: [ADR-0063](./0063-two-kernel-agents-skills-are-the-extension-primitive.md) (two agents bound by surface; skill ↔ agent affinity), [ADR-0033](./0033-ai-assisted-metadata-authoring.md) (draft-gated authoring tools)
diff --git a/skills/objectstack-ai/SKILL.md b/skills/objectstack-ai/SKILL.md
@@ -23,6 +23,16 @@ pipelines using the ObjectStack specification. This skill covers the
 Agent → Skill → Tool three-tier architecture aligned with Salesforce
 Agentforce, Microsoft Copilot Studio, and ServiceNow Now Assist patterns.
 
+> **Edition boundary (cloud ADR-0025 — `service-ai → cloud; open = MCP-only`).**
+> The in-UI AI **runtime** — the `ask` / `build` agents, in-product chat, and the
+> `/api/v1/ai/*` routes (`@objectstack/service-ai`) — ships in the **cloud /
+> Enterprise** distribution, not the open framework. The agent / skill / tool
+> **schemas** in `@objectstack/spec/ai` stay open, so you author `*.agent.ts` /
+> `*.skill.ts` / `*.tool.ts` as source either way — but they only execute in a
+> cloud / EE host. On the **open edition** there is no in-product agent: expose the
+> app to your own AI via `@objectstack/mcp` (BYO-AI) for data query, and author
+> metadata in **source mode** with an AI coding agent (Claude Code, Cursor).
+
 ---
 
 ## When to Use This Skill
@@ -65,8 +75,10 @@ never picks from a roster; the surface they are in selects the agent:
 - **`ask`** — the **data product** (≈ Claude Chat). Conversational read / query /
   explore over records, plus running the business **actions** the app already
   exposes. End-user audience, RLS-bounded. Canonical id `ask` (`ASK_AGENT_NAME`).
-  Open-source · free — ships in `@objectstack/service-ai`, and is the implicit
-  copilot for any app that does not pin `app.defaultAgent`.
+  **Cloud / Enterprise** — the `ask` runtime moved from the open framework into the
+  cloud AI runtime (`@objectstack/service-ai` → `cloud/packages/service-ai`, closed)
+  per cloud ADR-0025; it is the implicit copilot for any cloud / EE app that does
+  not pin `app.defaultAgent`. (Open editions have no in-product `ask`; use MCP.)
 - **`build`** — the **authoring product** (≈ Claude Code). Agentic authoring of
   *metadata* (objects, fields, views, flows) through plan → draft → verify →
   publish. Builder audience, governance-gated. Canonical id `build`. Cloud-only ·
diff --git a/skills/objectstack-platform/SKILL.md b/skills/objectstack-platform/SKILL.md
@@ -428,7 +428,7 @@ CLI: `os serve` / `os dev`
      ├── HonoServerPlugin
      ├── RESTPlugin (auto-generated API)
      ├── DispatcherPlugin
-     └── AIServicePlugin (if available)
+     └── AIServicePlugin (cloud / EE only — reverse-mounted by a cloud host; absent in the open framework per cloud ADR-0025)
   5. Runtime.start() → init + start all plugins
   6. Server listens on the resolved port (see "Ports & networking" in Part 3)
 ```
@@ -449,7 +449,7 @@ Plugins initialize in registration order. Key dependencies:
 | AppPlugin | ObjectQLPlugin | Registers objects/metadata with engine |
 | AuthPlugin | ObjectQLPlugin | Needs user/session objects |
 | RESTPlugin | ObjectQLPlugin, AppPlugin | Generates routes from registered objects |
-| AIServicePlugin | ObjectQLPlugin, AppPlugin | Needs metadata for tool generation |
+| AIServicePlugin | ObjectQLPlugin, AppPlugin | Needs metadata for tool generation. **Cloud / EE only** — `@objectstack/service-ai` moved to cloud (cloud ADR-0025); the open edition has no in-UI AI plugin and uses `@objectstack/mcp` (BYO-AI) |
 
 ### Programmatic Bootstrap (Without CLI)
 
