@supportpages.io/wtfm 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+/**
+ * jit_mockup_css.js — Render-time local Tailwind JIT.
+ *
+ * The project's compiled branding.css is Tailwind-purged (it contains only the
+ * classes the REAL app uses), so a mockup's own authored classes — arbitrary
+ * values (`size-[18px]`), responsive variants (`lg:grid-cols-3`), plugin/component
+ * classes — usually aren't in it. That's why inject_assets otherwise falls back to
+ * the Tailwind Play CDN, which is unreliable in the headless Puppeteer render.
+ *
+ * This script instead compiles Tailwind LOCALLY against the MOCKUP HTML as the
+ * content source, using the project's cached `css_build` recipe (its real entry +
+ * config + plugins, so the theme/brand tokens apply) — producing exactly the
+ * classes the mockups use. Output: <out_dir>/mockup.css. inject_assets.js links it
+ * and drops the Play CDN when present.
+ *
+ * Usage: node jit_mockup_css.js <out_dir> <project_dir> <project_map.json>
+ * Exit:  0 = mockup.css written; 3 = skipped (no usable recipe / not tailwind);
+ *        1 = attempted but the local compile failed.
+ * SAFETY: on any skip/failure the caller keeps its current CDN/fallback behaviour,
+ * so this never regresses the pipeline.
+ */
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+function log(m) { console.error('  jit: ' + m); }
+function skip(m) { log(m); process.exit(3); }
+function fail(m) { log(m); process.exit(1); }
+
+let [outDir, projectDir, projectMapPath] = process.argv.slice(2);
+if (!outDir || !projectDir) skip('missing args (out_dir project_dir project_map.json)');
+if (!fs.existsSync(outDir) || !fs.existsSync(projectDir)) skip('out_dir or project_dir missing');
+// Resolve to ABSOLUTE now — callers pass a relative out_dir (e.g. output/articles/<slug>)
+// but we run the compile from a different cwd (the assets/node_modules dir), so any
+// relative -o / --content path would resolve against the wrong base and emit 0 bytes.
+outDir = path.resolve(outDir);
+projectDir = path.resolve(projectDir);
+
+// --- Load the css_build recipe -------------------------------------------------
+let recipe = null;
+try { recipe = JSON.parse(fs.readFileSync(projectMapPath, 'utf8')).css_build; } catch (_) {}
+if (!recipe) skip('no css_build recipe in project_map — keeping CDN');
+if (recipe.method === 'fallback_synthesis') skip('recipe is fallback_synthesis — keeping CDN');
+const twV = recipe.tw_version === 3 || recipe.tw_version === 4 ? recipe.tw_version : null;
+if (!twV) skip('recipe is not a Tailwind build — keeping CDN');
+
+// --- Gather the mockup HTML as the content to scan -----------------------------
+const stepHtml = fs.readdirSync(outDir)
+  .filter(f => /^(?:step_\d+|block_[a-z0-9]+(?:-[a-z0-9]+)*)\.html$/.test(f))
+  .map(f => path.join(outDir, f));
+if (!stepHtml.length) skip('no article mockup HTML to scan');
+
+const outCss = path.join(outDir, 'mockup.css');
+const entryRel = recipe.entry || '';
+const entryAbs = entryRel ? path.resolve(projectDir, entryRel) : '';
+
+// Run from the nearest ancestor of the entry (or projectDir) that has a
+// node_modules — that's where detect-project installed tailwindcss + plugins, so
+// `@import "tailwindcss"` / `@plugin` resolve. Falls back to projectDir.
+function findCwd() {
+  let dir = entryAbs ? path.dirname(entryAbs) : projectDir;
+  const root = path.parse(dir).root;
+  while (dir && dir !== root) {
+    if (fs.existsSync(path.join(dir, 'node_modules', 'tailwindcss')) ||
+        fs.existsSync(path.join(dir, 'node_modules', '@tailwindcss'))) return dir;
+    dir = path.dirname(dir);
+  }
+  return projectDir;
+}
+const cwd = findCwd();
+
+// Prefer a locally-installed Tailwind binary (detect-project installs one) so the
+// render never depends on npx fetching @tailwindcss/cli over the network — the
+// failure mode that silently drops back to the flaky Play CDN in constrained envs.
+function twCli(v) {
+  const localBin = path.join(cwd, 'node_modules', '.bin', 'tailwindcss');
+  if (fs.existsSync(localBin)) return JSON.stringify(localBin);
+  return v === 4 ? 'npx --yes @tailwindcss/cli@4' : 'npx --yes tailwindcss@3';
+}
+
+// --- Build the compile command from recipe fields (not string-munging) ---------
+let cmd;
+let tmpCfg = null;   // v3 temp config path — hoisted so the retry can rewrite it
+if (twV === 4) {
+  // v4 CLI: the real entry supplies @import "tailwindcss" + @plugin (theme/plugins);
+  // repeated --content points scanning at the MOCKUP html (overrides source(none)).
+  if (!entryAbs || !fs.existsSync(entryAbs)) skip('v4 recipe has no usable entry file');
+  const content = stepHtml.map(h => `--content ${JSON.stringify(h)}`).join(' ');
+  cmd = `${twCli(4)} -i ${JSON.stringify(entryAbs)} -o ${JSON.stringify(outCss)} ${content}`;
+} else {
+  // v3: spread the real config but override `content` to the mockup html, so the
+  // theme/plugins from the real config apply while only the mockup's classes emit.
+  const cfgRel = recipe.config;
+  tmpCfg = path.join(outDir, '.jit_tw.config.js');
+  if (cfgRel) {
+    const cfgAbs = path.resolve(projectDir, cfgRel);
+    fs.writeFileSync(tmpCfg,
+      `const base = require(${JSON.stringify(cfgAbs)});\n` +
+      `module.exports = { ...base, content: ${JSON.stringify(stepHtml)} };\n`);
+  } else {
+    fs.writeFileSync(tmpCfg, `module.exports = { content: ${JSON.stringify(stepHtml)} };\n`);
+  }
+  // v3 needs an entry with @tailwind directives; synthesize one if the recipe's
+  // entry isn't a plain v3 entry.
+  const tmpIn = path.join(outDir, '.jit_tw_in.css');
+  fs.writeFileSync(tmpIn, '@tailwind base;\n@tailwind components;\n@tailwind utilities;\n');
+  cmd = `${twCli(3)} -c ${JSON.stringify(tmpCfg)} -i ${JSON.stringify(tmpIn)} -o ${JSON.stringify(outCss)}`;
+}
+
+// --- Run it (timed) ------------------------------------------------------------
+// The render container is typically network-isolated, so the "keep the CDN"
+// fallback is a mirage — a local compile is the ONLY thing that can work. The
+// usual reason a first attempt fails is an unresolvable plugin: the real config
+// `require()`s a plugin (`tailwind-scrollbar`, a v4 `@plugin`) that isn't in the
+// render env's node_modules (detect-time installs don't always persist, pnpm
+// symlinks dangle). A missing PLUGIN must not sink the whole compile — the
+// mockup's own utility classes (`size-[18px]`, `grid-cols-3`, responsive
+// variants) are theme/plugin-independent and the brand theme is already carried
+// by the separately-linked `branding.css`. So on failure, retry once with a
+// minimal, plugin-free config/entry rather than surrendering to the CDN.
+log(`(cwd=${cwd}, tw v${twV}) compiling mockup classes -> ${path.basename(outCss)}`);
+const buildLog = path.join(outDir, 'mockup_build.log');
+function runCompile(c) {
+  return execFileSync('bash', ['-c', `cd ${JSON.stringify(cwd)} && ${c} 2>&1`],
+    { timeout: 120000, encoding: 'utf8' });
+}
+let out = '', ok = false;
+try { out = runCompile(cmd); ok = true; }
+catch (e) { out = (e.stdout || '') + (e.stderr || '') + '\n' + String(e.message || e); }
+
+if (!ok && twV !== 4 && recipe.config) {
+  // v3: drop the real config's theme+plugins; keep only the mockup content.
+  log('config load failed (likely a missing plugin) — retrying with a minimal plugin-free config');
+  fs.writeFileSync(tmpCfg, `module.exports = { content: ${JSON.stringify(stepHtml)} };\n`);
+  try { out += '\n--- retry (minimal config) ---\n' + runCompile(cmd); ok = true; }
+  catch (e) { out += '\n--- retry (minimal config) FAILED ---\n' + (e.stdout || '') + (e.stderr || '') + '\n' + String(e.message || e); }
+} else if (!ok && twV === 4 && entryAbs) {
+  // v4: the real entry's `@plugin`/`@import` lines can fail to resolve; retry
+  // with a bare `@import "tailwindcss"` entry (default theme, no plugins).
+  log('v4 entry compile failed (likely a missing @plugin) — retrying with a bare tailwindcss entry');
+  const bareIn = path.join(outDir, '.jit_tw_in.css');
+  fs.writeFileSync(bareIn, '@import "tailwindcss";\n');
+  const content = stepHtml.map(h => `--content ${JSON.stringify(h)}`).join(' ');
+  const bareCmd = `${twCli(4)} -i ${JSON.stringify(bareIn)} -o ${JSON.stringify(outCss)} ${content}`;
+  try { out += '\n--- retry (bare v4 entry) ---\n' + runCompile(bareCmd); ok = true; }
+  catch (e) { out += '\n--- retry (bare v4 entry) FAILED ---\n' + (e.stdout || '') + (e.stderr || '') + '\n' + String(e.message || e); }
+}
+
+if (!ok && twV === 4) {
+  // Last resort: even the bare `@import "tailwindcss"` needs the tailwindcss
+  // PACKAGE resolvable from the filesystem, and workspace monorepos (bun/pnpm)
+  // often have no usable node_modules at render time at all. Scratch-install
+  // tailwindcss@4 into a tmp cache (persists across runs on the same machine)
+  // and import it by absolute path — mirroring the isolated build detect-time
+  // compiles already use. Network-dependent like the npx CLI fetch above; in a
+  // fully offline env this fails harmlessly into the existing CDN fallback.
+  const scratch = path.join(os.tmpdir(), 'rtfm-jit-tw4');
+  const pkgCss = path.join(scratch, 'node_modules', 'tailwindcss', 'index.css');
+  try {
+    if (!fs.existsSync(pkgCss)) {
+      log('tailwindcss package unresolvable — scratch-installing tailwindcss@4 (cached in tmp)');
+      execFileSync('bash', ['-c',
+        `npm install --prefix ${JSON.stringify(scratch)} --no-save --no-audit --no-fund --ignore-scripts tailwindcss@4 2>&1`],
+        { timeout: 120000, encoding: 'utf8' });
+    }
+    if (fs.existsSync(pkgCss)) {
+      const absIn = path.join(outDir, '.jit_tw_in.css');
+      fs.writeFileSync(absIn, `@import ${JSON.stringify(pkgCss)};\n`);
+      const content = stepHtml.map(h => `--content ${JSON.stringify(h)}`).join(' ');
+      const absCmd = `${twCli(4)} -i ${JSON.stringify(absIn)} -o ${JSON.stringify(outCss)} ${content}`;
+      out += '\n--- retry (scratch-installed tailwindcss) ---\n' + runCompile(absCmd);
+      ok = true;
+    }
+  } catch (e) { out += '\n--- retry (scratch install) FAILED ---\n' + (e.stdout || '') + (e.stderr || '') + '\n' + String(e.message || e); }
+}
+try { fs.writeFileSync(buildLog, `CMD: ${cmd}\nCWD: ${cwd}\nok=${ok}\n--- output ---\n${out}\n`); } catch (_) {}
+if (!ok) fail('local Tailwind compile failed — keeping CDN\n' + out.split('\n').slice(-8).join('\n'));
+
+// Clean temp files
+for (const t of ['.jit_tw.config.js', '.jit_tw_in.css']) {
+  try { fs.unlinkSync(path.join(outDir, t)); } catch (_) {}
+}
+
+let bytes = 0;
+try { bytes = fs.statSync(outCss).size; } catch (_) {}
+if (bytes < 2000) fail(`mockup.css too small (${bytes}b) — keeping CDN`);
+log(`wrote ${path.basename(outCss)} (${bytes} bytes)`);
+process.exit(0);

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

