@supportpages.io/wtfm 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+/**
+ * Prepare and publish one article screenshot as soon as its mockup is ready.
+ *
+ * The injector mutates step HTML in place, while later steps need the original
+ * source (including <!-- INJECT_CSS --> and image tokens) for clone-and-edit.
+ * This helper snapshots every authored step, injects the current set, validates
+ * and renders one requested step, then restores all source HTML. The PNG is
+ * rendered to a temporary path and renamed only after the quality, evidence,
+ * and geometry gates pass, so observers never consume a half-written asset.
+ *
+ * Usage: render_ready.js <article_dir> <step_index> [project_root]
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { puppeteer, launchOptions, renderOnBrowser, probeStringsFor } = require('./render_mockup.js');
+
+function existingPath(candidates) {
+    return candidates.find(candidate => fs.existsSync(candidate));
+}
+
+function evidenceForStep(articleDir, location) {
+    try {
+        const viewSources = JSON.parse(
+            fs.readFileSync(path.join(articleDir, 'view_sources.json'), 'utf8')
+        );
+        const entries = viewSources.blocks || viewSources.steps || [];
+        const step = entries.find(item => item.block_id === location || Number(item.index) === Number(location));
+        return (step && step.verbatim_evidence || [])
+            .map(item => typeof item === 'string' ? item : (item && item.string) || '')
+            .filter(Boolean);
+    } catch {
+        return [];
+    }
+}
+
+function run(command, args, options = {}) {
+    const result = spawnSync(command, args, {
+        encoding: 'utf8',
+        maxBuffer: 10 * 1024 * 1024,
+        ...options,
+    });
+    if (result.stdout) process.stdout.write(result.stdout);
+    if (result.stderr) process.stderr.write(result.stderr);
+    if (result.error) throw result.error;
+    if (result.status !== 0) {
+        throw new Error(`${path.basename(command)} exited with status ${result.status}`);
+    }
+    return result;
+}
+
+async function main() {
+    const articleDir = path.resolve(process.argv[2] || '');
+    const rawIndex = process.argv[3];
+    const projectRoot = path.resolve(process.argv[4] || process.cwd());
+    if (!articleDir || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(rawIndex || '') || !fs.existsSync(articleDir)) {
+        throw new Error('Usage: render_ready.js <article_dir> <block_id|step_index> [project_root]');
+    }
+
+    const legacy = /^\d+$/.test(rawIndex);
+    const index = legacy ? Number(rawIndex) : null;
+    const stepName = legacy ? `step_${index}` : `block_${rawIndex}`;
+    const htmlPath = path.join(articleDir, `${stepName}.html`);
+    const finalPng = path.join(articleDir, `${stepName}.png`);
+    const finalDiagnostics = path.join(articleDir, `${stepName}_diagnostics.json`);
+    if (!fs.existsSync(htmlPath)) throw new Error(`Missing ${htmlPath}`);
+
+    const authoredHtml = fs.readdirSync(articleDir)
+        .filter(name => /^(?:step_\d+|block_[a-z0-9]+(?:-[a-z0-9]+)*)\.html$/.test(name))
+        .map(name => path.join(articleDir, name));
+    const originals = new Map(
+        authoredHtml.map(file => [file, fs.readFileSync(file, 'utf8')])
+    );
+
+    const brandDir = existingPath([
+        path.join(projectRoot, '.rtfm', 'branding.json'),
+        path.join(projectRoot, '.rtfm-branding', 'branding.json'),
+    ]);
+    const brandingJson = brandDir || null;
+    const brandingCss = brandingJson
+        ? path.join(path.dirname(brandingJson), 'branding.css')
+        : null;
+    if (brandingCss && fs.existsSync(brandingCss)) {
+        fs.copyFileSync(brandingCss, path.join(articleDir, 'branding.css'));
+    }
+
+    const imagesJson = existingPath([
+        path.join(projectRoot, '.rtfm', 'images_base64.json'),
+        path.join(projectRoot, '.rtfm-branding', 'images_base64.json'),
+    ]) || path.join(projectRoot, '.rtfm', 'images_base64.json');
+    const generatedImages = path.join(articleDir, 'generated_images.json');
+    const injectArgs = [
+        path.join(__dirname, 'inject_assets.js'), articleDir, '', imagesJson,
+    ];
+    if (brandingJson) injectArgs.push('--branding', brandingJson);
+    if (fs.existsSync(generatedImages)) {
+        injectArgs.push('--generated-images', generatedImages);
+    }
+    injectArgs.push('--refresh-jit');
+
+    const tempPng = path.join(articleDir, `.${stepName}.rendering-${process.pid}.png`);
+    const tempDiagnostics = tempPng.replace(/\.png$/, '_diagnostics.json');
+    let browser;
+    try {
+        run(process.execPath, injectArgs, { cwd: projectRoot });
+
+        const validation = spawnSync(process.execPath, [
+            path.join(__dirname, 'validate_html.js'), htmlPath,
+        ], { encoding: 'utf8', maxBuffer: 1024 * 1024 });
+        const validationText = `${validation.stdout || ''}${validation.stderr || ''}`;
+        fs.writeFileSync(path.join(articleDir, `${stepName}_validation.json`), validationText);
+        if (validation.error) throw validation.error;
+        if (validation.status !== 0) {
+            throw new Error(`${stepName}.html is not ready: HTML validation failed`);
+        }
+
+        const evidence = evidenceForStep(articleDir, legacy ? index : rawIndex);
+        let viewSources = null;
+        try { viewSources = JSON.parse(fs.readFileSync(path.join(articleDir, 'view_sources.json'), 'utf8')); } catch { /* optional */ }
+        const probe = probeStringsFor(projectRoot, viewSources, legacy ? index : rawIndex, evidence);
+        browser = await puppeteer.launch(launchOptions());
+        const started = Date.now();
+        const diagnostics = await renderOnBrowser(browser, tempPng, htmlPath, { evidence, probe });
+        const quality = diagnostics.qualityScore || {};
+        const invisibleEvidence = ((diagnostics.metrics || {}).evidenceVisibility || [])
+            .filter(item => !item.visible).map(item => item.string);
+        const evidenceChecked = ((diagnostics.metrics || {}).evidenceVisibility || []).length;
+        const geometryErrors = (((diagnostics.metrics || {}).regionGeometry || {}).errors || []);
+
+        if (quality.rating === 'poor') {
+            throw new Error(`${stepName} rendered POOR (score ${quality.score})`);
+        }
+        if (evidenceChecked && invisibleEvidence.length * 2 > evidenceChecked) {
+            throw new Error(`${stepName} hides ${invisibleEvidence.length}/${evidenceChecked} evidence strings`);
+        }
+        if (geometryErrors.length) {
+            throw new Error(`${stepName} violates runtime geometry: ${geometryErrors.join('; ')}`);
+        }
+
+        fs.renameSync(tempPng, finalPng);
+        fs.renameSync(tempDiagnostics, finalDiagnostics);
+        fs.writeFileSync(path.join(articleDir, `${stepName}_progress.json`), JSON.stringify({
+            ...(legacy ? { step_index: index } : { block_id: rawIndex }),
+            published: true,
+            render_ms: Date.now() - started,
+            quality: quality.rating,
+            score: quality.score,
+        }, null, 2));
+        console.log(`Published ${path.basename(finalPng)} progressively (quality: ${quality.rating}, ${quality.score})`);
+    } finally {
+        if (browser) await browser.close();
+        for (const [file, contents] of originals) fs.writeFileSync(file, contents);
+        for (const temporary of [tempPng, tempDiagnostics]) {
+            try { fs.unlinkSync(temporary); } catch { /* already published or absent */ }
+        }
+    }
+}
+
+main().catch(error => {
+    console.error(`render_ready failed: ${error.message}`);
+    process.exit(1);
+});

