feat: bracket GIF exports with START/END marker cards

[kws0210]

What

record-video --format gif now opens with a START card and closes with an END card (~1 s each), on all three surfaces.
Opt-in via --gif-markers — the default output remains a faithful capture of the screen.

Why

Team feedback on real repro clips from #84: a forever-looping GIF has no visible boundary — viewers can't tell where the flow starts and ends.

Design

• Cards are rendered with CoreText at the encoded frame size (from the track's naturalSize, which matches decoded frames for sim-use's own identity-transform recordings), centered white label on a dark background.
• The boolean flag leaves room to grow into a mode argument (overlay|color|image=...) later.
• The flag resolves through ResolvedRecordingOptions / RecordingOutputPlan like the other GIF options, so the surfaces cannot drift.
• A failed card render degrades to a marker-less GIF (stderr warning) instead of failing the transcode — footage over chrome.
• I went with dedicated card frames over overlay badges on the first/last content frames; happy to switch if you prefer the overlay style.

Demo

Testing

• make test fully green (862), including new cases: opt-in frame count and marker delays, card rendering (dark background + bright label pixels), default-off parity with the previous output, and the default in ResolvedRecordingOptions.
• Live-verified on an iPhone 17 simulator (demo above).

🤖 Generated with Claude Code

[onevcat]

Nice feature — the boundary problem on looping GIFs is real, and the implementation is clean (options resolved through ResolvedRecordingOptions, render failure degrading to a marker-less GIF instead of failing the transcode). I'd like to keep it, but flipped to opt-in: default marker-less, with a --gif-markers flag to enable.

Why the default should be marker-less

• A recording tool's default contract is a faithful capture of the screen. Injecting two synthetic frames means the first frame is now a "START" card — anything downstream that grabs the first frame as a thumbnail, does frame-by-frame analysis, or visual-diffs the output gets polluted by chrome. sim-use's primary consumer is agents observing the screen, not humans watching demos.
• It's a silent behavior change to existing output. The most telling evidence is in this diff itself: two existing tests had to add markers: false to keep passing. User scripts and the GIF-output E2E assertions hit the same thing.
• The motivating use case — a human watching a repro clip — is a presentation concern for a subset of usage; it shouldn't define the default output.

Proposed changes

1. On all three surfaces, drop inversion: .prefixedNo and default to false:

   @Flag(help: "Bracket a GIF with START/END marker cards (~1 s each) so the looping clip has a visible boundary. GIF only.")
   public var gifMarkers: Bool = false

   Keeping the gif- prefix in the name is right — it scopes the flag to GIF (mp4 has a scrubber, no loop-boundary problem) and leaves room to evolve into a valued option (e.g. an overlay style) later.
2. Remove the = true default parameters from the library layer (ResolvedRecordingOptions.init, RecordingOutputPlan.init, GIFTranscoder.transcode / transcodeRecording). Right now the CLI layer and the library layer each carry a copy of the default, which is a drift hazard. The default should live only in ResolvedRecordingOptions (its doc comment already claims "the default lives here and nowhere else"); make the downstream parameters required.
3. Tests: the markers: false retrofits on the two pre-existing tests can be reverted (that's the default again), the marker tests pass markers: true explicitly, and the ResolvedRecordingOptions assertion flips to #expect(!gif.gifMarkers).
4. README / CHANGELOG / cheatsheet wording: "disable with --no-gif-markers" → "opt in with --gif-markers". Also, per the repo's development rules, option changes should be reflected in skills/sim-use/SKILL.md as well — worth a check that record-video's option list there picks this up.

[kws0210]

Thank you for the thoughtful feedback — both points make a lot of sense!
Apologies for the internal URL; understood, and I will keep them out of this repo going forward.

414ca1b reverses the flag as suggested: markers are now opt-in via --gif-markers, and the default output stays a faithful capture of the screen, unchanged from v0.13.0.
I kept it a boolean for now so it can grow into your mode-argument idea (overlay|color|image=...) without breaking the surface.
Happy to build that out if there is interest.
We will enable the flag on our side (agent skill/scripts) as you suggested.
Suite green (862).

[onevtail]

The core marker implementation looks sound on the exact head (414ca1b1556d78320a8799bd5e152a6f72516aa7), including the default-disabled behavior and START/content/END frame ordering. A few items still need to be addressed:

1. Please remove the repeated gifMarkers / markers default arguments from the library and orchestration layers (ResolvedRecordingOptions, RecordingOutputPlan, GIFTranscoder, and AndroidRecordVideoCommand.record). Internal callers should pass the value explicitly so the default policy has a single authoritative source.
2. Please update the evidence-GIF entry in skills/sim-use/SKILL.md to document or use --gif-markers. Updating the reference cheatsheet does not cover this primary skill entry.
3. Please add focused coverage showing that --gif-markers parses and forwards as true through the top-level, iOS, and Android command surfaces.
4. The visible Unit tests (macOS) check was cancelled after an hour and remains failed. Local tests pass, so this may be a runner or output-filtering issue, but the check should be rerun or investigated until the exact head has a successful result.

The main implementation does not appear to require a redesign; these are contained follow-up changes.

onevtail - an assistant to @onevcat

[onevcat]

Never mind with the comments above. I can follow up for the left things!

[onevcat]

Taking over the remaining review items as promised — continued in #101, which carries your two commits forward unchanged (authorship preserved). Thanks again for the feature and the quick turnaround on the opt-in flip! The CI timeout investigation also moves there: the raw-log artifact never uploaded on timeout cancellations, which #101 fixes so a reproducing hang finally names the wedged test.