docs(builder-agent): document REST-bound and cascading JSON Form dropdowns

[ZackStr]

Replaces #35 — same commit content; only the branch name changed (claude/... → docs/...) to satisfy the branch-naming CI check.

Summary

• Adds a new helper template helpers/create-json-form-rest-bound.json for JSON Forms whose dropdowns are populated live from IAP endpoints, including the cascading pattern (one dropdown's URL path parameter fed by another field).
• Documents three previously-undocumented details in builder-agent/SKILL.md: bulk DELETE /json-forms/forms, the struct ↔ bindingSchema mirroring requirement, and the variables[] + DependencyWidget mechanism that wires cascading dropdowns.

Background

While building a Site/Device cascade against Inventory Manager I produced a form whose dropdowns rendered but never fetched. Working from the existing create-json-form.json helper, I had assumed bindingSchema: {} was always correct and used {customKey} curly-brace interpolation in href. Both wrong. The user hand-built a working form to demonstrate the actual pattern; this PR captures what was learned so the next agent doesn't repeat the mistakes.

Changes

New file: helpers/create-json-form-rest-bound.json

• Annotated scaffold in the same _comment_* style as the other helpers
• Worked example: Site (inventory list) → Device (nodes from selected inventory) cascade against Inventory Manager
• Inline gotchas list at the bottom

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

• Endpoint table: add GET /json-forms/forms/{id} and DELETE /json-forms/forms (bulk; body {"ids":[...]} — there is no per-id DELETE; per-id 404s)
• New "REST-bound dropdowns" subsection: covers struct.type: "array" requirement, the struct ↔ bindingSchema mirroring requirement, :name colon syntax for path params (not {name}), the variables[] cascade mechanism with reference JSON pointers into form data, the DependencyWidget ui:widget requirement on both source and dependent fields, and GET /automation-studio/json-forms/method-options for bindable-endpoint discovery
• Templates table at the bottom: split the JSON Form row into static and REST-bound entries

Edit: helpers/create-json-form.json

• One-line _comment_bindingSchema redirecting readers to the new helper when bindingSchema must not be empty

Test plan

• jq type passes on both helpers (verified locally)
• POST the new helper's body to /json-forms/forms against a live platform → form appears in Studio with two dropdowns
• Selecting a site repopulates the device dropdown via the cascade (:inventoryIdentifier filled from /site reference)
• Bulk DELETE removes both forms
• Reviewer reads the new SKILL.md subsection and verifies the gotchas match observed Studio behavior

🤖 Generated with Claude Code