fix(docs): show inline read_when hints in docs:list (#95243)

* fix(docs): show inline read_when hints in docs:list

* test(scripts): use shared temp directory helper

* test(scripts): route docs list helper test

---------

Co-authored-by: Vincent Koc <vincentkoc@ieee.org>

scripts/docs-list.js

@@ -116,6 +116,11 @@ function extractMetadata(fullPath) {
         } catch {
           // ignore malformed inline arrays
         }
+      } else if (
+        (inline.startsWith('"') && inline.endsWith('"')) ||
+        (inline.startsWith("'") && inline.endsWith("'"))
+      ) {
+        readWhen.push(...compactStrings([inline.slice(1, -1)]));
       }
       continue;
     }

scripts/test-projects.test-support.mjs

@@ -1026,6 +1026,7 @@ const TOOLING_SOURCE_TEST_TARGETS = new Map([
     "scripts/deadcode-unused-files.allowlist.mjs",
     ["test/scripts/check-deadcode-unused-files.test.ts"],
   ],
+  ["scripts/docs-list.js", ["test/scripts/docs-list.test.ts"]],
   ["scripts/docs-link-audit.mjs", ["src/scripts/docs-link-audit.test.ts"]],
   ["scripts/lib/arg-utils.mjs", ["test/scripts/arg-utils.test.ts"]],
   [

src/scripts/test-projects.test.ts

@@ -887,6 +887,7 @@ describe("test-projects args", () => {
           "test/scripts/codex-install-assertions.test.ts",
           "test/scripts/config-reload-mutate-metadata.test.ts",
           "test/scripts/control-ui-i18n.test.ts",
+          "test/scripts/docs-list.test.ts",
           "test/scripts/doctor-install-switch-wrapper.test.ts",
           "test/scripts/e2e-text-file-utils.test.ts",
           "test/scripts/fixture-common.test.ts",

test/scripts/docs-list.test.ts

@@ -0,0 +1,46 @@
+// docs-list tests cover source docs metadata discovery for docs-aware tooling.
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { cleanupTempDirs, makeTempDir } from "../helpers/temp-dir.js";
+
+const tempDirs: string[] = [];
+const repoRoot = path.resolve(import.meta.dirname, "../..");
+const docsListScriptPath = path.join(repoRoot, "scripts", "docs-list.js");
+
+function makeTempRepoRoot(prefix: string): string {
+  return makeTempDir(tempDirs, prefix);
+}
+
+function runDocsList(cwd: string): string {
+  return execFileSync(process.execPath, [docsListScriptPath], {
+    cwd,
+    encoding: "utf8",
+  });
+}
+
+afterEach(() => {
+  cleanupTempDirs(tempDirs);
+});
+
+describe("docs-list", () => {
+  it("prints single-line read_when strings as read hints", () => {
+    const tempRepoRoot = makeTempRepoRoot("openclaw-docs-list-");
+    mkdirSync(path.join(tempRepoRoot, "docs"), { recursive: true });
+    writeFileSync(
+      path.join(tempRepoRoot, "docs", "page.md"),
+      `---
+summary: "Single-line read_when page"
+read_when: "Read this page when the hint is inline."
+---
+`,
+      "utf8",
+    );
+
+    const output = runDocsList(tempRepoRoot);
+
+    expect(output).toContain("page.md - Single-line read_when page");
+    expect(output).toContain("Read when: Read this page when the hint is inline.");
+  });
+});

test/scripts/test-projects.test.ts

@@ -1389,6 +1389,11 @@ describe("scripts/test-projects changed-target routing", () => {
       targets: ["test/scripts/update-clawtributors.test.ts"],
     });
 
+    expect(resolveChangedTestTargetPlan(["scripts/docs-list.js"])).toEqual({
+      mode: "targets",
+      targets: ["test/scripts/docs-list.test.ts"],
+    });
+
     expect(resolveChangedTestTargetPlan(["scripts/docs-link-audit.mjs"])).toEqual({
       mode: "targets",
       targets: ["src/scripts/docs-link-audit.test.ts"],