docs: document Hermit appeal forms

[thewilloftheshadow]

Summary

• document Hermit Forms as the OpenClaw appeals and moderator-report system
• update moderation docs from appeal.gg to appeal.openclaw.ai form paths
• document first-class forms hosts, review channels, Devvit Reddit bridge, and Hermit Forms operations

Testing

• docs-only; not run

[clawsweeper]

Codex review: needs maintainer review before merge.

Latest ClawSweeper review: 2026-05-23 21:18 UTC / May 23, 2026, 5:18 PM ET.

Workflow note: Future ClawSweeper reviews update this same comment in place.

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.

Summary
The branch adds an appeals-and-reports guide and updates README, moderation, bot-management, and roles docs to move appeals and moderator reports from appeal.gg to Hermit Forms on appeal.openclaw.ai/forms.openclaw.ai.

Reproducibility: not applicable. this is a documentation update, not a runtime bug with a reproduction path. The relevant checks are Markdown consistency, current-main comparison, and maintainer validation of the operational facts.

PR rating
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🐚 platinum hermit
Summary: The patch is a narrow, coherent docs update with clean diff checks and no blocking findings, with operational accuracy left for maintainer confirmation.

Rank-up moves:

• Confirm the live form hosts, review channels, and Reddit bridge details before merging.

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.

Real behavior proof
Not applicable: The PR is member-authored and changes only Markdown docs, so after-fix runtime proof is not a merge gate.

Risk before merge

• The branch documents live form hosts, form paths, private review channels, and Devvit Reddit bridge behavior that cannot be independently verified from this repository alone.
• If those operational facts are wrong, users could be directed to the wrong appeal or moderator-report flow until the docs are corrected.

Maintainer options:

1. Decide the mitigation before merge
   Land the focused docs update once the community operations owner confirms the Hermit Forms hosts, paths, review channels, and Shell Society routing are authoritative.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge
This member-authored draft documents operational policy details that need human confirmation rather than an automated repair.

Security
Cleared: Docs-only Markdown changes add OpenClaw-owned form URLs and do not change code execution, dependencies, secrets, permissions, or automation.

Review details

Best possible solution:

Land the focused docs update once the community operations owner confirms the Hermit Forms hosts, paths, review channels, and Shell Society routing are authoritative.

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

Not applicable; this is a documentation update, not a runtime bug with a reproduction path. The relevant checks are Markdown consistency, current-main comparison, and maintainer validation of the operational facts.

Is this the best way to solve the issue?

Unclear until maintainers confirm the operational facts; if the documented hosts and channels are current, the branch is a narrow maintainable way to replace stale appeal.gg guidance.

Label justifications:

• P3: This is a low-risk documentation update for community operations with no runtime code changes.
• rating: 🐚 platinum hermit: Current PR rating is 🐚 platinum hermit because proof is 🌊 off-meta tidepool, patch quality is 🐚 platinum hermit, and The patch is a narrow, coherent docs update with clean diff checks and no blocking findings, with operational accuracy left for maintainer confirmation.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The PR is member-authored and changes only Markdown docs, so after-fix runtime proof is not a merge gate.

What I checked:

• Current main still documents the old appeal flow: Current main still points users to appeal.gg in README, moderation, bot-management, and roles docs, so the branch is not obsolete or already implemented on main. (README.md:7, bd2eda8e70c3)
• PR adds the new Hermit Forms guide: The proposed guide documents appeal.openclaw.ai and forms.openclaw.ai, form paths, auth options, review channels, Mermaid appeal flow, accept/deny behavior, report-mod flow, and Reddit bridge context. (appeals-and-reports.md:1, 9e7d5774989b)
• Docs diff is narrow and syntactically clean: The branch changes five Markdown files, adding 129 lines and deleting 10, and git diff --check reports no whitespace errors. (9e7d5774989b)
• Repository diagram instruction is followed: AGENTS.md requires Mermaid for charts/diagrams, and the added appeal flow is fenced as mermaid. (appeals-and-reports.md:32, 9e7d5774989b)
• History points to Shadow as the docs area owner: Blame and log show Shadow introduced the original community policy docs and recently maintained the Hermit/bot-management docs that this branch changes. (bot-management.md:31, bd2eda8e70c3)
• Protected cleanup rule applies: The provided GitHub context marks the author association as MEMBER and the PR as draft, so conservative cleanup should not auto-close it even if the diff looks reviewable. (9e7d5774989b)

Likely related people:

• thewilloftheshadow: The GitHub context identifies the member handle, and local history shows Shadow authored the current community docs, the recent Hermit docs, and the two commits on this branch. (role: recent area contributor; confidence: high; commits: 45e03088805b, 573092875579, f55dcd1c9d1c; files: README.md, moderation.md, bot-management.md)

Codex review notes: model gpt-5.5, reasoning high; reviewed against bd2eda8e70c3.

[clawsweeper]

ClawSweeper PR egg

✨ Hatched: 🥚 common Gilded Branchling

Hatch command

Comment @clawsweeper hatch when this PR is hatchable.

Hatchability rules:

• Merged PRs are hatchable.
• Open PRs are hatchable when they are status: 👀 ready for maintainer look, status: 🚀 automerge armed, or labeled clawsweeper:automerge.
• Closed unmerged PRs are hatchable only when one of those hatchable labels is still present in the durable record.

Rarity: 🥚 common.
Trait: stacks clean commits.
Image traits: location CI tidepool; accessory lint brush; palette amber, ink, and glacier blue; mood sparkly; pose holding its accessory up for inspection; shell woven fiber shell; lighting golden review-room light; background little resolved-comment flags.
Share on X: post this hatch
Copy: My PR egg hatched a 🥚 common Gilded Branchling in ClawSweeper.

What is this egg doing here?

• Eggs appear after the PR passes real-behavior proof. It is here for vibes, not verdicts: it does not change labels, ratings, merge decisions, or automation.
• The shell reacts to review momentum: open follow-up work warms it up, re-review makes it wobble, and a clean final review lets it hatch.
• Hatchability usually comes from sufficient real-behavior proof, no blocking P0/P1/P2 findings, no security attention needed, and clean correctness. A merged PR is already final, so merge makes the egg hatchable independently.
• The hatch is seeded from this repository and PR number, so the same PR keeps the same creature; the reviewed head SHA can only change safe visual details.
• Rarity is just collectible sparkle: 🥚 common, 🌱 uncommon, 💎 rare, ✨ glimmer, and 🌈 legendary.