docs: update imsg skill for new features

[omarshahine]

Summary

• update .agents/skills/imsg/SKILL.md with the combined agent guidance for the new feature PR stack
• add read-only stats guidance and RPC method names
• document bridge surfaces added across the stack: poll unvote, scheduled create/list, rich URL previews, stickers, contact-card probes, and chat backgrounds
• include fail-closed caveats so agents do not suggest unproven behavior: poll add-option, scheduled cancel/delete, scheduled attachments/replies, arbitrary-image chat backgrounds, or currently unavailable contact-card sharing

Merge Order

Merge this PR last, after the feature PRs it documents:

• feat: add message stats #161 message stats
• feat: add poll unvote updates #162 poll unvote
• feat: list scheduled messages read-only #163 scheduled messages
• feat: add sticker sends #164 stickers
• feat: add bridge rich links #165 rich links
• feat: add guarded contact-card probes #166 contact-card probes
• feat: inspect chat backgrounds read-only #167 chat backgrounds

Proof

This is a skill-only PR, so the proof is an agent-contract proof rather than a new Messages runtime proof.

Current proof collected from PR168 head 99606b7:

$ git diff --name-only openclaw/main...HEAD
.agents/skills/imsg/SKILL.md

$ git diff --stat openclaw/main...HEAD
.agents/skills/imsg/SKILL.md | 29 +++++++++++++++++++++++++++--
1 file changed, 27 insertions(+), 2 deletions(-)

Skill surface added by this PR:

standard tier includes: stats
bridge tier includes: sticker, scheduled, chat-background, contact-card
examples include: imsg stats --chat-id ID --json
examples include: imsg send-rich --chat GUID --url 'https://example.com/' --rich-link
examples include: imsg send-rich --chat GUID --text 'later' --schedule 2026-07-10T20:00:00Z
examples include: imsg scheduled list --json
examples include: imsg sticker --chat GUID --file ~/Desktop/sticker.png --attach-to MSG_GUID
examples include: imsg poll unvote --chat GUID --message POLL_GUID --option OPTION_ID
examples include: imsg chat-background clear --chat GUID
examples include: imsg chat-background set --chat GUID --file /path/to/poster-package
examples include: imsg contact-card status --chat GUID
RPC aliases listed: polls.unvote, poll.unvote, messages.poll.unvote, scheduledMessages.createScheduledMessage, scheduledMessages.getScheduledMessages, attachments.sendSticker, sticker.send, contacts.shouldShareContact, contacts.shareContactCard, chats.setBackground, chats.removeBackground

Dependency proof at time of writing:

#161 draft=false status=ready for maintainer look checks=macos:SUCCESS,linux-read-core:SUCCESS :: feat: add message stats
#162 draft=false status=ready for maintainer look checks=macos:SUCCESS,linux-read-core:SUCCESS :: feat: add poll unvote updates
#163 draft=false status=ready for maintainer look checks=macos:SUCCESS,linux-read-core:SUCCESS :: feat: add scheduled messages
#164 draft=false status=ready for maintainer look checks=macos:SUCCESS,linux-read-core:SUCCESS :: feat: add sticker sends
#165 draft=false status=ready for maintainer look checks=macos:SUCCESS,linux-read-core:SUCCESS :: feat: add bridge rich links
#166 draft=false status=ready for maintainer look checks=macos:SUCCESS,linux-read-core:SUCCESS :: feat: add guarded contact-card probes
#167 draft=false status=ready for maintainer look checks=macos:SUCCESS,linux-read-core:SUCCESS :: feat: inspect and set chat backgrounds

I attempted to create a temporary local combined stack proof by merging #161-#167 plus this PR onto openclaw/main. That correctly exposed that PR168 must merge last: before the feature PRs are landed in order, the independent feature branches can conflict in Sources/IMsgHelper/IMsgInjected.m. Because of that, final combined binary proof cannot be collected honestly from this branch alone.

Final proof gate before merging PR168:

git checkout main
git pull --ff-only openclaw main
make build
./bin/imsg completions llm | rg 'stats|poll unvote|scheduled list|--schedule|--rich-link|sticker|chat-background|contact-card'
./bin/imsg status --json | jq '.rpc_methods | map(select(test("server.getMessageStats|getMediaStatistics|getMediaStatisticsByChat|polls.unvote|poll.unvote|messages.poll.unvote|scheduledMessages.createScheduledMessage|scheduledMessages.getScheduledMessages|attachments.sendSticker|sticker.send|contacts.shouldShareContact|contacts.shareContactCard|chats.setBackground|chats.removeBackground")))'

