@nac3/forge-cli 0.2.0-alpha.1

package/dist/commands/migrate.js

@@ -0,0 +1,1410 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import prompts from 'prompts';
+import { c, header } from '../ui/colors.js';
+import { auditProject } from '../migrate/audit.js';
+import { applyMigration } from '../migrate/apply.js';
+import { runHtmlSilent, prepareHtmlAssisted, finalizeHtmlAssisted, } from '../migrate/html-orchestrator.js';
+import { aiDecorateFile } from '../migrate/ai-decorator.js';
+import { aiApplyProject } from '../migrate/ai-apply.js';
+import { readOverrides, writeOverrides, computeBaselineHash, applyOverrides, searchManifest, OVERRIDES_VERSION, } from '../migrate/overrides.js';
+import { unifiedDiff } from '../migrate/diff.js';
+import { loadLicense, isPaidSeat } from '../license/index.js';
+export function registerMigrateCommand(program) {
+    program
+        .command('migrate <repo>')
+        .description('Audit or apply a NAC-3 migration to an existing project (React or HTML).')
+        .option('--audit', 'produce a migration report without mutating files (default)', true)
+        .option('--apply', 'execute the proposed AST migration on .tsx/.jsx (requires paid seat)')
+        .option('--html', 'silent HTML walker -- auto-apply on .html files (paid seat)')
+        .option('--assisted', 'HTML walker with CLI prompts for ambiguous elements (paid seat)')
+        .option('--ai-silent', 'AI-powered (Claude) silent decoration of an HTML file (paid seat)')
+        .option('--ai-assisted', 'AI-powered (Claude) decoration with CLI prompts on ambiguity (paid seat)')
+        .option('--ai-model <id>', 'Anthropic model id (default: claude-sonnet-4-6)')
+        .option('--ai-hint <text>', 'Page hint passed to Claude (e.g. "calculator app")')
+        .option('--ai-out <dir>', 'Output directory for decorated HTML + manifest (default: <repo>-ai-<mode>)')
+        .option('--with-pilot', 'inject Yujin Pilot bundle into the decorated output')
+        .option('--ai-search <query>', 'search the active manifest in <repo>/manifest.json for elements matching <query>')
+        .option('--ai-override <nacId>', 'interactively re-decorate one element (writes to overrides.json + patches index.html + manifest.json)')
+        .option('--no-overrides', 'skip applying overrides.json on a --ai-silent re-run')
+        .option('--ai-apply', 'AI-powered JSX decoration: walk JSX/TSX files in <repo>/<subdir>, decorate each, aggregate manifest (paid seat)')
+        .option('--ai-plugin-slug <s>', 'plugin slug hint for --ai-apply (default: model derives from project)')
+        .option('--ai-concurrency <n>', 'parallel LLM calls during --ai-apply (default 4, max 8)')
+        .option('--with-i18n-tags', 'also emit data-i18n="<key>" on user-facing text nodes + write i18n/<lang>.json catalogs (paid seat extra to --ai-apply)')
+        .option('--i18n-langs <list>', 'comma-separated locales for --with-i18n-tags (default: en,es,pt,fr,it,de,ja,zh,hi,ar)')
+        .option('--multi-page', 'with --ai-silent / --ai-assisted on a directory, decorate every .html file (not just index.html); shared plugin_slug across pages')
+        .option('--dry-run', 'with --apply / --html / --assisted / --ai-silent / --ai-assisted, compute edits without writing files (prints unified diff for ai modes)')
+        .option('-y, --yes', 'skip confirmation prompts (CI mode)')
+        .option('-o, --out <path>', 'write the audit report to a JSON file')
+        .option('--subdir <name>', 'subdirectory to scan under <repo> (default: src)', 'src')
+        .option('--threshold <num>', 'confidence threshold for silent auto-apply (default 0.6)')
+        .action(async (repo, opts) => {
+        if (opts.aiSearch) {
+            await runAiSearch(repo, opts);
+            return;
+        }
+        if (opts.aiOverride) {
+            await runAiOverride(repo, opts);
+            return;
+        }
+        if (opts.aiApply) {
+            await runAiApply(repo, opts);
+            return;
+        }
+        if (opts.aiAssisted) {
+            if (opts.multiPage)
+                await runAiHtmlMultiPage(repo, opts, 'assisted');
+            else
+                await runAiHtml(repo, opts, 'assisted');
+            return;
+        }
+        if (opts.aiSilent) {
+            if (opts.multiPage)
+                await runAiHtmlMultiPage(repo, opts, 'silent');
+            else
+                await runAiHtml(repo, opts, 'silent');
+            return;
+        }
+        if (opts.assisted) {
+            await runAssistedHtml(repo, opts);
+            return;
+        }
+        if (opts.html) {
+            await runSilentHtml(repo, opts);
+            return;
+        }
+        if (opts.apply) {
+            await runApply(repo, opts);
+            return;
+        }
+        await runAudit(repo, opts);
+    });
+}
+export async function runAudit(repo, opts) {
+    header('Yujin Forge -- migration audit');
+    console.log('');
+    const projectRoot = path.resolve(process.cwd(), repo);
+    let report;
+    try {
+        report = await auditProject({ projectRoot, scanSubdir: opts.subdir });
+    }
+    catch (err) {
+        console.error(c.error(err instanceof Error ? err.message : String(err)));
+        process.exitCode = 1;
+        return;
+    }
+    console.log('  Project:        ' + c.dim(projectRoot));
+    console.log('  Files scanned:  ' + report.scanned_files);
+    console.log('  Candidates:     ' + report.summary.total);
+    console.log('');
+    console.log('  ' + c.brand('action ') + ' ' + report.summary.actions);
+    console.log('  ' + c.brand('field  ') + ' ' + report.summary.fields);
+    console.log('  ' + c.brand('region ') + ' ' + report.summary.regions);
+    console.log('  ' + c.dim('already tagged ') + report.summary.already_tagged);
+    console.log('');
+    if (opts.out) {
+        const outPath = path.resolve(process.cwd(), opts.out);
+        await fs.writeFile(outPath, JSON.stringify(report, null, 2), 'utf-8');
+        console.log(c.success('Wrote report to ' + outPath));
+    }
+    else if (report.candidates.length > 0) {
+        const preview = report.candidates.slice(0, 10);
+        console.log(c.dim('First ' + preview.length + ' candidate(s):'));
+        for (const cand of preview) {
+            const tag = cand.already_tagged ? c.dim('[ok] ') : '';
+            console.log('  ' + tag + cand.file + ':' + cand.line + '  '
+                + c.brand(cand.kind) + '  ' + c.dim(cand.element + '  ->  ' + cand.proposed_id));
+        }
+        if (report.candidates.length > preview.length) {
+            console.log(c.dim('  ... + ' + (report.candidates.length - preview.length) + ' more (use --out to dump JSON)'));
+        }
+    }
+    if (report.summary.total === 0) {
+        console.log(c.success('Nothing to migrate -- project already looks NAC-3 clean.'));
+    }
+    else {
+        const todo = report.summary.total - report.summary.already_tagged;
+        console.log('');
+        console.log(c.dim(todo + ' element(s) need a data-nac-id. Run ')
+            + c.code('yf migrate ' + repo + ' --apply')
+            + c.dim(' (paid seat) to add them.'));
+    }
+}
+export async function runApply(repo, opts) {
+    header('Yujin Forge -- migration apply' + (opts.dryRun ? ' (dry run)' : ''));
+    console.log('');
+    const lic = await loadLicense();
+    if (!isPaidSeat(lic)) {
+        console.error(c.error('migrate --apply requires a paid seat.'));
+        console.error('  ' + c.dim('Trial mode produces the audit only. Run ')
+            + c.code('yf license activate --key <jwt>')
+            + c.dim(' to install a seat.'));
+        process.exitCode = 1;
+        return;
+    }
+    const projectRoot = path.resolve(process.cwd(), repo);
+    try {
+        const result = await applyMigration({
+            projectRoot,
+            scanSubdir: opts.subdir,
+            dryRun: !!opts.dryRun,
+        });
+        console.log('  Project:        ' + c.dim(projectRoot));
+        console.log('  Files scanned:  ' + result.report.scanned_files);
+        console.log('  Files edited:   ' + result.edited_files.length);
+        console.log('  Skipped (already tagged): ' + result.skipped_already_tagged);
+        console.log('');
+        for (const e of result.edited_files) {
+            console.log('  ' + c.success('+ ') + e.file + c.dim(' (' + e.inserts + ' insert(s))'));
+        }
+        console.log('');
+        if (opts.dryRun) {
+            console.log(c.warn('Dry run -- no files were written.'));
+            console.log(c.dim('Re-run without --dry-run to apply.'));
+        }
+        else if (result.edited_files.length === 0) {
+            console.log(c.success('Nothing to do -- project is already NAC-3 clean.'));
+        }
+        else {
+            console.log(c.success('Migration applied. Run your test suite to verify.'));
+        }
+        if (opts.out) {
+            const outPath = path.resolve(process.cwd(), opts.out);
+            await fs.writeFile(outPath, JSON.stringify(result.report, null, 2), 'utf-8');
+            console.log(c.dim('Audit report written to ' + outPath));
+        }
+    }
+    catch (err) {
+        console.error(c.error(err instanceof Error ? err.message : String(err)));
+        process.exitCode = 1;
+    }
+}
+/* ============================================================
+   HTML walker -- silent + assisted modes (paso 4 of the V24-04
+   benchmark roadmap; eventual destination of the auto-decoration
+   product layer cited in SPEC.md sec 9.)
+   ============================================================ */
+export async function runSilentHtml(repo, opts) {
+    header('Yujin Forge -- HTML walker (silent)' + (opts.dryRun ? ' (dry run)' : ''));
+    console.log('');
+    const lic = await loadLicense();
+    if (!isPaidSeat(lic)) {
+        console.error(c.error('migrate --html requires a paid seat.'));
+        process.exitCode = 1;
+        return;
+    }
+    const inputPath = path.resolve(process.cwd(), repo);
+    const threshold = opts.threshold ? Number(opts.threshold) : 0.6;
+    try {
+        const result = await runHtmlSilent({
+            inputPath,
+            confidenceThreshold: threshold,
+            dryRun: !!opts.dryRun,
+        });
+        console.log('  Input:                ' + c.dim(inputPath));
+        console.log('  Files walked:         ' + result.files.length);
+        console.log('  Total applied:        ' + result.total_applied);
+        console.log('  Skipped low-conf:     ' + result.total_skipped_low_conf);
+        console.log('  Already decorated:    ' + result.total_already_decorated);
+        console.log('  Decisions persisted:  ' + result.decisions_added);
+        console.log('');
+        for (const f of result.files) {
+            const rel = path.relative(process.cwd(), f.filePath);
+            const tag = f.wrote ? c.success('+ ') : (opts.dryRun ? c.warn('~ ') : c.dim('. '));
+            console.log('  ' + tag + rel + c.dim(' (' + f.applied.length + ' applied, '
+                + f.skipped_low_confidence.length + ' skipped, '
+                + f.skipped_already_decorated + ' already)'));
+        }
+        if (opts.dryRun) {
+            console.log('');
+            console.log(c.warn('Dry run -- no files were written.'));
+        }
+        else if (result.total_applied === 0) {
+            console.log('');
+            console.log(c.success('Nothing to apply.'));
+        }
+        else {
+            console.log('');
+            console.log(c.success('HTML decoration applied. Decisions saved to .yujin/nac-decisions.json'));
+        }
+    }
+    catch (err) {
+        console.error(c.error(err instanceof Error ? err.message : String(err)));
+        process.exitCode = 1;
+    }
+}
+export async function runAssistedHtml(repo, opts) {
+    header('Yujin Forge -- HTML walker (assisted)' + (opts.dryRun ? ' (dry run)' : ''));
+    console.log('');
+    const lic = await loadLicense();
+    if (!isPaidSeat(lic)) {
+        console.error(c.error('migrate --assisted requires a paid seat.'));
+        process.exitCode = 1;
+        return;
+    }
+    const inputPath = path.resolve(process.cwd(), repo);
+    const threshold = opts.threshold ? Number(opts.threshold) : 0.85;
+    try {
+        const queue = await prepareHtmlAssisted({
+            inputPath,
+            confidenceThreshold: threshold,
+            dryRun: !!opts.dryRun,
+        });
+        console.log('  Input:                  ' + c.dim(inputPath));
+        console.log('  Files walked:           ' + queue.walkResults.length);
+        console.log('  Auto-apply (>= ' + threshold + '): ' + queue.auto_apply.length);
+        console.log('  Need review:            ' + queue.items.filter(i => !i.prior).length);
+        console.log('  Resuming prior:         ' + queue.items.filter(i => !!i.prior).length);
+        console.log('');
+        /* Collect decisions: auto + prior + manual. */
+        const decisions = [];
+        for (const c of queue.auto_apply) {
+            decisions.push({
+                fingerprint: c.fingerprint,
+                nac_id: c.proposed_id,
+                role: c.role,
+                verb: c.proposed_verb,
+                plugin: c.proposed_plugin,
+            });
+        }
+        for (const item of queue.items) {
+            if (item.prior) {
+                /* Reuse persisted decision without prompting. */
+                decisions.push({
+                    fingerprint: item.prior.fingerprint,
+                    nac_id: item.prior.nac_id,
+                    role: item.prior.role,
+                    verb: item.prior.verb,
+                    plugin: item.prior.plugin,
+                });
+            }
+        }
+        const toReview = queue.items.filter(i => !i.prior);
+        if (toReview.length === 0) {
+            console.log(c.dim('No candidates need manual review.'));
+        }
+        else if (opts.yes) {
+            console.log(c.dim('--yes: accepting all proposed values as-is.'));
+            for (const item of toReview) {
+                decisions.push(proposedToDecision(item.candidate));
+            }
+        }
+        else {
+            for (let i = 0; i < toReview.length; i++) {
+                const item = toReview[i];
+                if (!item)
+                    continue;
+                const cand = item.candidate;
+                console.log(c.brand('[' + (i + 1) + '/' + toReview.length + '] ')
+                    + path.relative(process.cwd(), item.filePath)
+                    + c.dim('  conf=' + cand.confidence.toFixed(2)));
+                console.log(c.dim('  text:        ') + (cand.text || '(empty)'));
+                if (cand.aria_label)
+                    console.log(c.dim('  aria-label:  ') + cand.aria_label);
+                console.log(c.dim('  tag:         ') + cand.tag);
+                console.log(c.dim('  proposed:    ') + cand.proposed_id);
+                console.log(c.dim('  role:        ') + cand.role + (cand.proposed_verb ? c.dim(' / verb=') + cand.proposed_verb : ''));
+                if (cand.verb_signal)
+                    console.log(c.dim('  why verb:    ') + cand.verb_signal);
+                const ans = await prompts([
+                    { type: 'select', name: 'action', message: 'Decide:',
+                        choices: [
+                            { title: 'Accept (use proposed)', value: 'accept' },
+                            { title: 'Edit nac_id...', value: 'edit_id' },
+                            { title: 'Change role...', value: 'edit_role' },
+                            { title: 'Change verb...', value: 'edit_verb' },
+                            { title: 'Skip this one', value: 'skip' },
+                            { title: 'Abort assisted walk', value: 'abort' },
+                        ],
+                    },
+                ]);
+                if (ans.action === 'abort') {
+                    console.log(c.warn('Aborted by user. Decisions made so far will not be persisted.'));
+                    return;
+                }
+                if (ans.action === 'skip')
+                    continue;
+                let nac_id = cand.proposed_id;
+                let role = cand.role;
+                let verb = cand.proposed_verb;
+                if (ans.action === 'edit_id') {
+                    const r = await prompts([{ type: 'text', name: 'v', message: 'nac_id:', initial: nac_id }]);
+                    if (r.v)
+                        nac_id = String(r.v);
+                }
+                if (ans.action === 'edit_role') {
+                    const r = await prompts([{ type: 'select', name: 'v', message: 'role:',
+                            choices: ['action', 'field', 'tab', 'region', 'option'].map(x => ({ title: x, value: x })) }]);
+                    if (r.v)
+                        role = r.v;
+                }
+                if (ans.action === 'edit_verb') {
+                    const r = await prompts([{ type: 'text', name: 'v', message: 'verb (empty to clear):',
+                            initial: verb || '' }]);
+                    verb = r.v ? String(r.v) : null;
+                }
+                decisions.push({ fingerprint: cand.fingerprint, nac_id, role, verb, plugin: cand.proposed_plugin });
+            }
+        }
+        /* Apply */
+        const result = await finalizeHtmlAssisted({
+            projectRoot: queue.projectRoot,
+            walkResults: queue.walkResults,
+            decisions,
+            dryRun: !!opts.dryRun,
+        });
+        console.log('');
+        console.log('  Total applied:        ' + result.total_applied);
+        console.log('  Decisions persisted:  ' + result.decisions_added);
+        for (const f of result.files) {
+            if (f.applied.length === 0)
+                continue;
+            const rel = path.relative(process.cwd(), f.filePath);
+            const tag = f.wrote ? c.success('+ ') : c.warn('~ ');
+            console.log('  ' + tag + rel + c.dim(' (' + f.applied.length + ' applied)'));
+        }
+        console.log('');
+        if (opts.dryRun) {
+            console.log(c.warn('Dry run -- no files were written.'));
+        }
+        else {
+            console.log(c.success('Assisted walk complete. Decisions saved to .yujin/nac-decisions.json'));
+        }
+    }
+    catch (err) {
+        console.error(c.error(err instanceof Error ? err.message : String(err)));
+        process.exitCode = 1;
+    }
+}
+function proposedToDecision(c) {
+    return {
+        fingerprint: c.fingerprint,
+        nac_id: c.proposed_id,
+        role: c.role,
+        verb: c.proposed_verb,
+        plugin: c.proposed_plugin,
+    };
+}
+/* ===== AI-powered decoration (Claude) =====
+   Two modes:
+     - silent:   one-shot decoration. Take whatever the model returns.
+     - assisted: model can flag ambiguities; CLI prompts user; re-runs.
+   Input:  one HTML file (--repo points to the file OR to a dir
+           containing an index.html).
+   Output: <repo>-ai-<mode>/ with the decorated HTML + manifest.json.
+*/
+export async function runAiHtml(repo, opts, mode) {
+    header('Yujin Forge -- AI-powered NAC-3 decoration (' + mode + ')');
+    console.log('');
+    const inputPath = path.resolve(process.cwd(), repo);
+    let htmlPath;
+    let baseDir;
+    let jsCompanion;
+    /* Resolve: file vs dir. */
+    const stat = await fs.stat(inputPath).catch(() => null);
+    if (!stat) {
+        console.error(c.error('Path does not exist: ' + inputPath));
+        process.exitCode = 1;
+        return;
+    }
+    if (stat.isDirectory()) {
+        htmlPath = path.join(inputPath, 'index.html');
+        baseDir = inputPath;
+        const stat2 = await fs.stat(htmlPath).catch(() => null);
+        if (!stat2) {
+            console.error(c.error('No index.html in directory: ' + inputPath));
+            process.exitCode = 1;
+            return;
+        }
+        /* Heuristic: look for a sibling *.js with similar basename. */
+        const candidates = ['calc.js', 'app.js', 'main.js', 'script.js'];
+        for (const name of candidates) {
+            const p = path.join(baseDir, name);
+            if (await fs.stat(p).then(() => true, () => false)) {
+                jsCompanion = p;
+                break;
+            }
+        }
+    }
+    else {
+        htmlPath = inputPath;
+        baseDir = path.dirname(inputPath);
+        const stem = path.basename(inputPath, path.extname(inputPath));
+        const jsTry = path.join(baseDir, stem + '.js');
+        if (await fs.stat(jsTry).then(() => true, () => false))
+            jsCompanion = jsTry;
+    }
+    const outDir = opts.aiOut
+        ? path.resolve(process.cwd(), opts.aiOut)
+        : baseDir + '-ai-' + mode;
+    const dryRun = !!opts.dryRun;
+    if (!dryRun) {
+        await fs.mkdir(outDir, { recursive: true });
+        /* Copy companion CSS so the served output renders. */
+        for (const name of await fs.readdir(baseDir)) {
+            if (name.endsWith('.css')) {
+                await fs.copyFile(path.join(baseDir, name), path.join(outDir, name));
+            }
+        }
+        /* In silent mode the JS companion goes through unchanged; the runtime
+           reads attributes off the DOM. We still pass it to Claude so it knows
+           the verb hints, but the output is just decoration. */
+        if (jsCompanion) {
+            await fs.copyFile(jsCompanion, path.join(outDir, path.basename(jsCompanion)));
+        }
+    }
+    console.log('  Input HTML:     ' + c.dim(htmlPath));
+    if (jsCompanion)
+        console.log('  JS companion:   ' + c.dim(jsCompanion));
+    console.log('  Output dir:     ' + c.dim(outDir) + (dryRun ? c.warn(' (dry run -- nothing will be written)') : ''));
+    console.log('  Mode:           ' + c.brand(mode));
+    console.log('  Model:          ' + c.dim(opts.aiModel || 'claude-sonnet-4-6'));
+    if (opts.aiHint)
+        console.log('  Hint:           ' + c.dim(opts.aiHint));
+    console.log('');
+    const outHtmlPath = path.join(outDir, 'index.html');
+    const outManifestPath = path.join(outDir, 'manifest.json');
+    let result;
+    try {
+        result = await aiDecorateFile({
+            htmlPath, jsCompanionPath: jsCompanion,
+            outHtmlPath, outManifestPath,
+            mode, pluginHint: opts.aiHint, model: opts.aiModel,
+            dryRun,
+        });
+    }
+    catch (err) {
+        console.error(c.error(err instanceof Error ? err.message : String(err)));
+        process.exitCode = 1;
+        return;
+    }
+    if (dryRun) {
+        /* Read the source HTML for diffing against the proposed decoration.
+           The diff is unified-format on stdout; manifest is printed as a
+           capped preview (it is a brand-new artifact, so a side-by-side
+           diff against an empty file would be noise). */
+        const originalHtml = await fs.readFile(htmlPath, 'utf-8');
+        const diff = unifiedDiff(originalHtml, result.decorated_html, htmlPath, outHtmlPath);
+        console.log(c.warn('Dry run -- no files were written.'));
+        console.log('');
+        console.log('  ' + c.dim('plugin:   ') + result.plugin_slug);
+        console.log('  ' + c.dim('tokens:   ') + result.meta.input_tokens + ' in / ' + result.meta.output_tokens + ' out');
+        console.log('  ' + c.dim('cost:     ') + '$' + result.meta.cost_usd.toFixed(4));
+        console.log('  ' + c.dim('latency:  ') + result.meta.latency_ms + 'ms');
+        console.log('');
+        if (!diff) {
+            console.log(c.dim('No HTML changes (decorator returned source unchanged).'));
+        }
+        else {
+            console.log(c.brand('--- HTML diff ---'));
+            console.log(diff);
+        }
+        console.log('');
+        console.log(c.brand('--- Manifest preview (would write to ' + outManifestPath + ') ---'));
+        const manifestPreview = result.manifest_json.length > 4000
+            ? result.manifest_json.slice(0, 4000) + '\n... + ' + (result.manifest_json.length - 4000) + ' bytes'
+            : result.manifest_json;
+        console.log(manifestPreview);
+        console.log('');
+        console.log(c.dim('Would also create in ' + outDir + ':'));
+        console.log(c.dim('  - nac-bridge.js (NAC3 contract bridge, ~2KB)'));
+        console.log(c.dim('  - nac.browser.js (local copy of NAC runtime when available; otherwise CDN tag injected)'));
+        if (jsCompanion)
+            console.log(c.dim('  - ' + path.basename(jsCompanion) + ' (companion JS copied unchanged)'));
+        if (opts.withPilot)
+            console.log(c.dim('  - pilot.bundle.js + pilot.css (Yujin Pilot cockpit)'));
+        console.log(c.dim('And inject the NAC3 runtime + bridge + register tags into the decorated HTML.'));
+        console.log('');
+        console.log(c.dim('Re-run without --dry-run to apply.'));
+        return;
+    }
+    console.log(c.success('AI decoration written:'));
+    console.log('  ' + c.dim('html:     ') + outHtmlPath);
+    console.log('  ' + c.dim('manifest: ') + outManifestPath);
+    console.log('  ' + c.dim('plugin:   ') + result.plugin_slug);
+    console.log('  ' + c.dim('tokens:   ') + result.meta.input_tokens + ' in / ' + result.meta.output_tokens + ' out');
+    console.log('  ' + c.dim('cost:     ') + '$' + result.meta.cost_usd.toFixed(4));
+    console.log('  ' + c.dim('latency:  ') + result.meta.latency_ms + 'ms');
+    console.log('');
+    /* Assisted: handle ambiguities. The model flagged questions; we prompt
+       the user, then either re-issue (full second round) or just record
+       the answers as notes alongside the manifest. For MVP we record. */
+    if (mode === 'assisted' && result.ambiguities.length > 0) {
+        console.log(c.warn('Model flagged ' + result.ambiguities.length + ' ambiguous elements:'));
+        const answers = [];
+        for (const a of result.ambiguities) {
+            console.log('');
+            console.log('  ' + c.brand(a.kind.toUpperCase()) + ' ' + c.dim(a.id));
+            console.log('  Element: ' + c.dim(a.element_excerpt.slice(0, 100)));
+            console.log('  Question: ' + a.question);
+            const choices = a.options.map((o) => ({ title: o, value: o }));
+            choices.push({ title: '<custom...>', value: '__custom__' });
+            const pick = await prompts({
+                type: 'select',
+                name: 'choice',
+                message: 'Pick:',
+                choices,
+            });
+            let chosen = pick.choice;
+            if (chosen === '__custom__') {
+                const custom = await prompts({
+                    type: 'text',
+                    name: 'val',
+                    message: 'Custom value:',
+                });
+                chosen = custom.val || a.options[0];
+            }
+            answers.push({ id: a.id, kind: a.kind, question: a.question, answer: chosen });
+        }
+        const notesPath = path.join(outDir, 'assisted-answers.json');
+        await fs.writeFile(notesPath, JSON.stringify(answers, null, 2), 'utf-8');
+        console.log('');
+        console.log(c.success('Assisted answers saved: ') + notesPath);
+        console.log(c.dim('(Re-run --ai-assisted to fold them into a second decoration pass.)'));
+    }
+    else if (mode === 'assisted') {
+        console.log(c.dim('Model did not flag any ambiguities -- output matches a silent run.'));
+    }
+    /* Wire the decorated HTML so it is drop-in NAC3-ready:
+       1. Ensure <body data-nac-plugin="<slug>"> (LLM may have forgotten).
+       2. Inject NAC runtime <script> in <head>.
+       3. Emit nac-bridge.js next to index.html.
+       4. Inject <script src="nac-bridge.js"> + inline NAC.register before </body>.
+       5. Optionally inject Pilot bundle when --with-pilot is set. */
+    await wireDecoratedOutput({
+        outDir, pluginSlug: result.plugin_slug,
+        manifestJson: result.manifest_json,
+        withPilot: !!opts.withPilot,
+    });
+    /* Apply any stored selective overrides on top of the fresh
+       Silent output. First run with no overrides.json yet -> writes
+       a fresh file with the baseline_hash. Subsequent runs merge. */
+    await applyOrSeedOverrides(outDir, opts);
+    console.log('');
+    console.log(c.success('Done. Open ') + outDir + c.success(' to inspect.'));
+}
+async function applyOrSeedOverrides(outDir, opts) {
+    const htmlPath = path.join(outDir, 'index.html');
+    const manifestPath = path.join(outDir, 'manifest.json');
+    const html = await fs.readFile(htmlPath, 'utf-8');
+    const manifestSrc = await fs.readFile(manifestPath, 'utf-8');
+    const baselineHash = computeBaselineHash(html, manifestSrc);
+    const existing = await readOverrides(outDir);
+    if (opts.noOverrides) {
+        /* Explicit opt-out. Reset overrides.json to a fresh empty file
+           so the user starts clean from this baseline. */
+        await writeOverrides(outDir, {
+            version: OVERRIDES_VERSION,
+            baseline_hash: baselineHash,
+            overrides: [],
+        });
+        console.log(c.dim('Overrides reset (--no-overrides). Fresh baseline_hash recorded.'));
+        return;
+    }
+    if (!existing || existing.overrides.length === 0) {
+        /* First run -- seed the file. */
+        await writeOverrides(outDir, {
+            version: OVERRIDES_VERSION,
+            baseline_hash: baselineHash,
+            overrides: existing ? existing.overrides : [],
+        });
+        return;
+    }
+    /* Apply stored overrides on top of fresh Silent output. */
+    const manifest = JSON.parse(manifestSrc);
+    const { html: patchedHtml, manifest: patchedManifest, result: applyResult } = applyOverrides(html, manifest, existing.overrides);
+    await fs.writeFile(htmlPath, patchedHtml, 'utf-8');
+    await fs.writeFile(manifestPath, JSON.stringify(patchedManifest, null, 2), 'utf-8');
+    /* Update the file's baseline_hash to the post-merge state so the
+       next run is internally consistent. */
+    await writeOverrides(outDir, {
+        version: OVERRIDES_VERSION,
+        baseline_hash: computeBaselineHash(patchedHtml, JSON.stringify(patchedManifest)),
+        overrides: existing.overrides,
+    });
+    if (applyResult.applied.length > 0) {
+        console.log(c.success('Applied ') + applyResult.applied.length + c.success(' override(s) on top of Silent output.'));
+    }
+    if (applyResult.orphaned.length > 0) {
+        console.log(c.warn('Orphaned ') + applyResult.orphaned.length + c.warn(' override(s) -- pre-image missing in fresh manifest:'));
+        for (const ov of applyResult.orphaned) {
+            console.log('  - ' + c.dim(ov.match_value) + ' (' + (ov.rationale || 'no rationale') + ')');
+        }
+        console.log(c.dim('Orphaned entries are kept in overrides.json; remove manually if no longer needed.'));
+    }
+}
+/**
+ * Build the plan of pages a multi-page run would touch. Pure +
+ * testable: no LLM calls, no writes. Exported so the test suite can
+ * exercise the directory-walk logic against a fixture.
+ */
+export async function planMultiPageHtml(baseDir, outDir) {
+    const entries = await fs.readdir(baseDir, { withFileTypes: true });
+    const items = [];
+    for (const e of entries) {
+        if (!e.isFile() || !e.name.toLowerCase().endsWith('.html'))
+            continue;
+        const basename = e.name;
+        items.push({
+            htmlPath: path.join(baseDir, basename),
+            basename,
+            outHtmlPath: path.join(outDir, basename),
+            /* Sidecar manifest pattern: <basename>.manifest.json. The single
+               "index.html" page gets index.html.manifest.json so the runtime
+               can find it via a deterministic pathname-based lookup. */
+            outManifestPath: path.join(outDir, basename + '.manifest.json'),
+        });
+    }
+    items.sort((a, b) => {
+        /* Sort index.html first when present, then alphabetical. The
+           first-page slug becomes the canonical plugin_slug. */
+        if (a.basename === 'index.html')
+            return -1;
+        if (b.basename === 'index.html')
+            return 1;
+        return a.basename.localeCompare(b.basename);
+    });
+    return items;
+}
+/**
+ * Decorate every .html file in `baseDir`, share a plugin_slug across
+ * pages, write per-page outputs. Pure + DI-friendly so the call site
+ * (`runAiHtmlMultiPage`) can stay terse and the test suite can drive
+ * it without hitting the network.
+ */
+export async function decorateMultiPageHtml(opts) {
+    const plan = await planMultiPageHtml(opts.baseDir, opts.outDir);
+    if (plan.length === 0) {
+        throw new Error('No .html files found in ' + opts.baseDir + ' -- nothing to do with --multi-page.');
+    }
+    if (!opts.dryRun) {
+        await fs.mkdir(opts.outDir, { recursive: true });
+        /* Copy companion CSS once; shared across all pages. */
+        for (const name of await fs.readdir(opts.baseDir)) {
+            if (name.endsWith('.css')) {
+                await fs.copyFile(path.join(opts.baseDir, name), path.join(opts.outDir, name));
+            }
+        }
+    }
+    const pages = [];
+    let totalTokensIn = 0;
+    let totalTokensOut = 0;
+    let totalCost = 0;
+    let totalLatency = 0;
+    let canonicalSlug = opts.pluginHint || '';
+    for (const item of plan) {
+        /* Each page gets its own decoration. Subsequent pages receive the
+           slug from the first page as the pluginHint so the model uses
+           the same one. */
+        const hintForThisPage = canonicalSlug || opts.pluginHint;
+        const result = await aiDecorateFile({
+            htmlPath: item.htmlPath,
+            outHtmlPath: item.outHtmlPath,
+            outManifestPath: item.outManifestPath,
+            mode: opts.mode,
+            pluginHint: hintForThisPage,
+            model: opts.model,
+            dryRun: opts.dryRun,
+            ...(opts.decorator ? { decorator: opts.decorator } : {}),
+        });
+        if (!canonicalSlug)
+            canonicalSlug = result.plugin_slug;
+        /* If the model picked a slug that disagrees with the canonical
+           (because the hint wasn't strong enough on the first call), force
+           the canonical slug into the manifest + into the decorated HTML's
+           body[data-nac-plugin] before persisting downstream. */
+        let manifestJson = result.manifest_json;
+        let decoratedHtml = result.decorated_html;
+        if (result.plugin_slug !== canonicalSlug) {
+            manifestJson = result.manifest_json.replace(new RegExp('"plugin_slug"\\s*:\\s*"' + escapeRegex(result.plugin_slug) + '"'), '"plugin_slug":"' + canonicalSlug + '"');
+            decoratedHtml = result.decorated_html.replace(new RegExp('data-nac-plugin\\s*=\\s*"' + escapeRegex(result.plugin_slug) + '"'), 'data-nac-plugin="' + canonicalSlug + '"');
+        }
+        /* Recompute the diff against the source page. */
+        const original = await fs.readFile(item.htmlPath, 'utf-8');
+        const diff = unifiedDiff(original, decoratedHtml, item.htmlPath, item.outHtmlPath);
+        if (!opts.dryRun) {
+            /* aiDecorateFile already wrote the raw output; if we mutated
+               slug, overwrite with the corrected versions. */
+            if (decoratedHtml !== result.decorated_html || manifestJson !== result.manifest_json) {
+                await fs.writeFile(item.outHtmlPath, decoratedHtml, 'utf-8');
+                await fs.writeFile(item.outManifestPath, manifestJson, 'utf-8');
+            }
+            await wireDecoratedOutput({
+                outDir: opts.outDir,
+                pluginSlug: canonicalSlug,
+                manifestJson,
+                withPilot: opts.withPilot,
+                htmlBasename: item.basename,
+            });
+        }
+        pages.push({
+            item,
+            plugin_slug: canonicalSlug,
+            manifest_json: manifestJson,
+            decorated_html: decoratedHtml,
+            diff,
+            ambiguities_count: result.ambiguities.length,
+            tokens_in: result.meta.input_tokens,
+            tokens_out: result.meta.output_tokens,
+            cost_usd: result.meta.cost_usd,
+            latency_ms: result.meta.latency_ms,
+        });
+        totalTokensIn += result.meta.input_tokens;
+        totalTokensOut += result.meta.output_tokens;
+        totalCost += result.meta.cost_usd;
+        totalLatency += result.meta.latency_ms;
+    }
+    return {
+        plan,
+        pages,
+        plugin_slug: canonicalSlug,
+        total_tokens_in: totalTokensIn,
+        total_tokens_out: totalTokensOut,
+        total_cost_usd: totalCost,
+        total_latency_ms: totalLatency,
+    };
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+export async function runAiHtmlMultiPage(repo, opts, mode) {
+    header('Yujin Forge -- AI-powered NAC-3 decoration (' + mode + ', multi-page)');
+    console.log('');
+    const inputPath = path.resolve(process.cwd(), repo);
+    const stat = await fs.stat(inputPath).catch(() => null);
+    if (!stat || !stat.isDirectory()) {
+        console.error(c.error('--multi-page requires a directory input: ' + inputPath));
+        process.exitCode = 1;
+        return;
+    }
+    const outDir = opts.aiOut
+        ? path.resolve(process.cwd(), opts.aiOut)
+        : inputPath + '-ai-' + mode;
+    const dryRun = !!opts.dryRun;
+    console.log('  Input dir:      ' + c.dim(inputPath));
+    console.log('  Output dir:     ' + c.dim(outDir) + (dryRun ? c.warn(' (dry run -- nothing will be written)') : ''));
+    console.log('  Mode:           ' + c.brand(mode));
+    console.log('  Model:          ' + c.dim(opts.aiModel || 'claude-sonnet-4-6'));
+    if (opts.aiHint)
+        console.log('  Hint:           ' + c.dim(opts.aiHint));
+    console.log('');
+    let result;
+    try {
+        result = await decorateMultiPageHtml({
+            baseDir: inputPath,
+            outDir,
+            mode,
+            pluginHint: opts.aiHint,
+            ...(opts.aiModel ? { model: opts.aiModel } : {}),
+            dryRun,
+            withPilot: !!opts.withPilot,
+        });
+    }
+    catch (err) {
+        console.error(c.error(err instanceof Error ? err.message : String(err)));
+        process.exitCode = 1;
+        return;
+    }
+    console.log('  Pages walked:   ' + result.pages.length);
+    console.log('  Plugin slug:    ' + c.brand(result.plugin_slug));
+    console.log('  Tokens in/out:  ' + result.total_tokens_in + ' / ' + result.total_tokens_out);
+    console.log('  Total cost:     ' + '$' + result.total_cost_usd.toFixed(4));
+    console.log('  Total latency:  ' + result.total_latency_ms + 'ms');
+    console.log('');
+    if (dryRun) {
+        console.log(c.warn('Dry run -- no files were written.'));
+        console.log('');
+        for (const p of result.pages) {
+            console.log(c.brand('--- ' + p.item.basename + ' ---'));
+            if (!p.diff) {
+                console.log(c.dim('No HTML changes.'));
+            }
+            else {
+                console.log(p.diff);
+            }
+            console.log(c.dim('Would write manifest to ' + p.item.outManifestPath +
+                ' (' + p.manifest_json.length + ' bytes)'));
+            console.log('');
+        }
+        console.log(c.dim('Would also create in ' + outDir + ':'));
+        console.log(c.dim('  - nac-bridge.js (shared across pages)'));
+        console.log(c.dim('  - nac.browser.js (shared across pages)'));
+        if (opts.withPilot)
+            console.log(c.dim('  - pilot.bundle.js + pilot.css (shared across pages)'));
+        console.log(c.dim('And inject the NAC3 runtime + bridge + register tags into every decorated HTML.'));
+        console.log('');
+        console.log(c.dim('Re-run without --dry-run to apply.'));
+        return;
+    }
+    console.log(c.success('Multi-page decoration written:'));
+    for (const p of result.pages) {
+        console.log('  ' + c.success('+ ') + p.item.basename + c.dim(' -> ') + p.item.outHtmlPath
+            + c.dim(' (manifest: ') + path.basename(p.item.outManifestPath) + c.dim(')'));
+    }
+    console.log('');
+    console.log(c.success('Done. Open ') + outDir + c.success(' to inspect.'));
+}
+/* ------------------------------------------------------------------
+ * Post-processing: turn raw Claude output into a drop-in NAC3 app.
+ * ------------------------------------------------------------------ */
+const NAC_BRIDGE_SOURCE = `/* nac-bridge.js -- emitted by Yujin Forge.
+ *
+ * Every element decorated with data-nac-role="action" and data-nac-id
+ * gets its inline onclick handler routed through NAC.bindAction, so the
+ * runtime's nac:action:succeeded contract fires after the host handler
+ * runs. Without this bridge, NAC.click() times out after 5 s even
+ * though el.click() already executed the host's handler.
+ *
+ * SPA-aware: also watches DOM mutations and binds newly mounted action
+ * elements as routes change (React/Vue/Angular re-render dynamically).
+ *
+ * The plugin slug is read from <body data-nac-plugin="...">. The
+ * Forge-decorated HTML always sets that attribute.
+ */
+(function () {
+  function bindOne(el, slug) {
+    if (!el || el.getAttribute('data-nac-bound') === '1') return false;
+    var id = el.getAttribute('data-nac-id');
+    if (!id) return false;
+    var handler = el.onclick;
+    if (typeof handler !== 'function') {
+      /* No inline onclick (typical of React: handlers attach via the
+         synthetic event system, not as inline attributes). Bind a
+         no-op so the contract event fires when the host's
+         React-managed click runs in the same dispatch tick. */
+      handler = function () { /* host owns the click */ };
+    } else {
+      el.onclick = null;
+    }
+    try {
+      window.NAC.bindAction(el, handler, { plugin: slug, action_id: id });
+      el.setAttribute('data-nac-bound', '1');
+      return true;
+    } catch (e) {
+      if (window.console) console.error('[nac-bridge] bindAction failed for ' + id, e);
+      return false;
+    }
+  }
+
+  function bindAll(slug) {
+    /* Bind every clickable role (action, navigation, tab, option,
+       breadcrumb-item, step, pagination-item, confirm-button,
+       sort-control, filter-control). Skip role=region/field --
+       containers / value-holders, not click targets. NAC.click()
+       listens for nac:action:succeeded as fallback on non-action
+       roles, so bindAction's emission works universally. */
+    var els = document.querySelectorAll(
+      '[data-nac-role="action"][data-nac-id]:not([data-nac-bound]),' +
+      '[data-nac-role="navigation"][data-nac-id]:not([data-nac-bound]),' +
+      '[data-nac-role="tab"][data-nac-id]:not([data-nac-bound]),' +
+      '[data-nac-role="option"][data-nac-id]:not([data-nac-bound]),' +
+      '[data-nac-role="breadcrumb-item"][data-nac-id]:not([data-nac-bound]),' +
+      '[data-nac-role="step"][data-nac-id]:not([data-nac-bound]),' +
+      '[data-nac-role="pagination-item"][data-nac-id]:not([data-nac-bound]),' +
+      '[data-nac-role="confirm-button"][data-nac-id]:not([data-nac-bound]),' +
+      '[data-nac-role="sort-control"][data-nac-id]:not([data-nac-bound]),' +
+      '[data-nac-role="filter-control"][data-nac-id]:not([data-nac-bound])'
+    );
+    var bound = 0;
+    els.forEach(function (el) { if (bindOne(el, slug)) bound++; });
+    return bound;
+  }
+
+  function bridge() {
+    if (!window.NAC || typeof window.NAC.bindAction !== 'function') {
+      if (window.console) console.error('[nac-bridge] window.NAC.bindAction missing -- include nac.browser.js before this bridge.');
+      return;
+    }
+    var slug = document.body && document.body.getAttribute('data-nac-plugin');
+    if (!slug) {
+      if (window.console) console.error('[nac-bridge] <body data-nac-plugin="..."> missing -- cannot scope bindAction.');
+      return;
+    }
+
+    var initialBound = bindAll(slug);
+    if (window.console && console.info) {
+      console.info('[nac-bridge] initial bind: ' + initialBound + ' action(s) for plugin ' + slug);
+    }
+
+    /* SPA support: observe DOM mutations and bind any new action
+       elements that appear (route changes, modal mounts, etc). */
+    var pendingFrame = 0;
+    var totalLateBound = 0;
+    var obs = new MutationObserver(function (mutations) {
+      var hasAdded = false;
+      for (var i = 0; i < mutations.length; i++) {
+        if (mutations[i].addedNodes && mutations[i].addedNodes.length > 0) { hasAdded = true; break; }
+      }
+      if (!hasAdded) return;
+      if (pendingFrame) return;
+      pendingFrame = window.requestAnimationFrame(function () {
+        pendingFrame = 0;
+        var bound = bindAll(slug);
+        if (bound > 0) {
+          totalLateBound += bound;
+          if (window.console && console.debug) {
+            console.debug('[nac-bridge] late bind: ' + bound + ' action(s) (total late: ' + totalLateBound + ')');
+          }
+        }
+      });
+    });
+    obs.observe(document.body, { childList: true, subtree: true });
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', bridge);
+  } else {
+    bridge();
+  }
+})();
+`;
+const NAC_RUNTIME_CDN = 'https://unpkg.com/nac-spec@2.3.1/dist/nac.browser.js';
+async function resolveNacRuntime() {
+    /* Forge looks for the NAC3 browser bundle in this order:
+         1. node_modules of the current cwd (npm install nac-spec)
+         2. Sibling rpaforce checkout (../rpaforce/packages/nac/dist/...)
+         3. Sibling nac-spec checkout
+         4. None: fall back to the unpkg CDN tag.
+       Returning a local path lets the decorated app run offline + works
+       around Chromium ORB blocks on cross-origin script in some configs. */
+    const candidates = [
+        path.resolve(process.cwd(), 'node_modules', 'nac-spec', 'dist', 'nac.browser.js'),
+        path.resolve(process.cwd(), '..', 'rpaforce', 'packages', 'nac', 'dist', 'nac.browser.js'),
+        path.resolve(process.cwd(), '..', 'nac-spec', 'dist', 'nac.browser.js'),
+        path.resolve(process.cwd(), '..', 'nac-spec-yujinapp', 'runtime', 'js', 'nac.js'),
+    ];
+    for (const p of candidates) {
+        if (await fs.stat(p).then(() => true, () => false))
+            return p;
+    }
+    return null;
+}
+async function wireDecoratedOutput(opts) {
+    const htmlBasename = opts.htmlBasename || 'index.html';
+    const htmlPath = path.join(opts.outDir, htmlBasename);
+    let html = await fs.readFile(htmlPath, 'utf-8');
+    /* 1. Ensure data-nac-plugin on <body>. */
+    html = html.replace(/<body([^>]*)>/i, (match, attrs) => {
+        if (/data-nac-plugin\s*=/.test(attrs))
+            return match;
+        return `<body${attrs} data-nac-plugin="${opts.pluginSlug}">`;
+    });
+    /* 2. Inject NAC runtime in <head>. Skip if already present.
+          Prefer a local copy of nac.browser.js for offline + ORB safety. */
+    const runtimeSrcPath = await resolveNacRuntime();
+    let runtimeSrcAttr;
+    if (runtimeSrcPath) {
+        await fs.copyFile(runtimeSrcPath, path.join(opts.outDir, 'nac.browser.js'));
+        runtimeSrcAttr = 'nac.browser.js';
+    }
+    else {
+        runtimeSrcAttr = NAC_RUNTIME_CDN;
+    }
+    if (!/nac\.browser\.js|nac-spec.*nac\.browser|js\/nac\.js/.test(html)) {
+        const runtimeTag = `  <script src="${runtimeSrcAttr}"></script>`;
+        if (/<\/head>/i.test(html)) {
+            html = html.replace(/<\/head>/i, `${runtimeTag}\n</head>`);
+        }
+        else {
+            /* No <head>? Prepend at top of body. */
+            html = html.replace(/<body([^>]*)>/i, `<body$1>\n${runtimeTag}`);
+        }
+    }
+    /* 3. Emit nac-bridge.js next to index.html. */
+    await fs.writeFile(path.join(opts.outDir, 'nac-bridge.js'), NAC_BRIDGE_SOURCE, 'utf-8');
+    /* 4. Inject bridge + inline register before </body>. */
+    const registerInline = `<script>
+    (function () {
+      var manifest = ${opts.manifestJson};
+      function reg() {
+        if (window.NAC && window.NAC.register) {
+          try { window.NAC.register(manifest); }
+          catch (e) { if (window.console) console.error('NAC.register failed', e); }
+        }
+      }
+      if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', reg);
+      else reg();
+    })();
+  </script>`;
+    const tailInjection = [
+        '<script src="nac-bridge.js"></script>',
+        registerInline,
+    ].join('\n');
+    if (/<\/body>/i.test(html)) {
+        html = html.replace(/<\/body>/i, `${tailInjection}\n</body>`);
+    }
+    else {
+        html += '\n' + tailInjection;
+    }
+    /* 5. Optional Pilot injection. */
+    if (opts.withPilot) {
+        await injectPilotBundle(opts.outDir, html, htmlBasename);
+        /* injectPilotBundle re-reads and writes the html itself. */
+    }
+    else {
+        await fs.writeFile(htmlPath, html, 'utf-8');
+    }
+    console.log(c.success('Wired NAC3 runtime + bridge into decorated output.'));
+    if (opts.withPilot)
+        console.log(c.success('Yujin Pilot bundle injected.'));
+}
+async function injectPilotBundle(outDir, html, htmlBasename = 'index.html') {
+    /* Pilot bundle ships under yujin-pilot/dist/. Forge resolves it at install
+       time. If the bundle is missing, fall back to a hint message. */
+    const pilotSrcCandidates = [
+        path.resolve(process.cwd(), '..', 'yujin-pilot', 'dist', 'pilot.bundle.js'),
+        path.resolve(process.cwd(), 'node_modules', '@yujin', 'pilot', 'dist', 'pilot.bundle.js'),
+    ];
+    const pilotCssCandidates = [
+        path.resolve(process.cwd(), '..', 'yujin-pilot', 'dist', 'pilot.css'),
+        path.resolve(process.cwd(), 'node_modules', '@yujin', 'pilot', 'dist', 'pilot.css'),
+    ];
+    let pilotJsSrc = null;
+    let pilotCssSrc = null;
+    for (const p of pilotSrcCandidates) {
+        if (await fs.stat(p).then(() => true, () => false)) {
+            pilotJsSrc = p;
+            break;
+        }
+    }
+    for (const p of pilotCssCandidates) {
+        if (await fs.stat(p).then(() => true, () => false)) {
+            pilotCssSrc = p;
+            break;
+        }
+    }
+    if (!pilotJsSrc) {
+        console.log(c.warn('Pilot bundle not found at ../yujin-pilot/dist/ -- skipping injection.'));
+        console.log(c.dim('Run from a sibling checkout of yujin-pilot or install @yujin/pilot.'));
+        await fs.writeFile(path.join(outDir, htmlBasename), html, 'utf-8');
+        return;
+    }
+    await fs.copyFile(pilotJsSrc, path.join(outDir, 'pilot.bundle.js'));
+    if (pilotCssSrc)
+        await fs.copyFile(pilotCssSrc, path.join(outDir, 'pilot.css'));
+    const tags = [
+        pilotCssSrc ? '<link rel="stylesheet" href="pilot.css">' : '',
+        '<script src="pilot.bundle.js"></script>',
+    ].filter(Boolean).join('\n');
+    if (/<\/body>/i.test(html)) {
+        html = html.replace(/<\/body>/i, `${tags}\n</body>`);
+    }
+    else {
+        html += '\n' + tags;
+    }
+    await fs.writeFile(path.join(outDir, htmlBasename), html, 'utf-8');
+}
+/* ------------------------------------------------------------------
+ * Selective re-decoration: --ai-search + --ai-override
+ * ------------------------------------------------------------------ */
+/**
+ * `yf migrate <repo> --ai-search "<query>"` -- list manifest
+ * elements matching the free-text query, ranked by relevance.
+ * Useful before running --ai-override to find the right nac_id.
+ */
+export async function runAiSearch(repo, opts) {
+    header('Yujin Forge -- manifest search');
+    console.log('');
+    const dir = path.resolve(process.cwd(), repo);
+    const manifestPath = path.join(dir, 'manifest.json');
+    const stat = await fs.stat(manifestPath).catch(() => null);
+    if (!stat) {
+        console.error(c.error('No manifest.json found in: ' + dir));
+        console.error(c.dim('Run --ai-silent first to produce one.'));
+        process.exitCode = 1;
+        return;
+    }
+    const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf-8'));
+    const hits = searchManifest(manifest, opts.aiSearch || '');
+    if (hits.length === 0) {
+        console.log(c.dim('No manifest elements match: ') + (opts.aiSearch || ''));
+        return;
+    }
+    console.log(c.success(hits.length + ' hit(s) for "') + (opts.aiSearch || '') + c.success('":'));
+    console.log('');
+    for (const h of hits.slice(0, 20)) {
+        const label = h.label_es || h.label_en;
+        const labelStr = label ? c.dim('  (') + label + c.dim(')') : '';
+        const verbStr = h.verbs.length ? c.dim(' verb=[') + h.verbs.join(',') + c.dim(']') : '';
+        console.log('  ' + c.brand(h.nac_id) + c.dim(' role=') + h.role + verbStr + labelStr);
+    }
+    if (hits.length > 20)
+        console.log(c.dim('  ... and ' + (hits.length - 20) + ' more.'));
+    console.log('');
+    console.log(c.dim('To re-decorate one of these:'));
+    console.log('  ' + c.brand('yf migrate ' + repo + ' --ai-override <nac-id>'));
+}
+/**
+ * `yf migrate <repo> --ai-override <nacId>` -- interactively
+ * re-decorate one element. Writes the override to overrides.json AND
+ * applies it immediately to index.html + manifest.json.
+ */
+export async function runAiOverride(repo, opts) {
+    header('Yujin Forge -- selective override');
+    console.log('');
+    const dir = path.resolve(process.cwd(), repo);
+    const manifestPath = path.join(dir, 'manifest.json');
+    const htmlPath = path.join(dir, 'index.html');
+    const ok = await Promise.all([
+        fs.stat(manifestPath).then(() => true, () => false),
+        fs.stat(htmlPath).then(() => true, () => false),
+    ]);
+    if (!ok[0] || !ok[1]) {
+        console.error(c.error('Expected ' + manifestPath + ' and ' + htmlPath + ' to exist.'));
+        console.error(c.dim('Run --ai-silent first to produce them.'));
+        process.exitCode = 1;
+        return;
+    }
+    const nacId = (opts.aiOverride || '').trim();
+    if (!nacId) {
+        console.error(c.error('--ai-override requires a nac-id argument.'));
+        process.exitCode = 1;
+        return;
+    }
+    const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf-8'));
+    const el = (manifest.elements || []).find((e) => e && e.id === nacId);
+    if (!el) {
+        console.error(c.error('No element with data-nac-id="' + nacId + '" in the manifest.'));
+        console.error(c.dim('Use --ai-search to find candidates.'));
+        process.exitCode = 1;
+        return;
+    }
+    const currentVerb = (el.actions && el.actions[0] && el.actions[0].verb) || '';
+    const currentLabelEs = (el.label_i18n && el.label_i18n.es) ||
+        (el.actions && el.actions[0] && el.actions[0].label_i18n && el.actions[0].label_i18n.es) || '';
+    const currentLabelEn = (el.label_i18n && el.label_i18n.en) ||
+        (el.actions && el.actions[0] && el.actions[0].label_i18n && el.actions[0].label_i18n.en) || '';
+    console.log(c.dim('Element selected:'));
+    console.log('  ' + c.brand(el.id) + c.dim(' role=') + el.role + (currentVerb ? c.dim(' verb=') + currentVerb : ''));
+    if (currentLabelEs)
+        console.log('  ' + c.dim('label.es = ') + currentLabelEs);
+    if (currentLabelEn)
+        console.log('  ' + c.dim('label.en = ') + currentLabelEn);
+    console.log('');
+    const answers = await prompts([
+        { type: 'text', name: 'nac_id', message: 'New nac_id (blank = keep)', initial: el.id },
+        {
+            type: 'select', name: 'role', message: 'Role',
+            choices: ['action', 'field', 'option', 'tab', 'region', 'navigation']
+                .map((r) => ({ title: r, value: r, selected: r === el.role })),
+            initial: ['action', 'field', 'option', 'tab', 'region', 'navigation'].indexOf(el.role),
+        },
+        { type: 'text', name: 'verb', message: 'Verb (blank = keep / not applicable)', initial: currentVerb },
+        { type: 'text', name: 'label_es', message: 'Label es (blank = keep)', initial: currentLabelEs },
+        { type: 'text', name: 'label_en', message: 'Label en (blank = keep)', initial: currentLabelEn },
+        { type: 'text', name: 'rationale', message: 'Rationale (one line, for the audit trail)' },
+    ]);
+    if (!answers || typeof answers.role !== 'string') {
+        console.log(c.dim('Cancelled.'));
+        return;
+    }
+    const patch = {};
+    if (answers.nac_id && answers.nac_id !== el.id)
+        patch.nac_id = answers.nac_id;
+    if (answers.role && answers.role !== el.role)
+        patch.role = answers.role;
+    if (answers.verb && answers.verb !== currentVerb)
+        patch.verb = answers.verb;
+    if (answers.label_es || answers.label_en) {
+        patch.label_i18n = {};
+        if (answers.label_es)
+            patch.label_i18n.es = answers.label_es;
+        if (answers.label_en)
+            patch.label_i18n.en = answers.label_en;
+    }
+    if (Object.keys(patch).length === 0) {
+        console.log(c.dim('No changes -- nothing to write.'));
+        return;
+    }
+    const override = {
+        match_by: 'nac_id',
+        match_value: el.id,
+        patch,
+        rationale: answers.rationale || undefined,
+        locked_at: new Date().toISOString(),
+        locked_by: process.env.USER || process.env.USERNAME || 'cli',
+    };
+    /* Apply on top of current files (not just store -- want immediate effect). */
+    const html = await fs.readFile(htmlPath, 'utf-8');
+    const { html: patchedHtml, manifest: patchedManifest, result: applyResult } = applyOverrides(html, manifest, [override]);
+    if (applyResult.applied.length === 0) {
+        console.error(c.error('Override application failed (orphaned).'));
+        process.exitCode = 1;
+        return;
+    }
+    await fs.writeFile(htmlPath, patchedHtml, 'utf-8');
+    await fs.writeFile(manifestPath, JSON.stringify(patchedManifest, null, 2), 'utf-8');
+    /* Append to overrides.json. */
+    const existing = await readOverrides(dir);
+    const file = existing || {
+        version: OVERRIDES_VERSION,
+        baseline_hash: computeBaselineHash(html, JSON.stringify(manifest)),
+        overrides: [],
+    };
+    /* Replace any prior override on the same nac_id; otherwise append. */
+    const ix = file.overrides.findIndex((o) => o.match_value === el.id);
+    if (ix >= 0)
+        file.overrides[ix] = override;
+    else
+        file.overrides.push(override);
+    await writeOverrides(dir, file);
+    console.log('');
+    console.log(c.success('Override applied + persisted.'));
+    console.log('  ' + c.dim('overrides.json now carries ') + file.overrides.length + c.dim(' entry(ies).'));
+    console.log('  ' + c.dim('Re-running --ai-silent will preserve this override.'));
+}
+/* ------------------------------------------------------------------
+ * --ai-apply: Claude-powered JSX decoration of a React project
+ * ------------------------------------------------------------------ */
+export async function runAiApply(repo, opts) {
+    header('Yujin Forge -- AI-powered JSX decoration (--ai-apply)');
+    console.log('');
+    if (!process.env.ANTHROPIC_API_KEY) {
+        console.error(c.error('ANTHROPIC_API_KEY env variable missing -- set it before --ai-apply.'));
+        process.exitCode = 1;
+        return;
+    }
+    const lic = await loadLicense();
+    if (!isPaidSeat(lic)) {
+        console.error(c.error('--ai-apply requires a paid seat.'));
+        console.error('  ' + c.dim('Trial mode produces the audit only. Run ')
+            + c.code('yf license activate --key <jwt>')
+            + c.dim(' to install a seat.'));
+        process.exitCode = 1;
+        return;
+    }
+    const projectRoot = path.resolve(process.cwd(), repo);
+    const subdir = opts.subdir || 'src';
+    const outDir = opts.aiOut
+        ? path.resolve(process.cwd(), opts.aiOut)
+        : undefined;
+    const concurrency = opts.aiConcurrency
+        ? Math.max(1, Math.min(parseInt(opts.aiConcurrency, 10) || 4, 8))
+        : 4;
+    console.log('  Project:        ' + c.dim(projectRoot));
+    console.log('  Subdir:         ' + c.dim(subdir));
+    console.log('  Output:         ' + c.dim(outDir || '(in-place)'));
+    console.log('  Plugin hint:    ' + c.dim(opts.aiPluginSlug || '(model derives)'));
+    console.log('  Model:          ' + c.dim(opts.aiModel || 'claude-sonnet-4-6'));
+    console.log('  Concurrency:    ' + c.dim(String(concurrency)));
+    console.log('  Dry-run:        ' + c.dim(opts.dryRun ? 'YES (no files written)' : 'no'));
+    console.log('');
+    let lastReport = 0;
+    const i18nLangs = opts.i18nLangs
+        ? opts.i18nLangs.split(',').map(s => s.trim()).filter(Boolean)
+        : undefined;
+    const result = await aiApplyProject({
+        projectRoot,
+        subdir,
+        outDir,
+        pluginSlugHint: opts.aiPluginSlug,
+        model: opts.aiModel,
+        dryRun: opts.dryRun,
+        concurrency,
+        withI18n: !!opts.withI18nTags,
+        i18nLangs,
+        onProgress: (i, total, rel, r) => {
+            /* Throttle progress to one line every ~5 files or last file. */
+            if (i === total || i - lastReport >= 5) {
+                const mark = r.decorated ? c.success('+') : c.dim('.');
+                console.log('  ' + mark + ' [' + i + '/' + total + '] ' + rel +
+                    (r.decorated ? c.dim(' (' + r.elements.length + ' element' + (r.elements.length === 1 ? '' : 's') + ')') : ''));
+                lastReport = i;
+            }
+        },
+    });
+    /* Persist top-level manifest alongside the project (or the outDir). */
+    const manifestTargetDir = outDir || projectRoot;
+    const manifestPath = path.join(manifestTargetDir, 'manifest.json');
+    if (!opts.dryRun) {
+        await fs.mkdir(manifestTargetDir, { recursive: true });
+        await fs.writeFile(manifestPath, JSON.stringify(result.manifest, null, 2), 'utf-8');
+    }
+    /* SPA wiring: if the project has an index.html at root (Vite / CRA /
+       similar bundler patterns) and a public/ dir, copy nac.browser.js
+       + nac-bridge.js + manifest into public/ and inject the tags into
+       index.html. Skip when the file is already wired (idempotent). */
+    if (!opts.dryRun) {
+        await wireSpaIndexHtml({
+            projectRoot: manifestTargetDir,
+            pluginSlug: result.manifest.plugin_slug,
+            manifestJson: JSON.stringify(result.manifest),
+        });
+    }
+    console.log('');
+    console.log(c.success('AI apply complete.'));
+    console.log('  ' + c.dim('Files scanned:   ') + result.files.length);
+    console.log('  ' + c.dim('Files decorated: ') + result.files.filter((f) => f.decorated).length);
+    console.log('  ' + c.dim('Manifest elements: ') + result.manifest.elements.length);
+    console.log('  ' + c.dim('Plugin slug:     ') + result.manifest.plugin_slug);
+    /* H2: surface qualifier warnings (reusable components without an
+       inferable qualifier). These are the "N DOM instances collide on
+       the same id" cases that destroy agent disambiguation if hidden. */
+    if (result.warnings && result.warnings.length > 0) {
+        console.log('');
+        console.log(c.warn('Qualifier warnings -- ') + result.warnings.length + c.warn(' reusable component(s) without an inferable qualifier:'));
+        for (const w of result.warnings) {
+            console.log('  ' + c.warn('!') + ' ' + c.dim(w.file) + '  ' + c.brand(w.id));
+            console.log('    ' + c.dim(w.warning));
+        }
+        console.log('  ' + c.dim('Each of these will collapse N DOM instances onto a single nac_id.'));
+        console.log('  ' + c.dim('Disambiguate with: ') + c.code('yf migrate ' + repo + ' --ai-override <nac-id>'));
+    }
+    console.log('  ' + c.dim('Tokens in/out:   ') + result.total_tokens_in + ' / ' + result.total_tokens_out);
+    console.log('  ' + c.dim('Total cost:      ') + '$' + result.total_cost_usd.toFixed(4));
+    console.log('  ' + c.dim('Total LLM time:  ') + Math.round(result.total_latency_ms / 1000) + 's wall (across all files)');
+    if (!opts.dryRun) {
+        console.log('  ' + c.dim('Manifest:        ') + manifestPath);
+    }
+    else {
+        console.log('  ' + c.warn('Dry-run -- no files written. Re-run without --dry-run to apply.'));
+    }
+}
+async function wireSpaIndexHtml(opts) {
+    const indexPath = path.join(opts.projectRoot, "index.html");
+    const has = await fs.stat(indexPath).then(() => true, () => false);
+    if (!has)
+        return;
+    let html = await fs.readFile(indexPath, "utf-8");
+    if (/nac\.browser\.js/.test(html)) {
+        /* Already wired (idempotent re-run). */
+        return;
+    }
+    /* Resolve nac.browser.js source. */
+    const runtimePath = await resolveNacRuntime();
+    const publicDir = path.join(opts.projectRoot, "public");
+    const hasPublic = await fs.stat(publicDir).then(() => true, () => false);
+    if (!hasPublic) {
+        await fs.mkdir(publicDir, { recursive: true });
+    }
+    if (runtimePath) {
+        await fs.copyFile(runtimePath, path.join(publicDir, "nac.browser.js"));
+    }
+    await fs.writeFile(path.join(publicDir, "nac-bridge.js"), NAC_BRIDGE_SOURCE, "utf-8");
+    await fs.writeFile(path.join(publicDir, "nac-manifest.json"), opts.manifestJson, "utf-8");
+    const runtimeTag = "<script src=\"/nac.browser.js\"></script>";
+    const bridgeTag = "<script src=\"/nac-bridge.js\"></script>";
+    const registerInline = "<script>\n  (function () {\n    function reg() {\n      fetch(\"/nac-manifest.json\").then(function (r) { return r.json(); }).then(function (m) {\n        if (window.NAC && window.NAC.register) {\n          try { window.NAC.register(m); }\n          catch (e) { if (window.console) console.error(\"NAC.register failed\", e); }\n        }\n      });\n    }\n    if (document.readyState === \"loading\") document.addEventListener(\"DOMContentLoaded\", reg);\n    else reg();\n  })();\n</script>";
+    /* 1. Inject runtime tag before </head>. */
+    if (/<\/head>/i.test(html)) {
+        html = html.replace(/<\/head>/i, runtimeTag + "\n</head>");
+    }
+    else {
+        html = runtimeTag + "\n" + html;
+    }
+    /* 2. Add data-nac-plugin to body. */
+    html = html.replace(/<body([^>]*)>/i, (m, attrs) => {
+        if (/data-nac-plugin/.test(attrs))
+            return m;
+        return "<body" + attrs + " data-nac-plugin=\"" + opts.pluginSlug + "\">";
+    });
+    /* 3. Inject bridge + register before </body>. */
+    if (/<\/body>/i.test(html)) {
+        html = html.replace(/<\/body>/i, bridgeTag + "\n" + registerInline + "\n</body>");
+    }
+    else {
+        html += "\n" + bridgeTag + "\n" + registerInline;
+    }
+    await fs.writeFile(indexPath, html, "utf-8");
+}
+//# sourceMappingURL=migrate.js.map