package/engine/generate-illustrated-article/scripts/resolve_workspace.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# Recover the project workspace when a shell tool starts in a non-project
+# directory (Antigravity scratch, $HOME, …). The CLI process was launched in
+# the target repo — walk parent pids until we find a directory that looks like
+# a project (.git or .rtfm). No project-specific paths.
+#
+# Prefer $RTFM_WORKSPACE when the harness already set it.
+# Prints one absolute path to stdout. Always exits 0.
+# bash 3.2 / macOS + Linux.
+
+if [ -n "$RTFM_WORKSPACE" ] && [ -d "$RTFM_WORKSPACE" ]; then
+  (cd "$RTFM_WORKSPACE" && pwd -P)
+  exit 0
+fi
+
+scratch_default="${HOME}/.gemini/antigravity-cli/scratch"
+here=$(pwd -P 2>/dev/null || pwd)
+home_real=$(cd "$HOME" && pwd -P 2>/dev/null || true)
+
+is_scratch() {
+  local p="$1" s
+  [ -n "$p" ] || return 1
+  [ -d "$scratch_default" ] || return 1
+  s=$(cd "$scratch_default" && pwd -P 2>/dev/null) || return 1
+  [ "$p" = "$s" ]
+}
+
+is_home() {
+  [ -n "$home_real" ] && [ "$1" = "$home_real" ]
+}
+
+looks_like_project() {
+  [ -d "$1/.git" ] || [ -d "$1/.rtfm" ]
+}
+
+is_untrusted() {
+  is_scratch "$1" && return 0
+  is_home "$1" && return 0
+  looks_like_project "$1" && return 1
+  return 0
+}
+
+pid_cwd() {
+  local pid="$1" cand=""
+  [ -n "$pid" ] || return 1
+  [ "$pid" -gt 1 ] 2>/dev/null || return 1
+  if command -v lsof >/dev/null 2>&1; then
+    cand=$(lsof -a -p "$pid" -d cwd -Fn 2>/dev/null | awk '/^n\// {print substr($0,2); exit}')
+  fi
+  if [ -z "$cand" ] && [ -L "/proc/$pid/cwd" ]; then
+    cand=$(readlink "/proc/$pid/cwd" 2>/dev/null || true)
+  fi
+  [ -n "$cand" ] && [ -d "$cand" ] || return 1
+  (cd "$cand" && pwd -P)
+}
+
+if ! is_untrusted "$here"; then
+  printf '%s\n' "$here"
+  exit 0
+fi
+
+pid=${PPID:-$$}
+i=0
+found=""
+while [ "$i" -lt 12 ]; do
+  cand=$(pid_cwd "$pid" || true)
+  if [ -n "$cand" ] && ! is_untrusted "$cand"; then
+    printf '%s\n' "$cand"
+    exit 0
+  fi
+  if [ -z "$found" ] && [ -n "$cand" ] && ! is_scratch "$cand" && ! is_home "$cand"; then
+    found=$cand
+  fi
+  next=$(ps -o ppid= -p "$pid" 2>/dev/null | tr -d ' ')
+  [ -n "$next" ] && [ "$next" != "$pid" ] && [ "$next" -gt 1 ] 2>/dev/null || break
+  pid=$next
+  i=$((i + 1))
+done
+
+if [ -n "$found" ]; then
+  printf '%s\n' "$found"
+  exit 0
+fi
+
+printf '%s\n' "$here"
+exit 0

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

