[Harrys76]

Steps 18 to 20 of the 1.0.0 overlay plan (doc/plan_overlay_1_0_0.md): docs, the sidecar and release prep. Stacked on #27.

The device checks (steps 10 and 21, with the README screenshots and the snapshot_heavy_compute.json re-record) and the final adversarial review (step 22) come after this PR is reviewed, once both test phones are connected.

Sidecar 0.10.0 (step 19)

• Lineage. From 1.0.0 a lineage is the major version, since sleuth 1.x follows semver: versionLineage('1.4.2') returns 1, and below 1.0.0 it stays major.minor. Any 1.x app connects, with version_skew_minor when it is not the pinned version.
• Pin. sleuthPackageVersionPin = '1.0.0' and acceptedPriorLineages = {'0.38'}, so 0.37 apps are refused.
• Payloads. compactIssueKeys gains measurement. get_issues passes the app's notUsefulMarks through, and the snapshot projection already kept it.
• Docs and tests. The tool schema, the README compatibility section, the CHANGELOG and doc/release_notes/0.10.0.md describe 0.10.0. The test fakes report 1.0.0 and use 0.38 for the accepted prior lineage.
• sleuth's own version moves to 1.0.0 in the same commit, because the sidecar's smoke test pins the two together.

Guide, docs and example (step 18)

• Guide. The quick start names --no-dds. The run label, Mark flagged widgets, text size and Escape tips match the new overlay.
• Docs. README, doc/overlay.md, doc/accessibility.md, doc/configuration.md and doc/internals.md drop the footer, the Export button, the Seen X/Y badge, the header theme toggle, the source accent and the Ask AI shimmer. They describe the More menu, the meta line and the back and Escape order with the menu and the bar. doc/overlay.md gains sections on the highlight bar (with list-card stepping) and the empty-list status lines.
• Device procedures. doc/validation_matrix.md and doc/capture_procedure.md check the "· VM" run label instead of the VM+ and FRAME badges, and so do the example's capture screens.
• Example. ext.sleuthDemo.overlay gains menu (taps More, reports menuOpen) and notUseful (taps Not useful on the expanded card, reports the mark). Both look up a semantics button by exact label (findSemanticsButton).
• The README stability section came with 1.0 public API, API enforcement and list-card crosshair #27.

Release prep (step 20)

• pubspec.yaml and kSleuthPackageVersion read 1.0.0.
• The CHANGELOG's 1.0.0 section summarises the release and links doc/release_notes/1.0.0.md. The release notes hold every change grouped by area: public API, issue data and exports, and the overlay. They include each item the plan lists (the measurement and Not useful types, the moved and hidden names with the import to use, the removed theme fields, and the behaviour changes).
• CLAUDE.md describes the 1.0 API and overlay.
• Release order. sleuth 1.0.0 and sleuth_mcp 0.10.0 publish together, because sidecar 0.9.0 refuses 1.0.0 apps. Publishing is your step.

Review

The doc changes started from an audit of stale overlay text across the guide, docs and example. Every prose edit went through unslop.

Codex reviewed in two rounds; round 2 found nothing. Round 1 found that overlay action=menu could tap the open menu panel, which carries the same "More" label, instead of the button. 317b728 fixes it, and a test fails without the fix.

Gates: fvm flutter analyze, format and dart doc --dry-run clean; publish dry runs of sleuth and sleuth_mcp report 0 warnings; 5,049 tests on 3.47.6 and on the 3.32.8 floor; 655 sidecar tests on both; 349 example tests.

compare_snapshots across 1.x (3bf85e6)

From 1.0.0 one lineage spans every 1.x release, so compare_snapshots diffs a 1.0.0 snapshot against a 1.2.0 one without a word. The result now carries versionWarning (sleuth_version_differs:, both versions) when the two releases differ, since a release can add detectors, move thresholds or fix false positives. Build metadata does not count. The tool schema documents the key and describes arg_lineage_mismatch with lineages by major from 1.0.0. Sidecar tests: 658.

Docs (892a3bf)

