docs(common-patterns): fix patterns that validate but fail at runtime

All ten patterns were dropped verbatim into a scaffolded 16.0.0-rc.1 app
and run through npm run validate — twice: as-published (passes, proving
the gate does NOT catch these) and as-fixed. The fixes target
runtime-fatal issues invisible to validate:

- Both flow patterns lacked the start-node trigger binding
  (config.objectName + triggerType: 'record-after-update' …) — they
  validated but never fired; approval-flow nodes (auto_approve /
  request_approval / update_record) had no config at all, making them
  no-ops. Bindings, node configs, status: 'active', and a CEL start
  condition added.
- reference: 'user' → 'sys_user' (no 'user' object exists; lookups
  silently never resolve).
- notify recipient '{record.assigned_to.email}' → '{record.assigned_to}'
  (recipients are user ids; path-walking a string yields empty
  recipients and a node error).
- Formula field: bare 'quantity * unit_price' →
  'record.quantity * record.unit_price' + returnType (bare identifiers
  resolve to null in the CEL scope).
- Cursor-pagination section replaced with keyset pagination (cursor is
  schema-reserved, zero engine/driver execution — same finding as
  PR #3374).
- Frontmatter description no longer promises realtime; import callout
  gains definePermissionSet.

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

Author: claude

content/docs/getting-started/common-patterns.mdx

@@ -1,14 +1,14 @@
 ---
 title: Common Patterns
-description: Top 10 patterns for building applications with ObjectStack — CRUD, search, auth, realtime, and more
+description: Top 10 patterns for building applications with ObjectStack — CRUD, views, flows, agents, security, and more
 ---
 
 # Common Patterns Guide
 
 This guide covers the most common patterns you will use when building applications with ObjectStack. Each pattern includes a complete, copy-pasteable example.
 
 <Callout type="info">
-**Import:** `import { defineStack, defineView, defineApp, defineFlow, defineAgent } from '@objectstack/spec'`
+**Import:** `import { defineStack, defineView, defineApp, defineFlow, defineAgent, definePermissionSet } from '@objectstack/spec'`
 </Callout>
 
 <Callout type="warn">
@@ -46,7 +46,8 @@ export default defineStack({
           { label: 'Complete', value: 'complete' },
           { label: 'Archived', value: 'archived' }
         ]},
-        owner: { label: 'Owner', type: 'lookup', reference: 'user' },
+        // Person references target the platform user object `sys_user`
+        owner: { label: 'Owner', type: 'lookup', reference: 'sys_user' },
         due_date: { label: 'Due Date', type: 'date' },
         budget: { label: 'Budget', type: 'currency', currencyConfig: { precision: 2, defaultCurrency: 'USD' } },
       }
@@ -73,7 +74,8 @@ export default defineStack({
           { label: 'Complete', value: 'complete' },
           { label: 'Archived', value: 'archived' }
         ]},
-        owner: { label: 'Owner', type: 'lookup', reference: 'user' },
+        // Person references target the platform user object `sys_user`
+        owner: { label: 'Owner', type: 'lookup', reference: 'sys_user' },
         due_date: { label: 'Due Date', type: 'date' },
         budget: { label: 'Budget', type: 'currency', currencyConfig: { precision: 2, defaultCurrency: 'USD' } },
       },
@@ -134,7 +136,8 @@ Create a parent-child relationship between a master and its detail records. Note
         product: { label: 'Product', type: 'lookup', reference: 'product' },
         quantity: { label: 'Qty', type: 'number', min: 1, required: true },
         unit_price: { label: 'Unit Price', type: 'currency' },
-        line_total: { label: 'Line Total', type: 'formula', expression: 'quantity * unit_price' },
+        // Formula expressions are CEL — reference fields through `record.`
+        line_total: { label: 'Line Total', type: 'formula', expression: 'record.quantity * record.unit_price', returnType: 'number' },
       }
     }
   ]
