objectstack-ai · os-zhuang · Jul 6, 2026 · Jul 6, 2026 · Jul 6, 2026
diff --git a/.objectui-sha b/.objectui-sha
@@ -1 +1 @@
-6cbccf386cf3fe15d1b8e79ab69fcf8f08c4cadf
+c27bd3264f394bec5f5f71326118bfb115fbe884
diff --git a/apps/docs/app/[lang]/docs/layout.tsx b/apps/docs/app/[lang]/docs/layout.tsx
@@ -13,10 +13,9 @@ export default async function Layout({
   const { lang } = await params;
 
   return (
-    <DocsLayout 
-      tree={source.pageTree[lang]} 
+    <DocsLayout
+      tree={source.pageTree[lang]}
       {...baseOptions()}
-      i18n
     >
       {children}
     </DocsLayout>

diff --git a/apps/docs/lib/layout.shared.tsx b/apps/docs/lib/layout.shared.tsx
@@ -22,13 +22,6 @@ export function baseOptions(): BaseLayoutProps {
         </div>
       ),
     },
-    links: [
-      {
-        text: 'Documentation',
-        url: '/docs/',
-        active: 'nested-url',
-      },
-    ],
     githubUrl: `https://github.com/${gitConfig.user}/${gitConfig.repo}`,
   };
 }
diff --git a/content/docs/ai/actions-as-tools.mdx b/content/docs/ai/actions-as-tools.mdx
@@ -7,6 +7,8 @@ description: Expose declarative Action metadata as AI-callable tools with explic
 
 Part of the [AI module](/docs/ai) — how existing Action metadata becomes LLM-callable, and the guardrails around it.
 