@@ -0,0 +1,55 @@
+'use strict';
+
+// This function is deliberately self-contained: Puppeteer serialises it into
+// the browser for page.evaluate(). Keep every helper inside the function so the
+// article renderer and walkthrough recorder measure the exact same contract.
+function measureRuntimeRegionGeometry() {
+    const nodes = [...document.querySelectorAll('[data-rtfm-region]')];
+    if (!nodes.length) return { checked: false, regions: [], errors: [] };
+    const vw = window.innerWidth;
+    const vh = window.innerHeight;
+    const regions = nodes.map(el => {
+        const r = el.getBoundingClientRect();
+        return {
+            id: el.getAttribute('data-rtfm-region'),
+            placement: el.getAttribute('data-rtfm-placement') || '',
+            left: r.left, top: r.top, right: r.right, bottom: r.bottom,
+            width: r.width, height: r.height, area: r.width * r.height,
+        };
+    });
+    const errors = [];
+    const canvas = regions.find(r => r.placement === 'canvas');
+    const nonOverlays = regions.filter(r => !r.placement.startsWith('overlay-'));
+    if (canvas && nonOverlays.some(r => r.id !== canvas.id && r.area > canvas.area)) {
+        errors.push(`canvas region '${canvas.id}' is not the dominant non-overlay region`);
+    }
+    const overlapArea = (a, b) => Math.max(0, Math.min(a.right, b.right) - Math.max(a.left, b.left))
+        * Math.max(0, Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top));
+    for (const r of regions) {
+        if (r.width <= 1 || r.height <= 1) {
+            errors.push(`region '${r.id}' is collapsed`);
+            continue;
+        }
+        if (r.placement === 'top' && (r.top > vh * 0.3 || r.width < vw * 0.45))
+            errors.push(`top region '${r.id}' is not positioned across the upper screen`);
+        if (r.placement === 'bottom' && r.bottom < vh * 0.7)
+            errors.push(`bottom region '${r.id}' is not positioned near the lower screen`);
+        if (r.placement === 'left' && (r.left > vw * 0.25 || (r.left + r.right) / 2 >= vw * 0.5))
+            errors.push(`left region '${r.id}' is not anchored on the left`);
+        if (r.placement === 'right' && (r.right < vw * 0.75 || (r.left + r.right) / 2 <= vw * 0.5))
+            errors.push(`right region '${r.id}' is not anchored on the right`);
+        if (r.placement.startsWith('overlay-')) {
+            if (!canvas || overlapArea(r, canvas) < r.area * 0.2)
+                errors.push(`overlay region '${r.id}' does not visibly overlap the canvas`);
+            if (r.placement === 'overlay-left' && (r.left + r.right) / 2 >= vw * 0.5)
+                errors.push(`overlay-left region '${r.id}' is on the wrong side`);
+            if (r.placement === 'overlay-right' && (r.left + r.right) / 2 <= vw * 0.5)
+                errors.push(`overlay-right region '${r.id}' is on the wrong side`);
+            if (r.placement === 'overlay-bottom' && r.bottom < vh * 0.65)
+                errors.push(`overlay-bottom region '${r.id}' is not bottom-anchored`);
+        }
+    }
+    return { checked: true, viewport: { width: vw, height: vh }, regions, errors };
+}
+
+module.exports = { measureRuntimeRegionGeometry };

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