The release notes and CHANGELOG say that cards hidden under 0.38 stay hidden (#24) and that a new issue list rebuilds only the cards it changes (#26). doc/internals.md documents the version 1 key migration.

Fixes from the iPhone walk

• The Guide's Back tip now names the More menu and the highlight bar, as the Escape tip does, with a test that scrolls to it.
• The release notes, CHANGELOG (a Fixed line for the source locations) and CLAUDE.md describe the fixes made in Overlay data for the 1.0.0 card #22, Overlay chrome for the 1.0.0 card: run label, More menu, status row #23, 1.0.0 overlay: expanded issue card (step 13) #25 and Overlay 1.0.0 PR6: trust states and the highlight flow #26.
• Gates at this tip: 5,069 tests on 3.47.6 and on the 3.32.8 floor, 44 benchmarks, 349 example tests, analyze and format clean. A demo walk on main and on this branch, with repeats, matched on every stable id and severity apart from run variance.

Fixes from the final review

• The Guide, doc/overlay.md and doc/accessibility.md say an app dialog or sheet keeps its Escape, and an app text field does too unless the highlight bar is up.
• The release notes, CHANGELOG and CLAUDE.md describe the review fixes, including that an app's own AnimatedBuilder, TweenAnimationBuilder, Checkbox and ShaderMask rebuilds count again and that the API diff fails only on a breaking change.
• Gates at this tip: 5,076 tests on 3.47.6 and on the 3.32.8 floor, 44 benchmarks, 349 example tests, 655 sidecar tests, analyze, format and dartdoc clean.

Example store and docs (Galaxy follow-up)

• FileSleuthStateStore kept its file in Directory.systemTemp. On Android that is the app's code_cache, which every install of a new build empties, so the example lost hidden cards and the card's place after each flutter run. overlayStateDirectory puts the file in the app's own files (Android) or Library/Application Support (iOS), beside the temp directory, and keeps the temp directory for any other layout. On the Galaxy A07 a hidden card stayed hidden after adb install -r and after a flutter run of a new build. On the iPhone 12 (iOS 17.5) the file lands in Library/Application Support beside tmp, and a hidden card stayed hidden after devicectl device install app and a new flutter run.
• compare_snapshots on a Galaxy snapshot: 1.0.0 against 1.1.0 returns versionWarning, against 1.0.0+build.7 returns none, and 2.0.0 or 0.38.0 is refused with arg_lineage_mismatch.
• The release notes, CHANGELOG and CLAUDE.md describe the Jank tag hold, the Hidden page labels and the example store.
• Gates at this tip: 5,099 tests on 3.47.6 and on the 3.32.8 floor, 44 benchmarks, 353 example tests, analyze and format clean. Every stack branch analyzes clean and passes its tests.

Doc audit

Three read-only passes checked every 1.0.0 doc against the code, and each finding was confirmed in the code before it was fixed here (doc comments in #23 and the Guide's Jank text in #24 went to the PRs that made them stale).

• Release notes and CHANGELOG: Why it rebuilds shows in every debug run and asks for enableDebugCallbacks when it is off; the public-name test and the api-diff job are described; only a version 1 hide key without a widget becomes an any-widget key; cardDivider, the severity graphic parameters, Escape over an app dialog, the collapsed title's three lines at large text and the light-theme marks match the code; a repeated banner bullet is gone.
• API stability: dart_apitool 0.23.2 rates a removed @experimental member of a class that is not experimental (such as a capture static on Sleuth) as breaking. The README and doc/api_1_0_0.md now say that removal waits for a major release instead of promising it in a minor one.
• README and docs: Rebuild stats is a page in the More menu; the trend example reads "seen 19 of 20 scans, persistent" (12 of 20 cannot read persistent); the test badge says 5,099; reduced motion, the back order, the crosshair before its first scan, the colours fromColorScheme keeps and the example store's directory match the code. The Guide's 1.3x tip names the status row and the trigger, and the markers tip says a second tap hides them.
• Sidecar docs: diagnose reports the stream and stall counters on every accepted app, compact issues have 13 fields, the prior lineage is 0.38, connect's warning fires for any accepted version other than the pin, notes and the explain_issue description no longer describe 0.36 and 0.37 apps (refused at connect), and notUsefulMarks is a data key. The capture procedure names the "Profile · no VM" label.
• The README and pub.dev screenshots still showed the 0.38 overlay (VM+ badge, summary bar, confidence badges, footer). They are re-taken on an iPhone 12 (profile, --no-dds, Chat App demo, card maximized): dark shows the issue list with the run label, severity chips and meta lines; light shows Heavy Computation expanded to its gauge, route, evidence, two linked causes and fix. The pubspec captions match and stay under pub.dev's 160 characters.
• CLAUDE.md names the 1.0 replacements of the 0.37 card internals and counts the API fixture in names. doc/internals.md and mcp_tool_schema.md lose three passive sentences.
• Gates at this tip: every stack branch analyzes clean and passes its tests; 5,099 tests on 3.47.6 and on the 3.32.8 floor, 353 example tests, 658 sidecar tests, format and dartdoc clean, both publish dry runs 0 warnings. Benchmarks were not re-run: only docs, comments and Guide strings changed.

Device snapshot for the 1.0.0 shapes (step 21)

The six snapshots under test/validation/captures/mcp_snapshots/ come from sleuth 0.34, so no device payload exercised measurement or notUsefulMarks. snapshot_measurement.json is a new iPhone 12 capture (iOS 17.5, Flutter 3.47.6, profile, --no-dds, capture mode): the Always-Repaint and CSV Import routes, two CSV imports and one card marked Not useful. It holds four issues with a measurement each and one mark, and checkSnapshotCapturesMatchSchema checks the mark and its measurement against doc/mcp_schema.json; a planted unknown key fails it. The plan said to re-record snapshot_heavy_compute.json, but frame_stats_real_frames_test reads the 0.34 files' frames as real-device jank data, so this is a seventh file instead. A Galaxy A07 snapshot taken the same way passed the same audit and is not committed. doc/mcp_schema_derivation.md counts seven captures and notes where the new one differs. 5,099 tests pass.

Prompts use the 1.0.0 data

The triage_performance, audit_memory and release_check prompts predated 1.0.0, so a model following them ignored each issue's measurement and the issues marked Not useful, although the overlay's toast says MCP output includes the mark. Each prompt now explains both: quote the measured value against its warning or critical line, and match a notUsefulMarks key (the issue's stableId, plus |widgetName when it names a widget). The triage lists marked issues last, the memory audit sets them aside and names them, and the release gate names the mark but keeps the issue in its verdict. A new test checks that every prompt reading get_issues covers both and that the gate keeps marked issues; it fails on the old prompts. 659 sidecar tests pass and the publish dry run reports 0 warnings.

🤖 Generated with Claude Code