docs: add scripts directory index by qingminglong · Pull Request #97250 · openclaw/openclaw

qingminglong · 2026-06-27T13:14:24Z

What Problem This Solves

Fixes the low-risk documentation/index portion of #59728 by adding a discoverable scripts/README.md for the current scripts/ directory.

The issue also proposes a wholesale scripts directory reorganization. This PR intentionally does not move or rename scripts because those paths are referenced by package.json, GitHub Actions, docs, and maintainer runbooks. Any relocation still needs a maintainer-approved taxonomy and compatibility plan.

Why This Change Was Made

The existing scripts/ directory has many entry points but no local index for contributors or agents to quickly find the right wrapper. This adds a small README that documents:

what the directory owns
why script paths should not be moved casually
common check, lint, test, build, docs, release, GitHub, Docker, and remote-proof entry points
maintenance pointers to scripts/AGENTS.md and the public scripts docs

User Impact

Contributors can find existing script wrappers faster before adding new tooling or running broad commands. Maintainers get a safer first step toward #59728 without changing any script paths, package scripts, workflows, lockfiles, or generated files.

Evidence

Claim proved: this PR is docs-only and adds a scripts/README.md index for the existing flat scripts/ layout. It does not move, rename, or regroup scripts, and it does not change package.json, GitHub Actions, lockfiles, generated files, or runtime behavior.

Commands / artifacts:

pnpm docs:list
git diff --check HEAD~1 HEAD -- scripts/README.md
CI check-docs passed on this PR: https://github.com/openclaw/openclaw/actions/runs/28290280970/job/83821022006
PR context gate passed after the no-BOM body refresh: https://github.com/openclaw/openclaw/actions/runs/28290509317

Copied terminal output:

$ pnpm docs:list
$ node scripts/docs-list.js
Listing all markdown files in docs folder:
agent-runtime-architecture.md - How OpenClaw runs the built-in agent runtime, providers, sessions, tools, and extensions.
AGENTS.md - [missing front matter]
announcements\bluebubbles-imessage.md - BlueBubbles support was removed from OpenClaw. Use the bundled iMessage plugin with imsg for new and migrated iMessage setups.
...
web\webchat.md - Loopback WebChat static host and Gateway WS usage for chat UI
  Read when: Debugging or configuring WebChat access

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.
Exit code: 0

$ git diff --check HEAD~1 HEAD -- scripts/README.md
Exit code: 0

$ git diff --name-status HEAD~1 HEAD
A       scripts/README.md

$ git diff --stat HEAD~1 HEAD
 scripts/README.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)

Duplicate PR preflight:

gh search prs --repo openclaw/openclaw --state open --match title,body -- 59728 returned no open PRs
gh search prs --repo openclaw/openclaw --state open --match title,body -- "scripts README" returned no open PRs
gh issue view 59728 --repo openclaw/openclaw confirmed Scripts: Organize 150+ files in scripts/ directory by function with README index #59728 is still open

Result: the docs index renders as Markdown, docs discovery still lists successfully, whitespace checks pass, and scoped CI docs validation is green.

Not tested / proof gaps: no runtime, script execution, script relocation, package-script rewiring, or workflow behavior was tested because this PR intentionally does not change those surfaces. The broader #59728 directory reorganization still needs a maintainer-approved taxonomy and compatibility plan before implementation.

clawsweeper · 2026-06-27T13:15:21Z

Codex review: needs maintainer review before merge. Reviewed June 27, 2026, 10:13 AM ET / 14:13 UTC.

Summary
Adds scripts/README.md as a local index for script ownership, compatibility cautions, common entry points, script families, maintenance rules, and the public scripts guide link.

PR surface: Docs +75. Total +75 across 1 file.

Reproducibility: not applicable. this is a documentation/discoverability PR, not a runtime bug. Source inspection verifies current main lacks scripts/README.md while related public docs are not a local directory index.

Review metrics: none identified.