@@ -0,0 +1,49 @@
+// Cited source paths: project-relative, or `../<sibling>/<path>` into another
+// checkout of a multi-repo product. Siblings are only reachable when the
+// harness set RTFM_REPOS_ROOT and the project directory sits directly inside
+// it (see related_repos.sh) — interactive single-repo runs keep the strict
+// project-relative rule. The resolved file must stay inside its checkout.
+const fs = require('fs');
+const path = require('path');
+
+function reposRoot() {
+    const root = process.env.RTFM_REPOS_ROOT;
+    return typeof root === 'string' && root.trim() ? root : null;
+}
+
+// Syntactic check, no filesystem: a plain relative path, or (with
+// RTFM_REPOS_ROOT set) exactly one leading `..` followed by a sibling name.
+function isSafeSourcePath(value) {
+    if (typeof value !== 'string' || !value.trim() || path.isAbsolute(value)) return false;
+    const parts = value.split(/[\\/]/);
+    if (!parts.includes('..')) return true;
+    return Boolean(reposRoot()) && parts[0] === '..' && parts.length > 2 &&
+        Boolean(parts[1]) && parts[1] !== '.' && !parts.slice(1).includes('..');
+}
+
+// Absolute real path of a cited file, or throws. Sibling citations must land
+// in a git checkout that is a direct child of RTFM_REPOS_ROOT, next to the
+// project directory.
+function resolveSourcePath(projectDir, file) {
+    if (!isSafeSourcePath(file)) throw Error('cite a project-relative source file (or ../<repo>/<path> for a related repository)');
+    const base = fs.realpathSync(projectDir);
+    const parts = file.split(/[\\/]/);
+    let checkout = base;
+    if (parts[0] === '..') {
+        const root = fs.realpathSync(reposRoot());
+        if (path.dirname(base) !== root) throw Error('related repositories are only reachable from a checkout inside RTFM_REPOS_ROOT');
+        checkout = fs.realpathSync(path.join(root, parts[1]));
+        if (path.dirname(checkout) !== root || checkout === base || !fs.existsSync(path.join(checkout, '.git'))) {
+            throw Error(`${parts[0]}/${parts[1]} is not a related repository`);
+        }
+    }
+    const resolved = fs.realpathSync(path.join(base, file));
+    if (!resolved.startsWith(checkout + path.sep)) throw Error('source resolves outside the project');
+    return resolved;
+}
+
+function sourceExists(projectDir, file) {
+    try { resolveSourcePath(projectDir, file); return true; } catch { return false; }
+}
+
+module.exports = { isSafeSourcePath, resolveSourcePath, sourceExists };

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

