docs: document scoped script helpers

scripts/github/dependency-guard.mjs

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
 
+// GitHub dependency-change guard: detects dependency files, manages override
+// comments/labels, and can autoscrub lockfile-only PR changes.
 import { appendFile, readFile } from "node:fs/promises";
 import { readBoundedResponseText } from "../lib/bounded-response.mjs";
 
+/** Marker used to identify dependency guard comments. */
 export const dependencyChangeMarker = "<!-- openclaw:dependency-guard -->";
 export const dependencyGraphGuardMarker = "<!-- openclaw:dependency-graph-guard -->";
 export const dependencyChangedLabel = "dependencies-changed";

scripts/github/real-behavior-proof-check.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// Checks PR real-behavior proof labels/comments and writes GitHub Action outputs.
 import { readFileSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import {

scripts/github/real-behavior-proof-policy.mjs

@@ -1,5 +1,7 @@
+// Shared real-behavior proof policy for GitHub PR checks and label decisions.
 import { readBoundedResponseText } from "../lib/bounded-response.mjs";
 
+/** Label that lets maintainers override real-behavior proof requirements. */
 export const PROOF_OVERRIDE_LABEL = "proof: override";
 export const PROOF_SUPPLIED_LABEL = "proof: supplied";
 export const PROOF_SUFFICIENT_LABEL = "proof: sufficient";

scripts/mantis/build-telegram-desktop-proof-evidence.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// Builds an HTML/manifest evidence bundle from Telegram Desktop proof artifacts.
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -159,6 +160,9 @@ function laneArtifactEntries() {
   ]);
 }
 
+/**
+ * Builds the manifest for paired baseline/candidate Telegram Desktop proof artifacts.
+ */
 export function buildTelegramDesktopProofManifest({
   baseline,
   baselineRef,

scripts/mantis/build-telegram-evidence.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// Builds an HTML/manifest evidence bundle from Telegram QA scenario summaries.
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -88,6 +89,9 @@ function renderObservedMessages(observedMessages) {
     .join("\n");
 }
 
+/**
+ * Renders a self-contained Telegram evidence HTML report.
+ */
 export function renderTelegramEvidenceHtml({ observedMessages, summary }) {
   const counts = summary.counts ?? {};
   const pass = counts.failed === 0 && Number(counts.total ?? 0) > 0;

scripts/mantis/publish-pr-evidence.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// Publishes evidence manifest artifacts and optional PR comments for Mantis proof.
 import { execFileSync } from "node:child_process";
 import { createHash, createHmac } from "node:crypto";
 import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
@@ -86,6 +87,9 @@ function resolveArtifact(manifestDir, artifact) {
   };
 }
 
+/**
+ * Loads and validates an evidence manifest from disk.
+ */
 export function loadEvidenceManifest(manifestPath) {
   const resolvedManifest = path.resolve(manifestPath);
   const manifestDir = path.dirname(resolvedManifest);

scripts/perf/summarize-cpuprofile.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// Summarizes V8 CPU profile files by frame and module.
 import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
@@ -7,6 +8,9 @@ import { parsePositiveInt } from "../lib/numeric-options.mjs";
 
 const DEFAULT_LIMIT = 30;
 
+/**
+ * Parses CPU profile file paths and --limit.
+ */
 export function parseArgs(argv) {
   const files = [];
   let limit = DEFAULT_LIMIT;

scripts/pre-commit/filter-staged-files.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// Filters staged file paths for pre-commit lint/format hooks.
 import path from "node:path";
 
 /**

scripts/pre-commit/pnpm-audit-prod.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+// Production dependency audit helper using pnpm lock data and npm bulk advisories.
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
@@ -8,6 +9,7 @@ import { pathToFileURL } from "node:url";
 const DEFAULT_REGISTRY = "https://registry.npmjs.org";
 const BULK_ADVISORY_PATH = "/-/npm/v1/security/advisories/bulk";
 const MIN_SEVERITY = "high";
+/** Maximum advisory error body characters retained in messages. */
 export const BULK_ADVISORY_ERROR_BODY_MAX_CHARS = 4096;
 export const BULK_ADVISORY_RESPONSE_BODY_MAX_BYTES = 8 * 1024 * 1024;
 export const BULK_ADVISORY_REQUEST_TIMEOUT_MS = 60_000;

scripts/repro/limit-edge-case-live-proof.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// Live repro for numeric limit edge cases across diagnostics, usage, and voice-call CLI.
 import assert from "node:assert/strict";
 /**
  * Live repro for limit/CLI numeric fixes (PR #82679). Run: pnpm exec tsx scripts/repro/limit-edge-case-live-proof.mjs
@@ -15,6 +16,9 @@ import {
   resetDiagnosticPhasesForTest,
 } from "../../src/logging/diagnostic-phase.ts";
 
+/**
+ * Creates and cleans a temp root for live proof fixtures.
+ */
 export async function withProofTempRoot(callback) {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-proof-"));
   try {

scripts/secrets/openclaw-bws-resolver.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// Resolves SecretRef requests against Bitwarden Secrets Manager without printing secrets.
 import { execFileSync } from "node:child_process";
 
 const readStdin = () =>

scripts/test-planner/vitest-args.mjs

@@ -1,3 +1,5 @@
+// Parses Vitest passthrough args for test-planner entry filter accounting.
+/** Vitest options that consume the following CLI token as a value. */
 export const OPTION_TAKES_VALUE = new Set([
   "-t",
   "-c",
@@ -37,8 +39,12 @@ export const OPTION_TAKES_VALUE = new Set([
   "--experimental",
 ]);
 
+/** Flags that only make sense for a single generated test run. */
 export const SINGLE_RUN_ONLY_FLAGS = new Set(["--coverage", "--outputFile", "--mergeReports"]);
 
+/**
+ * Splits Vitest passthrough args into file filters and option args.
+ */
 export const parsePassthroughArgs = (args = []) => {
   const fileFilters = [];
   const optionArgs = [];