docs(site): mermaid rendering, stat removal, and full-corpus persona-review fixes (#2601)

* docs(site): render mermaid code fences as diagrams

Fumadocs was showing ```mermaid blocks (used on 7 pages: protocol
diagram, kernel architecture, data-flow, permissions matrix, field-type
decision tree, contracts, metadata-service) as plain code. Add a
client-side Mermaid component (theme-aware, falls back to the source
block on bad syntax) and a remark plugin that rewrites mermaid fences
into <Mermaid chart=.../> — no content changes required.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018r9mjpF7jr9BKdzEmUE4uZ

* docs(site): drop numeric stats; first round of persona-review fixes

Per review feedback, remove count-style statistics from module overviews
and landing (field type counts, hook event counts, namespace tallies) in
favor of qualitative descriptions — counts drift from the implementation
and don't help readers.

Also lands the first fixes from the reader-persona review pass:
- ai/actions-as-tools: remove walkthrough of HITL demo tests that do not
  exist in examples/app-todo (only mcp-actions/seed tests exist); point
  at the real delete_completed danger action instead
- ai/agents, ai/natural-language-queries: fix orphaned 'see above'
  references and same-page anchors that now live on sibling pages

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018r9mjpF7jr9BKdzEmUE4uZ

* docs(site): full-corpus persona review — fix what real readers would hit

Seven reader-persona passes (first-time developer, schema modeler, logic
author + API integrator, security admin, UI builder + AI admin, plugin
developer, production SRE) read every hand-written page and verified
claims against source before fixing. Highlights:

- hooks: ctx.input is flat (installFlatInput) — the documented
  ctx.input.doc pattern never worked; fixed across hooks, events,
  error-handling-server, and the plugin tutorial
- plugin tutorial: manifest example was missing required id (threw at
  parse) and registered a kernel hook name that never fires — a reader
  shipped a silently dead plugin; rewritten against engine.registerHook
- permissions: removed the false implicit manager-visibility claim
  (role hierarchy grants nothing by itself); owner-type sharing rules
  and group/guest recipients marked declared-but-unenforced; FLS
  semantics corrected to default-visible for undeclared fields;
  no-sharingModel = no record filter warning added
- data modeling: removed invented cdc/partitioning/recordTypes object
  config (schema hard-rejects), phantom field props (pruned 2026-06),
  wrong autonumber key; new expand (related records) query section
- api: removed ADR-0019-deleted workflow approve/reject endpoints,
  invented webhook rate-limiting; realtime status stated honestly
  (in-process pub/sub; WS/SSE transport plugin-provided); error
  handling documents the two real wire formats
- protocol: maskingRule/encryptionConfig sections re-scoped to their
  real status (System schemas exist; field wiring pruned, channel is
  type:'secret' + FLS)
- deployment: env-var table repaired and completed (OS_SECRET_KEY,
  cluster vars), stale CLI paths and ten dead links fixed
- onboarding: REST route /api/v1/data/:object, send_email→notify node,
  npx os pointers, nine dead ADR links
- runtime-services: binding note — services.* is the contract surface;
  open-framework hooks use ctx.api / ctx.getService

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018r9mjpF7jr9BKdzEmUE4uZ

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

apps/docs/components/mermaid.tsx

@@ -0,0 +1,60 @@
+'use client';
+
+import { useEffect, useId, useState } from 'react';
+import { useTheme } from 'next-themes';
+
+/**
+ * Client-side Mermaid renderer. Code fences with the `mermaid` language are
+ * rewritten to <Mermaid chart="..."/> by the remark plugin in source.config.ts,
+ * so authors keep writing standard ```mermaid blocks.
+ */
+export function Mermaid({ chart }: { chart: string }) {
+  const id = useId();
+  const [svg, setSvg] = useState('');
+  const { resolvedTheme } = useTheme();
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function render() {
+      const { default: mermaid } = await import('mermaid');
+      mermaid.initialize({
+        startOnLoad: false,
+        securityLevel: 'strict',
+        fontFamily: 'inherit',
+        theme: resolvedTheme === 'dark' ? 'dark' : 'default',
+      });
+      try {
+        const rendered = await mermaid.render(
+          // mermaid requires a DOM-safe element id
+          `mermaid-${id.replace(/[^a-zA-Z0-9]/g, '')}`,
+          chart,
+        );
+        if (!cancelled) setSvg(rendered.svg);
+      } catch {
+        // Leave the diagram source visible instead of a blank hole on bad syntax.
+        if (!cancelled) setSvg('');
+      }
+    }
+
+    void render();
+    return () => {
+      cancelled = true;
+    };
+  }, [chart, id, resolvedTheme]);
+
+  if (!svg) {
+    return (
+      <pre className="overflow-x-auto rounded-lg border p-4 text-sm">
+        <code>{chart}</code>
+      </pre>
+    );
+  }
+
+  return (
+    <div
+      className="my-6 flex justify-center overflow-x-auto [&_svg]:max-w-full"
+      dangerouslySetInnerHTML={{ __html: svg }}
+    />
+  );
+}

