docs: refresh Peekaboo agent skill guidance

[coygeek]

Closes #195.

Summary

Refreshes the Peekaboo agent skill and related docs so agent guidance matches the current repository layout and current CLI behavior.

• points install and maintenance docs at skills/peekaboo
• keeps the skill compact with only name and description frontmatter
• treats see / inspect-ui element IDs as opaque values copied from fresh output
• uses explicit /tmp/... --path examples for see --json flows
• updates the generated see --help example to avoid JSON-only screenshot ambiguity
• fixes the quickstart jq path to use .data.ui_elements

Notes

Related runtime issues remain open: #194 and #196. This PR updates guidance so it stays compatible with those current behaviors; runtime behavior changes remain tracked separately.

Verification

• node scripts/docs-lint.mjs
• skill frontmatter check
• stale-language scans for peekaboo-cli, allowed-tools, hardcoded stale ID examples, and unsafe see --json examples
• pnpm run build:cli
• rebuilt see, click, inspect-ui, browser, and tools --json help/catalog checks
• live Calculator see smoke with explicit /tmp output path
• git diff --check
• local autoreview: clean

Redacted Terminal Proof

Updated see --help Example

$ peekaboo see --help | rg -- "/tmp/safari-login.png|fresh element IDs|--json|--no-web-focus"
  --window-id <window-id>           Capture a specific window by CoreGraphics window id (window_id from `peekaboo window list --json`)
  --no-web-focus  Skip web-content focus fallback when no text fields are detected
  --json, -j      Emit machine-readable JSON output
  $ peekaboo see --json --annotate --path /tmp/see.png  Capture the frontmost window, print structured output, and save annotations.
  $ peekaboo see --app Safari --window-title "Login" --json --path /tmp/safari-login.png  Target a specific Safari window to collect fresh element IDs and keep the capture artifact in /tmp.
  - --json/-j (alias: --json-output) Emit machine-readable JSON output

Docs Lint And Skill Frontmatter

$ node scripts/docs-lint.mjs
docs-lint: ok
$ ruby -e "...frontmatter keys check..."
frontmatter-ok: description,name

Calculator Smoke With Explicit /tmp Screenshot Path

$ peekaboo app launch/focus Calculator; peekaboo see --app Calculator --path /tmp/peekaboo-pr197-calc.png --json --timeout-seconds 10 --no-remote
live-see-ok: elements=247 ids=247 role_coded=0 legacy=247 examples=elem_7,elem_8,elem_9,elem_10,elem_11
snapshot_id_present=true explicit_png_exists=true explicit_png_size=49288 explicit_png_path=/tmp/peekaboo-pr197-calc.png

Proof output is intentionally redacted: no raw UI JSON, screenshot contents, or local home paths are included.

[clawsweeper]

Codex review: needs changes before merge. Reviewed June 23, 2026, 6:33 PM ET / 22:33 UTC.

Summary
The PR updates the Peekaboo skill, docs, CLI see help example, and changelog entry to use the current skills/peekaboo path, opaque fresh element IDs, explicit /tmp screenshot paths, and .data.ui_elements JSON examples.

Reproducibility: yes. Current main still points at skills/peekaboo-cli while the repository contains skills/peekaboo/SKILL.md, and the review finding is source-reproducible from the current focus/delivery code path.

Review metrics: 3 noteworthy metrics.

• Changed files: 7 files changed. The review surface is limited to docs, one skill file, one generated help metadata source, and one changelog line.
• Runtime implementation changes: 0 behavior paths changed. The Swift edit changes a usage example string rather than command execution behavior.
• Linked work: 1 closing issue, 2 adjacent open issues. Maintainers should land the stale skill-path docs fix without collapsing the separate runtime follow-ups.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #195
Summary: This PR is the candidate fix for the stale agent-skill path issue; the other mentioned issues are adjacent runtime/docs concerns that remain separately tracked.

Members:

• canonical: docs/agent-skill.md points users at missing skills/peekaboo-cli directory #195 - The PR uses closing syntax for the exact stale skills/peekaboo-cli documentation problem and updates that central path.
• partial_overlap: CLI emits legacy elem_* IDs while current help and tool docs advertise B1/T2 IDs #194 - The PR reduces ID-shape assumptions in docs and the skill, but the runtime/help ID contract mismatch remains separate and open.
• partial_overlap: peekaboo see --json writes a Desktop screenshot even when --path is omitted #196 - The PR recommends explicit /tmp paths for see --json examples, but it does not change the implicit screenshot-write behavior.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🐚 platinum hermit
Patch quality: 🦐 gold shrimp
Result: needs maintainer review before merge.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• Update docs/automation.md so --no-auto-focus is described as foreground/no-focus delivery rather than a separate non-foreground mode.

Risk before merge

• [P1] Merging as-is would leave docs/automation.md inconsistent with the current delivery-mode source for --no-auto-focus.
• [P1] The related runtime issues at CLI emits legacy elem_* IDs while current help and tool docs advertise B1/T2 IDs #194 and peekaboo see --json writes a Desktop screenshot even when --path is omitted #196 remain open; this PR should be treated as a docs/help mitigation, not a runtime fix.

Maintainer options:

1. Decide the mitigation before merge
   Land the focused docs/help refresh after correcting the --no-auto-focus delivery wording and keeping the runtime ID-contract and implicit screenshot-write issues separate.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P2] A narrow automated repair can update the --no-auto-focus docs wording without changing runtime behavior or the useful parts of the PR.

Security
Cleared: No concrete security or supply-chain concern was found; the diff updates docs, skill text, one help example, and a changelog line without changing dependencies, workflows, secrets, or code execution paths.

Review findings

