docs: fix docs metadata spellcheck

[harjothkhara]

Summary

• Update docs/specs/claw-supervisor.md frontmatter from the old description / readWhen keys to the canonical summary / read_when keys parsed by pnpm docs:list.
• Add allowIn and planText to the docs spellcheck ignore list because they are documented camelCase API/config identifiers, not typos.

Real behavior proof

• Behavior or issue addressed: pnpm docs:list could not surface the Claw Supervisor doc summary/read-when metadata because that page used stale frontmatter keys, and docs spellcheck needed ignores for real camelCase docs tokens.

• Real environment tested: Local OpenClaw checkout on macOS, on branch codex/docs-metadata-spellcheck at 111fb71783cf5c5572becd8df148122cb2efa814.

• Exact steps or command run after this patch: pnpm docs:list and pnpm docs:spellcheck.

• Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output): Copied terminal output from the local checkout after this patch:

  $ pnpm docs:list
  $ node scripts/docs-list.js
  Listing all markdown files in docs folder:
  ...
  specs/claw-supervisor.md - Fleet supervision plan for Codex app-server sessions controlled by OpenClaw.
    Read when: Designing Codex fleet supervision; Building OpenClaw tools that read, steer, or spawn Codex sessions; Choosing between local, Cloudflare, and VPS deployment for supervised Codex
  ...
  Reminder: keep docs up to date as behavior changes. When your task matches any "Read when" hint above (React hooks, cache directives, database work, tests, etc.), read that doc before coding, and suggest new coverage when it is missing.
  
  $ pnpm docs:spellcheck
  $ bash scripts/docs-spellcheck.sh
  

• Observed result after fix: specs/claw-supervisor.md appears in the docs listing with the intended summary and read-when hints, and the docs spellcheck command exits with no diagnostics for allowIn or planText.

• What was not tested: Runtime behavior, packaging, or the full product suite; this is a docs metadata and spellcheck configuration patch only.

• Proof limitations or environment constraints: pnpm docs:spellcheck is quiet on success, so the terminal capture shows the invoked script with no diagnostics after it.

Tests and validation

• pnpm docs:list
• pnpm docs:spellcheck
• pnpm docs:check-mdx
• pnpm docs:check-links
• pnpm docs:check-i18n-glossary
• pnpm format:docs:check
• pnpm lint:docs
• pnpm exec oxfmt --check --threads=1 docs/specs/claw-supervisor.md scripts/codespell-ignore.txt
• git diff --check -- docs/specs/claw-supervisor.md scripts/codespell-ignore.txt

Review

Claude autoreview reported the patch as correct and landable. It raised one P3 question about whether allowIn was needed in the ignore list; I verified that removing allowIn makes codespell fail on the bare allowIn tokens in docs/channels/groups.md, so the ignore entry is intentional.

Risk checklist

Did user-visible behavior change? Yes, docs tooling now reads this page's summary/read-when metadata correctly.

Did config, environment, or migration behavior change? No.

Did security, auth, secrets, network, or tool execution behavior change? No.

What is the highest-risk area? Low docs-tooling risk: keeping the codespell ignore list scoped to real docs identifiers.

How is that risk mitigated? Both ignored tokens were verified against documented identifiers in docs/**, and docs spellcheck passes after the patch.

Current review state

Ready for review and merge once GitHub checks are green.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 21, 2026, 9:39 AM ET / 13:39 UTC.

Summary
The PR renames the Claw Supervisor page frontmatter to the docs-list canonical summary/read_when keys and adds allowIn/planText to the codespell ignore list.

PR surface: Docs 0, Other +2. Total +2 across 2 files.

Reproducibility: yes. Source inspection shows current main still uses stale frontmatter keys on the page while scripts/docs-list.js only parses summary: and read_when:.

Review metrics: none identified.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🦞 diamond lobster
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:

• none.

Next step before merge

• [P2] No repair lane is needed; this PR is clean and only needs ordinary maintainer review.

Security
Cleared: Cleared: the diff changes only Markdown frontmatter and a codespell ignore list, with no dependency, workflow, credential, package, or executable-script change.

Review details

Best possible solution:

Merge the narrow docs metadata and ignore-list update after ordinary maintainer review; avoid adding parser aliases for one stale page.

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

Yes. Source inspection shows current main still uses stale frontmatter keys on the page while scripts/docs-list.js only parses summary: and read_when:.

Is this the best way to solve the issue?

Yes. Updating the one stale page and adding ignores for two documented camelCase identifiers is narrower than adding parser aliases or broader spellcheck suppression.

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

• P3: This is a low-risk docs tooling cleanup with no runtime, config, migration, or security impact.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): Sufficient: the PR body includes copied terminal output for pnpm docs:list after the patch and explains the quiet-success pnpm docs:spellcheck result.
• proof: sufficient: Contributor real behavior proof is sufficient. Sufficient: the PR body includes copied terminal output for pnpm docs:list after the patch and explains the quiet-success pnpm docs:spellcheck result.

Evidence reviewed

PR surface:

Docs 0, Other +2. Total +2 across 2 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	0	0	0	0
Tests	0	0	0	0
Docs	1	2	2	0
Config	0	0	0	0
Generated	0	0	0	0
Other	1	2	0	+2
Total	2	4	2	+2

What I checked:

• Current docs-list metadata contract: extractMetadata recognizes summary: and read_when: but not the stale description: or readWhen: keys. (scripts/docs-list.js:101, 11a2e03bd4de)
• Current main still has stale metadata: The Claw Supervisor page on current main still uses description: and readWhen:, so the PR is not already implemented on main. Public docs: docs/specs/claw-supervisor.md. (docs/specs/claw-supervisor.md:3, 11a2e03bd4de)
• Latest release still has stale metadata: The latest release tag commit still has the old Claw Supervisor frontmatter, so the requested cleanup has not shipped there either. Public docs: docs/specs/claw-supervisor.md. (docs/specs/claw-supervisor.md:3, c645ec4555c0)
• PR head applies the canonical keys: The PR head changes the page to summary: and read_when: without changing the body content. Public docs: docs/specs/claw-supervisor.md. (docs/specs/claw-supervisor.md:3, 111fb71783cf)
• Spellcheck ignore file is the active command input: docs:spellcheck passes scripts/codespell-ignore.txt through -I, so the ignore additions are on the command path they claim to fix. (scripts/docs-spellcheck.sh:18, 11a2e03bd4de)
• allowIn is a documented identifier: The group-channel docs use allowIn as a config field, supporting the ignore-list entry as an identifier rather than typo suppression. Public docs: docs/channels/groups.md. (docs/channels/groups.md:383, 11a2e03bd4de)

Likely related people:

• vincentkoc: Current blame points the touched docs, docs-list, and spellcheck files at recent current-main snapshot commit 61d1fd1, and file history links this person to the custom spellcheck dictionary/ignore workflow. (role: recent area contributor; confidence: medium; commits: 61d1fd1f7217, 3002be76e482; files: docs/specs/claw-supervisor.md, scripts/docs-list.js, scripts/docs-spellcheck.sh)
• steipete: File history shows this person authored the docs-list helper/frontmatter support and later maintained docs-list and spellcheck fallback behavior. (role: docs tooling history owner; confidence: high; commits: bc3a14cde2a6, 86950d347426, 352b5262da32; files: scripts/docs-list.js, scripts/docs-spellcheck.sh, scripts/codespell-ignore.txt)

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.