fix: document element IDs as opaque

[steipete]

Summary

• define runtime element IDs as opaque public strings that callers copy unchanged
• remove role-shaped ID examples from CLI help, agent/MCP schemas, current docs, and public API comments
• add CLI, agent-schema, and docs-lint regressions while leaving runtime ID generation untouched

Closes #194.

Proof

• pnpm run format
• pnpm run lint (0 serious; 18 existing warnings)
• node scripts/docs-lint.mjs
• YAML-parsed skills/peekaboo/SKILL.md frontmatter
• swift test --package-path Apps/CLI --filter CommandHelpRendererTests (2 passed)
• swift test --package-path Core/PeekabooCore --filter AgentToolDescriptionTests (14 passed)
• pnpm run test:safe (627 passed)
• live Calculator inspect-ui returned elem_14; passing that exact ID and snapshot to click --input-strategy actionOnly clicked “All Clear” successfully
• autoreview clean: patch correct (0.82), no actionable findings

[clawsweeper]

Codex review: found issues before merge. Reviewed June 24, 2026, 3:53 AM ET / 07:53 UTC.

Summary
The branch updates CLI help, agent/MCP schemas, API comments, docs, docs-lint, and regression tests to describe element IDs as opaque strings copied from current output.

Reproducibility: yes. Source inspection on current main shows B1/T2-style IDs in CLI/MCP guidance while the runtime AX collector creates elem_* IDs, and the linked issue includes live Calculator reproduction details.

Review metrics: 2 noteworthy metrics.

• Changed surface: 38 files, +94/-51. The fix intentionally spans public help, docs, agent schemas, tests, and docs-lint, so consistency across surfaces matters before merge.
• Changelog files touched: 2 modified. Release-owned changelog edits are the only concrete cleanup needed before merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #194
Summary: This PR is the candidate fix for the linked issue about role-shaped element ID guidance disagreeing with runtime elem_* IDs.

Members:

• canonical: CLI emits legacy elem_* IDs while current help and tool docs advertise B1/T2 IDs #194 - The PR body uses closing syntax for this issue and the diff updates the exact CLI/docs/agent guidance named there.
• partial_overlap: docs: refresh Peekaboo agent skill guidance #197 - The merged docs PR refreshed related skill/docs guidance but explicitly left the element-ID runtime contract issue open.

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

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

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

Rank-up moves:

• [P2] Remove the changelog entries from both changelog files before merge.

Risk before merge

• [P1] The PR currently edits release-owned changelog files, which should be removed before merge under the review policy.

Maintainer options:

1. Decide the mitigation before merge
   Merge the opaque-ID documentation/schema/test correction after removing release-owned changelog edits and letting normal CI finish, while keeping runtime ID generation unchanged.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P2] No separate repair lane: the only cleanup is removing release-owned changelog entries, which should be handled in the PR or release flow rather than by an automated repair worker.

Security
Cleared: The diff only changes documentation, help/schema descriptions, docs-lint patterns, and focused tests; no security or supply-chain-sensitive surface is introduced.

Review findings

• [P3] Remove the release-owned changelog entry — CHANGELOG.md:6

Review details

Best possible solution:

Merge the opaque-ID documentation/schema/test correction after removing release-owned changelog edits and letting normal CI finish, while keeping runtime ID generation unchanged.

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

Yes. Source inspection on current main shows B1/T2-style IDs in CLI/MCP guidance while the runtime AX collector creates elem_* IDs, and the linked issue includes live Calculator reproduction details.

Is this the best way to solve the issue?

Mostly yes. Treating IDs as opaque is a narrow compatibility-preserving fix, but the release-owned changelog entries should be removed before merge.

Full review comments:

• [P3] Remove the release-owned changelog entry — CHANGELOG.md:6
CHANGELOG.md is release-owned for OpenClaw PRs, so this normal fix PR should not add release notes there. Please remove this entry and leave release-note wording for the release flow; the same cleanup is needed in Apps/CLI/CHANGELOG.md.
  Confidence: 0.91

