docs: bless the works-today iOS SpringBoard/widget workflow (#1296 PR A)

[thymikee]

Summary

First slice of #1296's delivery plan — PR A: bless the works-today SpringBoard workflow. Help/skill docs only, no product code, matching the issue's explicit re-scoping after the live simulator probe (see the issue's 2026-07-24 status update).

The probe proved on iPhone 16 sim (iOS 26.2, Xcode 26.2) that the shipping CLI, unchanged, already supports the full widget add/edit/remove flow by opening SpringBoard as the session app:

• agent-device open com.apple.springboard --platform ios binds a driveable SpringBoard session. Verified on iOS simulator only — physical-iPhone SpringBoard support is not yet verified (see iOS: first-class widget and Live Activity testing through a system UI target #1296); the CLI help topic and website/docs/docs/commands.md both say so explicitly and link back to the issue.
• The entire flow (edit mode via empty-space long-press → Edit menu → gallery → search → size picker → Add Widget → installed → long-press → Edit Widget/Remove Widget) is selector-driven from a fresh snapshot -i, except two coordinate fallbacks: entering edit mode, and (until the gallery capture fix in a later PR) tapping widget-gallery search-result rows, which currently return unlabeled accessibility nodes.
• System labels vary by iOS version/locale, so the topic tells agents to read them from the current snapshot instead of hard-coding strings like Edit/Add Widget.

Scope (4 files)

• src/cli/parser/cli-help.ts — new agent-device help ios-system-ui topic with the full command-shape loop and rules; cross-linked from help physical-device and help workflow's Escalate section.
• src/cli/parser/__tests__/cli-help-topics.test.ts — usageForCommand resolves ios-system-ui help topic test plus the physical-device-scoping assertion.
• skills/agent-device/SKILL.md — pointer added to the topic router.
• website/docs/docs/commands.md — matching section with the same physical-device scoping and issue link.

Not in the top-level Agent Workflows: list on bare agent-device help: adding it there pushed help macos past #1404's newly-enforced 30-line first-screen budget benchmark. The topic stays fully reachable via the cross-references above.

SkillGym coverage — intentionally omitted

docs/agents/testing.md currently requires a SkillGym case for command-planning-guidance changes. This PR does not include one: per explicit author direction, most of the SkillGym harness is being removed in #1411 (open, not yet merged), so iterating on a case here would be wasted work. Earlier revisions of this PR did include a sequence/adjacency-aware case (ios-system-ui-springboard-widget-add) that passed synthetic finalOutput validation; it was dropped rather than run live, since the harness it depends on is slated for removal. If #1411 lands first, this PR should be rebased and covered by whatever replaces it instead.

Test plan

• pnpm typecheck
• pnpm lint
• pnpm format:check
• npx fallow audit --base origin/main (clean)
• npx vitest run src/cli/parser/__tests__/cli-help-topics.test.ts src/__tests__/cli-help.test.ts
• npx vitest run scripts/__tests__/help-conformance-bench.test.ts (unaffected by this change; confirms no regression)
• pnpm build, then manually ran node ./bin/agent-device.mjs help ios-system-ui and node ./bin/agent-device.mjs help to confirm the rendered topic, its cross-links, and that the first-screen output stays within the 30-line budget.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-27 13:13 UTC

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.86 MB	1.87 MB	+3.4 kB
JS gzip	597.0 kB	598.1 kB	+1.1 kB
npm tarball	711.7 kB	712.9 kB	+1.2 kB
npm unpacked	2.49 MB	2.49 MB	+3.5 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	25.8 ms	25.2 ms	-0.6 ms
CLI --help	53.1 ms	52.6 ms	-0.5 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/cli-help.js	+3.4 kB	+1.1 kB

[thymikee]

Reviewed exact head ae00f90. Not ready. P1 — do not publish unverified physical-device support. website/docs/docs/commands.md says open com.apple.springboard binds SpringBoard “on a simulator or physical device today,” but #1296 explicitly lists the physical-iPhone SpringBoard snapshot and selector interaction as an unverified remaining gate; the only evidence is an iPhone simulator, whose private-AX fallback is simulator-only. Limit the claim to the validated simulator or attach physical-device evidence. P2 — add focused SkillGym coverage now. This PR publishes new agent-facing command-planning guidance and routes the skill to it, but only tests rendered strings. The repo requires a SkillGym case for planning-guidance changes; cover opening SpringBoard, fresh snapshots/localized-label discovery, the two bounded coordinate fallbacks, reopening the app, and session cleanup. The simulator workflow itself matches #1296; completed checks are green and iOS smoke is pending. No ready label.

[thymikee]

Addressed both at c70a1f7:

• P1: scoped the SpringBoard claim to verified iOS simulator support in both the help ios-system-ui topic and website/docs/docs/commands.md, with a link to iOS: first-class widget and Live Activity testing through a system UI target #1296 for the still-unverified physical-iPhone gate.
• P2: added a SkillGym skill-guidance case (ios-system-ui-springboard-widget-add) covering opening SpringBoard, fresh-snapshot label discovery, the two documented coordinate fallbacks (empty-space long-press, gallery search-result tap), reopening the app under test, and session close. Verified locally by running the case's assert() against a synthetic good plan (passes) and a plan that invents a widget add command (correctly fails on the forbidden-output check), since test:skillgym itself needs a live model runner not available here.

[thymikee]

Re-reviewed exact head c70a1f70. The physical-device overclaim is resolved, but the new SkillGym case is still not ready.

P2 — make the SkillGym contract test the workflow it documents. The case says SpringBoard labels vary and must be discovered from a fresh snapshot, yet it requires the fixed English literal label="Add Widget". It also does not require a fill action for \“Calendar,\” so a plan can satisfy the case while skipping the requested gallery search. Require snapshot-derived selector/ref use instead of the fixed label, and require the Calendar search action.

All current checks are green.

[thymikee]

Addressed at eef27de (rebased onto latest main):

• P2: the case no longer requires the fixed literal label="Add Widget". The contract now gives explicit snapshot-derived refs (@e30 for opening the gallery, @e31 for the search field, @e35 for placement) and the case requires pressing/filling those refs plus a fill @e31 ... Calendar search action, matching what the topic itself instructs (discover controls from a fresh snapshot, don't assume fixed English labels). Hardcoded label="Add Widget"/"Edit"/"Done" is now a forbidden output.
• Re-verified locally with three synthetic finalOutput plans against the case's assert(): a compliant ref+search plan passes, a plan that skips the Calendar search fails on the missing fill @e31 ... Calendar, and a plan that reverts to fixed English labels fails on the missing @e30/@e35 ref presses.
• Rebased onto main (14be01b78) to pick up fix(replay): preserve cwd scope for opened sessions #1401; no conflicts.

[thymikee]

Review at eef27de: one actionable test-validity issue remains. The updated SkillGym case correctly requires fill @e31 ... Calendar and removes the fixed-English Add Widget requirement, but its independent/unordered matchers still allow an invalid workflow to pass: one early snapshot -i, a selector-based longpress instead of the required empty-space coordinate long-press, stale/invented refs, and an unrelated coordinate action can satisfy the case. Please make the assertions sequence-aware and bind each fresh snapshot and coordinate fallback to the documented SpringBoard step. All current checks are green, but GitHub also reports this head CONFLICTING/DIRTY, so reconcile the branch before readiness.

[thymikee]

Addressed at b8366d2:

• Added a small sequentialSteps mechanism to makeCase (a cursor-based ordered-match helper, assertSequentialCommandSteps) and switched the SpringBoard widget case to use it instead of unordered presence matchers. Each fresh snapshot, ref (@e30/@e31/@e35), and coordinate fallback is now bound to its documented step in the required order: open SpringBoard → raw-coordinate empty-space long-press → snapshot exposing @e30 → press @e30 → snapshot exposing @e31 → fill @e31 ... Calendar → screenshot → raw-coordinate result tap → snapshot exposing @e35 → press @e35 → reopen the app → close.
• The long-press step now specifically requires raw coordinates (two numeric args), not a selector, so a selector-based longpress no longer satisfies it.
• Re-verified locally against six synthetic finalOutput plans: two valid orderings pass (with and without an extra leading snapshot), and four invalid ones fail — including the exact bad pattern you described (early unrelated snapshot + selector-based longpress + invented refs + unrelated coordinate action) and an out-of-order plan that presses @e30 before the long-press/snapshot that should expose it.
• No branch conflicts; still rebased on main (152894cce).

[thymikee]

Re-review at cbae02a: the conflict and original broad ordering issue are resolved, but one narrowed P2 remains. assertSequentialCommandSteps only requires each matcher at a later line; it allows arbitrary intervening commands. A plan can therefore run snapshot -i, mutate UI state with home/another press/open, then use @e30 (similarly @e31/@e35) and still pass even though the ref is stale. The same gap exists between the screenshot and raw-coordinate fallback. Please require adjacency for each freshness-sensitive observation/action pair, or explicitly reject intervening state-changing commands. Current checks are otherwise green with iOS Smoke pending; do not apply labels.

[thymikee]

Addressed at e102129 (rebased onto main, 256887f):

• Added a requireAdjacent flag to SequentialCommandStep and marked the four freshness-sensitive pairs as adjacent — the ref press/fill must be the literal next line after the snapshot that minted it, and the coordinate tap must be the literal next line after the screenshot it was read from: snapshot → press @e30, snapshot → fill @e31, screenshot → raw-coordinate press, snapshot → press @e35. Any intervening command (state-changing or not) now fails the case.
• Split assertSequentialCommandSteps into findStepMatchIndex/describeStepPosition to keep it under the Fallow Code Quality complexity gate after adding the adjacency logic (learned from the previous round — re-ran npx fallow audit --base origin/main locally this time, clean).
• Re-verified locally with eight synthetic finalOutput plans, including your two described staleness scenarios: a plan that snapshots, runs home, then presses the now-stale @e30 (fails), and a plan with a press between the screenshot and the coordinate tap it informed (fails). The two valid orderings (with and without an extra leading snapshot) still pass, along with the previously-fixed bad patterns.

[thymikee]

Re-review at e102129: the adjacency/freshness defect is fixed, the head is mergeable, and all listed checks are green. One owner-action validation blocker remains: this SkillGym prompt/assertion change requires pnpm test:skillgym:case ios-system-ui-springboard-widget-add under docs/agents/testing.md, but the evidence reports only synthetic finalOutput probes and no SkillGym check is present. Please run and post the focused case, or obtain explicit maintainer acceptance if the live-model runner is unavailable. Do not apply ready-for-human until then.

[thymikee]

Rebased and simplified at f482975:

• Per your note, dropped the SkillGym case entirely (most of that harness is being removed in feat(bench): renderer-pinned samples, topic-coverage gate, error-recovery quizzes; trim skillgym to agentic checks #1411, so the sequence/adjacency work from the last two rounds isn't worth keeping here). The PR is back to docs-only: the help ios-system-ui topic, its cross-references, and the P1 physical-device-scoping fix.
• Rebasing onto main also picked up feat: strengthen agent help benchmarks #1404's new 30-line first-screen budget benchmark gate. Adding ios-system-ui to the top-level Agent Workflows: list pushed help macos to line 31, past the gate. Dropped that list entry — the topic is still fully reachable via its cross-references from help physical-device, help workflow's Escalate section, the agent-device skill router, and website/docs/docs/commands.md.
• Local verification: pnpm typecheck, pnpm lint, pnpm format:check, npx fallow audit --base origin/main (clean), the affected cli-help-topics/cli-help vitest files, and scripts/__tests__/help-conformance-bench.test.ts all pass.

[thymikee]

Reviewed exact head f4829756. The simulator-only scope, physical-device disclaimer, two bounded coordinate fallbacks, help routing/cross-links, and first-screen help constraint are correct. Not ready:

• P2 — required guidance validation is absent. Current main still requires a SkillGym case when command-planning guidance changes. This head changes CLI help, the skill router, and website guidance but has no case; feat(bench): renderer-pinned samples, topic-coverage gate, error-recovery quizzes; trim skillgym to agentic checks #1411 is open, not merged. Restore/run the focused ios-system-ui-springboard-widget-add case, or rebase after feat(bench): renderer-pinned samples, topic-coverage gate, error-recovery quizzes; trim skillgym to agentic checks #1411 lands and provide the replacement help-conformance coverage.
• P2 — PR body is stale/incomplete. It still claims the topic is registered in the top-level Agent Workflows list even though the latest commit intentionally removes that entry, and it omits the required four-file scope disclosure.

All current checks are green; keep ready-for-human withheld.

[thymikee]

Re review at f482975:

• PR body: rewritten. Removed the stale Agent Workflows claim, added an explicit 4-file scope section, and a dedicated section explaining the SkillGym omission with the feat(bench): renderer-pinned samples, topic-coverage gate, error-recovery quizzes; trim skillgym to agentic checks #1411 rationale.
• SkillGym coverage: this is a deliberate scope decision made in this conversation (drop the case now rather than keep iterating on a harness that's being removed in feat(bench): renderer-pinned samples, topic-coverage gate, error-recovery quizzes; trim skillgym to agentic checks #1411), not something I'm treating as resolved on the merits — it's flagged as an open policy question in the PR body's new "SkillGym coverage — intentionally omitted" section. If docs/agents/testing.md still requires it while feat(bench): renderer-pinned samples, topic-coverage gate, error-recovery quizzes; trim skillgym to agentic checks #1411 is open, the options as I see them are: (a) hold this PR until feat(bench): renderer-pinned samples, topic-coverage gate, error-recovery quizzes; trim skillgym to agentic checks #1411 merges and add coverage for whatever replaces SkillGym, or (b) accept the gap for this docs-only change with an explicit maintainer waiver. Given you're both the author's principal here and the reviewer, that call is yours — let me know which way to go and I'll follow through (either restore+run the case, or wait on feat(bench): renderer-pinned samples, topic-coverage gate, error-recovery quizzes; trim skillgym to agentic checks #1411).

[thymikee]

Per explicit maintainer decision: skip SkillGym coverage for this PR. Accepting the gap as documented in the "SkillGym coverage — intentionally omitted" section of the PR body — treat this as a maintainer waiver rather than a blocker, given #1411 is already removing most of that harness. No further action planned on this point unless #1411's replacement coverage requirement changes that.