docs(scroll): tell the caller what a scroll's movement field means

[thymikee]

What

movement and scroll_no_progress change what an agent's next command should be, so every surface that describes the command says so — including when the field is absent, which an agent will otherwise read as "nothing moved".

• src/commands/interaction/metadata.ts — the versioned description (one string, read by both CLI help and the MCP tool description) names the four observations, the refusal, and the three absence cases. Flag-free wording, because command-surface-metadata.test.ts refuses CLI syntax in the MCP body (it caught my first draft).
• src/mcp/command-output-schemas.ts — the scroll output object was missing movement while the contract had it. Adds the enum with what each value warrants, and the four places the field is legitimately absent: the tiers that verify per pass (top/bottom, --until), a runtime bound without a capture, a platform whose scroll dispatches no swipe, and callers that own the observation already (--settle, replay with postGestureStabilization: false).
• website/docs/docs/commands.md — the same in prose, next to the keyboard-band behaviour it sits against.

Both agent-facing texts also carry the case this round added: moved is a claim about the scroller the swipe ran in, and a difference that sits only outside it answers unobserved rather than crediting the gesture. And the site no longer says unobserved covers "no capture on this runtime" — that case carries no movement field at all, which the same paragraph already said; the two sentences contradicted each other.

Validation

• This layer's diff is +6/−1 over three files; the stray rewrite of the --quality recording sentence (a restack artifact against main's 92b8fae) is dropped. pnpm check:command-docs (12/12), pnpm check:mcp-metadata --check, and pnpm check:affected --run at the stack head 882256121 all pass; pnpm check:fallow --base fix/scroll-observed-movement reports no issues.

Docs-only; no device evidence needed here. #2771 carries the live run.

🤖 Generated with Apex by Callstack

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-09-23 14:20 UTC

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	4.80 MB	4.80 MB	+1.7 kB
Package (unpacked)	4.80 MB	4.80 MB	+1.7 kB
Package (download)	1.43 MB	1.43 MB	+613 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	32.6 ms	26.6 ms	-6.0 ms
CLI --help	81.0 ms	77.6 ms	-3.4 ms

[thymikee]

Reviewed at b2ec05f: clean. The help string, the MCP movement enum and the website text match the four values in the contract and the scroll_no_progress refusal from #2771, and this is ready for human review once that PR settles. One optional note: the unobserved wording could name every case where movement is absent (no capture, non-swipe platforms, settle/replay). CI was still queued when I looked; the PR reports check:command-docs and check:mcp-metadata --check passing locally.

[thymikee]

Reviewed at 44f9a26: clean. The doc fixes from the earlier review landed, and this stays ready for human review once #2771 settles.

Not blocking: the website says unobserved covers "no capture on this runtime", but in scroll-runtime.ts that case has its own reason, and unobserved comes from a missing or stale baseline or a blind capture after the gesture; the MCP text for an absent movement could also name desktop/web, --settle and Maestro replay.

The CI failures on this branch are cancelled jobs from the stacked base, not results of this diff, which only changes a help string, an MCP enum and a docs page.

[thymikee]

Done — every absent case is now named on the two agent-facing surfaces. The MCP movement description spells out the four places the field disappears and says in terms that its absence is never a claim that nothing moved: the tiers that verify per pass (top/bottom, --until), a runtime bound without a capture, a platform whose scroll dispatches no swipe (the Linux wheel), and callers that already own the observation (--settle, or a replay with postGestureStabilization: false). The website paragraph covers the same, and the shared CLI/MCP description carries a shortened version.

One thing worth knowing from CI-side validation: my first draft wrote --settle into the shared description and command-surface-metadata.test.ts failed it — the MCP tool description may not contain CLI syntax — so the metadata string says "a settle observation" instead. The flag names appear verbatim on the surfaces where they're legal (the MCP output schema and the docs page).

[thymikee]

Reviewed ff72009. The docs still match the movement values the stack produces, so this is ready for review. No conflicts. CI was still running and no job had failed.

Not blocking: this commit also rewrites a recording-quality sentence in commands.md#L1140, and main already has that wording from 92b8fae. It probably came in with the restack. Maybe drop it?

[thymikee]

This looks ready for review at aa0d725. It is a rebase of the reviewed ff72009, and the stray --quality wording from that review is gone.

Not blocking: could the absence list in metadata.ts and commands.md also name the non-swipe platforms (macOS, web, Linux, Vega), since scroll-movement.ts returns non-swipe-platform for them? The MCP schema's "the Linux wheel" wording could use the same list, and "no capture on this runtime" could leave the unobserved causes, because directionalMovementClaim omits the field in that case.

All checks were still queued; this change only edits doc and schema-string text. The live evidence for the movement values is still open on #2771, so this doc should land with or after it.

[thymikee]

Both notes taken, on 6a0661bfa.

The --quality recording sentence is dropped — that was a restack artifact of mine, not a deliberate edit, and this layer is now +6/−1 over metadata.ts, command-output-schemas.ts and commands.md.

The unobserved wording was a real contradiction and is fixed in both directions. The site no longer says unobserved covers "no capture on this runtime" (that case carries no movement field at all, as the same paragraph's last sentence already said), and the MCP text now names the field's absence cases where they are legal: the per-pass tiers, a runtime bound without a capture, a platform whose scroll dispatches no swipe, and callers that already own the observation.

One addition since your review: moved is a claim about the scroller the swipe ran in, and a difference that sits only outside it answers unobserved. Both agent-facing texts say so — found on a device and described in #2776.

🤖 Generated with Apex by Callstack

[thymikee]

Reviewed 6a0661b. The docs now describe the container-confined moved case, both earlier notes are addressed, and this looks ready for human review.

Not blocking: the moved wording could also cover horizontal scrolls and screens with no scroller, where the whole surface decides (src/mcp/command-output-schemas.ts#L594), and the leftover "or no movement field at all" hedge in packages/contracts/src/platform-runtime-operations.ts#L258 could go.

The failing iOS Smoke Tests assertion (Simulator AX bridge evidence gap) is likely unrelated: this diff only changes description strings, and the same assertion fails on other unrelated PRs today.

The head has since moved to 8822561, a rebase onto main in which this commit is patch-identical, so the review above still applies.