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

Author: claude

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/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>

content/docs/api/environment-routing.mdx

@@ -73,7 +73,7 @@ const client = new ObjectStackClient({
 
 const env = client.project('env_prod');
 
-await env.data.find('customer', { top: 20 });
+await env.data.find('customer', { limit: 20 });
 await env.meta.getItems('object');
 await env.packages.list();
 ```

content/docs/api/error-catalog.mdx

@@ -5,7 +5,7 @@ description: Complete reference for all ObjectStack error codes with causes, fix
 
 # Error Code Catalog
 
-ObjectStack uses a structured error system with **9 error categories** and **41+ standardized error codes**. Every error includes a machine-readable code, HTTP status mapping, and retry guidance.
+ObjectStack uses a structured error system with **9 error categories** and **51 standardized error codes**. Every error includes a machine-readable code, HTTP status mapping, and retry guidance.
 
 <Callout type="info">
 **Source:** `packages/spec/src/api/errors.zod.ts`  
@@ -391,7 +391,7 @@ import type { EnhancedApiError } from '@objectstack/spec/api';
 
 async function handleApiCall() {
   try {
-    const result = await client.records.create('task', { title: 'New Task' });
+    const result = await client.data.create('task', { title: 'New Task' });
     return result;
   } catch (error) {
     const apiError = error as EnhancedApiError;

content/docs/api/error-handling-client.mdx

@@ -8,7 +8,7 @@ description: Best practices for handling ObjectStack errors in client applicatio
 This guide covers best practices for handling ObjectStack API errors in client applications — from parsing error responses to displaying validation errors in forms and implementing retry strategies.
 
 <Callout type="info">
-**Error Format:** All ObjectStack API errors follow the `ErrorResponseSchema` structure. See [Wire Format](/docs/api/wire-format#7-error-response-format) for the full JSON shape.
+**Error Format:** The patterns in this guide target the spec error envelope (`ErrorResponseSchema`). Note that today's kernel REST data routes emit a flatter `{ error, code }` shape — see the [API Overview](/docs/api#error-handling) for the two wire formats in use and [Wire Format](/docs/api/wire-format#7-error-response-format) for full JSON examples; adapt the parser accordingly.
 </Callout>
 
 ---

content/docs/api/error-handling-server.mdx

@@ -77,8 +77,8 @@ object (imported from `@objectstack/spec/data`) with `object`, `events`
 (an array of lifecycle events such as `beforeInsert` / `afterUpdate`), and a
 `handler: async (ctx) => { ... }`. Errors thrown from a hook handler abort the
 operation and propagate to the API layer. The handler receives a `HookContext`:
-the pending record lives on `ctx.input.doc`, the pre-change snapshot on
-`ctx.previous`, and the persisted result (after hooks) on `ctx.result`.
+the pending record's fields are exposed directly on `ctx.input`, the pre-change
+snapshot on `ctx.previous`, and the persisted result (after hooks) on `ctx.result`.
 
 ### Before Hooks (Validation / Guard)
 
@@ -90,7 +90,7 @@ export const ValidateStatusTransition: Hook = {
   object: 'task',
   events: ['beforeUpdate'],
   handler: async (ctx) => {
-    const changes = ctx.input.doc as Record<string, any>;
+    const changes = ctx.input as Record<string, any>;
     const previous = ctx.previous ?? {};
 
     // Guard: prevent modifying completed tasks
@@ -182,7 +182,7 @@ export const ValidateTaskData: Hook = {
   object: 'task',
   events: ['beforeInsert'],
   handler: async (ctx) => {
-    const data = ctx.input.doc as Record<string, any>;
+    const data = ctx.input as Record<string, any>;
     const schema = z.object({
       title: z.string().min(1, 'Title is required').max(200),
       priority: z.enum(['low', 'medium', 'high', 'critical']),
@@ -218,7 +218,7 @@ export const TaskWriteWithLogging: Hook = {
   onError: 'abort',   // failure aborts the write (default); use 'log' to continue
   handler: async (ctx) => {
     try {
-      await runBusinessRules(ctx.input.doc);
+      await runBusinessRules(ctx.input);
     } catch (error) {
       const httpStatus = (error as AppError).httpStatus ?? 500;
       const logEntry = {
@@ -496,7 +496,7 @@ export const ValidateBusinessRules: Hook = {
   object: 'task',
   events: ['beforeInsert'],
   handler: async (ctx) => {
-    const result = safeParsePretty(TaskBusinessRules, ctx.input.doc);
+    const result = safeParsePretty(TaskBusinessRules, ctx.input);
     if (!result.success) {
       throw new AppError(
         'validation_error',

content/docs/api/index.mdx

@@ -14,7 +14,7 @@ ObjectStack exposes a fully typed REST API. All endpoints use JSON request/respo
 | Surface | Status in this repo |
 | :--- | :--- |
 | **REST** | ✅ Auto-generated from the protocol (`@objectstack/rest`) — CRUD, query, batch, metadata, packages |
-| **Realtime** | ✅ WebSocket subscriptions plus SSE streaming (`@objectstack/service-realtime`) |
+| **Realtime** | ⚠️ In-process pub/sub service (`@objectstack/service-realtime`, single-instance); the `/realtime/*` REST routes and WebSocket/SSE transport are plugin-provided — none ships in the open framework |
 | **MCP** | ✅ Objects and opted-in actions exposed as Model Context Protocol tools ([AI module](/docs/ai)) |
 | **GraphQL** | ⚠️ Route is wired but **bring-your-own service**: `/graphql` returns 501 unless an implementation of the `IGraphQLService` contract is registered — none ships in the open framework |
 | **OData** | ⚠️ Vocabulary only: REST list endpoints accept OData-style operators (e.g. `$top`), but there is no standalone OData endpoint |

content/docs/api/plugin-endpoints.mdx

@@ -33,14 +33,16 @@ The following endpoints become available when the corresponding plugin is instal
 | GET | `/workflow/:object/config` | Get workflow configuration |
 | GET | `/workflow/:object/:recordId/state` | Get record's workflow state |
 | POST | `/workflow/:object/:recordId/transition` | Execute state transition |
-| POST | `/workflow/:object/:recordId/approve` | Approve workflow step |
-| POST | `/workflow/:object/:recordId/reject` | Reject workflow step |
+
+Approve/reject are **not** workflow routes (ADR-0019): approval is a flow node, and decisions are recorded on the approvals runtime via `POST /approvals/requests/:id/approve` and `POST /approvals/requests/:id/reject`.
 
 ### Automation (`/automation`) — Plugin Required
 
 | Method | Endpoint | Description |
 |:-------|:---------|:------------|
-| POST | `/automation/trigger/:name` | Trigger an automation flow by name |
+| POST | `/automation/:name/trigger` | Trigger an automation flow by name (legacy alias: `/automation/trigger/:name`) |
+
+The automation dispatcher also exposes flow CRUD (`GET`/`POST /automation`, `GET`/`PUT`/`DELETE /automation/:name`) and run observability/resume routes — see [Durable pause & resume](/docs/automation/flows#durable-pause--resume-adr-0019).
 
 ### Views (`/ui`) — Plugin Required
 
@@ -60,7 +62,7 @@ The following endpoints become available when the corresponding plugin is instal
 | POST | `/realtime/disconnect` | Close connection |
 | POST | `/realtime/subscribe` | Subscribe to channel |
 | POST | `/realtime/unsubscribe` | Unsubscribe |
-| POST | `/realtime/presence` | Set presence |
+| PUT | `/realtime/presence/:channel` | Set presence |
 | GET | `/realtime/presence/:channel` | Get channel presence |
 
 ### Notifications (`/notifications`) — Plugin Required

content/docs/automation/approvals.mdx

@@ -130,5 +130,5 @@ Separating *who configures* from *who approves* from *as whom it runs* is the sa
 ## See also
 
 - Decision records: **ADR-0049** (`runAs`), **ADR-0066** (unified authorization).
-- Guide: [Business Logic](/docs/automation/hooks) (Flows, Approval Nodes); [Who can see data / automation / interface](/docs/permissions/access-recipes).
+- Guide: [Hooks](/docs/automation/hooks) and [Flows](/docs/automation/flows); [Who can see data / automation / interface](/docs/permissions/access-recipes).
 - Reference: [Flow](/docs/references/automation/flow), [Approval](/docs/references/automation/approval).