@@ -236,7 +239,10 @@ export const crm = defineApp({
 
 ## 6. Automated Flow (Record-Triggered)
 
-Create an automation that fires when a record is created or updated.
+Create an automation that fires when a record changes. The **start node's `config`
+binds the trigger**: `objectName` plus one lifecycle event in `triggerType`
+(`record-after-create`, `record-after-update`, `record-after-delete`, or the
+`record-before-*` forms) — without it the flow never fires.
 
 ```typescript
 import { defineFlow } from '@objectstack/spec';
@@ -245,15 +251,23 @@ export const assignmentNotification = defineFlow({
   name: 'task_assignment_notification',
   label: 'Task Assignment Notification',
   type: 'record_change',
+  status: 'active', // arm the trigger deliberately (default 'draft' is ambiguous)
   nodes: [
-    { id: 'start', type: 'start', label: 'Start' },
+    {
+      id: 'start',
+      type: 'start',
+      label: 'Start',
+      // Trigger binding: which object + which lifecycle event launches this flow
+      config: { objectName: 'task', triggerType: 'record-after-update' }
+    },
     {
       id: 'notify',
       type: 'notify',
       label: 'Notify Assignee',
       config: {
-        // String fields use single-brace {…} templates, not {{…}}
-        to: '{record.assigned_to.email}',
+        // String fields use single-brace {…} templates, not {{…}}.
+        // `to` takes recipient USER IDs — a lookup value interpolates to the id.
+        to: '{record.assigned_to}',
         subject: 'Task Assigned: {record.title}',
         body: 'You have been assigned to task "{record.title}".'
       }
@@ -289,8 +303,8 @@ Define a multi-step approval flow for records.
         { label: 'Approved', value: 'approved' },
         { label: 'Rejected', value: 'rejected' }
       ]},
-      submitted_by: { label: 'Submitted By', type: 'lookup', reference: 'user' },
-      approved_by: { label: 'Approved By', type: 'lookup', reference: 'user' },
+      submitted_by: { label: 'Submitted By', type: 'lookup', reference: 'sys_user' },
+      approved_by: { label: 'Approved By', type: 'lookup', reference: 'sys_user' },
     },
     enable: {
       trackHistory: true,
@@ -301,11 +315,40 @@ Define a multi-step approval flow for records.
     name: 'expense_approval',
     label: 'Expense Approval',
     type: 'record_change',
+    status: 'active',
     nodes: [
-      { id: 'start', type: 'start', label: 'Start' },
+      {
+        id: 'start',
+        type: 'start',
+        label: 'Start',
+        config: {
+          objectName: 'expense_report',
+          triggerType: 'record-after-update',
+          // Start condition (bare CEL): launch only on the draft → submitted transition
+          condition: "record.status == 'submitted' && previous.status != 'submitted'"
+        }
+      },
       { id: 'check_amount', type: 'decision', label: 'Check Amount' },
-      { id: 'auto_approve', type: 'update_record', label: 'Auto Approve' },
-      { id: 'request_approval', type: 'notify', label: 'Request Approval' },
+      {
+        id: 'auto_approve',
+        type: 'update_record',
+        label: 'Auto Approve',
+        config: {
+          objectName: 'expense_report',
+          filter: { id: '{record.id}' },
+          fields: { status: 'approved' }
+        }
+      },
+      {
+        id: 'request_approval',
+        type: 'notify',
+        label: 'Request Approval',
+        config: {
+          to: '{record.submitted_by}',
+          subject: 'Expense approval needed: {record.title}',
+          body: 'Expense "{record.title}" needs manual approval.'
+        }
+      },
       { id: 'end', type: 'end', label: 'End' }
     ],
     edges: [
@@ -388,21 +431,27 @@ const page2 = { ...page1, offset: 25 };
 const page3 = { ...page1, offset: 50 };
 ```
 
-### Cursor-Based (Scalable)
+### Keyset (Scalable)
+
+Instead of skipping N rows, filter past the last row you already received —
+stable under concurrent writes and cheap at any depth. (The query schema also
+reserves a `cursor` property, but it is not executed by the engine — use the
+`where` + `orderBy` + `limit` form below.)
 
 ```typescript
-// First page — no cursor yet
+// First page
 const firstPage = {
   object: 'activity',
   fields: ['id', 'type', 'description', 'created_at'],
   orderBy: [{ field: 'created_at', order: 'desc' }],
   limit: 50
 };
 
-// Next page — pass the opaque cursor token returned with the previous response
+// Next page — filter past the last row of the previous page
+const lastRow = previousPage[previousPage.length - 1];
 const nextPage = {
   ...firstPage,
-  cursor: { /* opaque cursor token from the previous response */ }
+  where: { created_at: { $lt: lastRow.created_at } }
 };
 ```