@supportpages.io/wtfm 0.0.0-stage → 0.3.0

package/engine/generate-illustrated-article/package-lock.json

@@ -0,0 +1,366 @@
+{
+  "name": "rtfm-generate-illustrated-article",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "rtfm-generate-illustrated-article",
+      "version": "0.1.0",
+      "dependencies": {
+        "puppeteer": "25.11.0"
+      },
+      "engines": {
+        "node": ">=22.12.0"
+      }
+    },
+    "node_modules/@puppeteer/browsers": {
+      "version": "3.2.2",
+      "resolved": "https://registry.npmjs.org/@puppeteer/browsers/-/browsers-3.2.2.tgz",
+      "integrity": "sha512-q2BU4YfO9h/Wt7IcWPcggpOOqLk2Tbs1hDwolvKZrweRjy751OJBKMN9zO5bfD0pzU7X/tvKw/exQds4pM/LOg==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "modern-tar": "^0.8.4",
+        "yargs": "^18.0.0"
+      },
+      "bin": {
+        "browsers": "lib/main-cli.js"
+      },
+      "engines": {
+        "node": ">=22.12.0"
+      },
+      "peerDependencies": {
+        "proxy-agent": ">=8.0.1",
+        "yauzl": "^2.10.0 || ^3.4.0"
+      },
+      "peerDependenciesMeta": {
+        "proxy-agent": {
+          "optional": true
+        },
+        "yauzl": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/ansi-regex": {
+      "version": "6.3.0",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.3.0.tgz",
+      "integrity": "sha512-WpDfL7NO6j7tH88IDBNVdUJxDh9nmCteAVW9dsep846XdwF4naCBK+/tGLX3KJgcpgMRXCFlTM2hKGoK9FsdrQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-regex?sponsor=1"
+      }
+    },
+    "node_modules/ansi-styles": {
+      "version": "6.2.3",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-6.2.3.tgz",
+      "integrity": "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
+    "node_modules/chromium-bidi": {
+      "version": "17.0.2",
+      "resolved": "https://registry.npmjs.org/chromium-bidi/-/chromium-bidi-17.0.2.tgz",
+      "integrity": "sha512-5v9GQFhTktFvotn/OFNJBmKLKRAb6n9r0bVCwf7sHgWc3/JryK0bj1nn93L3pHFrfgcsu6Be6EWsDi+1XHTGDg==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "mitt": "^3.0.1",
+        "zod": "^3.24.1"
+      },
+      "engines": {
+        "node": ">=20.19.0 <22.0.0 || >=22.12.0"
+      },
+      "peerDependencies": {
+        "devtools-protocol": "*"
+      }
+    },
+    "node_modules/cliui": {
+      "version": "9.0.1",
+      "resolved": "https://registry.npmjs.org/cliui/-/cliui-9.0.1.tgz",
+      "integrity": "sha512-k7ndgKhwoQveBL+/1tqGJYNz097I7WOvwbmmU2AR5+magtbjPWQTS1C5vzGkBC8Ym8UWRzfKUzUUqFLypY4Q+w==",
+      "license": "ISC",
+      "dependencies": {
+        "string-width": "^7.2.0",
+        "strip-ansi": "^7.1.0",
+        "wrap-ansi": "^9.0.0"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/cliui/node_modules/string-width": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-7.2.0.tgz",
+      "integrity": "sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==",
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^10.3.0",
+        "get-east-asian-width": "^1.0.0",
+        "strip-ansi": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/devtools-protocol": {
+      "version": "0.0.1680125",
+      "resolved": "https://registry.npmjs.org/devtools-protocol/-/devtools-protocol-0.0.1680125.tgz",
+      "integrity": "sha512-rVARKAvOFJCFkvgX01VLvYqKIvt+cRCqvUxIhB2oAqVGPalxk3w3sb5TUGDagpow/EFblBpm/Zl/29QA2dd+jA==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/emoji-regex": {
+      "version": "10.6.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-10.6.0.tgz",
+      "integrity": "sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==",
+      "license": "MIT"
+    },
+    "node_modules/escalade": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz",
+      "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/get-caller-file": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz",
+      "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==",
+      "license": "ISC",
+      "engines": {
+        "node": "6.* || 8.* || >= 10.*"
+      }
+    },
+    "node_modules/get-east-asian-width": {
+      "version": "1.7.0",
+      "resolved": "https://registry.npmjs.org/get-east-asian-width/-/get-east-asian-width-1.7.0.tgz",
+      "integrity": "sha512-XjH1AECxf0giL2V1aU8vKyRR2ppRUb5c0EvT7zuJTokQ74bNo52zOtghqdWIqrhUD79fo3x0WfKZdOqxF6LG1Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/lilconfig": {
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/lilconfig/-/lilconfig-3.1.3.tgz",
+      "integrity": "sha512-/vlFKAoH5Cgt3Ie+JLhRbwOsCQePABiU3tJ1egGvyQ+33R/vcwM2Zl2QR/LzjsBeItPt3oSVXapn+m4nQDvpzw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/antonk52"
+      }
+    },
+    "node_modules/mitt": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/mitt/-/mitt-3.0.1.tgz",
+      "integrity": "sha512-vKivATfr97l2/QBCYAkXYDbrIWPM2IIKEl7YPhjCvKlG3kE2gm+uBo6nEXK3M5/Ffh/FLpKExzOQ3JJoJGFKBw==",
+      "license": "MIT"
+    },
+    "node_modules/modern-tar": {
+      "version": "0.8.5",
+      "resolved": "https://registry.npmjs.org/modern-tar/-/modern-tar-0.8.5.tgz",
+      "integrity": "sha512-snEhs+6G5Tjd4I7tLCDOaoln2RgE0bD19RzEKgvgK2hZ5VKy3MpLhLTZ2fWpXSTg4K2cyPwp+VHATFJhxfnOeA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    },
+    "node_modules/puppeteer": {
+      "version": "25.11.0",
+      "resolved": "https://registry.npmjs.org/puppeteer/-/puppeteer-25.11.0.tgz",
+      "integrity": "sha512-n+psxZFH/qlJ3gwTZMxTLUZoE98FAOEjT/BSxHXvPmNCGAfN/kq0UnIZ8m9RB4rAVvJr7zRHUnKKg98GLMUyyQ==",
+      "hasInstallScript": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@puppeteer/browsers": "3.2.2",
+        "chromium-bidi": "17.0.2",
+        "devtools-protocol": "0.0.1680125",
+        "lilconfig": "^3.1.3",
+        "puppeteer-core": "25.11.0",
+        "typed-query-selector": "^2.12.2"
+      },
+      "bin": {
+        "puppeteer": "lib/puppeteer/node/cli.js"
+      },
+      "engines": {
+        "node": ">=22.12.0"
+      }
+    },
+    "node_modules/puppeteer-core": {
+      "version": "25.11.0",
+      "resolved": "https://registry.npmjs.org/puppeteer-core/-/puppeteer-core-25.11.0.tgz",
+      "integrity": "sha512-Ujym7JbxoAqanaxGcHgmTomfhC01HfDCSuGZ8Hs9boHrDjzbNVMnFRJo2KtbDT9LCRgeJoFnkn9JQZ41eEUrLw==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@puppeteer/browsers": "3.2.2",
+        "chromium-bidi": "17.0.2",
+        "devtools-protocol": "0.0.1680125",
+        "typed-query-selector": "^2.12.2",
+        "webdriver-bidi-protocol": "0.4.3",
+        "ws": "^8.21.3"
+      },
+      "engines": {
+        "node": ">=22.12.0"
+      }
+    },
+    "node_modules/string-width": {
+      "version": "8.2.2",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-8.2.2.tgz",
+      "integrity": "sha512-GaPUh5gfdrYzqeVNZvUfT23vYYxXzKYidUcnMtJg/3rxRV63EFZy3k6xfKlmfeJD0176lnUV/Usr3XcwSvFzpg==",
+      "license": "MIT",
+      "dependencies": {
+        "get-east-asian-width": "^1.5.0",
+        "strip-ansi": "^7.1.2"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/strip-ansi": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-7.2.0.tgz",
+      "integrity": "sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^6.2.2"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/strip-ansi?sponsor=1"
+      }
+    },
+    "node_modules/typed-query-selector": {
+      "version": "2.12.2",
+      "resolved": "https://registry.npmjs.org/typed-query-selector/-/typed-query-selector-2.12.2.tgz",
+      "integrity": "sha512-EOPFbyIub4ngnEdqi2yOcNeDLaX/0jcE1JoAXQDDMIthap7FoN795lc/SHfIq2d416VufXpM8z/lD+WRm2gfOQ==",
+      "license": "MIT"
+    },
+    "node_modules/webdriver-bidi-protocol": {
+      "version": "0.4.3",
+      "resolved": "https://registry.npmjs.org/webdriver-bidi-protocol/-/webdriver-bidi-protocol-0.4.3.tgz",
+      "integrity": "sha512-uuN0goWfxP22B7J/uAgBpOYNPttC+XVseYE+rSY5+rQ+YBeVz/VORw8WbmLVcqW78zNg5A4qnjNXYUWR3il2ig==",
+      "license": "Apache-2.0"
+    },
+    "node_modules/wrap-ansi": {
+      "version": "9.0.2",
+      "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-9.0.2.tgz",
+      "integrity": "sha512-42AtmgqjV+X1VpdOfyTGOYRi0/zsoLqtXQckTmqTeybT+BDIbM/Guxo7x3pE2vtpr1ok6xRqM9OpBe+Jyoqyww==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^6.2.1",
+        "string-width": "^7.0.0",
+        "strip-ansi": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+      }
+    },
+    "node_modules/wrap-ansi/node_modules/string-width": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-7.2.0.tgz",
+      "integrity": "sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==",
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^10.3.0",
+        "get-east-asian-width": "^1.0.0",
+        "strip-ansi": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/ws": {
+      "version": "8.21.3",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.3.tgz",
+      "integrity": "sha512-201TZ/kPWxoPr/OKWjquZR1SWKXcvxdH+e1xrx89b3YbmzLMFCLfnaG1HFIgWzJOEWZ7MvpK++odZufgYR50Rw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/y18n": {
+      "version": "5.0.8",
+      "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz",
+      "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/yargs": {
+      "version": "18.2.0",
+      "resolved": "https://registry.npmjs.org/yargs/-/yargs-18.2.0.tgz",
+      "integrity": "sha512-9OpKOLeaoNFecEp7P6iYbzze/5CqWoH7N3SMs/6y1XF4nMvFMspEGZzJ6uFi9MmQwXhyzqYoSEKO3tvA3Z/o2w==",
+      "license": "MIT",
+      "dependencies": {
+        "cliui": "^9.0.1",
+        "escalade": "^3.1.1",
+        "get-caller-file": "^2.0.5",
+        "string-width": "^8.2.1",
+        "y18n": "^5.0.5",
+        "yargs-parser": "^22.0.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=23"
+      }
+    },
+    "node_modules/yargs-parser": {
+      "version": "22.0.0",
+      "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-22.0.0.tgz",
+      "integrity": "sha512-rwu/ClNdSMpkSrUb+d6BRsSkLUq1fmfsY6TOpYzTwvwkg1/NRG85KBy3kq++A8LKQwX6lsu+aWad+2khvuXrqw==",
+      "license": "ISC",
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=23"
+      }
+    },
+    "node_modules/zod": {
+      "version": "3.25.76",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz",
+      "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    }
+  }
+}