apps/docs/mdx-components.tsx

@@ -1,9 +1,11 @@
 import defaultMdxComponents from 'fumadocs-ui/mdx';
 import type { MDXComponents } from 'mdx/types';
+import { Mermaid } from '@/components/mermaid';
 
 export function getMDXComponents(components?: MDXComponents): MDXComponents {
   return {
     ...defaultMdxComponents,
+    Mermaid,
     ...components,
   };
 }

apps/docs/package.json

@@ -17,10 +17,13 @@
     "fumadocs-mdx": "15.0.12",
     "fumadocs-ui": "16.10.5",
     "lucide-react": "^1.22.0",
+    "mermaid": "^11.16.0",
     "next": "16.2.9",
+    "next-themes": "^0.4.6",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
-    "tailwind-merge": "^3.6.0"
+    "tailwind-merge": "^3.6.0",
+    "unist-util-visit": "^5.1.0"
   },
   "devDependencies": {
     "@objectstack/spec": "workspace:*",

apps/docs/source.config.ts

@@ -2,6 +2,25 @@ import { defineConfig, defineDocs } from 'fumadocs-mdx/config';
 import { metaSchema, pageSchema } from 'fumadocs-core/source/schema';
 import { z } from 'zod';
 import path from 'node:path';
+import { visit } from 'unist-util-visit';
+
+/**
+ * Rewrite ```mermaid code fences into <Mermaid chart="..."/> elements so
+ * diagrams render as SVG (components/mermaid.tsx) instead of code blocks.
+ */
+function remarkMermaid() {
+  return (tree: any) => {
+    visit(tree, 'code', (node: any, index: number | undefined, parent: any) => {
+      if (node.lang !== 'mermaid' || !parent || index === undefined) return;
+      parent.children[index] = {
+        type: 'mdxJsxFlowElement',
+        name: 'Mermaid',
+        attributes: [{ type: 'mdxJsxAttribute', name: 'chart', value: node.value }],
+        children: [],
+      };
+    });
+  };
+}
 
 export const docs = defineDocs({
   dir: path.resolve(process.cwd(), '../../content/docs'),
@@ -31,6 +50,6 @@ export const blog = defineDocs({
 
 export default defineConfig({
   mdxOptions: {
-    // MDX options
+    remarkPlugins: (v) => [...v, remarkMermaid],
   },
 });

content/docs/ai/actions-as-tools.mdx

@@ -116,21 +116,13 @@ The queue is exposed via four REST endpoints (`GET`, `GET/:id`, `POST/:id/approv
 
 ### End-to-end example
 
-Two runnable demos live in `examples/app-todo/test/`:
-
-- **`ai-hitl.test.ts`** — drives the tool registry directly (no LLM dependency). Asserts the full lifecycle: `variant:'danger'` action registered as a tool → invocation returns `pending_approval` without executing → row persisted → `approvePendingAction(id, actor)` re-runs the handler → row transitions to `executed`. Reject path is also covered.
-
-  ```bash
-  pnpm --filter @example/app-todo test:hitl
-  ```
-
-- **`ai-hitl-llm.test.ts`** — same scenario but with a real model behind Vercel AI Gateway. The LLM is given the auto-generated tool description and asked to "delete all completed tasks"; the framework returns `pending_approval` so the model summarises the wait instead of retrying. After we call approve from the test, the deletion completes.
-
-  ```bash
-  AI_GATEWAY_API_KEY=vck_... pnpm --filter @example/app-todo test:hitl:llm
-  ```
-
-  Gated on `AI_GATEWAY_API_KEY` (or `OPENAI_API_KEY`); exits 0 with a notice if no key is provided, so it can be wired into CI without leaking spend.
+The full lifecycle: a `variant:'danger'` action registered as a tool →
+invocation returns `pending_approval` without executing → row persisted →
+`approvePendingAction(id, actor)` re-runs the handler → row transitions to
+`executed` (the reject path mirrors it). The todo example's
+`delete_completed` action (`examples/app-todo/src/actions/task.actions.ts`)
+is authored exactly for this: `variant: 'danger'` + `confirmText` route it
+through the approval queue.
 
 A trimmed view of the integration path:
 

content/docs/ai/agents.mdx

@@ -18,7 +18,8 @@ is in — the user never picks from a roster:
 
 Both agents are part of the **cloud / Enterprise** in-UI AI runtime (cloud ADR-0025).
 The **open edition** ships neither — it uses `@objectstack/mcp` (BYO-AI) for data
-query and source-mode authoring instead (see the note above).
+query and source-mode authoring instead (see the callout in the
+[AI Overview](/docs/ai)).
 
 Within the cloud / EE runtime there is no per-turn intent classifier and no agent
 dropdown: the surface binds the agent (data console → `ask`, Studio → `build`). A
@@ -64,7 +65,7 @@ them via the chat endpoint.
 <Callout type="info">
 Agent tools are **references** to existing Actions, Flows, or queries — you do
 not define ad-hoc tool names with inline parameter schemas here. See
-[Actions as Tools](#actions-as-tools-explicit-opt-in) for how an Action becomes
+[Actions as Tools](/docs/ai/actions-as-tools) for how an Action becomes
 LLM-callable.
 </Callout>
 
@@ -219,7 +220,7 @@ Use the data tools to query records and aggregate metrics.`,
   },
 
   // Built-in data tools (query_records / get_record / aggregate_data) are
-  // available to agents automatically once registered — see "Actions as Tools".
+  // available to agents automatically once registered — see "Natural Language Queries".
   tools: [
     { type: 'flow', name: 'analyze_pipeline', description: 'Analyze sales pipeline health' },
   ],

content/docs/ai/chatbot-integration.mdx

@@ -26,12 +26,13 @@ This guide maps every chatbot configuration knob to its framework endpoint
 so you can drop the plugin into an app without reverse-engineering the
 contract.
 
-## 1. Enable the AI tier on the framework side
+## 1. Enable the AI tier on the backend
 
-The `default` and `full` plugin tier presets both include the `ai`
-capability, so `objectstack dev` boots the AI services unless you opt out
-with `--preset minimal`. Provide a Vercel AI Gateway model and key via env
-vars:
+On a cloud / EE dev host (where `@objectstack/service-ai` is available —
+see the callout above), the `default` and `full` plugin tier presets both
+include the `ai` capability, so `objectstack dev` boots the AI services
+unless you opt out with `--preset minimal`. Provide a Vercel AI Gateway
+model and key via env vars:
 
 ```bash
 AI_GATEWAY_API_KEY=vck_*** \

content/docs/ai/knowledge-rag.mdx

@@ -40,7 +40,10 @@ kernel.use(new KnowledgeMemoryPlugin());
 // kernel.use(new KnowledgeRagflowPlugin({ endpoint, apiKey }));
 ```
 
-Then register the AI tool so agents can call it:
+Then register the AI tool so agents can call it. (This step uses
+`@objectstack/service-ai`, i.e. the **cloud / Enterprise** in-UI AI runtime —
+see the callout in the [AI Overview](/docs/ai). The Knowledge Protocol itself
+and the adapter plugins above ship in the open framework.)
 
 ```ts
 import { registerKnowledgeTools } from '@objectstack/service-ai';

content/docs/ai/natural-language-queries.mdx

@@ -7,6 +7,11 @@ description: How agents query live data through the built-in data tools (query_r
 
 Part of the [AI module](/docs/ai) — how natural-language questions become ObjectQL queries at runtime.
 
+The data tools described here ship with `@objectstack/service-ai`, i.e. the
+**cloud / Enterprise** in-UI AI runtime (see the callout in the
+[AI Overview](/docs/ai)). On the open edition, point your own AI at the same
+objects and queries through `@objectstack/mcp` instead.
+
 Agents query your data through the built-in **data tools** —
 `query_records`, `get_record`, and `aggregate_data` — which the LLM calls with
 structured arguments. These run as ordinary [ObjectQL](/docs/protocol/objectql) queries over

content/docs/api/client-sdk.mdx

@@ -122,7 +122,7 @@ The `@objectstack/client` SDK aims to implement the ObjectStack API protocol spe
 | **storage** | ✅ | 2 | File upload & download |
 | **i18n** | ✅ | 3 | Internationalization |
 | **notifications** | 🟡 | 7 | Legacy notification helpers; receipt/inbox cut-over pending |
-| **realtime** | ✅ | 6 | WebSocket subscriptions |
+| **realtime** | ✅ | 6 | Connection/subscription/presence calls (server transport is plugin-provided) |
 | **ai** | ✅ | 3 | AI services (NLQ, suggest, insights) |
 
 <Callout type="info">
@@ -553,18 +553,18 @@ For detailed information about the client's protocol implementation:
 
 <Cards>
   <Card 
-    href="./api-reference" 
-    title="API Reference"
+    href="/docs/api/data-api" 
+    title="Data API"
     description="Complete REST endpoint documentation"
   />
   <Card 
-    href="./kernel-services" 
+    href="/docs/kernel/services-checklist" 
     title="Kernel Services"
     description="Service checklist and plugin development guide"
   />
   <Card 
-    href="../references/api/protocol" 
+    href="/docs/references/api/protocol" 
     title="Protocol Types"
-    description="All 57 Zod protocol schemas"
+    description="The Zod protocol schemas"
   />
 </Cards>