v2: ship a Boost upgrade guideline to take v1 apps to v2

Ship a Laravel Boost guideline that walks a downstream Nova app from v1 to v2 of this package. It lives on main and ships in a v1.x point release, so apps already on v1 receive it via Boost before they upgrade. References the v2 roadmap (#21).

What it is

A single guideline at resources/boost/guidelines/upgrade-v2.blade.php, written as an imperative runbook the consumer's agent executes. Passive Boost context can't guarantee execution, only instruct — that's accepted; the audience is downstream developers upgrading their own app, and Boost is the only channel that reaches them through composer.

It is not a Claude Code skill (those don't ship via composer and would only fire for us working on the package).

Shape — one guideline, two phases

Always run Phase A. After A is green, ask the developer: keep it minimal, or also suggest layout improvements? Only run Phase B on opt-in.

Phase A — mechanical upgrade (correctness)

1. Preflight scan (before bumping anything). The platform requirements are unchanged (PHP ^8.2, Laravel ^12|^13, Nova ^5.0), so composer require resolves cleanly even for an app that's about to break at runtime. Scan for the three silent-breakage patterns:
   • Raw Action::modal('modal-response', [...]) payloads — removed in v2, no shim → renders an empty modal body.
   • Code reading the raw wire format (body / code / html / top-level highlight).
   • Custom Vue override of the modal-response component → HARD STOP. Report it, point to UPGRADE.md's "overrode the Vue component" section, hand the frontend migration to the human. Do not auto-migrate bundled JS.
     Preflight is advisory-but-loud for the first two (reported, then migrated inline); the Vue override is the only hard gate.
2. Bump to ^2.0.
3. Migrate the raw-payload call sites found in preflight to the ModalResponse PHP API (per the key→method table in UPGRADE.md).
4. Verify (boundary is explicit):
   • Automated/static: composer show reports 2.x; zero surviving Action::modal('modal-response', …) call sites; test suite green if one exists.
   • Handed to human: open each affected modal once and confirm no legacy-payload console.warn (#42) fires. A guideline can't observe a browser console headlessly — say so honestly rather than claim the static checks suffice.

Phase B — opportunistic layout improvements (opt-in)

Inventory modal call sites and propose per-site improvements (e.g. collapsing sequential single-shape modals into one stack([...]), inline groups for label+badge pairs). Apply only the sites the human confirms. Never silently rewrite working modals.

Candidates are derived from UPGRADE.md's "New in v2" section and the v2 core guideline at runtime — do not hardcode the block-type list in this guideline (it's exactly what's still changing in v2).

Single source of truth

The guideline does not enumerate breaking changes or v2 features (subject to change until v2 ships). It embeds the canonical UPGRADE.md URL — https://github.com/markwalet/nova-modal-response/blob/main/UPGRADE.md — and tells the agent to fetch it. The guideline holds only the procedure; UPGRADE.md holds the change list.

Release sequencing (hard dependency)

The guideline ships in a v1.x release where UPGRADE.md is not vendored (it lives on the v2 branch). Therefore:

1. UPGRADE.md must be reachable at the canonical URL above (lands when v2 merges to main) before
2. the v1.x release that ships this guideline.

If the guideline ships first, its single source of truth 404s.

Out of scope

• Enumerating v2 breaking changes / block types here — see #21 and UPGRADE.md.
• A Claude Code skill or any active-execution mechanism beyond a Boost guideline.

References

• Roadmap: #21
• Legacy-payload warning: #42
• Raw Action::modal removal from docs: #41

Start with resources/boost/guidelines/upgrade-v2.blade.php and the canonical UPGRADE.md URL, then review the v2 roadmap (#21), legacy warning (#42), and raw Action::modal removal (#41). Check existing Boost guideline conventions and verify the documented composer show, call-site, and test checks. Done means the two-phase runbook is present and the v1.x release is sequenced after UPGRADE.md is reachable.