package/engine/generate-illustrated-article/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "rtfm-generate-illustrated-article",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Bundled renderer for the generate-illustrated-article skill",
+  "scripts": {
+    "test": "node scripts/test_related_repos.js && node scripts/test_source_paths.js && node scripts/test_label_evidence.js && node scripts/test_control_visibility.js && node scripts/test_generate_content_images.js && node scripts/test_lint_article_copy.js && node scripts/test_lint_mockup_fidelity.js && node scripts/test_render_ready.js && node scripts/test_polish_tickets.js && node scripts/test_include_census.js && node scripts/test_emit_walkthrough_signals.js && node scripts/test_node_ports.js"
+  },
+  "dependencies": {
+    "puppeteer": "25.11.0"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  }
+}

package/engine/generate-illustrated-article/scripts/article_blocks.js

@@ -0,0 +1,34 @@
+const ARTICLE_TYPES = ['how-to', 'troubleshooting', 'concept', 'faq'];
+const PRESENTATIONS = {
+    prose: ['lead', 'body', 'summary'],
+    section: ['numbered', 'plain'],
+    list: ['bullets', 'checklist', 'tips'],
+};
+
+function blocks(article) {
+    if (article && article.schema_version === 2 && Array.isArray(article.blocks)) return article.blocks;
+
+    const result = [];
+    if (article && article.introduction) result.push({ id: 'introduction', type: 'prose', presentation: 'lead', content: article.introduction });
+    if (Array.isArray(article && article.prerequisites) && article.prerequisites.length) {
+        result.push({ id: 'prerequisites', type: 'list', presentation: 'checklist', title: 'Prerequisites', items: article.prerequisites });
+    }
+    for (const [index, step] of ((article && article.steps) || []).entries()) {
+        result.push({ id: `step-${index + 1}`, type: 'section', presentation: 'numbered', ...step });
+    }
+    if (Array.isArray(article && article.tips) && article.tips.length) {
+        result.push({ id: 'tips', type: 'list', presentation: 'tips', title: 'Tips', items: article.tips });
+    }
+    if (article && article.summary) result.push({ id: 'summary', type: 'prose', presentation: 'summary', title: 'Summary', content: article.summary });
+    return result;
+}
+
+function sections(article) {
+    return blocks(article).filter(block => block.type === 'section');
+}
+
+function articleType(article) {
+    return ARTICLE_TYPES.includes(article && article.article_type) ? article.article_type : 'how-to';
+}
+
+module.exports = { ARTICLE_TYPES, PRESENTATIONS, blocks, sections, articleType };

