zuar-portal-mcp: Skill for Claude Code

Portal bulk ops (safe discipline)

Bulk changes touch many resources, so a mistake multiplies. Run them through the portal-bulk-operator agent (.claude/agents/) or the /portal-bulk command — this skill is the thin discipline they follow. The per-block authoring rules still apply on every edit: see assets/conventions.md (binding, the $ trap, scoped CSS, safety) and the global zportal skill. For bulk data writes back to a database, do not hand-roll SQL in a loop — use the global db-modifications skill (the /api/db_modifications/run service).

The loop (never skip a step)

1. Snapshot first — the rollback point. Call snapshot_portal before any write. This is your one-command revert if the batch goes wrong. (Writes are also mirrored to version control when configured — vc_status / vc_log — and any single resource is revertible via restore_resource.)
2. Enumerate the targets. list_resource (resource="block", etc.) to build the exact set you'll touch. Resolve it to concrete ids; don't operate on a fuzzy "all blocks like X" — name them.
3. Dry-run plan + confirm. Produce a plan: for each target, the current value → the proposed value (rename/restyle/retag/rebind/placement). Show it and get explicit confirmation before any mutation. No silent bulk writes.
4. Apply in a controlled loop — one at a time, validated. For each target:
   • get_resource resource="block" first to read current state, including its existing ui_queries.
   • Make the change.
   • validate_block on the new json_data + css; fix errors before writing.
   • update_block — and RE-SEND the existing ui_queries verbatim. Omitting it wipes the binding and the block goes blank. This is the #1 bulk footgun.
5. Page placement is one declarative call. To set the blocks on a page, use place_blocks (an atomic read-modify-write: mode:"merge" to append/update/remove, mode:"replace" + confirm:true when the page must become exactly the list — it preserves customized grid.layouts and survivors' hidden flags). Never fire parallel per-block placement writes — they race and corrupt page order / drop blocks.
6. Verify. After the batch, re-list_resource/get_resource a sample (and any rebound blocks) to confirm the changes landed and bindings survived. Spot-check live data still flows on rebinds.
7. Revert if wrong. Roll a single resource back with restore_resource, or fall back to the snapshot_portal taken in step 1 to undo the whole batch.