+This is what makes the app you built **AI-operable**: connect an MCP client (Claude Code, Cursor, …) and your business Actions become callable tools — so an agent can "resolve this ticket" or "convert this lead" through the same logic and permissions as the Console button.
+
 Any business `Action` you already have — a `script` action or a Flow — can be
 reached by an LLM as a callable tool. On the **open edition** this happens
 through [`@objectstack/mcp`](/docs/ai): your own AI (Claude, Cursor, any MCP

diff --git a/content/docs/ai/agents.mdx b/content/docs/ai/agents.mdx
@@ -11,7 +11,10 @@ skills are **typed metadata**: you author them as source with `defineAgent` /
 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.
+validates against. Like the rest of your metadata, you don't hand-write agents —
+Claude Code authors them from the `objectstack-ai` [skill](/docs/ai/skills); you
+`os validate` and test the tools in the Console
+([the loop](/docs/getting-started/build-with-claude-code)).
 
 <Callout type="info">
 **Cloud / Enterprise — the in-product chat runtime.** The authoring format on

diff --git a/content/docs/ai/index.mdx b/content/docs/ai/index.mdx
@@ -7,6 +7,12 @@ 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="info">
+**Two different "AI" stories — don't confuse them:**
+- **AI *builds* your app** (authoring) — Claude Code writes the typed metadata; you verify in the Console. That's the [Build with Claude Code](/docs/getting-started/build-with-claude-code) workflow, in *Get Started* — a different thing from this section.
+- **Your app *exposes/uses* AI** (runtime) — agents, tools, RAG, natural-language queries, and an MCP server that let an AI operate the app you built, under the same permissions. **This section covers that.**
+</Callout>
+
 <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**:
 
@@ -34,20 +40,11 @@ The **cloud / Enterprise** tier adds an in-product chat *runtime* on top of thes
 
 ObjectStack provides a comprehensive AI platform:
 
-```
-┌─────────────────────────────────────┐
-│        AI Agents                    │ ← Persona + skills/tools
-│        Skills & Tools               │ ← Actions/Flows exposed to the LLM
-├─────────────────────────────────────┤
-│        Knowledge Protocol           │ ← search_knowledge via adapters
-│  - memory / ragflow / custom        │
-│  - Permission-aware retrieval       │
-├─────────────────────────────────────┤
-│        Model Registry               │ ← LLM management
-│  - openai, azure_openai,            │
-│    anthropic, local                 │
-│  - Token accounting / cost          │
-└─────────────────────────────────────┘
+```mermaid
+flowchart TD
+    A["<b>AI Agents</b> — persona + skills/tools"] --> T["<b>Skills &amp; Tools</b><br/>Actions / Flows exposed to the LLM"]
+    T --> K["<b>Knowledge Protocol</b> — search_knowledge via adapters<br/>memory / ragflow / custom · permission-aware retrieval"]
+    K --> R["<b>Model Registry</b> — LLM management<br/>openai · azure_openai · anthropic · local · token accounting / cost"]
 ```
 
 ---

diff --git a/content/docs/ai/skills.mdx b/content/docs/ai/skills.mdx
@@ -7,7 +7,7 @@ import { Bot, Brain, Cpu, Database, Globe, Layout, Shield, Workflow, Wrench, Lan
 
 # AI Skills System
 
-ObjectStack introduces a **Skills System** — structured, domain-specific knowledge modules that enable AI assistants (GitHub Copilot, Claude Code, Cursor, etc.) to understand and generate protocol-compliant code.
+ObjectStack introduces a **Skills System** — structured, domain-specific knowledge modules that enable AI assistants (GitHub Copilot, Claude Code, Cursor, etc.) to understand and generate protocol-compliant code. Skills are what make [building with Claude Code](/docs/getting-started/build-with-claude-code) reliable: they teach the agent the protocol's rules up front, so it authors correct metadata instead of guessing.
 
 <Callout type="info">
 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.
@@ -186,6 +186,10 @@ Read skills/objectstack-query/SKILL.md and help me build a query
 that filters opportunities by stage and aggregates revenue by quarter.
 ```
 
+For the end-to-end workflow — scaffold, let Claude Code author the metadata,
+validate, and verify in the Console — follow
+[Build with Claude Code](/docs/getting-started/build-with-claude-code).
+
 ### With Cursor
 
 Add the skill files to your Cursor rules or reference them in prompts:
@@ -224,4 +228,4 @@ The `evals/` directory in each skill is reserved for test cases that validate an
 - [AI Skills Reference](/docs/ai/skills-reference) — Detailed guide to each skill with usage examples
 - [AI Capabilities](/docs/ai) — AI agents, RAG pipelines, and intelligent automation
 - [Plugin Development](/docs/plugins/development) — Build custom plugins
-- [Quick Start](/docs/getting-started/quick-start) — Build your first ObjectStack app
+- [Build with Claude Code](/docs/getting-started/build-with-claude-code) — Build your first ObjectStack app with an agent
diff --git a/content/docs/api/index.mdx b/content/docs/api/index.mdx
@@ -23,6 +23,40 @@ ObjectStack exposes a fully typed REST API. All endpoints use JSON request/respo
 **Base URL**: Configurable, defaults to `/api/v1`. All paths below are relative to the base URL.
 </Callout>
 
+## Your app as an MCP server
+
+REST and GraphQL are how *code* consumes your app. **MCP is how *AI* consumes it.**
+Because every object and action is typed metadata, ObjectStack can expose the whole app
+as a [Model Context Protocol](https://modelcontextprotocol.io) server — so an AI client
+(Claude Code, Claude Desktop, Cursor, a local model) can inspect and *operate* the app
+you built, under the same permissions and RLS as the UI. Enable it with
+`OS_MCP_SERVER_ENABLED=true` (see [environment variables](/docs/deployment/environment-variables#mcp-server)).
+
+The generated tools mirror the surfaces you already defined:
+`list_objects` / `describe_object` (discover the schema), `query_records` / `get_record`
+(read), `create_record` / `update_record` / `delete_record` (write), and
+`list_actions` / `run_action` (invoke your business actions by name). Every call runs as
+the caller — RBAC, RLS, and field-level security all apply.
+
+```mermaid
+sequenceDiagram
+    participant AI as AI client (Claude / Cursor)
+    participant MCP as MCP server (@objectstack/mcp)
+    participant Eng as Action / ObjectQL engine
+    participant Sec as RBAC · RLS · FLS
+    participant DB as Data
+
+    AI->>MCP: run_action("resolve", { recordId })
+    MCP->>Eng: dispatch as the caller's principal
+    Eng->>Sec: check permissions on this record
+    Sec-->>Eng: allowed (or denied — fail-closed)
+    Eng->>DB: apply the change
+    DB-->>AI: result, same as the Console would return
+```
+
+See [Actions as Tools](/docs/ai/actions-as-tools) for the `run_action` bridge and the
+[MCP reference](/docs/references/ai/mcp) for binding external MCP servers into your agents.
+
 ## What's in this module
 
 - [Data API](/docs/api/data-api) — CRUD, batch operations, record cloning, and analytics queries

diff --git a/content/docs/concepts/architecture.mdx b/content/docs/concepts/architecture.mdx
@@ -9,6 +9,15 @@ import { Database, Layout, Cpu, ArrowRight, CheckCircle, Workflow, Bot, Cloud }
 
 The architecture is built on foundational protocols that work together as a unified system:
 
+<Callout type="info">
+**This is the engine-level view.** When you *build*, you work by area — data,
+automation, interface, access, AI (see [What you build](/docs/getting-started/quick-start#what-you-build)).
+This page zooms one level down, into the runtime engines that implement those areas:
+**ObjectQL** (data), **ObjectOS** (control — automation, access, governance), and
+**ObjectUI** (interface). You rarely think in these three while building; they're the
+machinery underneath.
+</Callout>
+
 <Cards>
   <Card
     icon={<Database />}
@@ -48,25 +57,22 @@ Traditional applications tightly couple data, business logic, and presentation.
 
 ObjectStack enforces **Separation of Concerns** through protocol boundaries:
 
+```mermaid
+flowchart TD
+    UI["<b>UI Protocol &amp; AI Protocol</b><br/>Apps · Views · Dashboards · Agents · RAG<br/><i>How do users and agents interact?</i>"]
+    OS["<b>System · Automation · Cloud Protocol</b><br/>Auth · Permissions · Orchestration · Multi-tenancy<br/><i>Who / what can do what, when, and where?</i>"]
+    DATA["<b>Data Protocol</b><br/>Objects · Fields · Queries · Drivers<br/><i>What is the data structure?</i>"]
+    UI -->|Interface| OS
+    OS -->|Control| DATA
 ```
-┌───────────────────────────────────────────────────────────┐
-│              UI Protocol & AI Protocol                    │
-│  Apps, Views, Dashboards, Agents, RAG                     │
-│  "How do users and agents interact?"                       │
-└───────────────────────────┬───────────────────────────────┘
-                            │ Interface
-┌───────────────────────────┴───────────────────────────────┐
-│    System Protocol & Automation Protocol & Cloud Protocol │
-│  Auth, Permissions, Orchestration, Multi-tenancy          │
-│  "Who/What can do what, when, and where?"                  │
-└───────────────────────────┬───────────────────────────────┘
-                            │ Control
-┌───────────────────────────┴───────────────────────────────┐
-│                     Data Protocol                         │
-│  Objects, Fields, Queries, Drivers                        │
-│  "What is the data structure?"                             │
-└───────────────────────────────────────────────────────────┘
-```
+
+<Callout type="info">
+**Who writes this?** In practice, Claude Code authors across every area from your
+description — data (objects), automation (flows), access (permissions), and interface
+(views, apps) — guided by the matching [skills](/docs/ai/skills). Each passes
+`os validate` before you review it in the Console. See
+[How AI Development Works](/docs/getting-started/how-ai-development-works).
+</Callout>
 
 ## Layer 1: ObjectQL (Data Protocol)
 

diff --git a/content/docs/concepts/index.mdx b/content/docs/concepts/index.mdx
@@ -187,5 +187,5 @@ ObjectStack enforces strict naming rules for consistency:
 ## Next Steps
 
 - [Architecture](/docs/concepts/architecture) — How the protocol layers work together
-- [Quick Start](/docs/getting-started/quick-start) — Build your first app in 5 minutes
+- [Build with Claude Code](/docs/getting-started/build-with-claude-code) — Build your first app end-to-end with an agent
 - [Glossary](/docs/getting-started/glossary) — Key terminology
diff --git a/content/docs/concepts/metadata-driven.mdx b/content/docs/concepts/metadata-driven.mdx
@@ -9,6 +9,13 @@ import { Database, Code, Link, Laptop } from 'lucide-react';
 
 Metadata-driven development is a paradigm shift where **business intent is defined by declarative, analyzable metadata instead of scattered imperative code.**
 
+<Callout type="info">
+This is also what makes ObjectStack **AI-native**: because the whole app is a few hundred
+lines of typed, analyzable metadata — not tens of thousands of lines of glue — it fits in
+an agent's context window. Claude Code authors it, `os validate` catches mistakes, and you
+verify in the Console. See [How AI Development Works](/docs/getting-started/how-ai-development-works).
+</Callout>
+
 ## The Problem with Code-First
 
 In traditional development, the "Intent" (e.g., *"This field is a required email address"*) is scattered across multiple layers:

diff --git a/content/docs/deployment/environment-variables.mdx b/content/docs/deployment/environment-variables.mdx
@@ -215,11 +215,22 @@ Provider credentials keep their upstream names. ObjectStack does not rename
 
 ## MCP Server
 
+Enable this to make **the app you built AI-operable**: with the MCP server on, an
+MCP client — Claude Code, Claude Desktop, Cursor, or a local model — connects to your
+running app and gets a generated tool surface over your objects and actions
+(`query_records`, `run_action`, …), bound to the caller's principal and governed by the
+same RBAC / RLS as the Console. No custom tooling, no separate API. See
+[Actions as Tools](/docs/ai/actions-as-tools) for the tool set.
+
+```bash
+OS_MCP_SERVER_ENABLED=true os start     # boot with the MCP server (stdio by default)
+```
+
 | Variable | Type | Default | Description |
 |:---|:---|:---|:---|
-| `OS_MCP_SERVER_ENABLED` | boolean | `false` | When `true`, start the Model Context Protocol server at boot. |
+| `OS_MCP_SERVER_ENABLED` | boolean | `false` | When `true`, start the Model Context Protocol server at boot — exposing your objects and actions to MCP clients. |
 | `OS_MCP_SERVER_NAME` | string | `objectstack` | Server name advertised to MCP clients. |
-| `OS_MCP_SERVER_TRANSPORT` | enum | `stdio` | `stdio` \| `http`. |
+| `OS_MCP_SERVER_TRANSPORT` | enum | `stdio` | `stdio` \| `http`. Use `http` (Streamable HTTP) for a remote client; `stdio` for a local one. |
 
 ---
 

diff --git a/content/docs/deployment/index.mdx b/content/docs/deployment/index.mdx
@@ -133,6 +133,14 @@ settings are the exception — they route through the settings env-override
 convention as `OS_MAIL_<KEY>` (e.g. `OS_MAIL_SMTP_HOST`, `OS_MAIL_SMTP_PORT`),
 not a raw `SMTP_*` name.
 
+<Callout type="tip">
+**Make the deployed app AI-operable:** set `OS_MCP_SERVER_ENABLED=true` to start an MCP
+server alongside any deployment mode, exposing your objects and actions to AI clients
+under the same permissions and RLS. See
+[MCP Server env vars](/docs/deployment/environment-variables#mcp-server) and
+[Your app as an MCP server](/docs/api#your-app-as-an-mcp-server).
+</Callout>
+
 <Callout type="warn">
 **Set `OS_SECRET_KEY` for any containerized or multi-node deployment.** The
 default `LocalCryptoProvider` encrypts every `sys_secret` value under one
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		6cbccf386cf3fe15d1b8e79ab69fcf8f08c4cadf
		c27bd3264f394bec5f5f71326118bfb115fbe884