package/engine/generate-illustrated-article/scripts/check_article_json.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * check_article_json.js — validate the shape of a schema_version 2 article.json
+ * before illustration (Phase 2 flips has_image later, so this checks shape only).
+ *
+ * Usage: node check_article_json.js <article.json>
+ * Exits 0 when valid, 1 with one problem per line.
+ */
+
+const fs = require('fs');
+
+const ARTICLE_TYPES = ['how-to', 'troubleshooting', 'concept', 'faq'];
+const PRESENTATIONS = {
+    prose: ['lead', 'body', 'summary'],
+    section: ['numbered', 'plain'],
+    list: ['bullets', 'checklist', 'tips'],
+};
+const BLOCK_ID = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const CODE_FENCE = /```|~~~/;
+
+const isString = value => typeof value === 'string';
+
+/** String form of a value, as a JSON round-trip would render it inside a list. */
+function asText(value) {
+    return isString(value) ? value : JSON.stringify(value);
+}
+
+function check(article) {
+    const problems = [];
+    if (article === null || typeof article !== 'object' || Array.isArray(article)) return ['article.json must be a JSON object'];
+    if (article.schema_version !== 2) problems.push('schema_version must be 2');
+    if (!isString(article.title) || !article.title.length) problems.push('title must be a non-empty string');
+    if (!ARTICLE_TYPES.includes(article.article_type)) problems.push(`article_type must be one of ${ARTICLE_TYPES.join(', ')}`);
+
+    const blocks = article.blocks;
+    if (!Array.isArray(blocks) || !blocks.length) {
+        problems.push('blocks must be a non-empty array');
+        return problems;
+    }
+
+    const ids = blocks.map(block => (block && typeof block === 'object' ? block.id : undefined));
+    const seen = new Set();
+    for (const id of ids) {
+        const key = JSON.stringify(id ?? null);
+        if (seen.has(key)) problems.push(`duplicate block id ${key}`);
+        seen.add(key);
+    }
+
+    blocks.forEach((block, i) => {
+        const at = `blocks[${i}]${block && isString(block.id) ? ` (${block.id})` : ''}`;
+        if (!block || typeof block !== 'object' || Array.isArray(block)) {
+            problems.push(`${at} must be an object`);
+            return;
+        }
+        if (!isString(block.id) || !BLOCK_ID.test(block.id)) problems.push(`${at}.id must be lowercase words joined by hyphens`);
+
+        const allowed = PRESENTATIONS[block.type];
+        if (!allowed) {
+            problems.push(`${at}.type must be prose, section or list`);
+            return;
+        }
+        if (!allowed.includes(block.presentation)) problems.push(`${at}.presentation must be one of ${allowed.join(', ')} for ${block.type}`);
+
+        if (block.type === 'prose') {
+            if (!isString(block.content)) problems.push(`${at}.content must be a string`);
+            if (block.presentation === 'lead' && CODE_FENCE.test(asText(block.content ?? ''))) problems.push(`${at}: the lead must not contain a code fence`);
+        } else if (block.type === 'section') {
+            if (!isString(block.title)) problems.push(`${at}.title must be a string`);
+            if (!isString(block.content)) problems.push(`${at}.content must be a string`);
+            if (typeof block.has_image !== 'boolean') problems.push(`${at}.has_image must be a boolean`);
+        } else if (block.type === 'list') {
+            if (!isString(block.title)) problems.push(`${at}.title must be a string`);
+            if (!Array.isArray(block.items)) problems.push(`${at}.items must be an array`);
+            else if (block.items.some(item => CODE_FENCE.test(asText(item)))) problems.push(`${at}: list items must not contain code fences`);
+        }
+    });
+    return problems;
+}
+
+function main(argv) {
+    const [file] = argv;
+    if (!file) {
+        process.stderr.write('Usage: check_article_json.js <article.json>\n');
+        return 2;
+    }
+    let article;
+    try { article = JSON.parse(fs.readFileSync(file, 'utf8')); }
+    catch (error) {
+        process.stderr.write(`${file}: ${error.message}\n`);
+        return 1;
+    }
+    const problems = check(article);
+    if (problems.length) {
+        process.stderr.write(`${file} is not a valid article:\n${problems.map(p => `  - ${p}`).join('\n')}\n`);
+        return 1;
+    }
+    process.stdout.write(`${file} OK\n`);
+    return 0;
+}
+
+if (require.main === module) process.exitCode = main(process.argv.slice(2));
+
+module.exports = { check };

package/engine/generate-illustrated-article/scripts/emit_walkthrough_signals.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+'use strict';
+
+// Distills walkthrough-worthiness signals from a generated article's artifacts
+// (article.json + view_sources.json) into $OUT/walkthrough_signals.json.
+// Consumed later by the recommend-walkthroughs skill via the RTFM context file.
+// Informational, never a lint: any missing or unparsable input logs a warning
+// and exits 0 without writing, so the article pipeline can never fail here.
+
+const fs = require('fs');
+const path = require('path');
+const { blocks, articleType } = require('./article_blocks.js');
+
+// Interaction kinds record_walkthrough.js cannot perform (supported: click,
+// type-into, select, check, swipe, hover, scroll-to).
+const UNSUPPORTED_KINDS = new Set(['drag', 'upload', 'keyboard']);
+
+function readJson(file) {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function atomicWrite(file, value) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const temporary = `${file}.tmp-${process.pid}`;
+    fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`);
+    fs.renameSync(temporary, file);
+}
+
+function detectAppType(projectRoot) {
+    for (const dir of ['.rtfm', '.rtfm-branding']) {
+        try {
+            const map = readJson(path.join(projectRoot, dir, 'project_map.json'));
+            if (map && typeof map.app_type === 'string') return map.app_type;
+        } catch (error) { /* missing or unparsable map — fall through */ }
+    }
+    return 'web';
+}
+
+function computeSignals(article, viewSources, appType) {
+    const sections = blocks(article).filter(block => block && block.type === 'section');
+
+    // view_sources step containers: block-keyed `blocks[]` (schema v2 articles)
+    // or index-keyed `steps[]` (legacy). External-surface entries carry
+    // `external_surface` and no primary_view.
+    const entries = Array.isArray(viewSources && viewSources.blocks) ? viewSources.blocks
+        : Array.isArray(viewSources && viewSources.steps) ? viewSources.steps : [];
+    const surfaces = new Set();
+    let externalSurfaces = 0;
+    for (const entry of entries) {
+        if (!entry || typeof entry !== 'object') continue;
+        if (entry.external_surface) externalSurfaces += 1;
+        else if (typeof entry.primary_view === 'string' && entry.primary_view.trim()) {
+            surfaces.add(entry.primary_view.trim());
+        }
+    }
+
+    const coverage = Array.isArray(viewSources && viewSources.action_coverage)
+        ? viewSources.action_coverage.filter(item => item && typeof item === 'object') : [];
+    const kinds = [...new Set(coverage.map(item => item.kind).filter(kind => typeof kind === 'string' && kind))].sort();
+
+    return {
+        schema_version: 1,
+        article_type: articleType(article),
+        sections_total: sections.length,
+        sections_with_images: sections.filter(section => section.has_image === true).length,
+        distinct_surfaces: surfaces.size,
+        action_count: coverage.length,
+        action_kinds: kinds,
+        typed_input: kinds.includes('type'),
+        unsupported_action_kinds: kinds.filter(kind => UNSUPPORTED_KINDS.has(kind)),
+        external_surfaces: externalSurfaces,
+        app_type: appType,
+    };
+}
+
+function main() {
+    const outDir = process.argv[2];
+    if (!outDir) {
+        console.error('usage: emit_walkthrough_signals.js OUT_DIR');
+        process.exitCode = 2;
+        return;
+    }
+    let article;
+    let viewSources;
+    try {
+        article = readJson(path.join(outDir, 'article.json'));
+        viewSources = readJson(path.join(outDir, 'view_sources.json'));
+    } catch (error) {
+        console.error(`walkthrough signals skipped: ${error.message}`);
+        return;
+    }
+    const signals = computeSignals(article, viewSources, detectAppType(process.cwd()));
+    atomicWrite(path.join(outDir, 'walkthrough_signals.json'), signals);
+    console.log(`walkthrough signals: ${signals.distinct_surfaces} surfaces, `
+        + `${signals.action_count} actions (${signals.action_kinds.join(', ') || 'none'})`);
+}
+
+module.exports = { UNSUPPORTED_KINDS, computeSignals, detectAppType };
+
+if (require.main === module) main();