fix(docs): preserve plugin reference manual sections

docs/plugins/reference/policy.md

@@ -18,6 +18,8 @@ Adds policy-backed doctor checks for workspace conformance.
 
 plugin
 
+<!-- openclaw-plugin-reference:manual-start -->
+
 ## Behavior
 
 The Policy plugin contributes doctor health checks for policy-managed OpenClaw
@@ -63,6 +65,8 @@ for its selector. Overlay rules are additional claims, so they do not weaken
 top-level policy and can produce their own findings when the same observed
 config violates both scopes.
 
+<!-- openclaw-plugin-reference:manual-end -->
+
 ## Related docs
 
 - [policy](/cli/policy)

scripts/generate-plugin-inventory-doc.mjs

@@ -29,8 +29,8 @@ const PLUGIN_DOC_ALIASES = new Map([
   ["tavily", "/tools/tavily"],
   ["tokenjuice", "/tools/tokenjuice"],
 ]);
-/** @type {ReadonlyMap<string, string>} */
-const PLUGIN_REFERENCE_EXTRA_SECTIONS = new Map();
+const MANUAL_SECTION_START = "<!-- openclaw-plugin-reference:manual-start -->";
+const MANUAL_SECTION_END = "<!-- openclaw-plugin-reference:manual-end -->";
 
 function readJson(relativePath) {
   return JSON.parse(fs.readFileSync(path.join(ROOT, relativePath), "utf8"));
@@ -377,9 +377,48 @@ function renderRelatedDocs(record) {
 ${record.docs.map((link) => `- ${docLink(link)}`).join("\n")}`;
 }
 
-function renderReferencePage(record) {
+function extractManualReferenceSections(content) {
+  const markerStart = content.indexOf(MANUAL_SECTION_START);
+  if (markerStart !== -1) {
+    const contentStart = markerStart + MANUAL_SECTION_START.length;
+    const markerEnd = content.indexOf(MANUAL_SECTION_END, contentStart);
+    if (markerEnd !== -1) {
+      return content.slice(contentStart, markerEnd).trim();
+    }
+  }
+
+  const surfaceMatch = /\n## Surface\n\n[^\n]*(?:\n|$)/u.exec(content);
+  if (!surfaceMatch?.index) {
+    return "";
+  }
+  const manualStart = surfaceMatch.index + surfaceMatch[0].length;
+  const relatedDocsStart = content.indexOf("\n## Related docs\n", manualStart);
+  const manualEnd = relatedDocsStart === -1 ? content.length : relatedDocsStart;
+  return content.slice(manualStart, manualEnd).trim();
+}
+
+function readManualReferenceSections(relativePath) {
+  const fullPath = path.join(ROOT, relativePath);
+  if (!fs.existsSync(fullPath)) {
+    return "";
+  }
+  return extractManualReferenceSections(fs.readFileSync(fullPath, "utf8"));
+}
+
+function renderManualReferenceSections(manualSections) {
+  if (!manualSections) {
+    return "";
+  }
+  return `${MANUAL_SECTION_START}
+
+${manualSections}
+
+${MANUAL_SECTION_END}`;
+}
+
+function renderReferencePage(record, manualSections = "") {
   const relatedDocs = renderRelatedDocs(record);
-  const extraSections = PLUGIN_REFERENCE_EXTRA_SECTIONS.get(record.id) ?? "";
+  const manualBlock = renderManualReferenceSections(manualSections);
   return `---
 summary: "${record.description.replaceAll('"', '\\"')}"
 read_when:
@@ -398,7 +437,7 @@ ${record.description}
 
 ## Surface
 
-${record.surface}${extraSections ? `\n\n${extraSections}` : ""}${relatedDocs ? `\n\n${relatedDocs}` : ""}
+${record.surface}${manualBlock ? `\n\n${manualBlock}` : ""}${relatedDocs ? `\n\n${relatedDocs}` : ""}
 `;
 }
 
@@ -493,9 +532,11 @@ function collectPluginRecords() {
 function writeGeneratedDocs(records) {
   fs.mkdirSync(path.join(ROOT, REFERENCE_DIR), { recursive: true });
   for (const record of records) {
+    const relativePath = path.join(REFERENCE_DIR, `${record.id}.md`);
+    const manualSections = readManualReferenceSections(relativePath);
     fs.writeFileSync(
-      path.join(ROOT, REFERENCE_DIR, `${record.id}.md`),
-      renderReferencePage(record),
+      path.join(ROOT, relativePath),
+      renderReferencePage(record, manualSections),
       "utf8",
     );
   }
@@ -505,10 +546,10 @@ function writeGeneratedDocs(records) {
 function readGeneratedDocs(records) {
   return [
     [REFERENCE_INDEX_PATH, renderReferenceIndex(records)],
-    ...records.map((record) => [
-      path.join(REFERENCE_DIR, `${record.id}.md`),
-      renderReferencePage(record),
-    ]),
+    ...records.map((record) => {
+      const relativePath = path.join(REFERENCE_DIR, `${record.id}.md`);
+      return [relativePath, renderReferencePage(record, readManualReferenceSections(relativePath))];
+    }),
   ];
 }