docs(skills): teach the flow value-expression function vocabulary in objectstack-automation

[claude]

Closes#11348

Teaches the flow value-expression function vocabulary at the point the skill
describes value interpolation (Common Pitfalls #6, the {$User.Id} / {NOW()}
macros list) — the six names, the CEL mirror, the integer-only round plus the
scale idiom, and the loud unknown-function failure.

⚠️ Merge blocker — check:skills-token-ratchet is RED by 132 tokens

This PR cannot merge as-is and needs a ruling before it can. Reporting it
rather than working around it, because both available workarounds are owned
above this seat.

✗ check-skills-token-ratchet: skills/objectstack-automation/SKILL.md is 12643
tokens; the ratchet ceiling is 12511 (over by 132). … New text is paid for by
deleting text IN THE SAME FILE — genuine deletion, never a re-wrap … these
ceilings are shrink-only. ⛔ MAINTAINER-ONLY

The file sits at its ceiling with headroom 0, so any net addition is over
budget. The two ways forward are both rulings, not implementation choices:

• Pay by deletion — delete ~132 tokens of published text from this same
  file. Which customer-facing guidance is worth dropping is a content-value
  judgment for the published catalog; no deletion target was granted with this
  card, so none was taken.
• Raise the ceiling — explicitly marked ⛔ MAINTAINER-ONLY by the gate,
  landing only in a PR whose body quotes a maintainer ruling authorising it.

The addition was compressed to the minimum that still carries the card's
prescription (first draft +210 tokens → +132). It cannot reach +0 while
still teaching the six names, the rounding rule and the failure mode.

Size readings (published-skills budget)

Reading	Before	After	Δ
skills/objectstack-automation/SKILL.md — lines	985	992	+7
skills/objectstack-automation/SKILL.md — tokens	12511	12643	+132
Whole published package — lines (11 SKILL.md)	10505	10512	+7
Whole published package — tokens (bundle)	117725	117851	+126

Token convention is the ratchet's own: ceil(utf8 bytes / 4). The bundle delta
is smaller than the file delta because objectstack-data currently sits 6
tokens under its own ceiling.

Premise verification — one dispatch detail was falsified

The card's substance holds: the skill taught only the three template macros and
none of the function vocabulary. Verified against the landed code in
packages/services/service-automation, not the card.

Confirmed as described: the six names, mirrored 1:1 from the CEL stdlib
(EXPRESSION_FUNCTION_ARITY / KNOWN_EXPRESSION_FUNCTIONS in
src/builtin/template.ts), round integer-only with round(x * 100) / 100 as
the scale idiom, and the named FlowExpressionFunctionError.

Falsified: the error does not fire "at flow-save". It is a run-time
failure. AutomationEngine.validateFlowExpressions deliberately skips
flow-template slots — only predicate slots are checked, because no validator
implements the single-brace {var} dialect. So a bad function name in a node
value survives registration and refuses when the node interpolates. It is
guard-marked, so a fault edge cannot route it.

That distinction is load-bearing for an AI author and is what the new text says:
conditions are caught by the build, value expressions are not. Writing
"flow-save" would have taught an author that a typo is caught before deployment
when it is not. It also matches the docs page that landed with the feature,
which says the unsupported function "fails the node".

Gates

Derived from the real diff via node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (change set taken from the merge base, not a
hand-built list). Union re-run at final commit 3da41ede1, clean tree:

Gate	Verdict
check:doc-authoring	✓ 389 files clean · 38 published skill files clean — no internal issue-id references
check:skills-token-ratchet	✗ over by 132 (see above)
check:doc-formula-expressions	✓ EXIT=0 (needed @objectstack/formula + @objectstack/lint built first)
check:role-word	✓ no new occurrences of the reserved word
check:skill-compatibility	✓ 11 SKILL.md file(s) reconciled against 78 workspace packages
check:skill-frame-sync	✓ 4 copies of the decision frame are structurally isomorphic
check:agent-test-spelling	✓ EXIT=0
check:cross-package-test-inputs	✓ All 109 self-test cases passed
check:pm-governed-merges	✓ 129 assertions
check-ci-filter-parity	✓ all 96 declared cross-package glob(s) … covered
check-cross-package-test-inputs	✓ 16 package(s) read outside themselves, all declared
check-nul-bytes	✓ scanned 6711 text file(s) … no raw ASCII control bytes

No changeset: published-skill prose only, ships no user-visible runtime change;
labelled skip-changeset per repo convention.

Scope

Untouched, as dispatched: the :937 conditions (bare-CEL) row — a different
surface, already correct — and content/docs/automation/flows.mdx, current
since the feature PR.

Filed while working, not fixed here: #12092 — the same file's
"Verify your work" section still teaches that an unknown function in a
condition fails silently at runtime, which the :937 row and the engine both
contradict. Different passage, and it carries this same zero-headroom budget.

---

Generated by Claude Code