docs(readme): document the full locator/interaction/assertion/mocking surface

[BenSheridanEdwards]

Summary

Docs-only. The README documented roughly a third of the shipped public surface; this fills the gaps without changing the pitch or structure:

• Locators: full getBy* list plus narrowing — first()/last()/nth()/count() and the near() relative locator (with maxDistance).
• Interactions: fill()/clear() (the v0.11.0 atomic path), check()/uncheck(), press({ duration }), waitFor(), tap({ clickableAncestor }), and native.fill(label, text).
• Assertions: all eight matchers with .not, plus the did-you-mean failure hint shown as a sample error.
• Mocking: mock.route().fulfill/reject/abort, expect(mock).toHaveSent/toHaveReceived, and mock.send() — the Playwright-page.route() half of the pitch was previously invisible.
• Troubleshooting: the "Locator times out" row now points at the automatic did-you-mean candidates instead of telling users to grep page source.
• Evidence: the single closing line grew into a short section with captureState("checkpoint").

Every example was verified against the current exports (src/index.ts star-exports, FrameMatch shape, MockRoute signatures, locator options) before writing.

Proof

• npm run check
  • Passed on docs/readme-overhaul (no code changes).
• npm test
  • Passed at branch point (154/154); no code touched.
• Generated project/device proof, or N/A:
  • Not applicable: README-only change.
  • Screenshots: Not applicable; documentation text with no rendered UI or behavioural surface.

Risk

• None beyond docs accuracy; all documented calls checked against the source.

Notes

• Full device coverage not run: docs only.
• Deliberately not documented: features still in open PRs (scrollIntoView, inspect) — docs should trail merges.

PR Proof Law

• I followed .agents/DEFINITION_OF_DONE.md and .agents/skills/pr-inline-screenshot-proof/SKILL.md.
• Screenshots are committed and embedded inline with ![alt](...png?raw=1), or the proof section says Not applicable with the technical reason.
• The PR body has no bare screenshot links, local paths, relative paths, or proof placeholders.