docs(agents): write agent docs in ASD-STE100 and remove misleading docs

AGENTS.md

@@ -1,61 +1,62 @@
 # AGENTS.md
 
-`agent-device` is a CLI and daemon for automating devices and web targets.
+`agent-device` is a CLI and daemon that automates devices and web targets.
 The daemon owns sessions. Registry declarations route commands to platform runtimes.
 
 ## Task routing
 
-Read only the row for your current task. Follow further links only when they apply.
+Read only the row for your current task. Follow other links only when they apply.
 
 | When the task involves | Read |
 | --- | --- |
-| Domain vocabulary | `CONTEXT.md`, `docs/agents/domain.md` |
+| Domain vocabulary | `CONTEXT.md` |
 | Architecture decisions | `docs/adr/README.md` |
 | Source changes, package boundaries, routing, diagnostics | `docs/agents/code-ownership.md` |
-| Running checks or diagnosing a failed gate | `docs/agents/testing.md` |
-| Writing or changing tests | `docs/agents/test-authoring.md` |
-| Auditing or deleting tests | `docs/agents/test-audit.md` |
+| Checks or a failed gate | `docs/agents/testing.md` |
+| New or changed tests | `docs/agents/test-authoring.md` |
+| Test audits or deletions | `docs/agents/test-audit.md` |
 | Mutation experiments or base comparisons | `docs/agents/test-experiments.md` |
-| Changing gate selection, fuzzing, or mutation harnesses | `docs/agents/gates.md` |
+| Gate selection, fuzzing, or mutation harnesses | `docs/agents/gates.md` |
 | Selector capture, polling, interaction fast paths, replay | `docs/agents/selector-capture.md` |
-| Adding or changing a CLI flag | `docs/agents/cli-flags.md` |
-| Opening or updating a PR | `docs/agents/pull-requests.md` |
-| Reviewing a change | `docs/agents/review.md` |
+| A new or changed CLI flag | `docs/agents/cli-flags.md` |
+| A PR to open or update | `docs/agents/pull-requests.md` |
+| A change to review | `docs/agents/review.md` |
 | Device-facing changes or manual device verification | `docs/agents/device-verification.md` |
-| Writing issues or PRDs, and triage labels | `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md` |
+| Issues, PRDs, or triage labels | `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md` |
 | Web backend setup or diagnostics | `docs/agents/web-backend.md` |
 
-Device-facing changes affect live device behavior: dispatch, capture, interaction, app lifecycle, or native execution.
-A daemon edit that changes none of these needs no device run.
+A device-facing change affects live device behavior: dispatch, capture, interaction, app lifecycle, or native execution.
+If a daemon edit changes none of these, a device run is not required.
 
-Versioned CLI help owns command semantics. For app-driving startup, use the skill's routing card.
+The versioned CLI help owns command semantics. To drive an app, start with the skill's routing card.
 
 ## Working rules
 
-- Keep edits within the requested command family or module group. Inspect other platforms only when the task requires it.
-- Fix recurring failures at the owning type, registry, or construction path. Do not reconstruct another owner's state.
-- Use typed reasons and details for behavior. Never match error text.
-- Add compatibility or fallback behavior only when explicitly requested or approved. Remove superseded paths during migrations.
-- Encode invariants in names, types, and boundaries. Comments explain public APIs, tool directives, or constraints code cannot express.
-- Resolve gate failures at the reported invariant. Do not suppress them or add an allowlist to get a pass.
-- Use `@agent-device/selectors` for selector parsing and matching. See `docs/agents/code-ownership.md` for other shared owners.
-- Keep skills as routing cards. Keep `CONTEXT.md` glossary-only. Update owning help and user docs when behavior changes.
+- Keep edits in the requested command family or module group. Examine other platforms only when the task requires it.
+- Fix a recurring failure at the owning type, registry, or construction path. Do not rebuild another owner's state.
+- Use typed reasons and details for behavior. Do not match error text.
+- Add compatibility or fallback behavior only on explicit request or approval. During a migration, remove superseded paths.
+- Encode invariants in names, types, and boundaries. Write comments only for public APIs, tool directives, or constraints that code cannot show.
+- Resolve a gate failure at the reported invariant. Do not suppress it. Do not add an allowlist to get a pass.
+- Use `@agent-device/selectors` to parse and match selectors. For other shared owners, see `docs/agents/code-ownership.md`.
+- Keep skills as routing cards. Keep `CONTEXT.md` as a glossary only. When behavior changes, update the owning help and user docs.
 
 ## Worktree setup
 
-- Use `pnpm`. Use OXC for lint and format. Run `pnpm format` repository-wide.
-- In a fresh worktree, run `pnpm install --frozen-lockfile && pnpm build` before testing.
-- Preserve other worktrees, devices, sessions, dirty files, and experiments.
-- Never copy `.env` into a worktree. For host credentials, source the main checkout's file by absolute path.
-- Give parallel workers disjoint files and distinct devices. `pnpm check:affected --run` and `pnpm check` serialize automatically.
-- The layering scan reads tracked files. Stage new modules before trusting its result.
-- Move a path's Fallow baseline entry when renaming its file. Do not regenerate unrelated baselines.
+- Use `pnpm`. Use OXC to lint and format. Run `pnpm format` on the full repository.
+- In a new worktree, run `pnpm install --frozen-lockfile && pnpm build` before you test.
+- Do not change other worktrees, devices, sessions, dirty files, or experiments. Do not use `git stash`; all worktrees share it.
+- Do not copy `.env` into a worktree. For host credentials, source the main checkout's file by its absolute path.
+- Give each parallel worker different files and a different device. `pnpm check:affected --run` and `pnpm check` run one at a time automatically.
+- The layering scan reads only tracked files. Stage new modules before you trust its result.
+- When you rename a file, move its Fallow baseline entry. Do not regenerate unrelated baselines.
 
-The validation lock reclaims provably dead owners automatically. Unknown owners remain blocking.
-If waiting times out, report the printed owner and lock state; do not remove it by hand.
+The validation lock automatically reclaims owners that are provably dead. An unknown owner continues to block.
+If the wait times out, report the printed owner and the lock state. Do not remove the lock manually.
 
 ## Agent docs
 
-Write short instructions with one action per sentence. Put the condition before its action.
-Use the same term for the same concept. Keep commands and domain terms exact.
-Route specialized rules to their task document. Delete duplicate or enforced rules before adding reminders.
+Write agent docs in ASD-STE100. Write one instruction in each sentence.
+Put the condition before the instruction. Use one term for one concept.
+Keep commands and domain terms exact. Put specialized rules and new shared constraints in the owning task document, not in agent memory.
+Before you add a reminder, delete duplicate or enforced rules.