Stored data model
Persistent data-model change detected: migration/backfill/repair: scripts/README.md. Confirm migration or upgrade compatibility proof before merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #59728
Summary: This PR is a candidate partial fix for the open scripts organization issue, limited to the README/index portion while broader relocation remains undecided.

Members:

canonical: Scripts: Organize 150+ files in scripts/ directory by function with README index #59728 - The open issue requests both a scripts README/index and wider scripts directory organization; this PR addresses only the low-risk index slice.
superseded: dx: PR template chooser, justfile, and scripts README index (#59737, #59736, #59728) #80676 - The earlier broad DX PR included a scripts README attempt but was closed unmerged, so it is not a viable canonical landing path.

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:

none.

Next step before merge

[P2] No repair lane is needed; the PR has no actionable patch defect and only needs ordinary maintainer docs review.

Security
Cleared: The diff adds one Markdown file and does not alter code execution, dependencies, workflows, permissions, package metadata, or secrets handling.

Review details

Best possible solution:

Land the narrow scripts README after ordinary maintainer docs review, and leave any script relocation or taxonomy change in the canonical broader issue until maintainers approve a compatibility plan.

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

Not applicable: this is a documentation/discoverability PR, not a runtime bug. Source inspection verifies current main lacks scripts/README.md while related public docs are not a local directory index.

Is this the best way to solve the issue?

Yes for the index slice: adding a root scripts README is the narrowest maintainable docs path and avoids the compatibility risk of moving script paths. It intentionally does not solve the broader scripts reorganization request.

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

P3: This is low-risk contributor documentation and discoverability work with no runtime, config, workflow, dependency, or migration change.
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 (terminal): The PR body now includes copied terminal output for the docs/list and whitespace checks, and live PR checks show the real-behavior-proof gate succeeded for the current head.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body now includes copied terminal output for the docs/list and whitespace checks, and live PR checks show the real-behavior-proof gate succeeded for the current head.

Evidence reviewed

PR surface:

Docs +75. Total +75 across 1 file.

View PR surface stats

Area	Files	Added	Net
Source	0	0	0
Tests	0	0	0
Docs	1	75	+75
Config	0	0	0
Generated	0	0	0
Other	0	0	0
Total	1	75	+75

What I checked:

PR diff is docs-only and narrow: The PR adds one Markdown file, scripts/README.md, with compatibility guidance, common script entry points, script-family descriptions, and maintenance rules; it does not change package scripts, workflows, lockfiles, generated files, or runtime code. (scripts/README.md:1, 46660e7ab8c2)
Current main lacks the requested local index: Current main has no scripts/README.md; find scripts -maxdepth 2 -name README.md only found scripts/clawdock/README.md, while find scripts -maxdepth 1 -type f | wc -l reported 365 root-level script files. (scripts/README.md, 5ccfc97b319e)
Existing public docs are related but not a local directory index: docs/help/scripts.md documents public script conventions and the gh-read helper, and docs/docs.json exposes it at help/scripts; it does not replace a root scripts/README.md for contributors working inside the directory. (docs/help/scripts.md:9, 5ccfc97b319e)
Documented entry points match current package scripts: The README's build, changed checks, docs, formatting, lint, release, Docker, live, and test entries map to existing package scripts and script files, including build, changed:lanes, check:changed, docs:list, docs:check-mdx, docs:check-links, format:docs:check, release:check, test:changed, test:docker:all, and test:live. (package.json:1509, 5ccfc97b319e)
Scoped scripts policy supports the README guidance: scripts/AGENTS.md tells contributors to prefer existing wrappers, avoid bare Vitest, keep changed-file verification centralized in check-changed.mjs/changed-lanes.mjs, and update tests under test/scripts/ for script behavior changes, which aligns with the new README. (scripts/AGENTS.md:7, 5ccfc97b319e)
Contributor proof is now present: The PR body includes copied terminal output for pnpm docs:list, git diff --check HEAD~1 HEAD -- scripts/README.md, name/status/stat checks, and the live PR checks show both Real behavior proof and check-docs succeeded on the current head. (46660e7ab8c2)

Likely related people:

RomneyDa: Recent commits updated scripts/AGENTS.md and changed lint/check wrapper guidance that overlaps the new README's wrapper-discovery advice. (role: recent scripts-guidance contributor; confidence: high; commits: 8670d2812663, 7de025eacd8c; files: scripts/AGENTS.md, scripts/check-changed.mjs)
vincentkoc: Recent history touched docs/help/scripts.md and changed-lane/script routing surfaces adjacent to the new index. (role: recent documentation and scripts contributor; confidence: medium; commits: 1ded8de5a91c, 7dc7deaa13a1, 4b23b36f207a; files: docs/help/scripts.md, scripts/changed-lanes.mjs, scripts/check-changed.mjs)
steipete: Recent commits added gh-read, changed-lane local gate guidance, and docs-list/script documentation referenced by the README. (role: recent scripts and docs tooling contributor; confidence: medium; commits: 788b47536c86, d51f527ccaf1, 980c91d29326; files: scripts/AGENTS.md, docs/help/scripts.md, scripts/gh-read)
hugenshen: Recent docs-list work is relevant because the PR uses docs-style metadata and validates docs discovery output. (role: recent docs-list contributor; confidence: medium; commits: 3cc05d590cb6; files: scripts/docs-list.js)

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.

qingminglong · 2026-06-27T14:04:15Z

@clawsweeper re-review

clawsweeper · 2026-06-27T14:04:18Z

🦞🧹
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.

qingminglong · 2026-06-27T14:08:16Z

@clawsweeper re-review

docs: add scripts directory index

46660e7

openclaw-barnacle Bot added scripts Repository scripts size: S triage: needs-pr-context Candidate: external PR body lacks required problem context or evidence. labels Jun 27, 2026

openclaw-barnacle Bot removed the triage: needs-pr-context Candidate: external PR body lacks required problem context or evidence. label Jun 27, 2026

clawsweeper Bot mentioned this pull request Jun 27, 2026

Scripts: Organize 150+ files in scripts/ directory by function with README index #59728

Closed

7 tasks

vincentkoc merged commit 9f66f61 into openclaw:main Jun 28, 2026
142 of 164 checks passed

github-actions Bot mentioned this pull request Jun 28, 2026

📡 Upstream Digest — 2026-06-28 20:53 UTC curtismercier/openclaw-mods#1169

Open

github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request Jun 29, 2026

docs: add scripts directory index (openclaw#97250)

45c7624

QiuYuang pushed a commit to QiuYuang/openclaw that referenced this pull request Jul 1, 2026

docs: add scripts directory index (openclaw#97250)

81c7f6d

chenyangjun-xy pushed a commit to chenyangjun-xy/openclaw that referenced this pull request Jul 1, 2026

docs: add scripts directory index (openclaw#97250)

762b787

chenyangjun-xy pushed a commit to chenyangjun-xy/openclaw that referenced this pull request Jul 3, 2026

docs: add scripts directory index (openclaw#97250)

462c48e

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

docs: add scripts directory index#97250

docs: add scripts directory index#97250
vincentkoc merged 1 commit into
openclaw:mainfrom
qingminglong:codex/docs-scripts-index

qingminglong commented Jun 27, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jun 27, 2026 •

edited

Loading

Uh oh!

qingminglong commented Jun 27, 2026

Uh oh!

clawsweeper Bot commented Jun 27, 2026 •

edited

Loading

Uh oh!

qingminglong commented Jun 27, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

qingminglong commented Jun 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Problem This Solves

Why This Change Was Made

User Impact

Evidence

Uh oh!

clawsweeper Bot commented Jun 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

qingminglong commented Jun 27, 2026

Uh oh!

clawsweeper Bot commented Jun 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

qingminglong commented Jun 27, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

qingminglong commented Jun 27, 2026 •

edited

Loading

clawsweeper Bot commented Jun 27, 2026 •

edited

Loading

clawsweeper Bot commented Jun 27, 2026 •

edited

Loading