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

[os-zhuang]

Docs: mermaid support + statistics removal + full-corpus reader review

Follow-up to #2584/#2593. Three parts (one commit each):

1. Mermaid diagrams render (b1ec299)

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

2. Numeric statistics removed (8a3e5ca)

Count-style claims ("N field types", "N hook events", namespace tallies) drift from the implementation and don't help readers — replaced with qualitative descriptions across the landing page and module overviews.

3. Full-corpus persona review (f0f60a2)

Seven reader personas — first-time developer, schema modeler, logic author, API integrator, security admin, UI builder, AI-enabling admin, plugin developer, production SRE — each read every hand-written page in their area end-to-end and verified claims against source (packages/spec, packages/plugins/plugin-security/plugin-sharing, packages/rest, packages/objectql, packages/core, packages/cli, examples) before fixing. ~40 pages touched. The fixes that mattered most:

Would have broken your code:

• Every hook example taught ctx.input.doc.<field> — the engine passes a flatctx.input (installFlatInput); the documented pattern never worked. Fixed in hooks, kernel/events, error-handling-server, and the plugin tutorial.
• The plugin tutorial's manifest example omitted the required id (throws at .parse()), and its flagship example registered a kernel hook name that is never triggered — a reader shipped a silently dead plugin. Rewritten against the real engine.registerHook path.
• objects.mdx documented cdc, partitioning, and recordTypes config that ObjectSchema.create()hard-rejects; AutoNumber used the wrong key (format → autonumberFormat); many field props documented were pruned in the 2026-06 dead-surface cleanup.

Would have misconfigured your security (admin persona):

• Docs claimed the role hierarchy gives managers automatic visibility of subordinates' records — no such grant exists (verified in buildReadFilter); rewritten around the two real opt-in paths (sharing-rule recipients, readScope scope-depth grants).
• Owner-type sharing rules and group/guest recipients are declared but not enforced (seeder skips with a warning) — now labeled.
• FLS was described as fail-closed; actual semantics are default-visible for undeclared fields — corrected, plus a warning that an object with no sharingModel has no record-level filter at all.
• maskingRule/encryptionConfig were taught as live field-level features; the field wiring was pruned (never had a runtime consumer) — re-scoped to schema-shape status with the real channel (type: 'secret' + FLS).

Would have misled integrators/operators:

• Removed ADR-0019-deleted POST /workflow/.../approve|reject endpoints and invented webhook rate-limiting; realtime status stated honestly (in-process pub/sub; WS/SSE transport is plugin-provided, none ships open); error handling now documents the two real wire formats.
• Deployment: env-var table render repaired and completed (OS_SECRET_KEY, cluster vars); stale CLI file references and ~25 dead links fixed across deployment/protocol/releases.
• services.* runtime docs got a binding note: they are the contract surface; open-framework hooks reach the same capabilities via ctx.api / ctx.getService(...).

Verification

• check-doc-authoring clean (180 files); internal-link sweep: 0 broken /docs/... targets outside generated references
• Full next build passes; mermaid transformation verified in built HTML

Follow-ups surfaced by the review (not addressed here)

• Possible code bugs:unit_and_subordinates sharing recipient expands to zero users silently (sharing-rule-service.ts has no case for it); client analytics.meta(cube)/explain call routes the dispatcher doesn't serve; HookContextSchema doc-comment still says doc where the engine passes data; spec role.zod.ts comment repeats the manager-visibility misconception.
• Docs debt:releases/implementation-status.mdx self-contradicts (sharing/identity marked plugin-pending vs live elsewhere) and should be regenerated; no upgrade notes for v10/v11 though packages ship 11.x; troubleshooting page is dev-time only (no production incident runbook); auth token lifecycle for integrators is undocumented; relationships.mdx deserves a fuller rewrite (deleteBehavior, lookup-picker config); nameField (ADR-0079) has no first-class doc; the os init scaffold emits a bare object literal while docs brand that style deprecated (needs a product decision).

🤖 Generated with Claude Code

https://claude.ai/code/session_018r9mjpF7jr9BKdzEmUE4uZ

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jul 4, 2026 6:01pm