@@ -0,0 +1,12 @@
+---
+'@objectstack/skills': patch
+---
+
+docs(skills): objectstack-formula names action `visible` / `disabled` as the sparse, client-side exception to the total-record rule, and teaches the `has()` guard that surface needs
+
+Clause-②: no
+Metadata-protocol: none
+
+- **Before.** The "`has()` is NOT a null check" section said every predicate reads a `record` that is total over the object's declared fields, so `has(record.<declared_field>)` is always `true` and tells you nothing. An agent following it dropped the `has()` guard from an action's `visible` predicate on a `list_item` location, where the row can lack the key: the predicate faults `No such key` and the button silently vanishes. The Surfaces table listed only `Action.disabled`.
+- **Now.** The total-record statement is scoped to the server-evaluated surfaces (validation rules, `requiredWhen`, option `visibleWhen`, `readonlyWhen`, hook `condition`, the flow trigger record), where `!= null` is the whole guard. A new paragraph says action `visible` / `disabled` bind the row the client already holds, which lacks a key when the column is outside the view's projection, refused by field-level security, or never written (the mongo and memory drivers), and teaches the guard: `has(record.x) && record.x != null`; `has()` alone beside a literal `==` / `!=`; one `has()` per segment of a nested path. The Surfaces table lists `visible` beside `disabled`, marked client-side and sparse.
+- `SKILL.md` stays under its token ceiling (no ceiling moves). No schema, key, command or behaviour changes.
@@ -172,8 +172,8 @@ export const ResolveTicketAction = defineAction({
   locations: ['record_header', 'list_item'],
   // Only offer "Resolve" on tickets that aren't already resolved or closed.
   // Predicates are CEL, record-scoped — `record.status`, never bare `status`.
-  // `has()` guards the sparse list row: a list projects only the columns it
-  // shows, and CEL faults on an absent key (which hides the button silently).
+  // `has()` guards the sparse list row; the rule and its guard table live in
+  // `packages/objectql/src/declared-fields.ts`.
   visible: 'has(record.status) && record.status != "resolved" && record.status != "closed"',
   successMessage: 'Ticket resolved.',
   refreshAfter: true,
 
@@ -95,11 +95,13 @@ ADR-0068 — spec field docs write predicates like `current_user.positions`.
 `null`. To check for "value present and non-blank" use the stdlib helper
 `isBlank()` or compare to `null` explicitly.
 
-Every predicate reads a `record` — and, where §5 binds it, a `previous` — that
-is **total over the object's declared fields**: a declared column the driver
-never returned reads as `null`, not as a fault. So `has(record.<declared_field>)`
-and `has(previous.<declared_field>)` are uniformly `true` and tell you nothing at
-all. The idiom that reads like a guard is not one:
+Every server-evaluated predicate — validation rules, `requiredWhen`, option
+`visibleWhen`, `readonlyWhen`, hook `condition`, the flow trigger record —
+reads a `record` (and, where §5 binds it, a `previous`) that is **total over
+the object's declared fields**: a declared column the driver never returned
+reads as `null`, not as a fault. There `has(record.<declared_field>)` and
+`has(previous.<declared_field>)` are uniformly `true`, and `!= null` is the
+whole guard. The idiom that reads like a guard is not one:
 
 ```text
 # WRONG — both has() calls are true on a NULL row, so this reaches `null < null`,
@@ -117,7 +119,23 @@ or hook predicate that applies an ordering (`< <= > >=`) or arithmetic
 no `defaultValue`, no default option — unless an explicit `!= null` / `== null` /
 `!isBlank()` test dominates it in the same boolean branch. `has()` deliberately
 does not satisfy that gate. `has()` over an **undeclared** key stays legal: that
-is its real use — telling "absent from this PATCH" apart from "explicitly null".
+is its use there — telling "absent from this PATCH" apart from "explicitly null".
+
+**The exception: action `visible` / `disabled` are client-side and sparse.**
+They bind the row the client already holds, and that row — a `list_item` row
+above all — lacks a key when the column is outside the view's projection, when
+field-level security refuses it, or when it was never written (the mongo and
+memory drivers).
+Reading an absent key faults `No such key`: a `visible` predicate hides the
+action, a `disabled` one leaves it refused, silently either way.
+There the guard is `has(record.x) && record.x != null`; `has()` alone is enough
+beside a literal `==` / `!=`; a nested path takes one `has()` per segment:
+
+```text
+has(record.status) && record.status != 'resolved'
+has(record.amount) && record.amount != null && record.amount > 1000
+has(record.viewer) && has(record.viewer.can_approve) && record.viewer.can_approve == true
+```
 
 ### Null + string throws
 
@@ -407,7 +425,7 @@ to the envelope.
 | `View` / `Page` | `visibleWhen` (form section/field, page component) | cel |
 | `Field` | `defaultValue` (envelope only; bare string = literal) | cel |
 | `ConditionalValidation` | `when` | cel |
-| `Action` | `disabled` | cel (or boolean) |
+| `Action` | `visible` / `disabled` — client-side, sparse | cel (or boolean) |
 | `Hook` | `condition` | cel |
 | `SharingRule` | `condition` | cel |
 | `Flow.decision` | `expression` / edge `condition` | cel (use `vars.<step>.<key>`) |