• [P2] Keep --no-auto-focus in foreground delivery — docs/automation.md:31

Review details

Best possible solution:

Land the focused docs/help refresh after correcting the --no-auto-focus delivery wording and keeping the runtime ID-contract and implicit screenshot-write issues separate.

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

Yes. Current main still points at skills/peekaboo-cli while the repository contains skills/peekaboo/SKILL.md, and the review finding is source-reproducible from the current focus/delivery code path.

Is this the best way to solve the issue?

No, not quite. The overall docs/help approach is narrow and maintainable, but the --no-auto-focus sentence should match current source before merge.

Full review comments:

• [P2] Keep --no-auto-focus in foreground delivery — docs/automation.md:31
  The new wording removes --no-auto-focus from the flags that imply foreground delivery, but current source includes noAutoFocus in hasForegroundFocusOverrides and ClickCommand selects .foreground for those overrides. As written, the docs would tell users this is a separate mode even though the CLI still runs foreground/no-focus delivery.
  Confidence: 0.9

Overall correctness: patch is incorrect
Overall confidence: 0.89

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against ab0d96e6d530.

Label changes

Label changes:

• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🐚 platinum hermit and patch quality is 🦐 gold shrimp.
• add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (terminal): The PR body includes redacted after-fix terminal output for the updated help text, docs/frontmatter checks, and a live Calculator see --path /tmp/... --json smoke.
• remove rating: 🐚 platinum hermit: Current PR rating is rating: 🦐 gold shrimp, so this older rating label is no longer current.
• remove status: 👀 ready for maintainer look: Current PR status label is status: ⏳ waiting on author.

Label justifications:

• P3: This is a low-risk docs and help-text cleanup with limited runtime blast radius.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🐚 platinum hermit and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (terminal): The PR body includes redacted after-fix terminal output for the updated help text, docs/frontmatter checks, and a live Calculator see --path /tmp/... --json smoke.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes redacted after-fix terminal output for the updated help text, docs/frontmatter checks, and a live Calculator see --path /tmp/... --json smoke.

Evidence reviewed

Acceptance criteria:

• [P1] node scripts/docs-lint.mjs.
• [P1] git diff --check -- docs/automation.md.
• [P1] rg -n 'no-auto-focus|hasForegroundFocusOverrides|foreground delivery|focus-background' docs/automation.md docs/commands/click.md Apps/CLI/Sources/PeekabooCLI/Commands/Shared/FocusCommandOptions.swift Apps/CLI/Sources/PeekabooCLI/Commands/Interaction/ClickCommand.swift.

What I checked:

• PR scope: gh pr view reports 7 changed files with 86 additions and 72 deletions across docs, skills/peekaboo/SKILL.md, one see help metadata edit, and CHANGELOG.md; the head commit is 03e66e4a1dfb2c8b939c25d760d0863443c0b0b1. (03e66e4a1dfb)
• Current main still has stale skill path: Current main still tells users to copy skills/peekaboo-cli, so the linked stale-path docs issue is not already implemented on main. (docs/agent-skill.md:19, ab0d96e6d530)
• Actual skill path exists: The repository’s actual skill file is skills/peekaboo/SKILL.md, matching the PR’s corrected install path. (skills/peekaboo/SKILL.md:1, ab0d96e6d530)
• JSON path source check: see JSON output is wrapped as command success data and the command result contains ui_elements, supporting the PR’s .data.ui_elements examples. (Apps/CLI/Sources/PeekabooCLI/Commands/AI/SeeCommand+Output.swift:77, ab0d96e6d530)
• No-auto-focus source behavior: Current source includes noAutoFocus in hasForegroundFocusOverrides, so docs should not present it as separate from foreground delivery. (Apps/CLI/Sources/PeekabooCLI/Commands/Shared/FocusCommandOptions.swift:33, ab0d96e6d530)
• Click delivery source behavior: ClickCommand chooses foreground delivery when foreground is set or any foreground focus override is present, which includes --no-auto-focus. (Apps/CLI/Sources/PeekabooCLI/Commands/Interaction/ClickCommand.swift:71, ab0d96e6d530)

Likely related people:

• Peter Steinberger: Current blame ties the stale agent-skill docs, current skill file, and adjacent see help example to the v3.5.2 release import, and Peter also authored the latest PR changelog commit. (role: recent area contributor; confidence: high; commits: 1fa8eead7eea, 03e66e4a1dfb, 4f2b0e9cb4ac; files: docs/agent-skill.md, skills/peekaboo/SKILL.md, Apps/CLI/Sources/PeekabooCLI/Commands/AI/SeeCommand.swift)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

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.

How this review workflow works

• 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.

[coygeek]

Added redacted terminal proof to the PR body covering the updated see --help example, docs/frontmatter checks, and the Calculator /tmp path smoke. @clawsweeper re-review

[steipete]

Landed as 1771d7db349b16abe3d45842a9a337c589215871.

Maintainer verification:

• node scripts/docs-lint.mjs
• Ruby YAML/frontmatter parse requiring exactly name and description
• git diff --check origin/main...HEAD and git diff --check
• Codex autoreview of the full branch against origin/main: clean, no accepted/actionable findings
• Codex autoreview of the maintainer changelog fixup: clean, no accepted/actionable findings
• GitHub Actions run 28061066900: PeekabooCore, CLI, Tachikoma, macOS apps, and SwiftLint all passed

Live proof: the PR body contains the contributor's redacted Calculator smoke using an explicit /tmp screenshot path. I did not capture or upload an additional screenshot because this landing changes docs/help metadata rather than runtime behavior.

Caveat: #194 and #196 remain open; this PR does not claim to change element-ID generation or implicit screenshot persistence.