[simonvanlaak]

This is the single PR for the combined Mac onboarding update. It supersedes the older guide slice #664 and annotation ticket #695; their requirements are included here. Integration target: t3/onboarding-mac-release-baseline. No main merge or public release is included.

Resulting flow

Choose pen → permissions if needed → choose recording shortcut → test it once without recording → press it again for the real guided capture → whiteboard drawing → text annotation → screen drawing → finish → manual paste → find the capture.

• No shortcut is preselected for new setup. Save a valid combination, release its selection keys, then press/release it for the non-recording trial. Continue unlocks after success; changing keys requires another trial.
• The first guided capture is real and local. Early shortcut/menu/picker/agent/iPhone starts cannot bypass setup.
• Whiteboard closes before the note lesson. The prompt is Add a note. — “Hold Shift and click a spot.” Only a nonempty durable note save enables the screen-drawing lesson. Drafts, empty Enter, dismissal, failed writes and Replay do not count. Earlier screen marks cannot satisfy the later screen-drawing prompt; stopping early cannot invent the missing lesson.
• During screen drawing, the companion hint says “Pressing down on your trackpad? No need. Just hold Shift and glide.” It sits beside the guide when space permits, falls inline on smaller displays, and disappears as the lesson advances.
• After finishing and confirming a manual paste, the final guide points to Apparent's menu-bar icon and Open Latest Capture.

Installer, permissions and resume fixes

Change	Behavior
Frog installer in the download	The DMG includes Install Apparent. Open it, then click the frog or drag the app into Applications. Normal Finder dragging remains available; mounting the DMG does not automatically run the installer.
Safe replacement	Replacement requires confirmation and a user-initiated quit. Signature/team/version/path checks, staged-copy verification, exclusive renaming and a hidden backup protect the existing app. The installer does not change capture settings, permission grants or the public update feed.
Permission-card positioning	The opaque Screen Recording card covers the lower audio-only area in System Settings, leaving the correct upper recording list exposed. It follows movement and updates on resize.
Old onboarding progress	Unfinished legacy setup restarts once from the beginning instead of its old middle page. Later quits/permission restarts preserve progress. Completed users are not forced through setup again.

The recurring startup-popup report #653 / hotfix #658 remains separate: the one-time old-progress migration here does not prove that report fixed.

Visual design

Seven compact action examples cover recording keys, Screen → Whiteboard, Shift-click notes, Shift drawing, Finish → Copied, paste keys, and menu icon → Open Latest Capture. They play once, offer Replay and reduced-motion stills, and avoid extra result scenes and excess blank space. The location example uses a neutral menu and target arrow, without the unwanted blue treatment.

Host Grotesk, approved Paper/Stock/Carbon/Lilac/Signal roles, 36/18/16 main type scale, consistent miniature menu-label sizes (including Microphone), the 8px spacing grid and stable coach widths apply. Approved frogs, puddles and pop-up shapes remain.

Current candidate and verification

Current build source: 210ec1919dce4e00c33acaff6221efade336e591.
Planned private test version: 0.12.3 / build 12.3, Apple Silicon. Download blocked: no installer artifact was produced.

• Onboarding implementation 3cd3e9da: Rust rebuild, 886 passing tests, 7 existing ignores; 63 frontend tests and 9 Electron cases; independent source review and normal push checks passed.
• Mac verification passed on 08f811fd, but that run's packaging stopped at an installer fixture. The fixture's wrong-team injection now compares filesystem paths, asserts it actually ran, and requires the signing-identity rejection. Production signature checks were not relaxed.
• All exact-head Mac verification jobs and all 10 installer fixtures passed on Intel Mac in the current run.
• ARM packaging never started. The original packaging attempt and one targeted packaging-only retry were both cancelled with zero executed steps. GitHub reported ARM64 capacity constraints and “The job was not acquired by Runner of type hosted even after multiple attempts”. Artifact lookup confirms no onboarding candidate download exists for this run.
• Remaining prerequisite: an available Apple Silicon build runner, then ARM fixtures, signed/notarized packaging and exact-source/checksum verification. Further identical retries are held until runner availability changes.
• Fixture-only diagnostics cannot produce an app, signing action, artifact or release receipt. Normal packaging still requires full verification and installer fixtures.
• Normal hooks remain enabled. No new paid Mac rental was started.

Remaining acceptance — keep draft

• Complete exact-head Mac verification and all 10 Intel Mac installer fixtures.
• Run ARM installer fixtures once an Apple Silicon runner is available.
• Produce the signed/notarized private candidate and verify its source, identity, version and asset checksums.
• Install from the actual DMG: frog click, drag, replacement consent, quit handling and launch.
• Verify actual System Settings cover/drop, movement, resizing and permission restart.
• Verify native global keys: chosen shortcut → non-recording trial → real guided capture.
• Verify whiteboard → note → screen drawing, actual note editor/Attach/Enter, focus restoration, saved note semantics and bundle text/images.
• Verify immediate save/stop and incomplete practice handling, restart/resume, actual paste and final menu/location guide.
• Complete current-base integration and applicable release gates before merge/publication.

Renderer previews use simulated capture state and are not native proof. Mac is the agreed priority; Linux-native testing is deferred, and existing Linux behavior is preserved. A separate website/logo change is outside this work.