zuar-portal-mcp: Command for Claude Code

Migrate the connected portal's content to a new portal version, following the migration playbook (zportal://guide/migration-playbook). Load the portal-118-migration skill for the block-level conversion pattern; this command is the portal-WIDE method around it.

Confirm a portal is connected: check_connection — one call gives you both the connection and the version (the target build). If it reports connected:false, relay its reason + fix and send the user to /portal-setup. If $ARGUMENTS is given, treat it as the target version and/or scope note.

1. Kickoff — scope decisions once, up front. Run the migration_kickoff MCP prompt (it is a prompt in v3, not a tool). It walks the same five scope questions in chat: native chart-widget policy (convert to ECharts / repair / leave — the user wants to be asked), test/QA pages in scope, fix hardcoded origins, cadence, rollback home. Record the answers to .zuar-portal/migration-scope.json, then proceed to migration_preflight. Don't start converting with these unanswered.

2. Preflight — probe, don't trust docs. Run migration_preflight. Read it as scope-by-FUNCTION: every placed block classified (scripted / template / markup / native-widget — the last breaks with zero migratable code), legacy patterns labeled in_live_code vs comment/string-only, hardcoded origins, snippet findings, orphans (unreachable via layouts AND partials AND snippets), and the data preflight (failing queries, stale stored column metadata → repair_query_metadata, stringly numeric columns). Deep-read any block whose classification is ambiguous — regex under-detects.

3. Snapshot. snapshot_portal and require complete: true (coverage is verified against live listings). No first write before a complete snapshot. Note where it lives per the kickoff's rollback decision.

4. Browser probes. With Claude for Chrome available (check_connection → browser_assist), run the browser_probes the preflight returned against the live build — data lifecycle, filter API shapes (verify by ROW COUNTS, not by docs), event semantics, render timing. Record what the build actually does; it overrides any guide.

5. Canary. Convert ONE representative block end-to-end: convert → validate_block { against_block_id } (pre-existing violations are grandfathered, only new ones block) → update_block → reload in browser → observe render + console. Only a green canary licenses batching.

6. Batches. Minimal diff always — preserve markup, CSS, names, formatting, even pre-existing bugs (log, don't fix). Round-trip verify every write (re-fetch, compare content + ui_queries). Any scripted text-patch must assert its expected match count and re-parse before moving on. Honor the kickoff cadence for pauses. Use the portal-bulk-operator agent for large batches.

7. Performance pass. For any migrated block bound to a granular (100k+ row) datasource or reported slow: apply the portal-block-perf skill (or the block_perf_pass prompt) — measure the payload with timed curl, trim SELECT * to the columns the block reads (get_references first if the query may be shared), prefetch the chart library, verify 60 s honest timeouts.

8. Verification sweep. One pass at the end: DOM/JS assertions and console reads first, screenshots only for what's ambiguous, state round-trips for interactive blocks (toggle ON → row count → toggle OFF → row count). Compare against reference captures taken at baseline, not live navigation. Silently-blank blocks: follow the diagnosis ladder in the playbook (§6) before touching code.

Close with a report: converted / repaired / left, grandfathered violations flagged, data repairs applied, rollback pointers (vc_log), and anything deferred.