docs: tighten user-facing docs wording

[thymikee]

Summary

Wording pass and reorganization of the user docs: all 26 website/docs pages, README.md, and the TestMu README.

• Style: follows the writing-user-docs guide — second person, active voice, no time-relative or marketing wording, prerequisites up front. Every qualifier from the base text is kept ("can", "may", implicit vs named sessions, and so on).
• One page per topic: commands.md stays the full command reference (every command and flag, with a one-line meaning) and links to the page that explains each topic. Snapshot capture details moved to Snapshots, find to Selectors, log grep and remote diagnostics to Debugging & Profiling, session locks to Sessions, replay and batch details to their own pages, the takeover reason to Remote Proxy, and iOS device setup to Installation. Repeated install, PATH, MCP and help-topic text now lives in one place.
• New content: a selector syntax section (checked against packages/selectors), plus "Retry after a failed command" and "Output and warnings" sections in Commands.
• Corrections, checked against code:
  • --max-steps is 100 by default and can be set up to 1000.
  • The event-redaction text in Client API now matches the session journal.
  • Implicit-session wording now matches Sessions.
  • The Maestro --from wording now matches how flows are split into steps.
  • Doc links point to oss.callstack.com, not the agent-device.dev landing page.
• Snippet fix: the selector-helpers example in client-api.md was never closed. It's now closed, and the snippet compile test type-checks it.

31 files changed. The diff is over the 1,000-line budget because all docs were requested in one PR.

Validation

• pnpm check:affected --run passed on d7501dd, including the doc-content and snippet compile tests.
• pnpm --dir website build succeeds.
• A script confirmed every cross-page #anchor link resolves.
• Docs-only; no device runs needed.

🤖 Generated with Claude Code

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-10-08 11:06 UTC

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	5.13 MB	5.13 MB	-51 B
Package (unpacked)	5.13 MB	5.13 MB	-51 B
Package (download)	1.54 MB	1.54 MB	-15 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	27.9 ms	27.9 ms	-0.0 ms
CLI --help	82.3 ms	83.9 ms	+1.6 ms

[cubic-dev-ai]

All reported issues were addressed across 29 files

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[thymikee]

I found no code problems in cf6be5b, but eleven of the open inline review threads still hold and the docs wording needs fixes before merge. Several edits say more than the base text or the code supports. Please restore the base meaning in each, and keep every claim no stronger than what the code does.

The still-open threads are: testmu.md "always has something" (#3295 (comment)), security-trust.md newer-daemon refusal (#3295 (comment)), snapshots.md "releases the session" (#3295 (comment)), aws-device-farm.md "returns" (#3295 (comment)), selectors.md matched element (#3295 (comment)), introduction.md "It runs on" (#3295 (comment)), configuration.md installSource env var (#3295 (comment)), replay-e2e.md runFlow steps (#3295 (comment)), sessions.md cursors after rotation (#3295 (comment)), sessions.md "never attach" (#3295 (comment)), and eve.md cleanup wording (#3295 (comment)). Two threads do not apply, so you can resolve them. The agent-setup.md:27 thread says the same as the base text, and the PATH caveat is already covered at lines 52 and 178 (#3295 (comment)). The selectors.md:23 thread is about wording that did not change in meaning from base (#3295 (comment)).

The Smoke Tests check is still running and has not failed. The diff changes only markdown and one examples/sdk tsconfig path mapping, so that route is untouched. I did not re-run the affected checks or the website build, and I did not trace the BrowserStack local-upload or macOS-helper first-use corrections to source. I also did not read all 29 files line by line.

[cubic-dev-ai]

All reported issues were addressed across 27 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[thymikee]

The docs-only changes at ea7b43c look fine, but five wording claims are still open from the earlier review (#3295 (comment)), so they need fixing before merge. I found no new problems at ea7b43c, and I did not read the full delta diff or check other rewordings against versioned help.

Not blocking: the claims below can be taken or left. selectors.md line 43 says find rejects the query when more than one element matches, which may only hold for mutating actions. limrun.md line 70 may mislabel installs and port reverse as helper-backed. debugging-profiling.md line 88 may omit a requests/ directory in the diagnostics path. snapshots.md line 133 may wrongly pair the XCTest runner bound with truncated: true. replay-e2e.md line 80 may need "includes it can resolve and read". installation.md line 96 says "set only these environment variables" before more signing variables, so "only" should become conditional wording.

The open inline threads still apply. These two are worth fixing first: #3295 (comment) (find multiple-match scope) and #3295 (comment) (Limrun helper wording). Three more P2 threads still apply: #3295 (comment) (diagnostics path), #3295 (comment) (snapshot truncation), and #3295 (comment) (Maestro includes). One lower-priority thread still applies: #3295 (comment). I only weighed the selectors and installation threads, and I did not read the find handler, provider, runner or downloader code. For the other four I only confirmed the text matches what the thread quotes. I also did not verify the 13 resolved threads.

The Linux Smoke Tests job timed out in the apt "Install Linux desktop dependencies" step, before any repo code ran. This PR changes only docs, READMEs and the provider-testmu package.json, so the timeout is likely unrelated. No conflicts. Please fix the five wording claims and the "only" wording, then re-run the Smoke Tests job.

[thymikee]

Both findings from the earlier review at ea7b43c are fixed, and I found no new problems in the docs changes at d7501dd. Smoke Tests is still running and has not failed. This PR touches only docs, READMEs and package metadata, so it does not overlap the device runtime paths those tests cover. There are no conflicts. The remaining step before merge is for Smoke Tests to finish green.

I checked the reworded passages in this update, not every docs page against CLI help. I did not verify the trim measurements (165.7 MB to 5.9 MB) or the legacy ~/.agent-device/ios-runner claim against source. I also did not inspect the examples/sdk/tsconfig.json and provider-testmu package.json changes beyond the diffstat.

[thymikee]

The docs changes at d7501dd look good, and the earlier findings from ea7b43c no longer apply. No code problems remain. CI shows 21 checks with none failing, and the PR is docs-only, so it does not touch any device runtime route. Smoke Tests are still running, but nothing has failed so far. No conflicts. I did not check every reworded page against CLI help, and I did not verify the 165.7 MB to 5.9 MB trim figure or the legacy ios-runner claim against source. I read the range-diff and the key claims, not the full diff. Nothing else stands in the way. The PR is ready for human merge once the remaining checks finish green.