Expected result: the command names and RPC aliases documented in this skill are present in the final merged binary, and unsupported paths remain documented as fail-closed.

Verification

• git diff --check ✅
• GitHub CI macos ✅
• GitHub CI linux-read-core ✅
• docs-only; no Swift code changed

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed July 9, 2026, 7:18 PM ET / 23:18 UTC.

Summary
The PR updates .agents/skills/imsg/SKILL.md to document stats plus new bridge commands/RPC aliases for the open feature stack and their fail-closed caveats.

Reproducibility: not applicable. as a bug reproduction: this is a skill documentation PR. The high-confidence check is final command/RPC proof after the linked feature stack lands.

Review metrics: 3 noteworthy metrics.

• Skill files changed: 1 changed, 27 added, 2 removed. The whole PR is agent guidance, so correctness depends on matching the final CLI/RPC surface exactly.
• Open dependency stack: 7 linked feature PRs still open. The PR body explicitly says this skill update must merge after those feature branches.
• Current merge state: 1 conflicting skill file. Current main added read-state guidance in the same section, so the branch needs a rebase before review can clear.

Merge readiness
Overall: 🦪 silver shellfish
Proof: 🦪 silver shellfish
Patch quality: 🦪 silver shellfish
Result: blocked until real behavior proof is added.

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

Rank-up moves:

• Rebase against current main and preserve the existing imsg chats --unread-only and read-state skill guidance.
• [P1] After the linked feature stack lands or is narrowed, add redacted imsg completions llm and imsg status --json output from the final build.
• [P1] Refresh the skill text if any linked PR changes command names, RPC aliases, or fail-closed behavior.

Proof guidance:

• [P1] Needs real behavior proof before merge: The PR has diff and dependency-status proof, but it still needs redacted after-stack terminal output from the final binary before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Risk before merge

• [P1] Merging before the linked feature stack lands would publish agent guidance for commands and RPC aliases that current main does not expose.
• [P1] The branch is currently conflicting against main in .agents/skills/imsg/SKILL.md; the rebase must preserve current read-state guidance as well as the new stats guidance.
• [P1] The PR body contains proposed final verification commands, but not redacted observed output from the final combined binary.

Maintainer options:

1. Wait, rebase, and prove final surface (recommended)
   Require the linked feature stack to land or be narrowed first, then rebase this PR and add redacted final command/RPC proof before merge.
2. Retarget the skill to landed capabilities
   If maintainers drop or delay part of the stack, update the skill file so agents only see supported commands and RPC aliases.
3. Pause or close until the stack settles
   If the final feature surface is still moving, close or pause this skill PR rather than publishing speculative agent guidance.

Next step before merge

• [P1] Needs maintainer sequencing, final combined proof, and a conflict rebase; this is not a safe automated repair because the decisive proof depends on the final merged feature stack.

Maintainer decision needed

• Question: Should this skill-only PR wait behind the full linked feature stack and be refreshed after current main's read-state skill change, or should it be narrowed or closed if that stack changes?
• Rationale: The skill text is correct only if maintainers accept the underlying feature surface and sequence this PR after those branches; automation cannot decide that release order or final agent contract.
• Likely owner: steipete — Most relevant current-main history for the skill file and the conflicting read-state update points to steipete.
• Options:
  • Wait for stack and final proof (recommended): Keep this PR open, require a rebase that preserves read-state guidance, and merge it only after final command/RPC output proves the documented surface.
  • Narrow to landed features only: Revise the skill text to document only the features that maintainers actually merge, leaving rejected or delayed surfaces out of the agent contract.
  • Close and replace later: If the feature stack is too unsettled, close this branch and ask for a fresh skill PR after the final surface is known.

Security
Cleared: The diff only changes the imsg skill guidance and introduces no code execution, dependency, credential, or supply-chain surface.

Review findings

• [P2] Preserve current read-state guidance when rebasing — .agents/skills/imsg/SKILL.md:47-48

Review details

Best possible solution:

Land this only after the linked feature PRs are merged or narrowed, rebase over current main while preserving read-state guidance, then add redacted final imsg completions llm and imsg status --json output.

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

Not applicable as a bug reproduction: this is a skill documentation PR. The high-confidence check is final command/RPC proof after the linked feature stack lands.

