Skip to content

docs: improve README onboarding#1333

Open
thymikee wants to merge 4 commits into
mainfrom
agent/improve-readme
Open

docs: improve README onboarding#1333
thymikee wants to merge 4 commits into
mainfrom
agent/improve-readme

Conversation

@thymikee

@thymikee thymikee commented Jul 18, 2026

Copy link
Copy Markdown
Member

Summary

  • sharpen the README opening around the coding-agent feedback loop
  • move Quick start earlier and demonstrate a Contacts form flow using snapshot refs and --settle
  • consolidate overlapping capabilities and use cases
  • qualify target-dependent support and clarify the comparison with Appium, Detox, and Maestro
  • add concise AEO-friendly answers for product definition, React Native/Expo/Flutter support, CI, and framework comparison
  • preserve the project-approved user trust signal and current agent-readable documentation links

Why

The previous README repeated the product definition, delayed the first command loop, used an undefined sample app, and did not teach the current settle-first interaction workflow. The revised structure helps evaluating developers understand the product and complete a representative session sooner.

The form example also shows that refs belong to the snapshot or settled diff that returned them, so agents continue from the latest observation instead of treating refs as persistent identifiers. The compact FAQ keeps common search and answer-engine questions self-contained without duplicating the full documentation.

Impact

The README is shorter and more scannable while providing a more accurate default workflow for coding agents. It retains discovery terms such as AI mobile app testing, React Native, Expo, and Flutter, and calls out the Node.js 24 requirement for web automation. No runtime behavior or public API changes.

Validation

  • git diff origin/main...HEAD --check
  • verified local README image and document targets exist
  • verified Node.js and framework discovery wording against repository sources
  • docs-only change; no test suite required by the repository testing matrix

@thymikee
thymikee marked this pull request as ready for review July 18, 2026 19:11
@thymikee

Copy link
Copy Markdown
Member Author

The new quick-start chain is not executable as written. press @e2 --settle publishes a partial ref frame, so the next mutation cannot consume the settled diff's bare @e7; that is rejected as plain_ref_requires_complete_frame. A settled-diff ref must be generation-pinned (@e7~s<refsGeneration>), or the example must take a complete snapshot -i before using a bare ref (or use a selector). Please revise the example so a new user can copy/paste the whole flow successfully.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant