@supportpages.io/wtfm 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,168 @@
+#!/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 {
+    MAX_ASSETS,
+    buildPrompt,
+    generateAll,
+    validateRequests,
+} = require('./generate_content_images.js');
+
+function request(overrides = {}) {
+    return {
+        id: 'participant-alex',
+        kind: 'video-frame',
+        purpose: 'A fictional participant visible inside the real call tile',
+        reason: 'The source requires a live camera feed and provides no suitable image asset',
+        prompt: 'Natural webcam view of a fictional adult in a bright home office',
+        aspect_ratio: 'landscape',
+        alt: 'Fictional participant on camera',
+        used_in_steps: [1, 2],
+        ...overrides,
+    };
+}
+
+function manifest(assets = [request()]) { return { version: 1, assets }; }
+
+function externalRequest(overrides = {}) {
+    return request({
+        id: 'confirm-email',
+        kind: 'external-surface',
+        surface: 'confirmation-email',
+        source_basis: 'user-description',
+        source_files: [],
+        required_text: ['Confirm your email address', 'Confirm email'],
+        purpose: 'The confirmation email the reader must recognise and act in',
+        reason: 'The step happens outside the product and no renderable email template exists',
+        prompt: 'A clean transactional confirmation email on a neutral mail canvas',
+        alt: 'Confirmation email with a Confirm email button',
+        used_in_steps: [2],
+        ...overrides,
+    });
+}
+
+async function run() {
+    assert.strictEqual(validateRequests(manifest()).length, 1);
+    const blockAsset = validateRequests(manifest([request({ used_in_steps: undefined, used_in_blocks: ['join-call'] })]))[0];
+    assert.deepStrictEqual(blockAsset.used_in_blocks, ['join-call']);
+    assert.throws(() => validateRequests(manifest(Array.from({ length: MAX_ASSETS + 1 }, (_, i) =>
+        request({ id: `asset-${i}` })))), /maximum is 5/);
+    assert.throws(() => validateRequests(manifest([request(), request()])), /duplicates/);
+    assert.throws(() => validateRequests(manifest([request({ kind: 'ui-mockup' })])), /kind must be/);
+    assert.strictEqual(validateRequests(manifest([externalRequest()]))[0].surface, 'confirmation-email');
+    assert.throws(() => validateRequests(manifest([externalRequest({ surface: 'product-screen' })])), /surface must be/);
+    assert.throws(() => validateRequests(manifest([externalRequest({ required_text: [] })])), /required_text/);
+    assert.throws(() => validateRequests(manifest([externalRequest({ source_basis: 'repository', source_files: [] })])), /must not be empty/);
+    assert.throws(() => validateRequests(manifest([request({ required_text: ['Not allowed'] })])), /only valid/);
+
+    const prompt = buildPrompt(request());
+    assert(prompt.includes('Do not draw application UI'));
+    assert(prompt.includes('must not depict or imitate an identifiable real person'));
+
+    const externalPrompt = buildPrompt(validateRequests(manifest([externalRequest()]))[0]);
+    assert(externalPrompt.includes('External surface type: confirmation-email'));
+    assert(externalPrompt.includes('"Confirm your email address"'));
+    assert(externalPrompt.includes('authorised to contain interface elements and legible text'));
+    assert(externalPrompt.includes('Do not draw, extend, or imitate the product application UI'));
+
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'rtfm-content-images-'));
+    const out = path.join(root, 'out');
+    const cache = path.join(root, 'cache');
+    let calls = 0;
+    const fakeFetch = async () => {
+        calls += 1;
+        return {
+            ok: true,
+            json: async () => ({ data: [{ b64_json: Buffer.from('fake-png').toString('base64') }] }),
+        };
+    };
+
+    let result = await generateAll({ requests: manifest(), outDir: out, cacheDir: cache,
+        apiKey: 'test-key', fetchImpl: fakeFetch });
+    assert.strictEqual(result.assets['participant-alex'].status, 'generated');
+    assert.strictEqual(calls, 1);
+    assert.strictEqual(fs.readFileSync(path.join(out, 'generated-assets', 'participant-alex.png'), 'utf8'), 'fake-png');
+
+    result = await generateAll({ requests: manifest(), outDir: out, cacheDir: cache,
+        apiKey: 'test-key', fetchImpl: fakeFetch });
+    assert.strictEqual(result.assets['participant-alex'].status, 'cached');
+    assert.strictEqual(calls, 1);
+
+    result = await generateAll({ requests: manifest(), outDir: out, cacheDir: cache,
+        model: 'gpt-image-1', apiKey: 'test-key', fetchImpl: fakeFetch });
+    assert.strictEqual(result.assets['participant-alex'].status, 'generated');
+    assert.strictEqual(calls, 2);
+
+    const externalOut = path.join(root, 'external');
+    result = await generateAll({ requests: manifest([externalRequest()]), outDir: externalOut,
+        cacheDir: path.join(root, 'external-cache'), apiKey: 'test-key', fetchImpl: fakeFetch });
+    assert.strictEqual(result.assets['confirm-email'].status, 'generated');
+    assert.strictEqual(result.assets['confirm-email'].surface, 'confirmation-email');
+    assert.deepStrictEqual(result.assets['confirm-email'].required_text,
+        ['Confirm your email address', 'Confirm email']);
+    assert.deepStrictEqual(result.assets['confirm-email'].text_fidelity,
+        { enforcement: 'prompt-constrained', required_text_count: 2 });
+
+    const missingKeyOut = path.join(root, 'missing-key');
+    result = await generateAll({ requests: manifest(), outDir: missingKeyOut, cacheDir: path.join(root, 'empty-cache'),
+        apiKey: '' });
+    assert.strictEqual(result.count, 0);
+    assert.strictEqual(result.failure_count, 1);
+    assert.strictEqual(result.assets['participant-alex'], undefined);
+    assert.strictEqual(result.failures['participant-alex'].status, 'failed');
+    assert(result.failures['participant-alex'].warning.includes('no image was produced'));
+    assert(!fs.existsSync(path.join(missingKeyOut, 'generated-assets')));
+
+    const failedOut = path.join(root, 'api-failure');
+    const failedFetch = async () => ({ ok: false, status: 429, text: async () => 'rate limited' });
+    result = await generateAll({ requests: manifest(), outDir: failedOut, cacheDir: path.join(root, 'failed-cache'),
+        apiKey: 'test-key', fetchImpl: failedFetch });
+    assert.strictEqual(result.count, 0);
+    assert.strictEqual(result.failure_count, 1);
+    assert.strictEqual(result.assets['participant-alex'], undefined);
+    assert(result.failures['participant-alex'].warning.includes('429'));
+    assert(result.failures['participant-alex'].warning.includes('no image was produced'));
+    assert(!fs.existsSync(path.join(failedOut, 'generated-assets')));
+
+    const injectOut = path.join(root, 'inject');
+    fs.mkdirSync(injectOut, { recursive: true });
+    fs.writeFileSync(path.join(injectOut, 'step_0.html'),
+        '<!doctype html><html><head><!-- INJECT_CSS --></head><body><img src="{{generated:participant-alex}}" data-rtfm-generated-asset="participant-alex"></body></html>');
+    fs.writeFileSync(path.join(injectOut, 'images.json'), JSON.stringify({ images: {} }));
+    fs.copyFileSync(path.join(out, 'generated_images.json'), path.join(injectOut, 'generated_images.json'));
+    fs.cpSync(path.join(out, 'generated-assets'), path.join(injectOut, 'generated-assets'), { recursive: true });
+    const injected = spawnSync(process.execPath, [path.join(__dirname, 'inject_assets.js'), injectOut, '',
+        path.join(injectOut, 'images.json'), '--generated-images', path.join(injectOut, 'generated_images.json')],
+    { encoding: 'utf8' });
+    assert.strictEqual(injected.status, 0, injected.stdout + injected.stderr);
+    const injectedHtml = fs.readFileSync(path.join(injectOut, 'step_0.html'), 'utf8');
+    assert(injectedHtml.includes('src="data:image/png;base64,'));
+    assert(injectedHtml.includes('data-rtfm-generated-asset="participant-alex"'));
+
+    const omittedInjectOut = path.join(root, 'inject-omitted');
+    fs.mkdirSync(omittedInjectOut, { recursive: true });
+    fs.writeFileSync(path.join(omittedInjectOut, 'step_0.html'),
+        '<!doctype html><html><head><!-- INJECT_CSS --></head><body><img src="{{generated:participant-alex}}" data-rtfm-generated-asset="participant-alex"></body></html>');
+    fs.writeFileSync(path.join(omittedInjectOut, 'images.json'), JSON.stringify({ images: {} }));
+    fs.copyFileSync(path.join(missingKeyOut, 'generated_images.json'), path.join(omittedInjectOut, 'generated_images.json'));
+    const omittedInjection = spawnSync(process.execPath, [path.join(__dirname, 'inject_assets.js'), omittedInjectOut, '',
+        path.join(omittedInjectOut, 'images.json'), '--generated-images', path.join(omittedInjectOut, 'generated_images.json')],
+    { encoding: 'utf8' });
+    assert.strictEqual(omittedInjection.status, 0, omittedInjection.stdout + omittedInjection.stderr);
+    const omittedHtml = fs.readFileSync(path.join(omittedInjectOut, 'step_0.html'), 'utf8');
+    assert(omittedHtml.includes('src="{{generated:participant-alex}}"'));
+    assert(!omittedHtml.includes('src="data:image/'));
+
+    fs.rmSync(root, { recursive: true, force: true });
+    console.log('content image generation tests passed');
+}
+
+run().catch(error => {
+    console.error(error);
+    process.exitCode = 1;
+});

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

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+/**
+ * include_census.js — classification of includes by render condition on synthetic views
+ * (Rails ERB, JSX, Blade, Django), plus marker extraction. No app-specific fixtures.
+ */
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { census, includeRefs, extractMarkers } = require('./include_census.js');
+
+function project(files) {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'rtfm-census-'));
+    for (const [rel, text] of Object.entries(files)) {
+        fs.mkdirSync(path.dirname(path.join(root, rel)), { recursive: true });
+        fs.writeFileSync(path.join(root, rel), text);
+    }
+    return root;
+}
+const byName = c => Object.fromEntries(c.includes.map(i => [i.name, i]));
+
+// ── Rails ERB: unconditional partial, guarded partial, overlay partials, inline sections ──
+{
+    const root = project({
+        'app/views/things/new.html.erb': [
+            '<%= render partial: "layouts/header" %>',
+            '<main>',
+            '  <% if @account.premium? %>',
+            '    <%= render partial: "partials/upsell", locals: { feature: "x" } %>',
+            '  <% end %>',
+            '  <h3>Item details</h3>',
+            '  <%= f.label :title, "Title (Required)" %>',
+            '  <%= f.text_field :title %>',
+            '  <h3>Item options</h3>',
+            '  <label>Enable alerts</label>',
+            '  <% if current_user.admin? %>',
+            '  <h3>Admin controls</h3>',
+            '  <button>Purge</button>',
+            '  <% end %>',
+            '  <%= f.submit "Create item" %>',
+            '  <%= render partial: "modals/pick_owner_modal", locals: { title: "Pick" } %>',
+            '  <%= render partial: "shared/footer_actions" %>',
+            '</main>',
+        ].join('\n'),
+        'app/views/layouts/_header.html.erb': '<nav><a href="/">Home</a><a href="/things">Things</a></nav>',
+        'app/views/partials/_upsell.html.erb': '<div><h4>Upgrade to unlock</h4></div>',
+        'app/views/modals/_pick_owner_modal.html.erb': '<div class="modal"><h5>Pick an owner</h5><button>Close</button></div>',
+        'app/views/shared/_footer_actions.html.erb': '<div><button>Close</button><button>Save and continue</button></div>',
+    });
+    const c = census(root, 'app/views/things/new.html.erb');
+    const inc = byName(c);
+    assert.strictEqual(inc['layouts/header'].kind, 'unconditional');
+    assert.deepStrictEqual(inc['layouts/header'].markers, ['Home', 'Things']);
+    assert.strictEqual(inc['partials/upsell'].kind, 'conditional', 'guarded by the surrounding if');
+    assert.strictEqual(inc['modals/pick_owner_modal'].kind, 'overlay', 'modal by name');
+    assert.strictEqual(inc['shared/footer_actions'].kind, 'unconditional');
+    assert(inc['shared/footer_actions'].markers.includes('Save and continue'));
+    const secs = Object.fromEntries(c.inline_sections.map(s => [s.heading, s]));
+    assert.strictEqual(secs['Item details'].guarded, false);
+    assert(secs['Item details'].markers.includes('Title (Required)'), secs['Item details'].markers);
+    assert.strictEqual(secs['Item options'].guarded, false);
+    assert.strictEqual(secs['Admin controls'].guarded, true, 'heading directly under an if is guarded');
+    fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ── JSX: resolved component with markers, ternary-guarded component, Dialog primitive skipped ──
+{
+    const root = project({
+        'src/pages/List.tsx': [
+            'import Toolbar from "./Toolbar";',
+            'import EmptyState from "./EmptyState";',
+            'import { Dialog } from "@ui/dialog";',
+            'export default function List({ items }) {',
+            '  return (<div>',
+            '    <Toolbar />',
+            '    {items.length === 0 ? <EmptyState /> : null}',
+            '    <Dialog open={false}><p>hidden</p></Dialog>',
+            '  </div>);',
+            '}',
+        ].join('\n'),
+        'src/pages/Toolbar.tsx': 'export default () => <div><button>New item</button><input placeholder="Search items" /></div>;',
+        'src/pages/EmptyState.tsx': 'export default () => <h2>Nothing here yet</h2>;',
+    });
+    const c = census(root, 'src/pages/List.tsx');
+    const inc = byName(c);
+    assert.strictEqual(inc.Toolbar.kind, 'unconditional');
+    assert.deepStrictEqual(inc.Toolbar.markers.sort(), ['New item', 'Search items']);
+    assert.strictEqual(inc.EmptyState.kind, 'conditional', 'ternary on the same line is a guard');
+    assert(!('Dialog' in inc), 'UI primitives are not includes');
+    fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ── Blade + Django: include syntaxes resolve and classify ──
+{
+    const root = project({
+        'resources/views/orders/show.blade.php': [
+            '@include("partials.summary")',
+            '@if($order->refundable)',
+            '  @include("partials.refund")',
+            '@endif',
+            '<x-drawer name="notes">…</x-drawer>',
+        ].join('\n'),
+        'resources/views/partials/summary.blade.php': '<h3>Order summary</h3><th>Total</th>',
+        'resources/views/partials/refund.blade.php': '<button>Refund order</button>',
+        'templates/reports/index.html': '{% include "reports/_filters.html" %}\n{% if perms.export %}{% include "reports/_export.html" %}{% endif %}',
+        'templates/reports/_filters.html': '<label>Date range</label>',
+        'templates/reports/_export.html': '<button>Export CSV</button>',
+    });
+    const b = byName(census(root, 'resources/views/orders/show.blade.php'));
+    assert.strictEqual(b['partials.summary'].kind, 'unconditional');
+    assert.deepStrictEqual(b['partials.summary'].markers, ['Order summary', 'Total']);
+    assert.strictEqual(b['partials.refund'].kind, 'conditional');
+    assert.strictEqual(b['x-drawer'].kind, 'overlay');
+    const d = byName(census(root, 'templates/reports/index.html'));
+    assert.strictEqual(d['reports/_filters.html'].kind, 'unconditional');
+    assert.deepStrictEqual(d['reports/_filters.html'].markers, ['Date range']);
+    assert.strictEqual(d['reports/_export.html'].kind, 'conditional');
+    fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ── markers: sentences, templating and identifiers are not markers ──
+assert.deepStrictEqual(extractMarkers('<h2>Settings</h2><p>You are not allowed to do this.</p><button>{{ t("x") }}</button><th>createdAt</th><label>Display name</label>'),
+    ['Settings', 'Display name']);
+assert.deepStrictEqual(includeRefs('/nonexistent-root', 'nope.erb'), []);
+
+console.log('include_census tests passed');

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

@@ -0,0 +1,49 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { verifyLabelEvidence } = require('./label_evidence');
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'rtfm-labels-'));
+const write = (file, text) => { fs.mkdirSync(path.dirname(path.join(root, file)), {recursive:true}); fs.writeFileSync(path.join(root, file), text); };
+const template = '<%= form_with(model: @new_record, url: records_path) do |form| %>\n<%= form.submit class: "btn" %>\n<% end %>';
+const model = 'class APIKey < ActiveRecord::Base\n  belongs_to :account\nend';
+const binding = 'def index\n  @new_record = APIKey.new\nend';
+const evidence = {string:'Create API key', found_in:'app/views/form.erb', generated:{kind:'rails_submit',locale:'en',action:'create',binding:'@new_record',binding_source:'app/controllers/records_controller.rb',model_source:'app/models/api_key.rb'}};
+function reset() {
+    fs.rmSync(root, {recursive:true,force:true}); fs.mkdirSync(root);
+    write(evidence.found_in, template); write(evidence.generated.binding_source, binding); write(evidence.generated.model_source, model);
+    write('config/initializers/inflections.rb', "# inflect.human /bad/, 'Wrong'\nActiveSupport::Inflector.inflections(:en) do |inflect|\n  inflect.acronym 'API'\nend");
+}
+const check = (entry=evidence) => verifyLabelEvidence(entry, null, root);
+try {
+    reset(); assert.equal(check().ok, true, JSON.stringify(check()));
+    assert.match(check({...evidence,string:'Create a banana'}).error, /contradicts source/);
+    assert.match(check({...evidence,generated:{...evidence.generated,action:'update'}}).error, /create\/update state/);
+    write(evidence.generated.binding_source, '@new_record = APIKey.find(params[:id])');
+    assert.equal(check({...evidence,string:'Update API key',generated:{...evidence.generated,action:'update'}}).ok, true);
+    for (const [file, text, expected] of [
+        [evidence.found_in, template.replace('form.submit class:', 'form.submit "Delete", class:'), /default submit/],
+        [evidence.found_in, template.replace('@new_record','@unrelated'), /bound to this model/],
+        [evidence.found_in, template + template, /single form_with/],
+        [evidence.generated.model_source, model.replace('APIKey', 'DifferentModel'), /create\/update state/],
+        [evidence.generated.binding_source, binding + '\n@new_record = APIKey.find(1)', /unambiguous/],
+        [evidence.generated.model_source, model.replace('belongs_to :account', 'def self.model_name; other; end'), /custom model/],
+        ['config/locales/en.yml', 'en:\n  helpers:\n    submit:\n      create: Add %{model}', /runtime resolver/],
+        ['config/locales/en.yml', 'en:\n  activerecord:\n    models:\n      api_key: Credential', /runtime resolver/],
+        ['config/application.rb', 'config.i18n.default_locale = :fr', /runtime resolver/],
+        ['config/initializers/inflections.rb', "ActiveSupport::Inflector.inflections(:en) do |i|\n i.human 'api_key', 'Credential'\nend", /custom inflections/],
+    ]) { reset(); write(file,text); assert.equal(check().ok,false, file); assert.match(check().error,expected); }
+    reset();
+    assert.equal(check({...evidence,generated:{kind:'trust_me'}}).ok,false);
+    assert.equal(check({...evidence,found_in:'../outside'}).ok,false);
+    assert.equal(check({...evidence,generated:undefined,derivation:'Rails does this'}).ok,false);
+    write('config/locales/en.yml','en:\n  button: Create API key');
+    assert.equal(check({string:'Create API key',found_in:'config/locales/en.yml'}).ok,true);
+    assert.equal(check({string:'Invented',found_in:'config/locales/en.yml'}).ok,false);
+    reset(); write(evidence.generated.model_source,'class InvoiceLine < ApplicationRecord\nend'); write(evidence.generated.binding_source,'@new_record = InvoiceLine.new');
+    assert.equal(check({...evidence,string:'Create Invoice line'}).ok,true);
+    reset(); write(evidence.generated.model_source,'class OAuthToken < ApplicationRecord\nend'); write(evidence.generated.binding_source,'@new_record = OAuthToken.new');
+    write('config/initializers/inflections.rb', "ActiveSupport::Inflector.inflections(:en) do |i|\n i.acronym 'OAuth'\nend");
+    assert.equal(check({...evidence,string:'Create OAuth token'}).ok,true);
+    console.log('Generated and literal label evidence tests passed');
+} finally {fs.rmSync(root,{recursive:true,force:true});}

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

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+// `dir` doubles as the output dir and the project dir, so a project map lands
+// at <dir>/.rtfm/project_map.json and mockups at <dir>/block_<id>.html.
+function run(article, { viewSources = { blocks: [] }, projectMap = null, files = {}, env = {} } = {}) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rtfm-block-copy-'));
+    fs.writeFileSync(path.join(dir, 'article.json'), JSON.stringify(article));
+    fs.writeFileSync(path.join(dir, 'view_sources.json'), JSON.stringify(viewSources));
+    if (projectMap) { fs.mkdirSync(path.join(dir, '.rtfm')); fs.writeFileSync(path.join(dir, '.rtfm', 'project_map.json'), JSON.stringify(projectMap)); }
+    for (const [name, text] of Object.entries(files)) { fs.mkdirSync(path.dirname(path.join(dir, name)), { recursive: true }); fs.writeFileSync(path.join(dir, name), text); }
+    const result = spawnSync(process.execPath, [path.join(__dirname, 'lint_article_copy.js'), dir, dir], { encoding: 'utf8', env: { ...process.env, ...env } });
+    const report = JSON.parse(fs.readFileSync(path.join(dir, 'article_lint_report.json'), 'utf8'));
+    fs.rmSync(dir, { recursive: true, force: true });
+    return { result, report };
+}
+const warningsOf = (check, id) => check.report.blocks.find(block => block.block_id === id).warnings;
+const section = (id, content, extra = {}) => ({ id, type: 'section', presentation: 'numbered', title: 'Run it', content, has_image: false, ...extra });
+const howTo = (...middle) => ({
+    schema_version: 2, title: 'How to send a message', article_type: 'how-to',
+    blocks: [
+        { id: 'introduction', type: 'prose', presentation: 'lead', content: 'Send a message from the terminal.' },
+        ...middle,
+        { id: 'summary', type: 'prose', presentation: 'summary', title: 'Summary', content: 'The message is sent.' },
+    ],
+});
+const FENCE = '```';
+
+const concept = {
+    schema_version: 2,
+    title: 'What is Meetily?',
+    article_type: 'concept',
+    blocks: [
+        { id: 'introduction', type: 'prose', presentation: 'lead', content: 'Meetily records and organises meetings.' },
+        { id: 'how-it-works', type: 'section', presentation: 'plain', title: 'How it works', content: 'Meetily turns conversations into useful notes.', has_image: false },
+        { id: 'summary', type: 'prose', presentation: 'summary', title: 'Summary', content: 'Use Meetily to keep meeting knowledge accessible.' },
+    ],
+};
+let check = run(concept);
+assert.strictEqual(check.result.status, 0, check.result.stdout + check.result.stderr);
+assert.strictEqual(check.report.all_passed, true);
+assert.deepStrictEqual(check.report.blocks.map(block => block.block_id), ['introduction', 'how-it-works', 'summary']);
+
+check = run({ title: 'Legacy', article_type: 'how-to', introduction: 'Old', steps: [] });
+assert.strictEqual(check.result.status, 1);
+assert(check.report.global_errors.some(error => error.includes('schema_version')));
+
+check = run({ ...concept, blocks: [...concept.blocks, { ...concept.blocks[1] }] });
+assert.strictEqual(check.result.status, 1);
+assert(check.report.global_errors.some(error => error.includes('duplicated')));
+
+// ---- Fence placement is schema-hard ---------------------------------------
+const leadFence = howTo(section('run', 'Run the command.'));
+leadFence.blocks[0].content = `Install it first.\n${FENCE}bash\nnpm install\n${FENCE}`;
+check = run(leadFence);
+assert.strictEqual(check.result.status, 1);
+assert(check.report.global_errors.some(error => error.includes('lead prose') && error.includes('fenced code block')));
+check = run(leadFence, { env: { RTFM_LINT_MODE: 'warn' } });
+assert.strictEqual(check.result.status, 1, 'fence placement stays hard under warn mode');
+
+check = run(howTo(section('run', 'Run the command.'), { id: 'prerequisites', type: 'list', presentation: 'checklist', title: 'Prerequisites', items: ['Node installed', `${FENCE}\nnpm -v\n${FENCE}`] }));
+assert.strictEqual(check.result.status, 1);
+assert(check.report.global_errors.some(error => error.includes('items[1]') && error.includes('inline-only')));
+
+check = run(howTo(section('run', `Run the command.\n${FENCE}bash\ntgt --help`)));
+assert.strictEqual(check.result.status, 1);
+assert(check.report.global_errors.some(error => error.includes('unclosed')));
+
+// ---- Fences in sections and the summary are fine; code never counts as prose --
+const fenced = howTo(section('run', `Open a terminal. Run the command below. Wait for it to finish.\n${FENCE}bash\necho a.b. c. d.\n${FENCE}`));
+fenced.blocks[2].content = `Wrap up with:\n${FENCE}bash\ntgt --send-message "Alice" "Hi"\n${FENCE}`;
+check = run(fenced);
+assert.strictEqual(check.result.status, 0, check.result.stdout + check.result.stderr);
+assert(!check.report.global_warnings.some(warning => warning.includes('exceeds')), JSON.stringify(check.report.global_warnings));
+assert.deepStrictEqual(check.report.metrics, { inline_code_spans: 0, fenced_blocks: 2, untagged_fences: 0 });
+
+check = run(howTo(section('run', `Run the command.\n${FENCE}\ntgt --help\n${FENCE}`)));
+assert.strictEqual(check.result.status, 0);
+assert(warningsOf(check, 'run').some(warning => warning.includes('without a language tag')));
+assert(check.result.stdout.includes('[WARN] block run:'), 'block warnings are printed for the model');
+
+check = run(howTo(section('run', `${FENCE}bash\ntgt --help\n${FENCE}\nThis prints the options.`)));
+assert.strictEqual(check.result.status, 0);
+assert(warningsOf(check, 'run').some(warning => warning.includes('starts with a code block')));
+
+// ---- Code-as-bold probe ----------------------------------------------------
+const terminalMap = { app_type: 'terminal', cli_metadata: { binary: 'tgt' } };
+check = run(howTo(section('run', 'Run **tgt --help** and pass **--send-message**; edit **~/.config/tgt/config.toml**. Select **Send**.')), { projectMap: terminalMap });
+assert.strictEqual(check.result.status, 0);
+const bold = warningsOf(check, 'run');
+assert(bold.some(warning => warning.includes('"tgt --help" looks like a command')), JSON.stringify(bold));
+assert(bold.some(warning => warning.includes('"--send-message" looks like a flag')));
+assert(bold.some(warning => warning.includes('config.toml" looks like a path')));
+assert(bold.some(warning => warning.includes('bold UI name "Send"')), 'plain labels still go through the bold check');
+
+check = run(howTo(section('run', 'Run **`tgt --help`**.')));
+assert(warningsOf(check, 'run').some(warning => warning.includes('bolds inline code')));
+
+// ---- Inline-code fidelity: warn only, dash/underscore-insensitive ----------
+const sources = { blocks: [{ block_id: 'run', verbatim_evidence: ['send_message', 'Usage: tgt [OPTIONS]'] }] };
+check = run(howTo(section('run', 'Pass `--send-message` to `tgt`, then try `--dry-run`.')), { viewSources: sources });
+assert.strictEqual(check.result.status, 0);
+const code = warningsOf(check, 'run');
+assert(!code.some(warning => warning.includes('--send-message')), JSON.stringify(code));
+assert(code.some(warning => warning.includes('"--dry-run" appears in none')), JSON.stringify(code));
+assert(!code.some(warning => warning.includes('"tgt"')), 'plain single words are not grounded');
+check = run(howTo(section('run', 'Try `--dry-run`.')));
+assert.strictEqual(warningsOf(check, 'run').length, 0, 'no sources resolved, nothing to check against');
+
+// ---- Redundant command screenshot on terminal projects ----------------------
+const cmdOnly = '<div class="terminal-line"><span class="terminal-prompt">$</span><span class="terminal-cmd">tgt --help</span></div>';
+check = run(howTo(section('run', 'Run the command.', { has_image: true })), { projectMap: terminalMap, files: { 'block_run.html': cmdOnly } });
+assert(warningsOf(check, 'run').some(warning => warning.includes('spends a screenshot on a typed command')));
+check = run(howTo(section('run', 'Run the command.', { has_image: true })), { projectMap: terminalMap, files: { 'block_run.html': cmdOnly + '<span class="terminal-output">Usage: tgt [OPTIONS]</span>' } });
+assert(!warningsOf(check, 'run').some(warning => warning.includes('spends a screenshot')));
+check = run(howTo(section('run', 'Run the command.', { has_image: true })), { files: { 'block_run.html': cmdOnly } });
+assert(!warningsOf(check, 'run').some(warning => warning.includes('spends a screenshot')), 'web projects are not checked');
+
+console.log('lint_article_copy block-contract tests passed');
+
+// Structured generated evidence must pass both copy and screenshot source checks.
+const generatedLabel = {string:'Create API key',found_in:'form.erb',generated:{kind:'rails_submit',locale:'en',action:'create',binding:'@record',binding_source:'controller.rb',model_source:'model.rb'}};
+const generatedFiles = {
+    'form.erb': '<%= form_with(model: @record) do |f| %><%= f.submit %><% end %>',
+    'controller.rb': '@record = APIKey.new',
+    'model.rb': 'class APIKey < ActiveRecord::Base\nend',
+    'config/initializers/inflections.rb': "ActiveSupport::Inflector.inflections(:en) do |i|\n i.acronym 'API'\nend",
+};
+const generatedSources = {blocks:[{block_id:'create',primary_view:'form.erb',verbatim_evidence:[generatedLabel]}]};
+check = run(howTo(section('create','Click **Create API key**.',{has_image:true})),{viewSources:generatedSources,files:generatedFiles});
+assert.equal(check.result.status,0,JSON.stringify(check.report));
+generatedLabel.string = 'Delete everything';
+check = run(howTo(section('create','Click **Delete everything**.',{has_image:true})),{viewSources:generatedSources,files:generatedFiles});
+assert.equal(check.result.status,1,'unverified generated claims must not enter the copy corpus');