Overall correctness: patch is correct
Overall confidence: 0.86

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

• add P2: The PR addresses a concrete CLI/agent documentation mismatch with limited blast radius.
• add proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix live CLI proof: Calculator returned an elem_14 ID and clicking that exact ID with click --input-strategy actionOnly succeeded.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body includes after-fix live CLI proof: Calculator returned an elem_14 ID and clicking that exact ID with click --input-strategy actionOnly succeeded.

Label justifications:

• P2: The PR addresses a concrete CLI/agent documentation mismatch with limited blast radius.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body includes after-fix live CLI proof: Calculator returned an elem_14 ID and clicking that exact ID with click --input-strategy actionOnly succeeded.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix live CLI proof: Calculator returned an elem_14 ID and clicking that exact ID with click --input-strategy actionOnly succeeded.

Evidence reviewed

What I checked:

• Current runtime ID source: AXTreeCollector still generates IDs with the elem_ prefix on current main, matching the linked issue's reported runtime output. (Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Services/UI/AXTreeCollector.swift:108, efde5b18caa5)
• Current CLI help source: ClickCommand help still advertises B1/T2-shaped IDs on current main, so the PR is not obsolete. (Apps/CLI/Sources/PeekabooCLI/Commands/Interaction/ClickCommand.swift:17, efde5b18caa5)
• Current MCP guidance source: SeeTool still says see returns B1/T1-style IDs on current main. (Core/PeekabooCore/Sources/PeekabooAgentRuntime/MCP/Tools/SeeTool.swift:24, efde5b18caa5)
• PR and linked issue context: The PR uses closing syntax for CLI emits legacy elem_* IDs while current help and tool docs advertise B1/T2 IDs #194 and changes the exact CLI/docs/agent guidance named there; GitHub reports it is mergeable with CI still in progress. (cb1dea56b4b1)
• Prior related docs PR: docs: refresh Peekaboo agent skill guidance #197 was merged and partially updated skill/docs guidance, but its body explicitly said the runtime element-ID issue remained open. (1771d7db349b)
• History provenance: Blame and log show the current runtime generator and stale guidance mostly trace through recent release/refactor history, with older agent/CLI introductions in the same area. (Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Services/UI/AXTreeCollector.swift:108, 1fa8eead7eea)

Likely related people:

• Peter Steinberger: Current blame ties the runtime ID generator and stale CLI/MCP guidance to the recent release snapshot, and older history shows the agent and Commander surfaces were introduced in the same area. (role: recent area contributor; confidence: high; commits: 1fa8eead7eea, 95ecdd423b96, 7614754369ae; files: Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Services/UI/AXTreeCollector.swift, Apps/CLI/Sources/PeekabooCLI/Commands/Interaction/ClickCommand.swift, Core/PeekabooCore/Sources/PeekabooAgentRuntime/MCP/Tools/SeeTool.swift)
• Coy Geek: Recent merged work refreshed the Peekaboo skill/docs around opaque element IDs, and history shows adjacent changes to the same interaction and agent-tool files. (role: adjacent contributor; confidence: medium; commits: 1771d7db349b, 01d10db9b07a; files: skills/peekaboo/SKILL.md, docs/commands/see.md, Apps/CLI/Sources/PeekabooCLI/Commands/Interaction/ClickCommand.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.

[steipete]

Verified on cb1dea56:

• focused CLI help tests: 2 passed
• focused agent description tests: 14 passed
• safe suite: 627 passed
• docs lint, formatting, and skill frontmatter parse: clean
• SwiftLint: 0 serious (18 existing warnings)
• live Calculator proof: inspect-ui returned elem_14; the exact unchanged ID clicked “All Clear” successfully
• autoreview: clean, no actionable findings
• CI run 28083539390: all five jobs green

Runtime ID generation remains unchanged; public guidance now treats IDs as opaque strings copied from current output.