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

Author: claude

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/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/automation/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: Automation
-description: 18 hook events, 20+ extensible flow node types, scheduled flows, approvals, and durable webhooks — the process engine that reacts to your data.
+description: Hooks, flows, workflows, approvals, scheduled jobs, and durable webhooks — the process engine that reacts to your data.
 ---
 
 # Automation
@@ -27,8 +27,8 @@ export const OpportunityStageHook: Hook = {
 
 ## The building blocks
 
-- **Hooks** intercept **18 lifecycle events** — before/after each of find, findOne, count, aggregate, insert, update, delete, updateMany, deleteMany. Hooks support priority ordering, fire-and-forget `async` mode, CEL `condition` guards, and a `retryPolicy` with backoff ([Hooks](/docs/automation/hooks)).
-- **Flows** are node-based processes with **20 built-in node types** (decision, loop, create/update/delete record, http, notify, script, screen, wait, subflow, parallel/join gateways, …) — and the set is **registry-extensible**: plugins can contribute new node types via `registerNodeExecutor`. Flows launch on record changes, on a schedule, from a screen, or via API ([Flows](/docs/automation/flows)).
+- **Hooks** intercept every record operation with before/after events — reads, writes, deletes, and their bulk variants. Hooks support priority ordering, fire-and-forget `async` mode, CEL `condition` guards, and a `retryPolicy` with backoff ([Hooks](/docs/automation/hooks)).
+- **Flows** are node-based processes built from nodes like decision, loop, record operations, http, notify, script, screen, wait, subflow, and parallel/join gateways — and the set is **registry-extensible**: plugins can contribute new node types via `registerNodeExecutor`. Flows launch on record changes, on a schedule, from a screen, or via API ([Flows](/docs/automation/flows)).
 - **Workflows** model a record's lifecycle as a **finite state machine**: states, transitions, and guards ([Workflows](/docs/automation/workflows)).
 - **Approvals** are flow nodes with approver resolution, approve/reject decisions, and escalation ([Approvals](/docs/automation/approvals)).
 - **Webhooks** deliver events to external systems through a **durable outbox** — exponential/linear/fixed retry with dead-lettering, HMAC signing, and an admin redeliver endpoint ([Webhook Delivery](/docs/automation/webhooks)).
@@ -39,7 +39,7 @@ Rule of thumb: model *state* with workflows, model *steps* with flows, use hooks
 ## What's in this module
 
 <Cards>
-  <Card href="/docs/automation/hooks" title="Hooks" description="18 before/after events on record operations" />
+  <Card href="/docs/automation/hooks" title="Hooks" description="Before/after events on record operations" />
   <Card href="/docs/automation/hook-bodies" title="Hook & Action Bodies (L1/L2)" description="The two authoring levels for hook logic" />
   <Card href="/docs/automation/flows" title="Flows" description="Node-based automation, screen flows, scheduled flows" />
   <Card href="/docs/automation/workflows" title="Workflows" description="State-machine lifecycle modeling" />

content/docs/data-modeling/field-types.mdx

@@ -1,11 +1,11 @@
 ---
 title: Field Type Gallery
-description: Complete reference for all 48 ObjectStack field types with per-type configuration properties
+description: Complete reference for every ObjectStack field type with per-type configuration properties
 ---
 
 # Field Type Gallery
 
-ObjectStack provides **49 field types** covering every data modeling need — from basic text and numbers to AI vectors and rich media. This guide organizes them by category with per-type configuration details.
+ObjectStack provides a **comprehensive set of field types** covering every data modeling need — from basic text and numbers to AI vectors and rich media. This guide organizes them by category with per-type configuration details.
 
 <Callout type="info">
 **Source:** `packages/spec/src/data/field.zod.ts`  
@@ -24,7 +24,6 @@ Single-line plain text input.
 | `maxLength` | `number` | — | Maximum character length |
 | `minLength` | `number` | — | Minimum character length |
 | `format` | `string` | — | Validation format pattern |
-| `caseSensitive` | `boolean` | — | Whether text comparisons are case-sensitive |
 
 ```typescript
 { name: 'first_name', label: 'First Name', type: 'text', maxLength: 100 }
@@ -303,10 +302,19 @@ Reference to a record in another object (foreign key).
 |:---|:---|:---|:---|
 | `reference` | `string` | **required** | Target object name (snake_case) |
 | `referenceFilters` | `string[]` | — | Filters applied to lookup dialogs (e.g. `"active = true"`) |
-| `deleteBehavior` | `'restrict' \| 'cascade' \| 'set_null'` | `'set_null'` | Behavior when referenced record is deleted |
+| `deleteBehavior` | `'restrict' \| 'cascade' \| 'set_null'` | `'set_null'` | Behavior when referenced record is deleted (a *required* lookup left at the default `set_null` is escalated to `restrict`, since a NOT NULL foreign key cannot be cleared) |
 
 ```typescript
-{ name: 'assigned_to', label: 'Assigned To', type: 'lookup', reference: 'user' }
+{ name: 'company', label: 'Company', type: 'lookup', reference: 'account' }
+```
+
+### `user`
+Person picker — a lookup specialized to the built-in `sys_user` object. Stored identically to `lookup` (foreign key to `sys_user.id`; `multiple: true` stores an array) and resolved through the same `$expand` machinery. Supports `defaultValue: 'current_user'` to stamp the acting user's id on insert.
+
+```typescript
+Field.user({ label: 'Assignee' })
+Field.user({ label: 'Watchers', multiple: true })
+Field.user({ label: 'Owner', defaultValue: 'current_user' })
 ```
 
 ### `master_detail`
@@ -419,15 +427,16 @@ Audio file attachment.
 ## Computed Types
 
 ### `formula`
-Calculated field using an expression.
+Calculated field using a CEL expression (see [Expressions](/docs/data-modeling/formulas)).
 
 | Property | Type | Default | Description |
 |:---|:---|:---|:---|
-| `expression` | `string` | **required** | Calculation expression |
-| `cached` | `object` | — | Cache settings for computed result |
+| `expression` | `string \| Expression` | **required** | CEL calculation expression |
+| `returnType` | `'number' \| 'text' \| 'boolean' \| 'date'` | — | Declared value type of the computed result |
+| `dependencies` | `string[]` | — | Fields the formula depends on |
 
 ```typescript
-{ name: 'total', label: 'Total', type: 'formula', expression: 'quantity * unit_price' }
+{ name: 'total', label: 'Total', type: 'formula', expression: 'record.quantity * record.unit_price', returnType: 'number' }
 ```
 
 ### `summary`
@@ -497,23 +506,14 @@ Name-keyed map of embedded sub-objects (`Record<string, SubObject>`). Insertion
 ## Enhanced Types
 
 ### `location`
-Geographic coordinates with optional map display.
-
-| Property | Type | Default | Description |
-|:---|:---|:---|:---|
-| `displayMap` | `boolean` | — | Show interactive map |
-| `allowGeocoding` | `boolean` | — | Enable address-to-coordinates conversion |
+Geographic coordinates. Stored as `{ latitude, longitude, altitude?, accuracy? }` (latitude −90..90, longitude −180..180). No per-type config properties.
 
 ```typescript
-{ name: 'headquarters', label: 'Location', type: 'location', displayMap: true, allowGeocoding: true }
+{ name: 'headquarters', label: 'Location', type: 'location' }
 ```
 
 ### `address`
-Structured postal address.
-
-| Property | Type | Default | Description |
-|:---|:---|:---|:---|
-| `addressFormat` | `'us' \| 'uk' \| 'international'` | — | Address format template |
+Structured postal address. Stored as `{ street, city, state, postalCode, country, countryCode, formatted }` (all parts optional). No per-type config properties.
 
 ```typescript
 { name: 'billing_address', label: 'Billing Address', type: 'address' }
@@ -525,11 +525,9 @@ Source code with syntax highlighting.
 | Property | Type | Default | Description |
 |:---|:---|:---|:---|
 | `language` | `string` | — | Programming language for highlighting |
-| `theme` | `string` | — | Editor theme |
-| `lineNumbers` | `boolean` | — | Show line numbers |
 
 ```typescript
-{ name: 'snippet', label: 'Code Snippet', type: 'code', language: 'typescript', lineNumbers: true }
+{ name: 'snippet', label: 'Code Snippet', type: 'code', language: 'typescript' }
 ```
 
 ### `json`
@@ -540,28 +538,23 @@ Raw JSON data.
 ```
 
 ### `color`
-Color picker with format options.
-
-| Property | Type | Default | Description |
-|:---|:---|:---|:---|
-| `colorFormat` | `'hex' \| 'rgb' \| 'rgba' \| 'hsl'` | — | Color value format |
-| `allowAlpha` | `boolean` | — | Allow alpha transparency |
-| `presetColors` | `string[]` | — | Preset color palette |
+Color picker. Stores the color value as a string. No per-type config properties.
 
 ```typescript
-{ name: 'brand_color', label: 'Brand Color', type: 'color', colorFormat: 'hex', presetColors: ['#FF0000', '#00FF00', '#0000FF'] }
+{ name: 'brand_color', label: 'Brand Color', type: 'color' }
 ```
 
 ### `rating`
 Star rating input.
 
 | Property | Type | Default | Description |
 |:---|:---|:---|:---|
-| `maxRating` | `number` | `5` | Maximum rating value |
-| `allowHalf` | `boolean` | `false` | Allow half-star ratings |
+| `max` | `number` | `5` | Maximum rating value (set by the `Field.rating(max)` factory) |
 
 ```typescript
-{ name: 'satisfaction', label: 'Rating', type: 'rating', maxRating: 5, allowHalf: true }
+{ name: 'satisfaction', label: 'Rating', type: 'rating', max: 5 }
+// or with the factory:
+// satisfaction: Field.rating(5, { label: 'Rating' })
 ```
 
 ### `slider`
@@ -571,12 +564,10 @@ Range slider input.
 |:---|:---|:---|:---|
 | `min` | `number` | — | Minimum value |
 | `max` | `number` | — | Maximum value |
-| `step` | `number` | — | Step increment |
-| `showValue` | `boolean` | — | Display current value |
-| `marks` | `object` | — | Tick marks on slider |
+| `step` | `number` | `1` | Step increment |
 
 ```typescript
-{ name: 'confidence', label: 'Confidence', type: 'slider', min: 0, max: 100, step: 5, showValue: true }
+{ name: 'confidence', label: 'Confidence', type: 'slider', min: 0, max: 100, step: 5 }
 ```
 
 ### `signature`
@@ -587,17 +578,10 @@ Digital signature capture.
 ```
 
 ### `qrcode`
-QR/barcode generator and scanner.
-
-| Property | Type | Default | Description |
-|:---|:---|:---|:---|
-| `barcodeFormat` | `'qr' \| 'ean13' \| 'ean8' \| 'code128' \| 'code39' \| 'upca' \| 'upce'` | — | Barcode format type |
-| `qrErrorCorrection` | `'L' \| 'M' \| 'Q' \| 'H'` | — | QR error correction level (only when `barcodeFormat` is `'qr'`) |
-| `displayValue` | `boolean` | — | Display human-readable value below barcode/QR code |
-| `allowScanning` | `boolean` | — | Enable camera scanning |
+QR/barcode value rendered as a scannable code. No per-type config properties.
 
 ```typescript
-{ name: 'asset_tag', label: 'Asset Tag', type: 'qrcode', allowScanning: true }
+{ name: 'asset_tag', label: 'Asset Tag', type: 'qrcode' }
 ```
 
 ### `progress`
@@ -623,17 +607,14 @@ Vector embeddings for semantic search and similarity.
 
 | Property | Type | Default | Description |
 |:---|:---|:---|:---|
-| `vectorConfig.dimensions` | `number` | **required** | Vector dimensionality (e.g., 1536 for OpenAI) |
-| `vectorConfig.distanceMetric` | `'cosine' \| 'euclidean' \| 'dotProduct' \| 'manhattan'` | `'cosine'` | Distance calculation method |
-| `vectorConfig.normalized` | `boolean` | `false` | Whether vectors are pre-normalized |
-| `vectorConfig.indexed` | `boolean` | `true` | Enable vector indexing |
-| `vectorConfig.indexType` | `'hnsw' \| 'ivfflat' \| 'flat'` | — | Index algorithm |
+| `dimensions` | `number` | **required** | Vector dimensionality (e.g., 1536 for OpenAI embeddings) |
+
+The nested `vectorConfig` object (with `distanceMetric`, `indexed`, `indexType`, …) is retained for back-compat only and is a runtime no-op — set the flat `dimensions` property instead.
 
 ```typescript
-{
-  name: 'embedding', label: 'Embedding', type: 'vector',
-  vectorConfig: { dimensions: 1536, distanceMetric: 'cosine', indexed: true, indexType: 'hnsw' }
-}
+{ name: 'embedding', label: 'Embedding', type: 'vector', dimensions: 1536 }
+// or with the factory:
+// embedding: Field.vector(1536, { label: 'Embedding' })
 ```
 
 ---
@@ -647,7 +628,7 @@ These properties are available on **all** field types:
 | `name` | `string` | **required** | Machine name (snake_case) |
 | `label` | `string` | — | Human-readable display label |
 | `description` | `string` | — | Field description / help text |
-| `type` | `FieldType` | **required** | One of the 49 field types |
+| `type` | `FieldType` | **required** | One of the supported field types |
 | `required` | `boolean` | `false` | Whether the field is required |
 | `unique` | `boolean` | `false` | Enforce uniqueness |
 | `multiple` | `boolean` | `false` | Allow array of values |
@@ -660,83 +641,16 @@ These properties are available on **all** field types:
 | `defaultValue` | `any` | — | Default value for new records |
 | `group` | `string` | — | Field grouping / section |
 | `inlineHelpText` | `string` | — | Inline help tooltip |
-| `trackFeedHistory` | `boolean` | — | Track changes in activity feed |
-| `encryptionConfig` | `object` | — | Field-level encryption settings |
-| `maskingRule` | `object` | — | Data masking configuration |
+| `trackHistory` | `boolean` | — | Render this field's value changes as entries on the record activity timeline |
+| `requiredPermissions` | `string[]` | — | Capabilities required to read/edit this field (masked on read, denied on write) |
 | `dependencies` | `string[]` | — | Names of fields this field depends on (formulas, visibility rules, etc.) |
-| `dataQuality` | `object` | — | Data quality validation rules |
 | `visibleWhen` | `Expression` | — | Show field only when predicate is true |
 | `readonlyWhen` | `Expression` | — | Make field read-only when predicate is true |
 | `requiredWhen` | `Expression` | — | Require field when predicate is true |
 | `conditionalRequired` | `Expression` | — | Deprecated alias of `requiredWhen` |
 
 ---
 
-## Field Type Decision Tree
-
-Use this guide to choose the right field type:
-
-```
-Is it text?
-├── Short text (< 255 chars) → text
-├── Long text → textarea
-├── Formatted text → markdown | html | richtext
-├── Email address → email
-├── URL → url
-├── Phone number → phone
-├── Login password (one-way hash) → password
-├── Reversible secret (API key/token) → secret
-└── Source code → code
-
-Is it a number?
-├── Integer or decimal → number
-├── Money amount → currency
-└── Percentage → percent
-
-Is it a date/time?
-├── Date only → date
-├── Date + time → datetime
-└── Time only → time
-
-Is it a choice?
-├── Single choice (dropdown) → select
-├── Single choice (visible) → radio
-├── Multiple choices (dropdown) → multiselect
-└── Multiple choices (visible) → checkboxes
-
-Is it a reference?
-├── Simple foreign key → lookup
-├── Parent-child (cascade delete) → master_detail
-└── Self-referential hierarchy → tree
-
-Is it a file?
-├── Any file → file
-├── Image → image
-├── Profile picture → avatar
-├── Video → video
-└── Audio → audio
-
-Is it computed?
-├── Formula calculation → formula
-├── Roll-up summary → summary
-└── Auto-incrementing ID → autonumber
-
-Is it embedded structured data (stored as JSON, no separate table)?
-├── Single embedded sub-object → composite
-├── Repeating embedded array → repeater
-└── Name-keyed map of sub-objects → record
-
-Is it specialized?
-├── Geographic location → location
-├── Postal address → address
-├── Yes/No toggle → boolean | toggle
-├── Star rating → rating
-├── Range slider → slider
-├── Color picker → color
-├── Raw JSON → json
-├── Tags/Labels → tags
-├── Progress bar → progress
-├── Signature → signature
-├── QR/Barcode → qrcode
-└── AI embedding → vector
-```
+## Choosing a Field Type
+
+Not sure which type fits your data? Follow the [Field Type Decision Tree](/docs/data-modeling/field-type-decision-tree) — a flowchart, quick-reference tables, and a use-case mapping for every type in this gallery.