docs: finish implementation-accuracy audit — durable reference grouping + hand-written doc sync (#1880) (#3243)

Wave 1: 164/164 hand-written docs audited + adversarially verified (335 evidence-backed fixes across 116 docs, 14 verifier repairs). Wave 2.1: durable reference-sidebar grouping in build-docs.ts. Wave 2.2: ui/view describe strings + generator verified. Follow-ups filed: #3244, #3276, #3277, #3278.

Author: os-zhuang

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

@@ -237,7 +237,8 @@ migrations) that genuinely need full authority opt in explicitly with
 never the consequence of a forgotten field.
 
 ```typescript
-await aiService.chatWithTools(messages, tools, {
+await aiService.chatWithTools(messages, {
+  tools,
   toolExecutionContext: {
     actor: {
       id: currentUser.id,

content/docs/ai/connect-mcp.mdx

@@ -68,7 +68,8 @@ copy-paste-ready connect snippets per client), or over REST:
 
 ```bash
 curl -b cookies.txt -X POST https://your-deployment.example.com/api/v1/keys
-# → { "key": "osk_..." }  — shown once; store it in your secret manager
+# → { "success": true, "data": { "key": "osk_...", "prefix": "osk_...", "name": "API Key" } }
+#   the raw key is shown once — store it in your secret manager
 ```
 
 Send it on every request in any of three equivalent forms:
@@ -87,11 +88,12 @@ run insecurely.
 
 ## What the agent gets
 
-Ten data and action tools, generated from your metadata:
+Eleven tools, generated from your metadata:
 
 | Tool | What it does |
 |:---|:---|
 | `list_objects` / `describe_object` | Discover which objects exist and their fields |
+| `validate_expression` | Check a CEL expression against an object's schema before authoring it into a formula, validation, or flow condition |
 | `query_records` / `get_record` | Read data (list queries are capped at 50 rows per page by default) |
 | `aggregate_records` | Grouped aggregation (registered when the active driver supports it) |
 | `create_record` / `update_record` / `delete_record` | Write data |

content/docs/ai/index.mdx

@@ -70,7 +70,7 @@ flowchart TD
 
 ✅ **DO:**
 - Declare knowledge sources via the Knowledge Protocol and pick the adapter (`memory`, `ragflow`, custom) that fits your data
-- Rely on the built-in data tools (`query_records` / `get_record` / `aggregate_data`) for live record access
+- Rely on the built-in data tools (`query_records` / `get_record` / `aggregate_records`) for live record access
 - Let permission-aware retrieval and RLS scope what each user's agent can see
 - Keep indexed objects in sync via the protocol's event sync
 
@@ -165,7 +165,7 @@ Server-side, the same flow runs through `chatWithTools`, threading the
 end-user's `ExecutionContext` so tool calls respect row-level security:
 
 ```typescript
