docs: make Peekaboo skill authoritative for current automation

[steipete]

Peekaboo's agent skill and copied guidance had drifted from the current CLI: ordinary automation was told to build from source, generic AXPress examples omitted foreground consent, and coordinate help incorrectly treated snapshot-only background clicks as global.

Make the repository skill the canonical automation guide, with installed-CLI setup, operation-specific host and permission selection, exact-window snapshots, background input, and outcome verification. Document symlink distribution and release-pinned copies. Correct click help and command docs to match the existing snapshot-relative implementation; runtime behavior is unchanged.

Validation: production-source audit against v4.3.4 and current main, installed CLI help checks, docs lint, skill/frontmatter and linked-target validation, SwiftFormat checks for both help metadata files, git diff --check, and independent review with no actionable findings. No live desktop mutation was needed for this guidance-only change.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[cursor]

PR Summary

Low Risk
Documentation and CLI help text only; no automation dispatch or coordinate resolution code changes.

Overview
This PR aligns agent guidance and user-facing docs with current Peekaboo behavior without changing click runtime logic. The repo skills/peekaboo/SKILL.md is reframed as the canonical automation workflow: use the installed signed CLI, pick the right Bridge/daemon/GUI host, grant TCC on the executing host, follow observe → target → act → verify, and treat background --at as snapshot-window-relative (with fresh exact-window screenshot receipts).

docs/agent-skill.md now documents symlink-based distribution (Codex/Claude/OpenClaw), release-pinned copy rules, validation commands, and openclaw/tap install checks instead of copy-and-build-from-source defaults.

CLI help (ClickCommand / Commander metadata) and automation docs (automation.md, commands/click.md) are updated so --at / --global describe background vs foreground coordinate spaces consistently with the existing resolveBackgroundCoordinateReference implementation. CHANGELOG records the unreleased documentation refresh.

^{Reviewed by Cursor Bugbot for commit 2faf54b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed September 13, 2026, 12:23 AM ET / 04:23 UTC.

ClawSweeper review

What this changes

Refreshes Peekaboo’s agent skill and distribution instructions, and corrects CLI help and documentation for snapshot-relative background clicks.

Merge readiness

✅ Ready for maintainer review

Keep open for normal landing: the guidance corrections remain useful and are absent from the inspected main and latest release. No actionable patch defect was found; collaborator-authored work is also protected from automatic closure.

Priority: P3
Reviewed head: 2faf54bbc6ee64497ce9bfff614165f30dbafcd2

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused, source-consistent guidance refresh with no actionable correctness or security findings.
Proof confidence	🌊 off-meta tidepool	Not applicable: The collaborator-authored patch changes guidance and click help strings only; the external-contributor proof gate does not apply, and no material runtime authority change requires additional proof.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: The collaborator-authored patch changes guidance and click help strings only; the external-contributor proof gate does not apply, and no material runtime authority change requires additional proof.
Evidence reviewed	8 items	Policy and patch scope: Read the complete root AGENTS.md and searched the changed subtrees for scoped instructions; no nested AGENTS.md or maintainer-notes directory was found. The introduced delta contains seven documentation/help files, with no dispatch implementation changes. Coordinate guidance matches production behavior: Background coordinate clicks require an explicit screenshot snapshot, resolve its exact window, convert coordinates relative to that window unless global is requested, and reject points outside captured bounds. This supports the revised help without changing execution behavior. Existing regression coverage supports the coordinate contract: Existing tests assert exact-window background routing, relative-coordinate conversion, explicit global coordinates, and rejection without a snapshot. These tests were inspected, not executed.
Findings	None	None.
Security	None	None.

How this fits together

Peekaboo’s agent skill guides agents from desktop observation through targeted macOS automation and result verification. The CLI selects an execution host and uses captured window information to route input.

flowchart LR
  A[Authorized user task] --> B[Agent skill guidance]
  B --> C[CLI and execution host]
  C --> D[Observe target window]
  D --> E[Snapshot and element IDs]
  E --> F[Targeted input]
  F --> G[Fresh result verification]

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Skill size	179 → 105 lines	The operational refresh reduces the canonical skill by 74 lines while moving distribution details into its documentation.

Technical review

Best possible solution:

Maintain one canonical operational skill, with release-pinned distribution copies and CLI help that accurately describes the existing targeting contract.

Do we have a high-confidence way to reproduce the issue?

Not applicable to this guidance-focused patch; source inspection establishes the coordinate documentation mismatch without requiring desktop input.

Is this the best way to solve the issue?

Yes. Updating the existing skill, installation guidance and both help declarations is a focused correction that preserves runtime behavior.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against b16325c98405.

Labels

Label changes:

• add P3: This is a bounded documentation and help correction with unchanged automation execution.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The collaborator-authored patch changes guidance and click help strings only; the external-contributor proof gate does not apply, and no material runtime authority change requires additional proof.

Label justifications:

• P3: This is a bounded documentation and help correction with unchanged automation execution.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The collaborator-authored patch changes guidance and click help strings only; the external-contributor proof gate does not apply, and no material runtime authority change requires additional proof.

Evidence

What I checked:

• Policy and patch scope: Read the complete root AGENTS.md and searched the changed subtrees for scoped instructions; no nested AGENTS.md or maintainer-notes directory was found. The introduced delta contains seven documentation/help files, with no dispatch implementation changes. (AGENTS.md:1, 2faf54bbc6ee)
• Coordinate guidance matches production behavior: Background coordinate clicks require an explicit screenshot snapshot, resolve its exact window, convert coordinates relative to that window unless global is requested, and reject points outside captured bounds. This supports the revised help without changing execution behavior. (Apps/CLI/Sources/PeekabooCLI/Commands/Interaction/ClickCommand.swift:1215, 2faf54bbc6ee)
• Existing regression coverage supports the coordinate contract: Existing tests assert exact-window background routing, relative-coordinate conversion, explicit global coordinates, and rejection without a snapshot. These tests were inspected, not executed. (Apps/CLI/Tests/CLIAutomationTests/ClickCommandTests.swift:250, 2faf54bbc6ee)
• Host selection and foreground consent checked: The host resolver prefers an exact-build daemon for the documented operation classes while preserving explicit socket selection. ActionCommand separately rejects foreground-capable accessibility actions without foreground consent, supporting the refreshed skill guidance. (Apps/CLI/Sources/PeekabooCLI/Commands/Base/Runtime/RuntimeHostResolver.swift:673, 2faf54bbc6ee)
• Still necessary on main and release: The inspected main skill still recommends a freshly built repository binary and contains the older AXPress examples. The v4.3.4 click metadata still describes coordinates as global without target flags. The submitted corrections are therefore not already present in those versions. (Apps/CLI/Sources/PeekabooCLI/Commands/Interaction/ClickCommand+CommanderMetadata.swift:75, 59a805b253c1)
• Merge ownership verified: The test merge records the pinned main followed by the exact PR head as parents. Its delta against main contains only the same seven introduced paths; the capture implementation and test changes are base-branch work. (3b36d9142f99)

Likely related people:

• steipete: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.