docs(ai),liveness: open-edition honesty for the agent capability

.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.

content/docs/ai/agents.mdx

@@ -85,11 +85,19 @@ API-key-only, fail-closed.
 
 ## You extend the platform with **skills**, not agents
 
+<Callout type="warn">
+**"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.
+</Callout>
+
 `*.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

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.
 
+<Callout type="info">
+**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).
+</Callout>
+
 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.
 
 <Callout type="info">
 **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';

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.
 </Callout>
 
+<Callout type="warn">
+**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.
+</Callout>
+
 ---
 
 ## Installing skills

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",

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",

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",

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",