docs(builder-agent): document JST step structure, Array callback methods, and Conditional.if...else

[ZackStr]

Summary

• Adds a new helper template helpers/create-transformation.json for building JSTs (JSON Transformations) from scratch via POST /transformations/.
• Adds a new ## JSON Transformations (JSTs) — Building subsection in builder-agent/SKILL.md covering step types, the per-method Array-callback table, the Conditional.if...else inline branching pattern, and the canonical "Anchors could not be found" failure mode.
• Captures patterns I had to learn the hard way: dropdowns rendered but failed silently when bindingSchema was empty (covered in docs(builder-agent): document REST-bound and cascading JSON Form dropdowns #36); JSTs rendered with canvas anchor errors when Array.map referenced a function name that wasn't defined in functions[].

Background

The plugin documents the transformation workflow task (consumer side: how to call a JST from a workflow) but has no coverage of how to BUILD a JST — no helper, no step-structure docs, no callback-method table. While fixing a corrupted JST in a customer engagement, I discovered that:

1. Sub-contexts for Array.map/filter/reduce/find/findIndex/some/every/sort/flatMap live in a top-level functions[] array, sibling to steps[] — NOT inline in steps[] with a context: "#/N[0]" pointer (which is the pattern for Conditional.if...else and other type: "context" containers).
2. Per-method function-name prefixes and slot names don't follow the method name. Array.filter/find/findIndex/some/every all share the ƒ_query_* namespace; Array.flatMap shares the ƒ_map_* namespace with Array.map. Read iteration values via currentValue (map family), element (predicate family), firstEl/secondEl (sort), or accumulator/currentValue (reduce). Write per-iteration results to newValue / return / comparison / accumulator — depends on family.
3. Extra parent args slots beyond [array, callbackName] bind to constantValue<N> slots in the function's incoming — IAP's mechanism for passing external constants into a callback.
4. Array.forEach does NOT exist in JST.

The user (an Itential employee) hand-built reference JSTs (teachClaudeJST, teachClaude2, teachClaude3, teachClaude4) so I could fetch each via GET /transformations/{id} and extract the canonical structure. Every method/pattern in this PR is verified against live IAP data, not inferred.

Changes

New file: helpers/create-transformation.json

• Annotated scaffold in the same _comment_* style as the other helpers
• Worked example: Array.map callback that wraps each input string into {MyOtherObject: {key1: "blah", key2: <item>}}
• Reference table of all 9 verified callback methods with parent-args / function-name / incoming / outgoing
• Inline Conditional.if...else pattern documentation
• Step types reference (method, assign, declaration, context)
• Endpoint reference

Edits: .claude/skills/builder-agent/SKILL.md

• New ## JSON Transformations (JSTs) — Building subsection (between JSON Forms and Operations Manager)
• Endpoint table for /transformations/ CRUD
• Step types table
• Per-method Array callback table (9 methods)
• Conditional.if...else inline-branching pattern
• "Anchors could not be found" gotcha and fix
• Templates table at the bottom: add the new helper

What's verified vs inferred

100% verified against live IAP transformations:

• All 9 Array callback methods (map, filter, reduce, find, findIndex, some, every, sort, flatMap)
• Conditional.if...else inline sub-context (including nested branches)
• constantValue<N> injection pattern across families
• One function entry referenced by multiple parent steps
• The PUT-without-{options:{}} format (distinct from json-forms PUT)

Not in scope (no claim made):

• Other type: "context" containers (e.g., Conditional.switch) — only if...else was verified
• Object-walking helpers like Object.map/Object.entries — out of scope for this PR

Test plan

• jq type passes on the helper (verified locally — file is valid JSON)
• POST the helper's body to /transformations/ against a live platform → JST appears in Studio
• Open the JST in canvas → no "Anchors could not be found" errors
• Run the JST against an array input → output matches the per-iteration mapping
• Reviewer reads the new SKILL.md subsection and verifies the per-method table matches Studio behavior

🤖 Generated with Claude Code