diff --git a/.changeset/agent-docs-open-edition-honesty.md b/.changeset/agent-docs-open-edition-honesty.md
new file mode 100644
index 0000000000..b257b2cbbb
--- /dev/null
+++ b/.changeset/agent-docs-open-edition-honesty.md
@@ -0,0 +1,19 @@
+---
+"@objectstack/spec": patch
+---
+
+Agent capability — open-edition honesty pass (docs + liveness annotation), no
+behavior change:
+
+- The `agent`/`skill`/`tool`/`action` liveness files cite
+ `packages/services/service-ai/...` as evidence, but that tree is a stale,
+ untracked build artifact — the real runtime is the closed cloud
+ `@objectstack/service-ai`. Each file's `_note` now says so explicitly, so an
+ auditor reading the ledger understands these props are `live` because a
+ CLOUD/EE runtime consumes them and the OPEN framework edition does not.
+- Docs (`content/docs/ai`): removed the `aggregate_data` over-claim from
+ Natural Language Queries — the open MCP surface registers 9 tools and
+ `query_records` has no aggregation args; `aggregate_data` is a cloud data
+ tool. And disambiguated the two things called "skill" (authoring `SKILL.md`
+ modules vs. runtime `defineSkill` agent capability bundles) with cross-linked
+ callouts on both pages.
diff --git a/content/docs/ai/agents.mdx b/content/docs/ai/agents.mdx
index d888487314..abfc0e815c 100644
--- a/content/docs/ai/agents.mdx
+++ b/content/docs/ai/agents.mdx
@@ -85,11 +85,19 @@ API-key-only, fail-closed.
## You extend the platform with **skills**, not agents
+
+**"Agent skill" ≠ "authoring skill."** The `*.skill.ts` / `defineSkill` files
+here are **agent skills** — runtime capability bundles the `ask` / `build`
+agents consume. They are a different thing from the `SKILL.md` **authoring
+skills** on the [AI Skills System](/docs/ai/skills) page, which teach a coding
+assistant to *write* your metadata and never run. Same word, two layers.
+
+
`*.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
+capability you author an agent **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
diff --git a/content/docs/ai/natural-language-queries.mdx b/content/docs/ai/natural-language-queries.mdx
index 1f1aca6541..75b860fdd7 100644
--- a/content/docs/ai/natural-language-queries.mdx
+++ b/content/docs/ai/natural-language-queries.mdx
@@ -1,6 +1,6 @@
---
title: Natural Language Queries
-description: How agents query live data through the built-in data tools (query_records, get_record, aggregate_data) under RLS
+description: How agents query live data through the open MCP data tools (query_records, get_record) under RLS
---
# Natural Language Queries
@@ -14,15 +14,25 @@ row-level security as the REST API. The data tools and the ObjectQL engine that
back this are part of the open framework — no `@objectstack/service-ai` and no
cloud studio are required.
-Your AI queries your data through the built-in **data tools** —
-`query_records`, `get_record`, and `aggregate_data` — which the model calls with
-structured arguments. These run as ordinary [ObjectQL](/docs/protocol/objectql) queries over
+Your AI queries your data through the open MCP **data tools** — `query_records`
+(filter, field selection, sort, pagination) and `get_record`, plus the
+discovery tools `list_objects` and `describe_object` — which the model calls
+with structured arguments. These run as ordinary [ObjectQL](/docs/protocol/objectql) queries over
your objects (ObjectStack uses ObjectQL, not SOQL), and they execute under the
caller's `ExecutionContext`, so row-level security applies exactly as it does
for the REST API.
+
+**Aggregation is a cloud data tool.** The open MCP surface reads and filters
+rows; it does not ship a server-side `aggregate_data` (group-by / roll-up)
+tool — `query_records` has no aggregation arguments. A BYO agent aggregates by
+fetching the rows it's allowed to see and summing client-side; the built-in
+`aggregate_data` tool is part of the cloud in-product chat runtime (below).
+
+
The open MCP server plugin exposes these tools automatically — it bridges the
-kernel's tool registry, metadata, and data engine to any connected MCP client:
+metadata and data engine to any connected MCP client, served per-request at
+`/api/v1/mcp` (default-on):
```typescript
import { LiteKernel } from '@objectstack/core';
@@ -34,18 +44,19 @@ await kernel.bootstrap();
```
Point any MCP client at the server and ask questions in natural language: the
-model discovers `query_records` / `get_record` / `aggregate_data` and calls them
-under RLS as the authenticated caller.
+model discovers `list_objects` / `describe_object` / `query_records` /
+`get_record` and calls them under RLS as the authenticated caller.
There is no separate natural-language-to-query metadata type to author — the
model is prompted with the available objects and translates the user's question
-into `query_records` / `aggregate_data` calls at runtime.
+into `query_records` calls at runtime.
**Cloud / Enterprise — bundled in-product chat.** The cloud tier's in-UI AI
runtime (`@objectstack/service-ai`, the `ask` data-query assistant, and the
-`/api/v1/ai/*` chat endpoints) registers these same data tools into its chat
-loop via `registerDataTools`:
+`/api/v1/ai/*` chat endpoints) registers these data tools — plus the
+group-by/roll-up `aggregate_data` tool — into its chat loop via
+`registerDataTools`:
```typescript
import { registerDataTools } from '@objectstack/service-ai';
diff --git a/content/docs/ai/skills.mdx b/content/docs/ai/skills.mdx
index 12408e9ebd..081d944120 100644
--- a/content/docs/ai/skills.mdx
+++ b/content/docs/ai/skills.mdx
@@ -13,6 +13,16 @@ ObjectStack introduces a **Skills System** — structured, domain-specific knowl
Skills are **not runtime code**. They are machine-readable knowledge definitions that teach AI assistants the ObjectStack protocol — its schemas, patterns, constraints, and best practices.
+
+**Two different things share the word "skill."** This page is about **authoring
+skills** — `SKILL.md` knowledge modules (from `skills.sh`) that teach a coding
+assistant to *write* correct ObjectStack metadata, at development time. They are
+unrelated to **agent skills** (`defineSkill` / `SkillSchema`) — the *runtime*
+capability bundles (tools + instructions + trigger conditions) attached to the
+`ask` / `build` platform agents, which are the cloud in-product chat runtime.
+See [Agents](/docs/ai/agents#you-extend-the-platform-with-skills-not-agents) for those.
+
+
---
## Installing skills
diff --git a/packages/spec/liveness/action.json b/packages/spec/liveness/action.json
index 38215de868..2de5885186 100644
--- a/packages/spec/liveness/action.json
+++ b/packages/spec/liveness/action.json
@@ -1,6 +1,6 @@
{
"type": "action",
- "_note": "ActionSchema. Seeded from docs/audits/2026-06-actionschema-property-liveness.md. Renderers live in objectui (evidence cited as prose, not framework paths); framework-side: service-ai action-tools, runtime body-runner/http-dispatcher. Containers (params/resultDialog/ai/aria) classified at top level — no divergent sub-statuses in the audit.",
+ "_note": "ActionSchema. Seeded from docs/audits/2026-06-actionschema-property-liveness.md. Renderers live in objectui (evidence cited as prose, not framework paths); framework-side: service-ai action-tools, runtime body-runner/http-dispatcher. Containers (params/resultDialog/ai/aria) classified at top level — no divergent sub-statuses in the audit. ⚠ EVIDENCE LIVES IN CLOUD/EE: the `packages/services/service-ai/...` paths cited below are the closed `@objectstack/service-ai` runtime in the CLOUD repo, NOT git-tracked framework code (the framework's own service-ai tree is a stale build artifact with no src/). These props are `live` because that cloud runtime consumes them; the OPEN framework edition does not — see content/docs/ai for the open/cloud boundary.",
"props": {
"name": {
"status": "live",
diff --git a/packages/spec/liveness/agent.json b/packages/spec/liveness/agent.json
index 338f2c0602..49a8d0976e 100644
--- a/packages/spec/liveness/agent.json
+++ b/packages/spec/liveness/agent.json
@@ -1,6 +1,6 @@
{
"type": "agent",
- "_note": "AgentSchema. Seeded from docs/audits/2026-06-agentschema-property-liveness.md. agent-runtime.ts is the runtime consumer; AgentPreview is display-only.",
+ "_note": "AgentSchema. Seeded from docs/audits/2026-06-agentschema-property-liveness.md. agent-runtime.ts is the runtime consumer; AgentPreview is display-only. ⚠ EVIDENCE LIVES IN CLOUD/EE: the `packages/services/service-ai/...` paths cited below are the closed `@objectstack/service-ai` runtime in the CLOUD repo, NOT git-tracked framework code (the framework's own service-ai tree is a stale build artifact with no src/). These props are `live` because that cloud runtime consumes them; the OPEN framework edition does not — see content/docs/ai for the open/cloud boundary.",
"props": {
"name": {
"status": "live",
diff --git a/packages/spec/liveness/skill.json b/packages/spec/liveness/skill.json
index f0ca44f44e..673b95cd51 100644
--- a/packages/spec/liveness/skill.json
+++ b/packages/spec/liveness/skill.json
@@ -1,6 +1,6 @@
{
"type": "skill",
- "_note": "SkillSchema. Seeded from docs/audits/2026-06-skillschema-property-liveness.md. skill-registry.ts + agent-runtime.ts are the runtime consumers.",
+ "_note": "SkillSchema. Seeded from docs/audits/2026-06-skillschema-property-liveness.md. skill-registry.ts + agent-runtime.ts are the runtime consumers. ⚠ EVIDENCE LIVES IN CLOUD/EE: the `packages/services/service-ai/...` paths cited below are the closed `@objectstack/service-ai` runtime in the CLOUD repo, NOT git-tracked framework code (the framework's own service-ai tree is a stale build artifact with no src/). These props are `live` because that cloud runtime consumes them; the OPEN framework edition does not — see content/docs/ai for the open/cloud boundary.",
"props": {
"name": {
"status": "live",
diff --git a/packages/spec/liveness/tool.json b/packages/spec/liveness/tool.json
index 8a35c4266a..2312bed0bd 100644
--- a/packages/spec/liveness/tool.json
+++ b/packages/spec/liveness/tool.json
@@ -1,6 +1,6 @@
{
"type": "tool",
- "_note": "ToolSchema. Seeded from docs/audits/2026-06-toolschema-property-liveness.md. Tool metadata is WRITE-ONLY (projected one-way for Studio; runtime uses a separate AIToolDefinition). LIVE props are live via that same-named surface, not metadata read-back.",
+ "_note": "ToolSchema. Seeded from docs/audits/2026-06-toolschema-property-liveness.md. Tool metadata is WRITE-ONLY (projected one-way for Studio; runtime uses a separate AIToolDefinition). LIVE props are live via that same-named surface, not metadata read-back. ⚠ EVIDENCE LIVES IN CLOUD/EE: the `packages/services/service-ai/...` paths cited below are the closed `@objectstack/service-ai` runtime in the CLOUD repo, NOT git-tracked framework code (the framework's own service-ai tree is a stale build artifact with no src/). These props are `live` because that cloud runtime consumes them; the OPEN framework edition does not — see content/docs/ai for the open/cloud boundary.",
"props": {
"name": {
"status": "live",