docs: convert ASCII diagrams to Mermaid

content/docs/ai/skills-reference.mdx

@@ -216,8 +216,9 @@ Use the [Quick Reference](#quick-reference) table to find the skill that matches
 
 Most real-world work spans multiple domains. A typical CRM feature chains:
 
-```
-Data → Query → UI → Automation → API
+```mermaid
+flowchart LR
+    Data --> Query --> UI --> Automation --> API
 ```
 
 ### 3. Load Formula alongside its host

content/docs/concepts/architecture.mdx

@@ -622,30 +622,34 @@ Datasource Protocol (Connection Config)
 
 UI auto-generated from data definitions:
 
-```
-Object → Field → View → Page → App
+```mermaid
+flowchart LR
+    Object --> Field --> View --> Page --> App
 ```
 
 ### Pattern 2: Custom UI with Data Binding
 
 Custom UI connected to data:
 
-```
-Page → Component → View (Custom) → Query → Object
+```mermaid
+flowchart LR
+    Page --> Component --> View["View (Custom)"] --> Query --> Object
 ```
 
 ### Pattern 3: Automation & Integration
 
 Business logic automation:
 
-```
-Object → Hook → Flow → Automation → API/Webhook
+```mermaid
+flowchart LR
+    Object --> Hook --> Flow --> Automation --> API["API / Webhook"]
 ```
 
 ### Pattern 4: AI-Enhanced Applications
 
 AI capabilities on top of data:
 
-```
-Object → RAG Pipeline → Agent → Conversation → UI
+```mermaid
+flowchart LR
+    Object --> RAG["RAG Pipeline"] --> Agent --> Conversation --> UI
 ```

content/docs/getting-started/build-with-claude-code.mdx

@@ -315,12 +315,12 @@ a client.
 
 ## Recap — where each guardrail sat
 
-```
-   describe ─▶ Claude authors ─▶ os validate ─▶ you verify in UI ─▶ iterate ─▶ MCP
-                    │                 │                 │
-              skills+AGENTS.md   the gate rejects   Console is the
-              taught the rules   silent-runtime     human review
-              up front           mistakes loudly    surface
+```mermaid
+flowchart LR
+    D["Describe"] --> A["Claude Code authors<br/>skills + AGENTS.md taught the rules"]
+    A --> V["os validate<br/>the gate rejects silent mistakes"]
+    V --> C["You verify in the UI<br/>Console = the human review surface"]
+    C --> I["Iterate"] --> M["MCP<br/>app is AI-operable"]
 ```
 
 - **Skills + `AGENTS.md`** meant the agent authored to the protocol, not from

content/docs/getting-started/index.mdx

@@ -12,10 +12,14 @@ import { Database, Layout, Cog } from 'lucide-react';
 ObjectStack is designed around one workflow: **an AI agent authors the app; you
 verify it in a visual UI; guardrails keep the agent from shipping mistakes.**
 
-```
-   describe ─▶ Claude Code authors ─▶ os validate ─▶ you verify in ─▶ iterate ─▶ MCP
-   in plain    the typed metadata     (the gate)      the Console                (app is
-   language                                                                       AI-operable)
+```mermaid
+flowchart LR
+    A["Describe<br/>in plain language"] --> B["Claude Code authors<br/>the typed metadata"]
+    B --> G{"os validate<br/>the gate"}
+    G -->|fails| B
+    G -->|passes| V["You verify in<br/>the Console"]
+    V -->|iterate| A
+    V -->|ship| M["MCP — your app<br/>is AI-operable"]
 ```
 
 You say what you want; Claude Code (or Cursor, Copilot, …) writes the typed

content/docs/protocol/backward-compatibility.mdx

@@ -67,11 +67,11 @@ When a feature, schema property, or API is deprecated, ObjectStack follows a str
 
 ### Timeline Summary
 
-```
-v3.2.0  →  Feature deprecated (warning emitted)
-v3.3.0  →  Migration period continues
-v3.4.0  →  Migration period continues (minimum 2 minor releases)
-v4.0.0  →  Feature removed (earliest possible removal)
+```mermaid
+flowchart TD
+    A["v3.2.0 — feature deprecated (warning emitted)"] --> B["v3.3.0 — migration period continues"]
+    B --> C["v3.4.0 — migration continues (minimum 2 minor releases)"]
+    C --> D["v4.0.0 — feature removed (earliest possible removal)"]
 ```
 
 <Callout type="warn">

content/docs/protocol/objectos/lifecycle.mdx

@@ -219,12 +219,17 @@ async function installPlugin(packageName: string, version: string) {
 
 A plugin progresses through these states:
 
-```
-NOT_INSTALLED → DOWNLOADING → VALIDATING → INSTALLING → INSTALLED → ENABLED
-                      ↓              ↓            ↓
-                   [ERROR]       [ERROR]      [ERROR]
-                      ↓              ↓            ↓
-                 FAILED_DOWNLOAD  FAILED_VALIDATION  FAILED_INSTALL
+```mermaid
+stateDiagram-v2
+    [*] --> NOT_INSTALLED
+    NOT_INSTALLED --> DOWNLOADING
+    DOWNLOADING --> VALIDATING
+    VALIDATING --> INSTALLING
+    INSTALLING --> INSTALLED
+    INSTALLED --> ENABLED
+    DOWNLOADING --> FAILED_DOWNLOAD: error
+    VALIDATING --> FAILED_VALIDATION: error
+    INSTALLING --> FAILED_INSTALL: error
 ```
 
 ### Dependency Resolution

content/docs/protocol/objectos/realtime-protocol.mdx

@@ -641,11 +641,10 @@ Each connection consumes server resources.
 
 WebSocket connections are sticky sessions:
 
-```
-Client → Load Balancer → Server A
-         (remembers)
-
-Client reconnects → Server A (same server)
+```mermaid
+flowchart LR
+    C["Client"] --> LB["Load Balancer<br/>(remembers via session-ID cookie)"] --> S["Server A"]
+    C2["Client reconnects"] -.->|routed to same server| S
 ```
 
 **Why sticky sessions:**
@@ -657,13 +656,12 @@ Client reconnects → Server A (same server)
 
 For multi-server deployments, ObjectStack uses Redis pub/sub:
 
-```
-Server A ←→ Redis Pub/Sub ←→ Server B
-   ↓                            ↓
-Client 1                    Client 2
-
-# Data changes on Server A
-Server A publishes to Redis → Server B receives → Client 2 gets update
+```mermaid
+flowchart LR
+    C1["Client 1"] --> SA["Server A"]
+    SA <-->|pub/sub| R["Redis Pub/Sub"]
+    R <-->|pub/sub| SB["Server B"]
+    SB --> C2["Client 2"]
 ```
 
 **How it works:**

content/docs/protocol/objectui/index.mdx

@@ -354,12 +354,16 @@ ListView.create({
 
 UI changes should **never** require rebuilding:
 
-```
-Traditional:  Change Code → Build → Test → Deploy → (iOS) App Store Wait
-              ────────────────────── 2-14 days ──────────────────────────
-
-ObjectUI:     Change Config → Refresh Page
-              ───────── 5 seconds ─────────
+```mermaid
+flowchart LR
+    subgraph T["Traditional — 2–14 days"]
+      direction LR
+      C1["Change Code"] --> B1["Build"] --> Te1["Test"] --> D1["Deploy"] --> A1["(iOS) App Store wait"]
+    end
+    subgraph O["ObjectUI — 5 seconds"]
+      direction LR
+      C2["Change Config"] --> R2["Refresh Page"]
+    end
 ```
 
 **Why:** Business requirements change daily. Code deployment cycles are weekly at best.

content/docs/references/cloud/app-store.mdx

@@ -21,10 +21,9 @@ installing, and managing marketplace apps from within ObjectOS.
 
 ## Customer Journey
 
-```
-
-Discover → Evaluate → Install → Configure → Use → Rate/Review → Manage
-
+```mermaid
+flowchart LR
+    Discover --> Evaluate --> Install --> Configure --> Use --> Rate["Rate / Review"] --> Manage
 ```
 
 ## Key Concepts

content/docs/references/cloud/developer-portal.mdx

@@ -11,10 +11,9 @@ Defines schemas for the developer-facing side of the marketplace ecosystem.
 
 Covers the complete developer journey:
 
-```
-
-Register → Create App → Develop → Validate → Build → Submit → Monitor → Iterate
-
+```mermaid
+flowchart LR
+    Register --> Create["Create App"] --> Develop --> Validate --> Build --> Submit --> Monitor --> Iterate
 ```
 
 ## Architecture Alignment

content/docs/references/cloud/marketplace.mdx

@@ -47,18 +47,12 @@ platform, and customers who install plugins.
 
 ## Platform Management Flow
 
-```
-
-1. Receive   → Accept submissions from verified publishers
-
-2. Scan      → Automated security scan and compatibility check
-
-3. Review    → Human review for quality and policy compliance
-
-4. Catalog   → Index in marketplace search catalog
-
-5. Monitor   → Track installs, ratings, issues, and enforce SLAs
-
+```mermaid
+flowchart LR
+    A["1 · Receive<br/>accept submissions from verified publishers"] --> B["2 · Scan<br/>automated security + compatibility check"]
+    B --> C["3 · Review<br/>human review for quality + policy"]
+    C --> D["4 · Catalog<br/>index in marketplace search"]
+    D --> E["5 · Monitor<br/>track installs, ratings, issues, SLAs"]
 ```
 
 <Callout type="info">

content/docs/references/data/seed-loader.mdx

@@ -21,20 +21,13 @@ relationship resolution, dependency ordering, and multi-pass insertion.
 
 ## Loading Flow
 
-```
-
-1. Build object dependency graph from field metadata (lookup/master_detail)
-
-2. Topological sort → determine insert order (parents before children)
-
-3. Pass 1: Insert/upsert records, resolve references via externalId
-
-4. Pass 2: Fill deferred references (circular/delayed dependencies)
-
-5. Validate & report unresolved references
-
-6. Return structured result with per-object stats
-
+```mermaid
+flowchart TD
+    A["1 · Build object dependency graph<br/>from field metadata (lookup / master_detail)"] --> B["2 · Topological sort<br/>→ insert order (parents before children)"]
+    B --> C["3 · Pass 1 — insert/upsert records,<br/>resolve references via externalId"]
+    C --> D["4 · Pass 2 — fill deferred references<br/>(circular / delayed dependencies)"]
+    D --> E["5 · Validate & report unresolved references"]
+    E --> F["6 · Return structured result<br/>with per-object stats"]
 ```
 
 <Callout type="info">

content/docs/references/kernel/package-upgrade.mdx

@@ -25,20 +25,13 @@ and rollback capabilities.
 
 ## Upgrade Flow
 
-```
-
-1. PreCheck    → Validate compatibility, check dependencies
-
-2. Plan        → Generate upgrade plan with metadata diff
-
-3. Snapshot    → Backup current state (metadata + customizations)
-
-4. Execute     → Apply new package metadata with 3-way merge
-
-5. Validate    → Run post-upgrade health checks
-
-6. Commit      → Finalize upgrade (or Rollback on failure)
-
+```mermaid
+flowchart LR
+    A["1 · PreCheck<br/>validate compatibility, deps"] --> B["2 · Plan<br/>upgrade plan + metadata diff"]
+    B --> C["3 · Snapshot<br/>backup metadata + customizations"]
+    C --> D["4 · Execute<br/>apply new metadata (3-way merge)"]
+    D --> E["5 · Validate<br/>post-upgrade health checks"]
+    E --> F["6 · Commit<br/>finalize (or Rollback on failure)"]
 ```
 
 <Callout type="info">