diff --git a/content/docs/ai/skills-reference.mdx b/content/docs/ai/skills-reference.mdx
index 928c3e5e10..c1cef10f81 100644
--- a/content/docs/ai/skills-reference.mdx
+++ b/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
diff --git a/content/docs/concepts/architecture.mdx b/content/docs/concepts/architecture.mdx
index 653e6138d8..96f76184cf 100644
--- a/content/docs/concepts/architecture.mdx
+++ b/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
```
diff --git a/content/docs/getting-started/build-with-claude-code.mdx b/content/docs/getting-started/build-with-claude-code.mdx
index 4add949061..76d21a73b6 100644
--- a/content/docs/getting-started/build-with-claude-code.mdx
+++ b/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
skills + AGENTS.md taught the rules"]
+ A --> V["os validate
the gate rejects silent mistakes"]
+ V --> C["You verify in the UI
Console = the human review surface"]
+ C --> I["Iterate"] --> M["MCP
app is AI-operable"]
```
- **Skills + `AGENTS.md`** meant the agent authored to the protocol, not from
diff --git a/content/docs/getting-started/index.mdx b/content/docs/getting-started/index.mdx
index e7418e505a..da6e34d8f0 100644
--- a/content/docs/getting-started/index.mdx
+++ b/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
in plain language"] --> B["Claude Code authors
the typed metadata"]
+ B --> G{"os validate
the gate"}
+ G -->|fails| B
+ G -->|passes| V["You verify in
the Console"]
+ V -->|iterate| A
+ V -->|ship| M["MCP — your app
is AI-operable"]
```
You say what you want; Claude Code (or Cursor, Copilot, …) writes the typed
diff --git a/content/docs/protocol/backward-compatibility.mdx b/content/docs/protocol/backward-compatibility.mdx
index 695c41e6b2..e7af5834ab 100644
--- a/content/docs/protocol/backward-compatibility.mdx
+++ b/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)"]
```
diff --git a/content/docs/protocol/objectos/lifecycle.mdx b/content/docs/protocol/objectos/lifecycle.mdx
index 04cc1a985d..965bf298ef 100644
--- a/content/docs/protocol/objectos/lifecycle.mdx
+++ b/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
diff --git a/content/docs/protocol/objectos/realtime-protocol.mdx b/content/docs/protocol/objectos/realtime-protocol.mdx
index 25c4f64902..1de66e9423 100644
--- a/content/docs/protocol/objectos/realtime-protocol.mdx
+++ b/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
(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:**
diff --git a/content/docs/protocol/objectui/index.mdx b/content/docs/protocol/objectui/index.mdx
index ade1737aa6..946bb1f3e2 100644
--- a/content/docs/protocol/objectui/index.mdx
+++ b/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.
diff --git a/content/docs/references/cloud/app-store.mdx b/content/docs/references/cloud/app-store.mdx
index 0077cbc064..8ccccfb6ac 100644
--- a/content/docs/references/cloud/app-store.mdx
+++ b/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
diff --git a/content/docs/references/cloud/developer-portal.mdx b/content/docs/references/cloud/developer-portal.mdx
index 6dd328f84e..142a6c4ded 100644
--- a/content/docs/references/cloud/developer-portal.mdx
+++ b/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
diff --git a/content/docs/references/cloud/marketplace.mdx b/content/docs/references/cloud/marketplace.mdx
index 025b13d553..47ddbdc459 100644
--- a/content/docs/references/cloud/marketplace.mdx
+++ b/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
accept submissions from verified publishers"] --> B["2 · Scan
automated security + compatibility check"]
+ B --> C["3 · Review
human review for quality + policy"]
+ C --> D["4 · Catalog
index in marketplace search"]
+ D --> E["5 · Monitor
track installs, ratings, issues, SLAs"]
```
diff --git a/content/docs/references/data/seed-loader.mdx b/content/docs/references/data/seed-loader.mdx
index 6986738a48..cd479c7a1f 100644
--- a/content/docs/references/data/seed-loader.mdx
+++ b/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
from field metadata (lookup / master_detail)"] --> B["2 · Topological sort
→ insert order (parents before children)"]
+ B --> C["3 · Pass 1 — insert/upsert records,
resolve references via externalId"]
+ C --> D["4 · Pass 2 — fill deferred references
(circular / delayed dependencies)"]
+ D --> E["5 · Validate & report unresolved references"]
+ E --> F["6 · Return structured result
with per-object stats"]
```
diff --git a/content/docs/references/kernel/package-upgrade.mdx b/content/docs/references/kernel/package-upgrade.mdx
index f1d3ca6423..ae99a8c1f0 100644
--- a/content/docs/references/kernel/package-upgrade.mdx
+++ b/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
validate compatibility, deps"] --> B["2 · Plan
upgrade plan + metadata diff"]
+ B --> C["3 · Snapshot
backup metadata + customizations"]
+ C --> D["4 · Execute
apply new metadata (3-way merge)"]
+ D --> E["5 · Validate
post-upgrade health checks"]
+ E --> F["6 · Commit
finalize (or Rollback on failure)"]
```