docs: clarify keyboard dismiss fallbacks

[thymikee]

Summary

Clarify safe keyboard-dismiss guidance across iOS and Android.

On iOS, retain the safe native-control path and report unsupported dismissal rather than inventing a generic blur action. On Android, document that normal back behavior is a fallback only when the task explicitly permits it for an IME that requires back navigation. Add focused SkillGym coverage.

Refs #1298.

Validation

• pnpm check:affected --base origin/main --run
• pnpm test:skillgym:case form-keyboard-dismiss-ios-fallback
• pnpm test:skillgym:case android-keyboard-dismiss-back-when-allowed

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.8 MB	1.8 MB	+403 B
JS gzip	566.2 kB	566.4 kB	+131 B
npm tarball	680.5 kB	680.7 kB	+122 B
npm unpacked	2.4 MB	2.4 MB	+403 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	27.3 ms	27.6 ms	+0.3 ms
CLI --help	57.8 ms	57.9 ms	+0.1 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/cli-help.js	+403 B	+131 B

[thymikee]

Current-head review (58c77a6bf): two blockers.

1. P1: the new help overstates an unproven generic iOS blur fallback. After keyboard dismiss returns UNSUPPORTED_OPERATION, tapping an arbitrary inert static text/heading is not itself a native first-responder dismissal contract. The linked Capacitor/WKWebView (iOS): no supported keyboard-dismiss / blur — web forms mis-tap under the keyboard #1298 specifically reports Capacitor/WKWebView, but the only live evidence here is a React Native test-app heading; that does not prove a WKWebView input will blur or the keyboard will close. Limit guidance to a fallback verified on the affected route/surface, or retain/report dismissal unavailable when no safe native dismiss control exists. Do not generalize the React Native observation into a generic iOS responder primitive.

2. P2: the SkillGym regression is vacuous. Its prompt/contract supplies visible static heading: Contact details and explicitly asks to blur through that heading, so reverting the help change can still yield the expected answer. /snapshot/i also does not enforce a post-action snapshot or proof that the keyboard disappeared. Make the case derive fallback behavior from help and assert action ordering plus post-action keyboard verification so the old guidance fails.

All CI is green, but these guidance/test findings block ready-for-human.

[thymikee]

Exact-head re-review (d7b0a87c1): the guidance itself is now correct. iOS no longer promises a generic blur and reports dismissal unavailable unless an explicitly intended app control exists; Android uses back only when normal back behavior is acceptable.

One P2 test blocker remains: the SkillGym cases are still revert-insensitive. The iOS contract names Done and the task explicitly tells the model to close through that control; assertions require only field/Done/press-or-click, with no action ordering or post-action evidence. The pre-PR guidance would still pass. The Android case likewise supplies that back is required/permitted and asks for back, so it does not derive the fallback from help. Make the cases choose the fallback from help rather than embedding the answer, and assert action → post-action verification ordering (prefer an observable previously occluded target or explicit keyboard-hidden evidence).

The current iOS Smoke failure is unrelated to this docs/SkillGym delta: untouched abandoned-XCTest-channel timing tests drained before observing RUNNER_BUSY. Rerun is appropriate, but the confirmed red check also prevents readiness until green. No ready-for-human yet.

[thymikee]

Exact-head re-review (0b67c4040): the production guidance is correct, CI is fully green, and the PR is mergeable, but the prior P2 SkillGym blocker is not fixed.

The iOS case still supplies the answer (visible app keyboard close control: Done; task says to close through that control), and its assertions require only field/Done/press-or-click—there is still no dismiss action → concrete post-action keyboard-hidden or previously-occluded-target evidence. The pre-PR help would pass it. The Android case now asserts back → is visible ordering, but it still says the IME needs back, explicitly permits back, and asks to use permitted back behavior, so the fallback choice is not derived from help and remains revert-insensitive.

Rewrite both prompts to provide the observed state and permission constraints without naming the fallback command/control choice; keep the Android ordering assertion and add equivalent concrete post-action evidence for iOS. No ready-for-human yet.

[thymikee]

Fixed in f174807b3.

The SkillGym coverage now derives the fallback from help instead of embedding the answer:

• iOS with no app-provided dismiss control must report keyboard dismissal unavailable and rejects static-heading/next-target presses.
• iOS with a real Done accessory requires press/click Done → is visible submit-order ordering.
• Android describes the navigation constraint/permission without naming back, then requires back → is visible field-name ordering.

Independent review is clean. Local build, typecheck, formatting, and diff checks pass. The full model-backed SkillGym execution could not be completed locally because its external runners require data-export approval; PR CI is authoritative for that job.

[github-actions]

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