@@ -0,0 +1,87 @@
+// Shared source grounding for literal labels and a deliberately small Rails subset.
+// No application code is executed, and free-text derivations are never evidence.
+const fs = require('fs');
+const path = require('path');
+const { resolveSourcePath } = require('./source_paths.js');
+const escape = s => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const uncomment = s => s.split('\n').filter(line => !/^\s*#/.test(line)).join('\n');
+// Project-relative, or ../<repo>/<path> into a related repository (source_paths.js).
+function source(root, file) {
+    return fs.readFileSync(resolveSourcePath(root, file), 'utf8');
+}
+function filesBelow(root, dir) {
+    const at = path.join(root, dir);
+    if (!fs.existsSync(at)) return [];
+    return fs.readdirSync(at, { withFileTypes: true }).flatMap(item => {
+        if (item.isSymbolicLink()) throw Error('symlinked locale/config files need a runtime resolver');
+        const file = path.join(dir, item.name);
+        return item.isDirectory() ? filesBelow(root, file) : [file];
+    });
+}
+function railsSubmit(root, entry) {
+    const g = entry.generated;
+    if (g.kind !== 'rails_submit' || g.locale !== 'en' || !['create', 'update'].includes(g.action)) throw Error('supported generated evidence is rails_submit with locale en and action create/update');
+    if (!/^@[a-z][a-z0-9_]*$/.test(g.binding || '')) throw Error('cite the form model instance variable as binding');
+    const template = source(root, entry.found_in).replace(/<%#[\s\S]*?%>/g, '');
+    const forms = [...template.matchAll(/<%=\s*form_with\s*\(?([\s\S]*?)\s+do\s+\|(\w+)\|\s*%>/g)];
+    if (forms.length !== 1 || !new RegExp(`\\bmodel:\\s*${escape(g.binding)}(?=\\s*[,)]|\\s*$)`).test(forms[0][1]) || /\b(?:builder|scope):/.test(forms[0][1])) throw Error('cite a single form_with bound to this model, without a custom builder or scope');
+    const builder = escape(forms[0][2]);
+    const submits = [...template.matchAll(new RegExp(`<%=\\s*${builder}\\.submit\\b([\\s\\S]*?)%>`, 'g'))];
+    // Only no argument or a literal CSS class: reject explicit labels, value overrides and dynamic options.
+    if (submits.length !== 1 || !/^\s*(?:class:\s*(?:"[^"\n]*"|'[^'\n]*'))?\s*$/.test(submits[0][1]) || submits[0].index < forms[0].index) throw Error('cite a default submit helper with no explicit label or dynamic options');
+    const model = uncomment(source(root, g.model_source));
+    const declaration = model.match(/^\s*class\s+([A-Z]\w*)\s*<\s*(?:ApplicationRecord|ActiveRecord::Base)\s*$/m);
+    if (!declaration || /\b(?:def|delegate|define_method|include|extend|prepend)\b|\b(?:model_name|human_attribute_name|persisted\?|i18n_scope)\b/.test(model)) throw Error('custom model behavior needs a runtime resolver');
+    const name = declaration[1];
+    const bindings = uncomment(source(root, g.binding_source));
+    const assignments = [...bindings.matchAll(new RegExp(`^\\s*${escape(g.binding)}\\s*=(?!=)\\s*([^\\n]+)`, 'gm'))];
+    if (assignments.length !== 1) throw Error('cite an unambiguous model assignment proving create/update state');
+    const assignment = assignments[0][1].trim();
+    const expectedAssignment = g.action === 'create'
+        ? new RegExp(`^${escape(name)}\\.new(?:\\(.*\\))?\\s*$`)
+        : new RegExp(`^${escape(name)}\\.find\\([^\\n]+\\)\\s*$`);
+    if (!expectedAssignment.test(assignment)) throw Error('model assignment does not prove the requested create/update state');
+    // Refuse custom naming/translation paths rather than guessing Rails runtime behavior.
+    const configFiles = ['config/application.rb', ...filesBelow(root, 'config/initializers'), ...filesBelow(root, 'config/environments'), ...filesBelow(root, 'config/locales'), 'app/models/application_record.rb', 'app/controllers/application_controller.rb', 'app/helpers/application_helper.rb', g.binding_source];
+    let inflections = '';
+    for (const file of configFiles) {
+        if (!fs.existsSync(path.join(root, file))) continue;
+        const text = uncomment(source(root, file));
+        if (file === 'config/initializers/inflections.rb') { inflections = text; continue; }
+        if (/\b(?:helpers\s*[:.]|activerecord\s*:|activemodel\s*:|model_name|i18n_scope|persisted\?|default_form_builder|field_error_proc)|I18n\.|i18n\.(?:default_locale|load_path)|Inflector\.inflections|FormBuilder|def\s+(?:submit|model_name)/.test(text)) throw Error(`custom locale, model naming or form behavior in ${file} needs a runtime resolver; cite a literal translation when available`);
+    }
+    // Only default inflections plus literal English acronym declarations are supported.
+    const acronyms = new Map();
+    const remainder = inflections.replace(/ActiveSupport::Inflector\.inflections\(:en\)\s+do\s+\|(\w+)\|([\s\S]*?)\bend\b/g, (_, receiver, body) => {
+        const rest = body.replace(new RegExp(`${escape(receiver)}\\.acronym\\s+['"]([A-Za-z]+)['"]`, 'g'), (__, word) => { acronyms.set(word.toLowerCase(), word); return ''; });
+        return rest;
+    });
+    if (remainder.trim()) throw Error('custom inflections need a runtime resolver');
+    let underscored = name;
+    if (acronyms.size) {
+        const pattern = new RegExp(`(?:(?<=([A-Za-z\\d]))|\\b)(${[...acronyms.values()].map(escape).join('|')})(?=\\b|[^a-z])`, 'g');
+        underscored = underscored.replace(pattern, (_, prefix, acronym) => `${prefix ? '_' : ''}${acronym.toLowerCase()}`);
+    }
+    const words = underscored.replace(/([A-Z])(?=[A-Z][a-z])|([a-z\d])(?=[A-Z])/g, (_, upper, lower) => (upper || lower) + '_').toLowerCase().replace(/_id$/, '').split('_');
+    let human = words.map(word => acronyms.get(word) || word).join(' ');
+    human = human[0].toUpperCase() + human.slice(1);
+    const label = `${g.action === 'create' ? 'Create' : 'Update'} ${human}`;
+    return label;
+}
+function verifyLabelEvidence(entry, primary, root) {
+    const string = typeof entry === 'string' ? entry : entry && entry.string;
+    const file = entry && typeof entry === 'object' && entry.found_in || primary;
+    if (typeof string !== 'string' || !string.trim()) return { ok: false, error: 'missing evidence string' };
+    try {
+        if (entry && entry.generated) {
+            const expected = railsSubmit(root, entry);
+            return expected === string ? { ok: true, kind: 'generated' } : { ok: false, error: `generated label contradicts source: expected "${expected}", received "${string}"` };
+        }
+        if (!file) return { ok: true, kind: 'legacy' }; // preserve legacy source-less terminal evidence
+        if (source(root, file).includes(string)) return { ok: true, kind: 'literal' };
+        return { ok: false, error: `verbatim_evidence "${string}" claimed in ${file} but absent from that file; if generated, supply supported structured generated evidence (a derivation note alone is not verified)` };
+    } catch (error) {
+        return { ok: false, error: `cannot verify label "${string}": ${error.code ? 'source file unavailable' : error.message}` };
+    }
+}
+module.exports = { verifyLabelEvidence };

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

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const { verifyLabelEvidence } = require('./label_evidence.js');
+const { ARTICLE_TYPES, PRESENTATIONS, blocks, articleType } = require('./article_blocks');
+
+function typeOf(value) {
+    if (Array.isArray(value)) return 'array';
+    if (value === null) return 'null';
+    return typeof value;
+}
+
+// ---- Markdown code scanner -------------------------------------------------
+// Line-based and CommonMark-shaped: a line whose first non-blank run is three
+// or more backticks or tildes opens a fence with an optional info string (a
+// backtick fence takes no backtick in its info string, so "```x```" stays
+// inline); the same marker character, at least as long, alone on a line closes
+// it. `prose` is the text with fence bodies and inline spans removed, so the
+// sentence cap and bold extraction never see code; `inline` holds the span
+// texts and `fences` the blocks, each with its language tag and closed flag.
+function scanCode(text) {
+    const prose = [], inline = [], fences = [];
+    let open = null;
+    for (const line of String(text || '').split('\n')) {
+        if (open) {
+            const close = line.match(/^[ \t]*(`{3,}|~{3,})[ \t]*$/);
+            if (close && close[1][0] === open.marker[0] && close[1].length >= open.marker.length) { open.closed = true; open = null; }
+            else open.body.push(line);
+            continue;
+        }
+        const start = line.match(/^[ \t]*(`{3,}|~{3,})(.*)$/);
+        if (start && !(start[1][0] === '`' && start[2].includes('`'))) {
+            open = { marker: start[1], lang: start[2].trim().split(/\s+/)[0] || '', body: [], closed: false };
+            fences.push(open);
+            continue;
+        }
+        prose.push(line.replace(/(`+)([^`]+?)\1/g, (_, __, span) => { inline.push(span.trim()); return ' '; }));
+    }
+    return { prose: prose.join('\n'), inline, fences: fences.map(f => ({ lang: f.lang, body: f.body.join('\n'), closed: f.closed })) };
+}
+
+function checkSchema(article) {
+    const errors = [];
+    const keys = Object.keys(article).sort();
+    const allowed = ['article_type', 'blocks', 'schema_version', 'title'];
+    if (article.schema_version !== 2) errors.push('"schema_version" must be 2');
+    if (typeof article.title !== 'string' || !article.title.trim()) errors.push('"title" must be a non-empty string');
+    if (!ARTICLE_TYPES.includes(article.article_type)) errors.push(`"article_type" must be one of ${ARTICLE_TYPES.join('|')}`);
+    if (!Array.isArray(article.blocks) || !article.blocks.length) errors.push('"blocks" must be a non-empty array');
+    for (const key of keys) if (!allowed.includes(key)) errors.push(`unknown top-level key "${key}" — schema v2 uses blocks only`);
+
+    const ids = new Set();
+    for (const [index, block] of (article.blocks || []).entries()) {
+        const at = `blocks[${index}]`;
+        if (!block || typeof block !== 'object' || Array.isArray(block)) { errors.push(`${at} must be an object`); continue; }
+        if (typeof block.id !== 'string' || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(block.id)) errors.push(`${at}.id must be URL-safe kebab-case`);
+        else if (ids.has(block.id)) errors.push(`${at}.id "${block.id}" is duplicated`);
+        else ids.add(block.id);
+        if (!Object.hasOwn(PRESENTATIONS, block.type)) { errors.push(`${at}.type must be prose|section|list`); continue; }
+        if (!PRESENTATIONS[block.type].includes(block.presentation)) errors.push(`${at}.presentation is invalid for ${block.type}`);
+        const allowedKeys = {
+            prose: ['id', 'type', 'presentation', 'title', 'content'],
+            section: ['id', 'type', 'presentation', 'title', 'content', 'has_image'],
+            list: ['id', 'type', 'presentation', 'title', 'items'],
+        }[block.type];
+        for (const key of Object.keys(block)) if (!allowedKeys.includes(key)) errors.push(`${at} has unknown key "${key}"`);
+        if (block.type === 'prose' && typeof block.content !== 'string') errors.push(`${at}.content must be a string`);
+        if (block.type === 'section') {
+            if (typeof block.title !== 'string' || !block.title.trim()) errors.push(`${at}.title must be non-empty`);
+            if (typeof block.content !== 'string') errors.push(`${at}.content must be a string`);
+            if (typeof block.has_image !== 'boolean') errors.push(`${at}.has_image must be a boolean`);
+        }
+        if (block.type === 'list') {
+            if (typeof block.title !== 'string' || !block.title.trim()) errors.push(`${at}.title must be non-empty`);
+            if (!Array.isArray(block.items) || block.items.some(item => typeof item !== 'string')) errors.push(`${at}.items must be an array of strings`);
+        }
+        // Fence placement is part of the rendering contract: the app renders the
+        // lead and list items inline-only, so a fence there reaches readers as raw
+        // backticks, and an unclosed fence swallows the rest of the block.
+        if (block.type === 'prose' && block.presentation === 'lead' && typeof block.content === 'string') {
+            if (scanCode(block.content).fences.length) errors.push(`${at} (lead prose) must not contain a fenced code block — the lead renders inline-only; move the snippet to a section`);
+        } else if ((block.type === 'prose' || block.type === 'section') && typeof block.content === 'string') {
+            if (scanCode(block.content).fences.some(fence => !fence.closed)) errors.push(`${at} has an unclosed fenced code block`);
+        }
+        if (block.type === 'list' && Array.isArray(block.items)) {
+            block.items.forEach((item, position) => {
+                if (typeof item === 'string' && scanCode(item).fences.length) errors.push(`${at}.items[${position}] must not contain a fenced code block — list items render inline-only`);
+            });
+        }
+    }
+    return errors;
+}
+
+function loadFileOrEmpty(file) { try { return fs.readFileSync(file, 'utf8'); } catch { return ''; } }
+function makeCorpus(text) {
+    const raw = text.toLowerCase();
+    return { raw, flat: text.replace(/<[^>]*>/g, ' ').replace(/\s+/g, ' ').toLowerCase(), compact: raw.replace(/[-_]/g, '') };
+}
+function corpusHas(corpus, term) { const value = term.toLowerCase(); return corpus.raw.includes(value) || corpus.flat.includes(value.replace(/\s+/g, ' ')); }
+// Flags and identifiers rarely appear in the sources spelled the way the user
+// types them (a derive-based CLI declares `send_message` and exposes
+// `--send-message`), so code tokens also match with dashes/underscores removed.
+function corpusHasCode(corpus, token) { return corpusHas(corpus, token) || corpus.compact.includes(token.toLowerCase().replace(/^-+/, '').replace(/[-_]/g, '')); }
+function extractBoldTerms(text) {
+    const terms = []; const re = /\*\*([^*\n]+?)\*\*/g; let match;
+    while ((match = re.exec(text || '')) !== null) {
+        const term = match[1].trim().replace(/^['"`“”‘’]+|['"`“”‘’]+$/g, '').replace(/[.,:;!?]+$/g, '');
+        if (term && term.length <= 80 && /[\p{L}\p{N}]/u.test(term)) terms.push(term);
+    }
+    return terms;
+}
+function segments(term) { const parts = term.split(/\s*[›»→]\s*|\s+>\s+/).filter(Boolean); return parts.length > 1 ? parts : [term]; }
+
+const FLAG_RE = /(?<![\w-])--?[a-z][\w-]*/gi;
+// The code tokens worth checking against the sources: single-token spans that
+// look like a flag, path or identifier (plain words such as `clear` are too
+// generic to ground), plus every flag inside multi-token spans and fence bodies.
+function codeTokens(scan) {
+    const tokens = new Set();
+    for (const span of scan.inline) {
+        if (!span || /^<[^>]+>$/.test(span) || /^["'].*["']$/.test(span) || /…|\.\.\./.test(span)) continue;
+        if (!/\s/.test(span)) { if (/[a-z]/i.test(span) && /^-|[/._-]|^~/.test(span)) tokens.add(span); continue; }
+        for (const flag of span.match(FLAG_RE) || []) tokens.add(flag);
+    }
+    for (const fence of scan.fences) for (const flag of fence.body.match(FLAG_RE) || []) tokens.add(flag);
+    return [...tokens];
+}
+// A bold span that is really a command, flag or path — the observed failure on
+// CLI projects before inline code existed in the prose rules.
+function looksLikeCode(term, binary) {
+    if (/^-{1,2}[a-z]/i.test(term)) return 'flag';
+    if (/^(~|\.{1,2})?\/[\w.-]/.test(term) || /^[\w-]+(\/[\w.-]+)+\.\w{1,5}$/.test(term)) return 'path';
+    if (/\s--?[a-z][\w-]*/i.test(term)) return 'command';
+    if (binary) {
+        const lower = term.toLowerCase(), name = binary.toLowerCase();
+        if (lower === name || lower.startsWith(name + ' ')) return 'command';
+    }
+    return null;
+}
+
+function buildCorpora(viewSources, projectDir) {
+    const perId = new Map(); let union = '';
+    for (const entry of (viewSources && (viewSources.blocks || viewSources.steps)) || []) {
+        const files = [entry.primary_view, entry.layout, ...(entry.partials_expanded || [])].filter(Boolean);
+        let text = files.map(file => loadFileOrEmpty(path.join(projectDir, file))).join('\n');
+        text += '\n' + (entry.verbatim_evidence || []).filter(item => verifyLabelEvidence(item, entry.primary_view, projectDir).ok).map(item => typeof item === 'object' ? item.string : item).join('\n');
+        const id = entry.block_id || (typeof entry.index === 'number' ? `step-${entry.index + 1}` : null);
+        if (id) perId.set(id, makeCorpus(text));
+        union += text;
+    }
+    return { perId, union: makeCorpus(union) };
+}
+
+// A terminal mockup that shows only the typed prompt line duplicates the
+// article's fenced block without being copyable; the slot belongs to output the
+// reader must read, or to a TUI state.
+function redundantCommandMockup(block, outputDir) {
+    const html = loadFileOrEmpty(path.join(outputDir, `block_${block.id}.html`));
+    if (!html || !/\bterminal-cmd\b/.test(html) || /\btui-screen\b/.test(html)) return false;
+    const outputs = [...html.matchAll(/class="[^"]*\bterminal-output\b[^"]*"[^>]*>([\s\S]*?)<\/span>/g)]
+        .map(match => match[1].replace(/<[^>]*>/g, '').trim()).filter(Boolean);
+    return outputs.length === 0;
+}
+
+function checkFidelity(article, corpora, options) {
+    const { warnMode, outputDir, appType, binary } = options;
+    const hasSources = corpora.union.raw.trim().length > 0;
+    const reports = [], metrics = { inline_code_spans: 0, fenced_blocks: 0, untagged_fences: 0 };
+    for (const block of blocks(article)) {
+        const errors = [], warnings = [];
+        const content = typeof block.content === 'string' ? block.content : '';
+        const scan = scanCode(content);
+        metrics.inline_code_spans += scan.inline.length;
+        metrics.fenced_blocks += scan.fences.length;
+        if (block.type === 'prose' || block.type === 'section') {
+            for (const fence of scan.fences) if (!fence.lang) { metrics.untagged_fences += 1; warnings.push(`block "${block.id}" has a fenced code block without a language tag (bash, json, toml, text)`); }
+        }
+        if (block.type !== 'section') { reports.push({ block_id: block.id, errors, warnings }); continue; }
+        if (/^\s*(`{3,}|~{3,})/.test(content)) warnings.push(`section "${block.id}" starts with a code block — lead with the instruction sentence`);
+        if (/\*\*\s*`[^`\n]+`\s*\*\*/.test(content)) warnings.push(`section "${block.id}" bolds inline code — drop the bold, inline code stands on its own`);
+        const own = corpora.perId.get(block.id);
+        for (const term of extractBoldTerms(scan.prose)) {
+            const kind = looksLikeCode(term, binary);
+            if (kind) { warnings.push(`bold "${term}" looks like a ${kind} — bold is for on-screen labels; use inline code`); continue; }
+            const parts = segments(term);
+            if (own && parts.every(part => corpusHas(own, part))) continue;
+            if (parts.every(part => corpusHas(corpora.union, part))) { warnings.push(`bold UI name "${term}" is not in this block's own sources`); continue; }
+            const message = `bold UI name "${term}" appears in none of the resolved source files`;
+            if (block.has_image && own && !warnMode) errors.push(message); else warnings.push(message);
+        }
+        if (hasSources) {
+            for (const token of codeTokens(scan)) {
+                if (own && corpusHasCode(own, token)) continue;
+                if (corpusHasCode(corpora.union, token)) { warnings.push(`inline code "${token}" is not in this block's own sources`); continue; }
+                warnings.push(`inline code "${token}" appears in none of the resolved source files — invented flag or path?`);
+            }
+        }
+        if (appType === 'terminal' && block.has_image && outputDir && redundantCommandMockup(block, outputDir)) {
+            warnings.push(`section "${block.id}" spends a screenshot on a typed command with no output — the fenced block already carries it; set has_image:false or show the output the reader must read`);
+        }
+        reports.push({ block_id: block.id, errors, warnings });
+    }
+    return { reports, metrics };
+}
+
+function sentenceCount(text) { const prose = scanCode(text).prose.replace(/\*\*/g, ''); const found = prose.match(/[.!?]+(?=\s|$)/g); return found ? found.length : (prose.trim() ? 1 : 0); }
+function styleWarnings(article) {
+    const warnings = [], type = articleType(article);
+    if (type === 'how-to' && !/^how\s+to\b/i.test(article.title || '')) warnings.push('how-to title should start with "How to"');
+    if (type === 'faq' && !(article.title || '').trim().endsWith('?')) warnings.push('faq title should end with "?"');
+    for (const block of blocks(article)) {
+        const cap = type === 'concept' ? 4 : 3;
+        if (block.type === 'section' && sentenceCount(block.content) > cap) warnings.push(`block "${block.id}" exceeds the ${cap}-sentence guidance`);
+        if (block.type === 'prose' && block.presentation === 'lead' && sentenceCount(block.content) > 2) warnings.push('lead prose should be 1-2 sentences');
+    }
+    return warnings;
+}
+
+function main() {
+    const outputDir = process.argv[2], projectDir = process.argv[3] || '.';
+    if (!outputDir) process.exit(2);
+    let article;
+    try { article = JSON.parse(fs.readFileSync(path.join(outputDir, 'article.json'), 'utf8')); }
+    catch (error) { console.error(`cannot read article.json: ${error.message}`); process.exit(2); }
+    let viewSources = null;
+    try { viewSources = JSON.parse(fs.readFileSync(path.join(outputDir, 'view_sources.json'), 'utf8')); } catch {}
+    let projectMap = {};
+    try { projectMap = JSON.parse(fs.readFileSync(path.join(projectDir, '.rtfm', 'project_map.json'), 'utf8')) || {}; } catch {}
+    const appType = projectMap.app_type || (viewSources && viewSources.framework === 'cli' ? 'terminal' : null);
+    const binary = projectMap.cli_metadata && typeof projectMap.cli_metadata.binary === 'string' ? projectMap.cli_metadata.binary : null;
+    const warnMode = (process.env.RTFM_LINT_MODE || '').toLowerCase() === 'warn';
+    const fidelity = checkFidelity(article, buildCorpora(viewSources, projectDir), { warnMode, outputDir, appType, binary });
+    const report = {
+        all_passed: true,
+        mode: warnMode ? 'warn' : 'fail',
+        global_errors: checkSchema(article),
+        global_warnings: styleWarnings(article),
+        blocks: fidelity.reports,
+        metrics: fidelity.metrics,
+    };
+    report.all_passed = !report.global_errors.length && !report.blocks.some(block => block.errors.length);
+    fs.writeFileSync(path.join(outputDir, 'article_lint_report.json'), JSON.stringify(report, null, 2));
+    for (const error of report.global_errors) console.log(`[FAIL] (schema) ERROR: ${error}`);
+    for (const warning of report.global_warnings) console.log(`[WARN] (article) WARN: ${warning}`);
+    for (const block of report.blocks) {
+        for (const error of block.errors) console.log(`[FAIL] block ${block.block_id}: ${error}`);
+        for (const warning of block.warnings) console.log(`[WARN] block ${block.block_id}: ${warning}`);
+    }
+    if (!report.all_passed) process.exit(1);
+    console.log('article.json passed the copy lint.');
+}
+main();