@@ -0,0 +1,30 @@
+const assert = require('assert');
+const {puppeteer, launchOptions, measureStringVisibility} = require('./render_mockup');
+(async () => {
+    const browser = await puppeteer.launch(launchOptions());
+    try {
+        const page = await browser.newPage();
+        await page.setViewport({width:800,height:600});
+        await page.setContent(`<style>button,input{width:140px;height:35px}</style>
+            <button>Text button</button><input type="submit" value="Create API key">
+            <input type="button" value="Input button"><input type="reset" value="Reset fields">
+            <button aria-label="Admin menu"><svg width="20" height="20"><rect width="20" height="20"/></svg></button>
+            <span id="control-label" hidden>Named control</span><button aria-labelledby="control-label">⚙</button>
+            <a data-rtfm-action-target="open-menu" aria-label="Scripted menu"><svg width="20" height="20"><rect width="20" height="20"/></svg></a>
+            <input type="hidden" value="Hidden value"><input type="password" value="Secret value">
+            <div aria-label="Not a control" style="width:80px;height:30px"></div>
+            <button style="display:none" aria-label="Hidden control"></button>
+            <div style="opacity:0"><input type="submit" value="Transparent submit"></div>
+            <div style="overflow:hidden;height:0"><button aria-label="Clipped control"></button></div>
+            <input type="submit" value="Below crop" style="position:absolute;top:1000px">
+            <input type="submit" value="Right of crop" style="position:absolute;left:1000px">
+            <button style="visibility:hidden">Invisible text</button>`);
+        const visible = ['Text button','Create API key','Input button','Reset fields','Admin menu','Named control','Scripted menu'];
+        const hidden = ['Hidden value','Secret value','Not a control','Hidden control','Transparent submit','Clipped control','Below crop','Right of crop','Invisible text','Absent'];
+        const results = await measureStringVisibility(page,[...visible,...hidden],600,800);
+        for (const item of results) assert.equal(item.visible,visible.includes(item.string),JSON.stringify(item));
+        assert.equal(results.find(r => r.string === 'Create API key').match_kind, 'input_value');
+        assert.equal(results.find(r => r.string === 'Admin menu').match_kind, 'accessible_control');
+        console.log('Text, input values and named-control visibility tests passed');
+    } finally { await browser.close(); }
+})().catch(error => { console.error(error); process.exitCode=1; });

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

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { computeSignals } = require('./emit_walkthrough_signals.js');
+
+const SCRIPT = path.join(__dirname, 'emit_walkthrough_signals.js');
+
+function articleV2(overrides = {}) {
+    return {
+        schema_version: 2,
+        title: 'How to invite a teammate',
+        article_type: 'how-to',
+        blocks: [
+            { id: 'intro', type: 'prose', presentation: 'lead', content: 'Invite teammates.' },
+            { id: 'open-settings', type: 'section', presentation: 'numbered', title: 'Open settings', content: 'Click **Settings**.', has_image: true },
+            { id: 'enter-email', type: 'section', presentation: 'numbered', title: 'Enter the email', content: 'Type the address.', has_image: true },
+            { id: 'confirm', type: 'section', presentation: 'numbered', title: 'Confirm', content: 'Click **Send**.', has_image: false },
+        ],
+        ...overrides,
+    };
+}
+
+function viewSourcesBlocks(overrides = {}) {
+    return {
+        framework: 'rails',
+        action_coverage: [
+            { article_block_id: 'open-settings', screenshot_block_id: 'open-settings', kind: 'click', target: 'Settings', state: 'action-ready' },
+            { article_block_id: 'enter-email', screenshot_block_id: 'enter-email', kind: 'type', target: 'Email', state: 'action-ready' },
+        ],
+        blocks: [
+            { block_id: 'open-settings', primary_view: 'app/views/settings/index.html.erb' },
+            { block_id: 'enter-email', primary_view: 'app/views/settings/invites.html.erb' },
+        ],
+        ...overrides,
+    };
+}
+
+function articleLegacy() {
+    return {
+        title: 'How to invite a teammate',
+        article_type: 'how-to',
+        introduction: 'Invite teammates.',
+        prerequisites: [],
+        steps: [
+            { title: 'Open settings', content: 'Click **Settings**.', has_image: true },
+            { title: 'Enter the email', content: 'Type the address.', has_image: false },
+        ],
+        tips: [],
+        summary: 'Done.',
+    };
+}
+
+function viewSourcesSteps() {
+    return {
+        framework: 'rails',
+        action_coverage: [
+            { article_step_index: 0, screenshot_step_index: 0, kind: 'click', target: 'Settings', state: 'action-ready' },
+        ],
+        steps: [
+            { index: 0, primary_view: 'app/views/settings/index.html.erb' },
+            { index: 1, primary_view: 'app/views/settings/index.html.erb' },
+        ],
+    };
+}
+
+function run() {
+    // Block-keyed schema-v2 artifacts.
+    let signals = computeSignals(articleV2(), viewSourcesBlocks(), 'web');
+    assert.deepStrictEqual(signals, {
+        schema_version: 1,
+        article_type: 'how-to',
+        sections_total: 3,
+        sections_with_images: 2,
+        distinct_surfaces: 2,
+        action_count: 2,
+        action_kinds: ['click', 'type'],
+        typed_input: true,
+        unsupported_action_kinds: [],
+        external_surfaces: 0,
+        app_type: 'web',
+    });
+
+    // Legacy index-keyed artifacts (article_blocks.js synthesizes sections).
+    signals = computeSignals(articleLegacy(), viewSourcesSteps(), 'web');
+    assert.strictEqual(signals.sections_total, 2);
+    assert.strictEqual(signals.sections_with_images, 1);
+    assert.strictEqual(signals.distinct_surfaces, 1);
+    assert.strictEqual(signals.action_count, 1);
+    assert.strictEqual(signals.typed_input, false);
+
+    // External-surface entries count separately and never contribute a surface.
+    signals = computeSignals(articleV2(), viewSourcesBlocks({
+        blocks: [
+            { block_id: 'open-settings', primary_view: 'app/views/settings/index.html.erb' },
+            { block_id: 'enter-email', url_or_route: 'external:confirmation-email',
+                external_surface: { asset_id: 'confirmation-email', surface: 'email' } },
+        ],
+    }), 'web');
+    assert.strictEqual(signals.external_surfaces, 1);
+    assert.strictEqual(signals.distinct_surfaces, 1);
+
+    // Recorder-unsupported kinds are surfaced; the supported set is not.
+    signals = computeSignals(articleV2(), viewSourcesBlocks({
+        action_coverage: [
+            { article_block_id: 'open-settings', kind: 'drag', target: 'Card', state: 'action-ready' },
+            { article_block_id: 'enter-email', kind: 'upload', target: 'Attach', state: 'action-ready' },
+            { article_block_id: 'confirm', kind: 'toggle', target: 'Notify', state: 'action-ready' },
+        ],
+    }), 'mobile');
+    assert.deepStrictEqual(signals.unsupported_action_kinds, ['drag', 'upload']);
+    assert.strictEqual(signals.app_type, 'mobile');
+
+    // Tolerates absent action_coverage / malformed entries (pre-v1.41 artifacts).
+    signals = computeSignals(articleLegacy(), { framework: 'rails', steps: [null, { index: 1 }] }, 'web');
+    assert.strictEqual(signals.action_count, 0);
+    assert.deepStrictEqual(signals.action_kinds, []);
+    assert.strictEqual(signals.distinct_surfaces, 0);
+
+    // CLI: writes the sidecar for a valid artifact dir.
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'rtfm-walkthrough-signals-'));
+    try {
+        fs.writeFileSync(path.join(root, 'article.json'), JSON.stringify(articleV2()));
+        fs.writeFileSync(path.join(root, 'view_sources.json'), JSON.stringify(viewSourcesBlocks()));
+        let cli = spawnSync(process.execPath, [SCRIPT, root], { encoding: 'utf8' });
+        assert.strictEqual(cli.status, 0, cli.stderr);
+        const written = JSON.parse(fs.readFileSync(path.join(root, 'walkthrough_signals.json'), 'utf8'));
+        assert.strictEqual(written.schema_version, 1);
+        assert.strictEqual(written.distinct_surfaces, 2);
+
+        // CLI: missing view_sources.json is a warning + exit 0, no file written.
+        const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'rtfm-walkthrough-signals-'));
+        try {
+            fs.writeFileSync(path.join(empty, 'article.json'), JSON.stringify(articleV2()));
+            cli = spawnSync(process.execPath, [SCRIPT, empty], { encoding: 'utf8' });
+            assert.strictEqual(cli.status, 0, cli.stderr);
+            assert.match(cli.stderr, /walkthrough signals skipped/);
+            assert.strictEqual(fs.existsSync(path.join(empty, 'walkthrough_signals.json')), false);
+        } finally {
+            fs.rmSync(empty, { recursive: true, force: true });
+        }
+
+        // CLI: no argument is a usage error.
+        cli = spawnSync(process.execPath, [SCRIPT], { encoding: 'utf8' });
+        assert.strictEqual(cli.status, 2);
+    } finally {
+        fs.rmSync(root, { recursive: true, force: true });
+    }
+
+    console.log('walkthrough signals tests passed');
+}
+
+run();