-const reply = await aiService.chatWithTools(messages, tools, {
+const reply = await aiService.chatWithTools(messages, {
   toolExecutionContext: {
     actor: { id: currentUser.id, name: currentUser.displayName, positions: currentUser.positions, permissions: currentUser.permissions },
     conversationId,

content/docs/api/client-sdk.mdx

@@ -17,7 +17,7 @@ The `@objectstack/client` is the official TypeScript client for ObjectStack. It
 - **Batch Operations**: Efficient bulk create/update/upsert/delete with transaction support
 - **Query Builder**: Programmatic query construction with `createQuery()` and `createFilter()`
 - **Standardized Errors**: Machine-readable error codes with retry guidance
-- **Protocol Compliant**: Implements the core API namespaces defined in `@objectstack/spec`, plus additional namespaces (approvals, feed, organizations, projects/environments)
+- **Protocol Compliant**: Implements the core API namespaces defined in `@objectstack/spec`, plus additional namespaces (approvals, organizations, projects/environments)
 
 ## Installation
 
@@ -76,7 +76,7 @@ async function main() {
 When you call `client.connect()`, the client:
 
 1. Probes `/api/v1/discovery` first, then falls back to `{origin}/.well-known/objectstack`
-2. Parses the discovery response including `routes`, `features`, and `services`
+2. Parses the discovery response including `routes`, `capabilities`, and `services`
 3. Configures all API route paths dynamically
 
 ```typescript
@@ -104,7 +104,7 @@ if (discovery.services?.auth?.enabled) {
 
 ## Protocol Coverage
 
-The `@objectstack/client` SDK aims to implement the ObjectStack API protocol specification. The core namespaces are listed below; the client also exposes additional namespaces (`approvals`, `feed`, `organizations`, `oauth`, `projects`/environments) — see [`index.ts`](https://github.com/objectstack-ai/framework/blob/main/packages/client/src/index.ts) for the full surface:
+The `@objectstack/client` SDK aims to implement the ObjectStack API protocol specification. The core namespaces are listed below; the client also exposes additional namespaces (`approvals`, `organizations`, `oauth`, `projects`/environments) — see [`index.ts`](https://github.com/objectstack-ai/framework/blob/main/packages/client/src/index.ts) for the full surface:
 
 | Namespace | Status | Methods | Purpose |
 |:----------|:------:|:--------|:--------|

content/docs/api/data-api.mdx

@@ -197,8 +197,9 @@ or the analytics service's `cubes` config) — a cube referenced by a query that
 yet registered is lazily auto-inferred from that query's shape, but metadata isn't
 proactively generated for every object.
 
-**Response**: Array of cube definitions with measures and dimensions (time-based
-dimensions are `dimensions` entries with `type: "time"`).
+**Response**: `{ success: true, data: [...] }` where `data` is an array of cube
+definitions with measures and dimensions (time-based dimensions are `dimensions`
+entries with `type: "time"`).
 
 ### `POST /analytics/sql`
 

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

@@ -202,8 +202,9 @@ export const ValidateTaskData: Hook = {
 ## 4. Error Logging and Monitoring
 
 There is no global `onError` lifecycle event — the hook `HookEvent` enum only
-covers `before*` / `after*` of `find`, `insert`, `update`, `delete` (and their
-bulk variants). Each `Hook` does expose an `onError` *strategy* field
+covers `before*` / `after*` of `find`, `insert`, `update`, `delete`. Bulk
+(`multi: true`) writes fire these same events, not separate `*Many` variants.
+Each `Hook` does expose an `onError` *strategy* field
 (`'abort'` — the default — or `'log'`) that decides whether a handler failure
 aborts the operation or is merely logged. For structured error logging, wrap the
 risky work in a try/catch inside the handler and log there:

content/docs/api/index.mdx

@@ -105,7 +105,7 @@ Returns the full discovery manifest.
 **Response**:
 ```json
 {
-  "version": "1.0.0",
+  "version": "v1",
   "apiName": "ObjectStack API",
   "routes": {
     "data": "/api/v1/data",
@@ -124,7 +124,7 @@ Returns the full discovery manifest.
     "auth": { "enabled": false, "status": "unavailable", "message": "Install plugin-auth to enable" }
   },
   "capabilities": {
-    "feed": { "enabled": false },
+    "cron": { "enabled": false },
     "automation": { "enabled": false },
     "search": { "enabled": false }
   }

content/docs/api/plugin-endpoints.mdx

@@ -28,6 +28,10 @@ The following endpoints become available when the corresponding plugin is instal
 
 ### Workflow (`/workflow`) — Plugin Required
 
+<Callout type="warn">
+Not yet mounted. These routes are declared in the API protocol but the core dispatcher registers no `/workflow` handler and no bundled plugin provides a `workflow` service (only an in-memory dev stub), so they return **404** today. `discovery.services.workflow` reports `unavailable` in a standard install.
+</Callout>
+
 | Method | Endpoint | Description |
 |:-------|:---------|:------------|
 | GET | `/workflow/:object/config` | Get workflow configuration |
@@ -46,6 +50,10 @@ The automation dispatcher also exposes flow CRUD (`GET`/`POST /automation`, `GET
 
 ### Views (`/ui`) — Plugin Required
 
+<Callout type="warn">
+Not yet mounted. The `/ui/views` CRUD routes are declared in the API protocol but no handler is registered for them, so they return **404** today (and the `/api/v1/ui` prefix is itself deprecated in favour of `/api/v1/meta/view`). The always-available view **resolver** is a separate route — see the note below.
+</Callout>
+
 | Method | Endpoint | Description |
 |:-------|:---------|:------------|
 | GET | `/ui/views/:object` | List views for an object |
@@ -60,6 +68,10 @@ The auto-generated (non-CRUD) view resolver `GET /ui/view/:object/:type` is alwa
 
 ### Realtime (`/realtime`) — Plugin Required
 
+<Callout type="warn">
+Not implemented. There is no realtime HTTP or WebSocket surface: `@objectstack/service-realtime` is an in-process pub/sub bus consumed via `kernel.getService('realtime')`, not over HTTP. The dispatcher has no `/realtime` branch, discovery deliberately omits the route (`features.websockets` is `false`), and the routes below would return **404** (ADR-0076 D12). They document the planned protocol shape only.
+</Callout>
+
 | Method | Endpoint | Description |
 |:-------|:---------|:------------|
 | POST | `/realtime/connect` | Establish WebSocket/SSE connection |

content/docs/api/wire-format.mdx

@@ -254,10 +254,6 @@ The response is the `DeleteDataResponse` envelope: `{ object, id, success }`.
 }
 ```
 
-<Callout type="info">
-**Soft Delete:** If the object enables soft delete (`softDelete: { enabled: true }` in its definition), the record is moved to the trash / recycle bin instead of being permanently deleted.
-</Callout>
-
 ---
 
 ## 6. Get Metadata
@@ -365,7 +361,7 @@ Field-level failures carry a `fields` array.
 
 ```json
 {
-  "error": "[Security] Access denied: operation 'update' on object 'task' is not permitted for roles [standard_user]",
+  "error": "[Security] Access denied: operation 'update' on object 'task' is not permitted for positions [standard_user]",
   "code": "PERMISSION_DENIED",
   "object": "task"
 }

content/docs/automation/approvals.mdx

@@ -24,7 +24,7 @@ A flow declares `runAs` (ADR-0049), and for approvals this is the decision that
 - `runAs: 'user'` (default) — the flow's data operations run as the **submitter**, respecting their RLS. Good when the flow only touches records the submitter can already see.
 - `runAs: 'system'` — **elevated**, bypasses RLS. Needed when the flow must read/write records the submitter can't (e.g. post to a ledger, notify an approver who owns rows the submitter can't see). Declare it **explicitly** so the elevation is visible, not accidental.
 
-A schedule-triggered escalation has no triggering user — so it must be `system` to act at all.
+A schedule-triggered escalation has no triggering user, so under the default `runAs: 'user'` its data operations run **unscoped** (elevated, RLS-bypassing) anyway — declare `system` to make that elevation explicit and intended rather than an implicit fail-open (the engine warns, and `os lint` flags the bare shape as `flow-schedule-runas-unscoped`).
 
 ### 3. The approval node