docs: explain ObjectOS in ontology terms, and correct four capability claims 17.7 contradicts

content/docs/architecture.mdx

@@ -8,15 +8,38 @@ A practical view of what runs when you deploy ObjectOS — on your own
 machines with **ObjectOS Enterprise**, or operated for you on **ObjectOS
 Cloud** — what data leaves your network, and what doesn't.
 
-The mental model is two thin layers:
-
-1. **Metadata** — packages of objects / views / actions / flows /
-   agents. Mostly written by the [AI Builder](/docs/build/ai-builder)
-   against a sandboxed tool API; sometimes hand-edited, always
+The mental model is one definition and one runtime that runs it:
+
+1. **Your [ontology](/docs/ontology)** — the definition of the business:
+   objects and fields, relations, actions, permissions, flows, and agent
+   and tool definitions. Views, dashboards, apps and translations are
+   authored beside it as its projections. Mostly written by the
+   [AI Builder](/docs/build/ai-builder) against a sandboxed tool API;
+   sometimes hand-edited; always validated before it runs,
    version-controlled and audited.
-2. **A single Node.js runtime** that interprets that metadata into a
-   working application — REST API, Console UI, permissions, jobs, AI
-   tools — all in one process, talking to your database.
+2. **A single Node.js runtime** that **derives** the working application
+   from it — the database schema, the REST API, the Console UI and the MCP
+   server agents call — and **enforces** it on every call: RBAC,
+   row-level and field-level security, sharing and audit apply to a REST
+   request, a Console click and an agent's tool call alike. All in one
+   process, talking to your database.
+
+```text
+your ontology
+  objects · relations · actions
+  permissions · flows · agents
+  + projections: views · dashboards
+    apps · translations
+      │
+      ▼
+ObjectOS runtime
+  derives the app, enforces it
+      │
+      ├──▶ database    its schema
+      ├──▶ REST API    /api/v1/*
+      ├──▶ Console     /_console/
+      └──▶ MCP server  /api/v1/mcp
+```
 
 No code generation step, no deploy pipeline between "user described
 what they want" and "it's live". The runtime hot-loads the new
@@ -39,6 +62,7 @@ licensed runtime image described under [Deployment](/docs/deploy).
 │  │   ├─ Security (RBAC + row-level + field)      │  │
 │  │   ├─ ObjectQL (data engine, generates SQL)    │  │
 │  │   ├─ REST API generator                       │  │
+│  │   ├─ MCP server  (/api/v1/mcp, on by default) │  │
 │  │   └─ Capabilities loaded per artifact         │  │
 │  │      (audit, storage, jobs, queue, AI …)      │  │
 │  └───────────────────────────────────────────────┘  │
@@ -81,11 +105,17 @@ supported license and cloud-posture pairs.
 2. HTTP dispatcher                (security headers, request id)
 3. AuthPlugin     — session cookie, bearer token, or API key
 4. SecurityPlugin — RBAC + row-level + field-level checks
-5. Route handler  — generated REST, declarative action, or custom
+5. Route handler  — generated REST, MCP tool call, declarative action,
+                    or custom
 6. Data driver    — ObjectQL compiles to SQL / Mongo query
 7. Response with X-Request-Id propagated
 ```
 
+An agent's call takes the same path. An MCP client authenticates as a
+user, by OAuth or an API key, and the same permission checks bound what
+its tool calls read and write — see
+[Connect AI Tools (MCP)](/docs/configure/mcp).
+
 The app is already resolved before the first request arrives: the
 kernel is built during startup, and the process does not report itself
 [ready](/docs/deploy/docker) until it is. So a served request carries no

content/docs/build/agents.mdx

@@ -75,7 +75,7 @@ export const ticketManagement = defineSkill({
     'update_ticket',
     'close_ticket',
     'escalate_ticket',
-    'action_*',         // wildcard: pick up any future actions on the active object
+    'action_*',         // wildcard: every action the app exposes to AI (`ai.exposed`)
   ],
 });
 ```
@@ -85,19 +85,26 @@ agents.
 
 ## Tools come from your declared metadata
 
-Every `*.action.ts` you declare automatically materializes as an
-`action_<name>` tool — no separate wiring. So if you've already
-defined `escalate_ticket` as an Action on the `support_ticket` object,
-both the AI Builder and your Agents can call it. Permissions still
-apply: the agent calls the action **as the user**, so the user's
-permission set decides whether it succeeds.
+An action becomes an `action_<name>` tool **when its author exposes it
+to AI** — `ai: { exposed: true }` with an `ai.description` of at least 40
+characters — and its type runs without a UI (`script`, `flow` or `api`).
+Nothing else needs wiring: if `escalate_ticket` on the `support_ticket`
+object is exposed, both the AI Builder and your Agents can call it. An
+action left unexposed is invisible to agents and refused if called,
+whatever capabilities the caller holds.
+
+The call is checked **as the user**: the action's `requiredPermissions`
+decide whether it may fire, and it loads the record as that user. A
+`script` body then runs as trusted app code, so expose an action only
+when its body is safe to run for anyone those checks let through. See
+[Actions](/docs/build/interface/actions#permissions).
 
 You can also expose:
 
 | Tool type | Source |
 |---|---|
-| **Action** | Any `*.action.ts` in any installed package |
-| **Flow** | A `type: 'flow'` action — the agent calls the action, which starts the flow |
+| **Action** | Any action exposed to AI (`ai.exposed`), in any installed package |
+| **Flow** | An exposed `type: 'flow'` action — the agent calls the action, which starts the flow |
 | **Query** | Saved ObjectQL queries (`*.query.ts`) |
 | **Knowledge search** | The `search_knowledge` tool, over the sources the user may read |
 | **MCP method** | Anything exposed by an attached MCP server |

content/docs/build/ai-builder.mdx

@@ -56,11 +56,14 @@ namespaced and validated against `@objectstack/spec`:
 | | `modify_field` | Change label, picklist options, validation |
 | | `delete_field` | Remove a field (with safety check) |
 | **Data** | `query_data` | Read records via ObjectQL |
-| **Actions / Knowledge** | `action_<name>`, `search_knowledge` | Invoke actions, RAG over docs |
-
-Plus action tools materialized from every declared `*.action.ts` —
-named `action_<name>` — so once an action exists in the package,
-the AI can call it like any built-in tool.
+| **Actions / Knowledge** | `action_<name>`, `search_knowledge` | Invoke the actions exposed to AI, RAG over docs |
+
+Plus one `action_<name>` tool for each action its author **exposed to
+AI** — `ai: { exposed: true }` with an `ai.description` of at least 40
+characters, on a type that runs without a UI (`script`, `flow` or `api`).
+Once an action is exposed, the AI can call it like any built-in tool; an
+action that is not exposed never becomes one. See
+[Actions](/docs/build/interface/actions#from-an-ai-agent).
 
 See the full tool catalog at runtime: `GET /api/v1/ai/tools`.