Is this the best way to solve the issue?

Yes, updating the imsg skill is the right solution for agent-facing guidance once the underlying features merge. The current branch is premature until it is rebased and proven against the final combined binary.

Full review comments:

• [P2] Preserve current read-state guidance when rebasing — .agents/skills/imsg/SKILL.md:47-48
  This branch is still based before current main added imsg chats --unread-only and read-state guidance in the same Reading section. GitHub reports the PR as conflicting, and git merge-tree shows the conflict at this hunk; when rebasing, keep the current read-state example and bullet alongside the new stats guidance so the skill does not lose shipped read-state instructions.
  Confidence: 0.92

Overall correctness: patch is incorrect
Overall confidence: 0.88

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

• P3: This is low-risk skill documentation work, but it remains blocked on sequencing, proof, and rebase cleanup.
• merge-risk: 🚨 other: If merged at the wrong point, the skill could direct agents toward command/RPC surfaces that the installed binary does not support.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦪 silver shellfish.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR has diff and dependency-status proof, but it still needs redacted after-stack terminal output from the final binary before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully; its focused PR and verification-output guidance applies to this skill/CLI review. (AGENTS.md:1, d9bd9c754d50)
• PR diff scope: The PR modifies only the imsg skill file, adding 27 lines and deleting 2 lines. (.agents/skills/imsg/SKILL.md:14, 99606b73b394)
• Documented future skill surface: The proposed skill text advertises stats, sticker, scheduled, chat-background, contact-card, new bridge examples, and RPC aliases for those surfaces. (.agents/skills/imsg/SKILL.md:14, 99606b73b394)
• Current main command surface: Current main's CommandRouter does not register the newly documented stats, scheduled, sticker, chat-background, or contact-card commands. (Sources/imsg/CommandRouter.swift:12, d9bd9c754d50)
• Current main RPC surface: Current main's kSupportedRPCMethods does not list the newly documented stats, poll-unvote, scheduled, sticker, contact-card, or chat-background RPC aliases. (Sources/imsg/RPCServer.swift:29, d9bd9c754d50)
• Current main conflict: GitHub reports the PR as conflicting, and git merge-tree shows a conflict in the skill reading section against current main's read-state additions. (.agents/skills/imsg/SKILL.md:47, d9bd9c754d50)

Likely related people:

• steipete: Git blame attributes the current imsg skill file to the release-prep baseline and the latest read-state update, and the relevant conflict is in that file. (role: current skill-file and CLI surface history owner; confidence: high; commits: dea78a9e9c49, d9bd9c754d50; files: .agents/skills/imsg/SKILL.md, Sources/imsg/CommandRouter.swift, Sources/imsg/RPCServer.swift)
• omarshahine: Prior merged history includes bridge and poll work, and this branch plus the linked feature stack define the new command/RPC surface the skill wants to document. (role: adjacent bridge feature contributor; confidence: medium; commits: c56c24d488ef, 617d941f7b1e, 1560a678ce0f; files: .agents/skills/imsg/SKILL.md, Sources/imsg/Commands/PollCommand.swift, Sources/imsg/Commands/BridgeMessagingCommands.swift)
• chiedo: The merged read-state PR credits Chiedo John for proposing and iterating on the feature whose skill guidance must be preserved during rebase. (role: adjacent read-state contributor; confidence: medium; commits: d9bd9c754d50; files: .agents/skills/imsg/SKILL.md, docs/chats.md, docs/json.md)

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.

Review history (3 earlier review cycles)

• reviewed 2026-07-09T20:31:49.771Z sha 99606b7 :: needs real behavior proof before merge. :: none
• reviewed 2026-07-09T20:49:02.405Z sha 99606b7 :: needs real behavior proof before merge. :: none
• reviewed 2026-07-09T20:57:55.604Z sha 99606b7 :: needs real behavior proof before merge. :: none

[omarshahine]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[steipete]

Thanks @omarshahine. Closing this umbrella skill PR as superseded by feature-specific documentation carried with the implementations.

Current main exposes messages.stats, read-only messages.scheduled, and read-only chat-background status. This branch still documents old stats RPCs, scheduled creation, old sticker aliases, --rich-link, background mutation, and contact-card APIs that were renamed, narrowed, deferred, or rejected. #161, #163, and #167 landed the exact proven contracts; remaining bridge features should update the skill when their implementations land.