docs: reframe getting-started around the AI build/verify loop (#2666)

* chore: bump objectui to c27bd3264f39

feat(studio): per-object API / Hooks / Actions tabs + Data-pillar polish (#2330)

objectui@c27bd3264f394bec5f5f71326118bfb115fbe884

* docs: reframe getting-started around the AI build/verify loop

Center the docs on the actual ObjectStack workflow: an AI agent (Claude Code)
authors typed metadata, a validation gate catches silent-at-runtime mistakes,
the human verifies in the visual Console, and the built app is itself AI-operable
over MCP.

- New flagship tutorial "Build with Claude Code" — the whole loop on a
  live-built Support Desk app, grounded in real `os` CLI output.
- New concept page "How AI Development Works" — why the loop is fast and safe
  (skills+AGENTS.md, os validate, contract-first, draft-gating, worktree).
- Repurpose the old hand-authoring Quick Start into "Anatomy of an ObjectStack
  App" (read-to-verify); keep the /quick-start slug so inbound links survive.
- Front-load the "your app is an MCP server" story: env-var value-prop, a
  dedicated api/index section + request-path diagram, deployment pointer.
- Reframe by real development layering (Data / Automation / Interface / Access /
  AI) instead of the ObjectQL/ObjectOS/ObjectUI protocol trinity.
- Add Mermaid diagrams (build loop, AI architecture, protocol stack, MCP request
  path) using the site's existing Mermaid support.
- Docs-site chrome: drop the meaningless "Documentation" self-link, fix the UI
  Engine icon (deprecated `Layout` -> `LayoutDashboard`), hide the
  single-language switcher.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: os-zhuang

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>

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}`,
   };
 }

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

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

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"]
 ```
 
 ---

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

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

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)
 

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

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: