docs: new-package publish rule, ADR scope, device-claim recipe, find default action

Merged
TH
8d ago
+48-22

Summary

Four small docs commits (7 files):

  1. docs/agents/pull-requests.md: a new public package under packages/ needs a safe npm transition before its PR merges. The maintainer publishes an empty placeholder (e.g. 0.0.0) under a non-latest dist-tag, configures the npm trusted publisher, and only then does the PR drop "private": true. Context: #4092 added @agent-device/revyl without that step, so the nightly Release failed twice (#4152). The 40,000-byte agent-docs budget is paid for by cutting duplicates in testing.md (lock sentences that AGENTS.md already states, the Integration/Coverage jobs sentence) and a pointer line in pull-requests.md, plus two duplicated lines in the PR flow.
  2. docs/adr/FORMAT.md: experiment logs, run details and measurements of a rejected alternative go in the issue; the ADR keeps the alternative with a one-line reason. Amend an ADR when its decision, consequences or open gaps change.
  3. website/docs/docs/sessions.md: a recipe that holds a device claim around an external command (xcrun simctl install): uniquely named explicit-UDID app-less open, || exit on a refused claim, trap close, exit status kept, boot side effect, crash recovery, and that it is not a process-owned claim. Fixes #3263.
  4. help find / selectors.md: usage is find <locator|text> [action] [value], the schema has action?, and the help says the action defaults to click (parseFindArgs already does).

Validation

Docs and help text only, so no new runtime test applies; the existing help, doc-coverage and agent-guidance guards cover the changed surfaces.

  • pnpm check:affected --run --head 5420f99ed0 passed (format, lint, typecheck, layering, fallow, build, vitest-related, unit, doc-links, doc-prose, agent-guidance). Receipt: .tmp/validation/run-sKSSei/receipt.json.
  • Recipe run live on iPhone 17 Pro Max DBEA214F-ā€¦ (shut down afterwards): a second claimant got DEVICE_IN_USE and did not run the command; a failing command's exit status came through; the trap closed the session; no claims remained.
  • Not verified: a real expo run:ios build, and a kill -9 of the shell.

šŸ¤– Generated with Claude Code