chore: automate personal iPhone previews

[musepy]

Summary

• add a fail-closed script for isolated personal-team iPhone Profile previews
• document the verified certificate-label, development-team, provisioning, signing, installation, and launch workflow
• record the failed approaches and their corrections so future previews do not repeat the same investigation
• link the runbook from the project README

Why

The previous device-preview attempts mixed up the certificate label suffix and Xcode development team, tried to launch a standalone Flutter Debug build, reused path-bound CocoaPods output, and initially missed an unsigned nested framework. This made a visual review unnecessarily slow and easy to repeat incorrectly.

The new workflow derives the team from the selected certificate, rejects the project-owner team and canonical bundle ID, regenerates Flutter/CocoaPods files inside an ignored isolated workspace, verifies the final signature and embedded provisioning profile, then installs and launches the Profile/AOT app by exact bundle and process path.

Safety and impact

• does not modify repository Xcode signing settings, bundle IDs, entitlements, versions, or release state
• does not invoke bootstrap, release signing, secret materialization, tags, uploads, or store operations
• removes the isolated workspace and lock after each run while retaining ignored DerivedData for faster repeat previews
• intentionally excludes Share Extension, Firebase authentication guarantees, and store-purchase verification from personal-bundle previews

Verification

• flutter pub get --enforce-lockfile
• flutter analyze --no-fatal-infos — passed with 13 existing info diagnostics
• flutter test — all 20 tests passed
• shell syntax, help output, Markdown heading structure, and diff whitespace checks passed
• full physical-iPhone E2E passed: isolated Profile/AOT build, deep code-sign verification, embedded profile verification, installation, launch, exact installed-process match, and worktree-status preservation
• an independent read-only agent repeated the final artifact/profile/process checks and reported PASS

Note

The locally verified personal provisioning profile expires on 2026-08-05; the script rejects expired profiles and warns when fewer than seven days remain.