@nac3/forge-cli 0.2.0-alpha.3 → 0.2.0-alpha.31

package/dist/chat/server.js

@@ -248,6 +248,68 @@ async function route(req, res, ctx) {
         await handleForgeToolDispatch(req, res, ctx);
         return;
     }
+    /* Open-in-editor escape hatch (Layer A.2). The panel surfaces
+       file paths as clickable; click triggers this endpoint, which
+       spawns the user's default editor (code / cursor / subl /
+       idea, in order). Best-effort -- on failure returns the
+       resolved path so the panel can copy-to-clipboard fallback. */
+    if (req.method === 'POST' && url.pathname === '/api/forge/open-in-editor') {
+        await handleOpenInEditor(req, res, ctx);
+        return;
+    }
+    /* Trust gradient tracking (Layer A.2). Panel increments
+       counters when the user expands a diff / opens a file in
+       their editor / overrides Forge. Forge reads them at session
+       boot and decides whether to surface or hide the detail
+       links. */
+    if (req.method === 'POST' && url.pathname === '/api/forge/trust-event') {
+        await handleTrustEvent(req, res, ctx);
+        return;
+    }
+    if (req.method === 'GET' && url.pathname === '/api/forge/trust-state') {
+        await handleTrustState(req, res, ctx);
+        return;
+    }
+    /* alpha.29 -- keys status for the settings dropdown. Returns
+       which BYOK provider keys + license are configured, without
+       exposing the values themselves. */
+    if (req.method === 'GET' && url.pathname === '/api/forge/keys-status') {
+        await handleKeysStatus(req, res);
+        return;
+    }
+    /* alpha.30 -- write/clear BYOK provider keys from the panel. */
+    if (req.method === 'POST' && url.pathname === '/api/forge/keys-set') {
+        await handleKeysSet(req, res);
+        return;
+    }
+    /* Favicon -- minimal SVG so Chrome stops 404-ing. The browser
+       auto-requests /favicon.ico on every page load; without this,
+       each open of the panel logs an error. */
+    if (req.method === 'GET' && (url.pathname === '/favicon.ico'
+        || url.pathname === '/favicon.svg')) {
+        const svg = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">'
+            + '<circle cx="16" cy="16" r="14" fill="#1a1a1a"/>'
+            + '<path d="M8 22 L16 8 L24 22 M11 17 L21 17" stroke="#fafafa" stroke-width="2" fill="none" stroke-linecap="round"/>'
+            + '</svg>';
+        res.writeHead(200, {
+            'content-type': 'image/svg+xml',
+            'cache-control': 'public, max-age=86400',
+        });
+        res.end(svg);
+        return;
+    }
+    /* Support report ingest (2026-05-31 -- F30-style). Panel sends
+     * runtime errors (window.onerror, fetch failures, unhandled
+     * promise rejections) here so Forge sees what the user saw
+     * without them having to copy logs. PII is scrubbed on save. */
+    if (req.method === 'POST' && url.pathname === '/api/forge/support/report') {
+        await handleSupportReport(req, res);
+        return;
+    }
+    if (req.method === 'GET' && url.pathname === '/api/forge/support/reports') {
+        await handleSupportReportList(req, res);
+        return;
+    }
     /* Spec doc ingest (V1.37 + V1.38 -- bloque 4.5 scaffolding).
        Client uploads a spec file (PDF / DOCX / HTML / md / ...)
        and the server parses it via the existing reader pipeline,
@@ -423,6 +485,19 @@ async function handleVoiceStt(req, res, ctx) {
         sendJson(res, 400, { ok: false, error: 'audio body is empty' });
         return;
     }
+    /* 2026-05-31 fix: Google STT sync rejects audio > 1 min with
+       HTTP 400. Refuse early with a useful message instead of
+       leaking the Google error verbatim. ~4 MB is the practical
+       ceiling for 60s of WebM/Opus at 32 kbps. */
+    if (audio.length > 4 * 1024 * 1024) {
+        sendJson(res, 413, {
+            ok: false,
+            error: 'audio too long for sync STT (limit ~1 min). '
+                + 'Got ' + audio.length + ' bytes. The chat panel auto-stops at 55s; '
+                + 'if you hit this from a different client, split the audio.',
+        });
+        return;
+    }
     /* Optional active document hint (V1.31). Lets the voice intent
        matcher resolve commands like "siguiente" or "buscar X" against
        the currently-open reader session. Client sets this header to
@@ -466,17 +541,17 @@ async function handleVoiceStt(req, res, ctx) {
  * runs.
  */
 const FORGE_TOOL_DIRECT_ALLOWLIST = new Set([
-    'forge.reader.open',
-    'forge.reader.list_documents',
-    'forge.reader.read_section',
-    'forge.reader.next_block',
-    'forge.reader.search',
-    'forge.reader.bookmark_set',
-    'forge.reader.bookmark_jump',
-    'forge.reader.recap',
+    'forge_reader_open',
+    'forge_reader_list_documents',
+    'forge_reader_read_section',
+    'forge_reader_next_block',
+    'forge_reader_search',
+    'forge_reader_bookmark_set',
+    'forge_reader_bookmark_jump',
+    'forge_reader_recap',
     /* Fase F.8 -- HTML user manuals in 10 languages. Read-only,
        same safety profile as the reader tools. */
-    'forge.manual.open',
+    'forge_manual_open',
 ]);
 async function handleForgeToolDispatch(req, res, ctx) {
     let body;
@@ -948,6 +1023,331 @@ async function handleVoiceTts(req, res, ctx) {
         });
     }
 }
+/* ============================================================
+ * Layer A.2 -- minority surface (open in editor + trust gradient)
+ * ============================================================ */
+/** Check that `target` is inside `root` (after resolving both).
+ *  Refuses path traversal like ../../../etc/passwd. */
+function isInside(target, root) {
+    const targetAbs = path.resolve(target);
+    const rootAbs = path.resolve(root) + path.sep;
+    return targetAbs === path.resolve(root) || targetAbs.startsWith(rootAbs);
+}
+/** Editor commands tried in order. First match wins. The args
+ *  templates are joined with the file path at runtime. All
+ *  commands run with stdio ignored + detached so the panel does
+ *  not block on the editor's window lifetime. */
+const EDITOR_CANDIDATES = [
+    { cmd: 'code', args: (f) => [f] }, // VS Code
+    { cmd: 'cursor', args: (f) => [f] }, // Cursor
+    { cmd: 'subl', args: (f) => [f] }, // Sublime Text
+    { cmd: 'idea', args: (f) => [f] }, // IntelliJ family
+    { cmd: 'webstorm', args: (f) => [f] },
+    { cmd: 'nano', args: (f) => [f] },
+    { cmd: 'vim', args: (f) => [f] },
+];
+async function handleOpenInEditor(req, res, ctx) {
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    if (typeof body.path !== 'string' || body.path.trim() === '') {
+        sendJson(res, 400, { ok: false, error: 'path (non-empty string) required' });
+        return;
+    }
+    /* Resolve to absolute under the project root. Refuse paths
+     *  that escape the project tree (no user opening /etc/passwd
+     *  through the chat). */
+    const requestedRel = body.path.trim().replace(/^[/\\]+/, '');
+    const absolute = path.join(ctx.projectRoot, requestedRel);
+    if (!isInside(absolute, ctx.projectRoot)) {
+        sendJson(res, 400, { ok: false, error: 'path escapes project root' });
+        return;
+    }
+    /* Walk the candidates, spawn the first one that does not
+     *  throw ENOENT. */
+    const { spawn } = await import('node:child_process');
+    for (const candidate of EDITOR_CANDIDATES) {
+        try {
+            const cmd = process.platform === 'win32' ? `${candidate.cmd}.cmd` : candidate.cmd;
+            const child = spawn(cmd, candidate.args(absolute), {
+                stdio: 'ignore',
+                detached: true,
+                shell: false,
+            });
+            child.on('error', () => { });
+            child.unref();
+            /* If spawn returned, the binary is at least present.
+             *  We do not wait for editor to launch (it might be slow
+             *  or might be a background daemon). Report success. */
+            sendJson(res, 200, {
+                ok: true,
+                editor: candidate.cmd,
+                path: absolute,
+            });
+            return;
+        }
+        catch { /* ENOENT etc -- try next candidate */ }
+    }
+    /* No editor found. Return the absolute path so the panel can
+     *  offer copy-to-clipboard fallback. */
+    sendJson(res, 200, {
+        ok: false,
+        error: 'no supported editor found in PATH',
+        path: absolute,
+        candidates: EDITOR_CANDIDATES.map((c) => c.cmd),
+        hint: 'Install VS Code (code), Cursor, Sublime (subl), or IntelliJ; or copy the path manually.',
+    });
+}
+function trustMetricsPath() {
+    return path.join(configDir(), 'trust_metrics.json');
+}
+async function loadTrustMetrics() {
+    const fs = await import('node:fs');
+    try {
+        const raw = await fs.promises.readFile(trustMetricsPath(), 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object') {
+            return {
+                v: 1,
+                diff_expansions: Number(parsed.diff_expansions) || 0,
+                editor_opens: Number(parsed.editor_opens) || 0,
+                forge_overrides: Number(parsed.forge_overrides) || 0,
+                last_event_at: typeof parsed.last_event_at === 'string' ? parsed.last_event_at : null,
+                last_proposal_at: typeof parsed.last_proposal_at === 'string' ? parsed.last_proposal_at : null,
+                user_choice: ['show', 'hide', 'default'].includes(parsed.user_choice) ? parsed.user_choice : 'default',
+            };
+        }
+    }
+    catch { /* missing or bad -- return defaults */ }
+    return {
+        v: 1,
+        diff_expansions: 0,
+        editor_opens: 0,
+        forge_overrides: 0,
+        last_event_at: null,
+        last_proposal_at: null,
+        user_choice: 'default',
+    };
+}
+async function saveTrustMetrics(m) {
+    const fs = await import('node:fs');
+    await fs.promises.mkdir(configDir(), { recursive: true });
+    await fs.promises.writeFile(trustMetricsPath(), JSON.stringify(m, null, 2), 'utf-8');
+}
+async function handleTrustEvent(req, res, _ctx) {
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    const kind = typeof body.kind === 'string' ? body.kind : '';
+    const m = await loadTrustMetrics();
+    const now = new Date().toISOString();
+    switch (kind) {
+        case 'diff_expansion':
+            m.diff_expansions += 1;
+            break;
+        case 'editor_open':
+            m.editor_opens += 1;
+            break;
+        case 'forge_override':
+            m.forge_overrides += 1;
+            break;
+        case 'user_chose_show':
+            m.user_choice = 'show';
+            break;
+        case 'user_chose_hide':
+            m.user_choice = 'hide';
+            break;
+        default:
+            sendJson(res, 400, { ok: false, error: 'unknown kind: ' + kind });
+            return;
+    }
+    m.last_event_at = now;
+    await saveTrustMetrics(m);
+    sendJson(res, 200, { ok: true, metrics: m });
+}
+async function handleKeysStatus(_req, res) {
+    /* Read ~/.yujin-forge/provider_keys.json + license.json without
+     * exposing values. Just boolean presence. */
+    const fs = await import('node:fs');
+    const path = await import('node:path');
+    const os = await import('node:os');
+    const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+    const out = {
+        anthropic: false,
+        openai: false,
+        google_ai: false,
+        google_stt: false,
+        google_tts: false,
+        whisper: false,
+        elevenlabs: false,
+        license_paid: false,
+    };
+    try {
+        const p = path.join(home, '.yujin-forge', 'provider_keys.json');
+        const raw = await fs.promises.readFile(p, 'utf-8');
+        const j = JSON.parse(raw);
+        out.anthropic = typeof j.anthropic_api_key === 'string' && j.anthropic_api_key.length > 0;
+        out.openai = typeof j.openai_api_key === 'string' && j.openai_api_key.length > 0;
+        out.google_ai = typeof j.google_ai_key === 'string' && j.google_ai_key.length > 0;
+        out.google_stt = typeof j.google_stt_key === 'string' && j.google_stt_key.length > 0;
+        out.google_tts = typeof j.google_tts_key === 'string' && j.google_tts_key.length > 0;
+        out.whisper = typeof j.whisper_api_key === 'string' && j.whisper_api_key.length > 0;
+        out.elevenlabs = typeof j.elevenlabs_api_key === 'string' && j.elevenlabs_api_key.length > 0;
+    }
+    catch { /* file absent -> all false */ }
+    try {
+        const p = path.join(home, '.yujin-forge', 'license.json');
+        const raw = await fs.promises.readFile(p, 'utf-8');
+        const j = JSON.parse(raw);
+        out.license_paid = j.plan === 'paid' || j.plan === 'institutional' || j.plan === 'gifted';
+    }
+    catch { /* no license file */ }
+    sendJson(res, 200, { ok: true, keys: out });
+}
+const ALLOWED_KEY_SLOTS = new Set([
+    'anthropic_api_key',
+    'openai_api_key',
+    'google_ai_key',
+    'google_stt_key',
+    'google_tts_key',
+    'whisper_api_key',
+    'elevenlabs_api_key',
+]);
+async function handleKeysSet(req, res) {
+    let raw;
+    try {
+        raw = await readBody(req);
+    }
+    catch (err) {
+        sendJson(res, 400, { ok: false, error: 'unreadable body' });
+        return;
+    }
+    let body;
+    try {
+        body = JSON.parse(raw);
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    const slot = typeof body.slot === 'string' ? body.slot.trim() : '';
+    if (!ALLOWED_KEY_SLOTS.has(slot)) {
+        sendJson(res, 400, { ok: false, error: 'slot must be one of: ' + Array.from(ALLOWED_KEY_SLOTS).join(', ') });
+        return;
+    }
+    /* value === '' OR null means clear. Otherwise it is the new
+     * key value (min 8 chars, no leading/trailing whitespace). */
+    const value = body.value === null ? '' : (typeof body.value === 'string' ? body.value.trim() : '');
+    if (value !== '' && value.length < 8) {
+        sendJson(res, 400, { ok: false, error: 'key value too short (min 8 chars)' });
+        return;
+    }
+    const fs = await import('node:fs');
+    const path = await import('node:path');
+    const os = await import('node:os');
+    const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+    const dir = path.join(home, '.yujin-forge');
+    const file = path.join(dir, 'provider_keys.json');
+    try {
+        await fs.promises.mkdir(dir, { recursive: true });
+    }
+    catch { /* ok */ }
+    let current = { v: 1 };
+    try {
+        const raw0 = await fs.promises.readFile(file, 'utf-8');
+        const j = JSON.parse(raw0);
+        if (j && typeof j === 'object')
+            current = j;
+    }
+    catch { /* fresh file */ }
+    if (value === '') {
+        delete current[slot];
+    }
+    else {
+        current[slot] = value;
+    }
+    current.v = current.v ?? 1;
+    /* Write atomically: tmp file + rename + chmod 0600. */
+    const tmp = file + '.tmp';
+    await fs.promises.writeFile(tmp, JSON.stringify(current, null, 2), { mode: 0o600 });
+    await fs.promises.rename(tmp, file);
+    sendJson(res, 200, { ok: true, slot, set: value !== '' });
+}
+async function handleSupportReport(req, res) {
+    let raw;
+    try {
+        raw = await readBody(req);
+    }
+    catch (err) {
+        sendJson(res, 400, { ok: false, error: 'unreadable body: ' + (err instanceof Error ? err.message : String(err)) });
+        return;
+    }
+    let body;
+    try {
+        body = JSON.parse(raw);
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    const { validateInbound, recordReport } = await import('../support/reports.js');
+    /* Support either a single report or an array (the panel
+     * batches up to 50 + flushes every 30s). */
+    const ua = typeof req.headers['user-agent'] === 'string' ? req.headers['user-agent'] : undefined;
+    const items = Array.isArray(body) ? body : [body];
+    let accepted = 0;
+    let rejected = 0;
+    for (const item of items.slice(0, 50)) {
+        const report = validateInbound(item, ua ? { user_agent: ua } : {});
+        if (report) {
+            await recordReport(report);
+            accepted++;
+        }
+        else {
+            rejected++;
+        }
+    }
+    sendJson(res, 200, { ok: true, accepted, rejected });
+}
+async function handleSupportReportList(req, res) {
+    /* Local panel only -- we already gate the chat server to
+     * loopback. No additional auth needed for read. */
+    const { readReports } = await import('../support/reports.js');
+    const u = new URL(req.url ?? '/', 'http://localhost');
+    const limit = Math.min(500, Math.max(1, parseInt(u.searchParams.get('limit') ?? '100', 10) || 100));
+    const reports = (await readReports()).slice(-limit);
+    sendJson(res, 200, { ok: true, count: reports.length, reports });
+}
+async function handleTrustState(_req, res, _ctx) {
+    const m = await loadTrustMetrics();
+    /* Decay logic: if no events in last 30 days AND user has not
+     *  explicitly chosen to keep showing, suggest auto-collapse.
+     *  The panel decides what to do with the suggestion. */
+    let shouldProposeCollapse = false;
+    if (m.user_choice === 'default') {
+        const last = m.last_event_at ? new Date(m.last_event_at).getTime() : 0;
+        const proposedRecently = m.last_proposal_at
+            ? (Date.now() - new Date(m.last_proposal_at).getTime()) < 7 * 24 * 3600 * 1000
+            : false;
+        const daysSince = last ? (Date.now() - last) / (24 * 3600 * 1000) : Infinity;
+        shouldProposeCollapse = daysSince > 30 && !proposedRecently;
+    }
+    sendJson(res, 200, {
+        ok: true,
+        metrics: m,
+        propose_auto_collapse: shouldProposeCollapse,
+    });
+}
 async function handleVaultList(res) {
     try {
         const vault = await Vault.open({ configDir: configDir() });
@@ -1384,32 +1784,334 @@ function buildSystemPrompt(ctx, mode = 'didactico', pilotState = {
     pilot_completed: true, target_pending: false, mode_pending: false,
 }) {
     return [
-        'You are Yujin Forge -- a friendly assistant embedded in a developer\'s React project.',
+        'You are Yujin Forge -- a voice-first NAC-3 React development framework that acts as a full IDE for the user\'s project. Embedded in their workspace as a chat panel + tool dispatcher + workflow guide. The user pays USD 10/mo (BYOK for LLM). You exist to deliver real software, not just answer questions.',
+        '',
+        'LEMA YUJIN: "La tecnologia desaparece. El sistema aprende de vos, no vos del sistema." Toda decision se evalua contra esto.',
+        '',
+        '=================================================================',
+        'CORE PRINCIPLES (from docs/SQ.md -- Estandares de Calidad)',
+        '=================================================================',
+        '',
+        '1. EL TIEMPO DEL USUARIO ES SAGRADO. Atrapa los bugs basicos',
+        '   ANTES de que el usuario los vea: syntax errors, broken buttons,',
+        '   404s, missing imports, modales que no abren, console errors.',
+        '   El usuario solo evalua decisiones de alta complejidad funcional',
+        '   ("este UX se siente intuitivo?", "esta voz suena bien?",',
+        '   "este flujo cubre el caso de uso?"). Para todo lo mecanico,',
+        '   YO atrapo / YO arreglo.',
+        '',
+        '2. CERO DEUDA TECNICA desde el commit 0. Bugs descubiertos en el',
+        '   camino van a root fix + spec de regresion en LA MISMA sesion.',
+        '   Nunca "lo arreglo despues".',
+        '',
+        '3. ASCII-PURE en codigo de producto. Sin acentos en source files,',
+        '   sin emojis, sin em-dashes, sin caracteres > 0x7F en .ts / .tsx',
+        '   / .py / .php / .sql / .json fuera de _i18n.',
+        '',
+        '4. DOCUMENTACION SINCRONIZADA. Cada commit cross-linkea con las',
+        '   secciones de RFP / Architecture / Solution Design / User Manual',
+        '   afectadas. Divergencia entre codigo y docs = bug.',
+        '',
+        '5. MATCH THE SCOPE. Si el usuario abre con un bug, arregla SOLO',
+        '   ese bug. No empieces un refactor "de paso". Si el usuario',
+        '   abre con una feature, no toques codigo no relacionado.',
+        '',
+        '6. RESPONDE EN EL IDIOMA DEL USUARIO. Default a espanol si no',
+        '   esta claro. Replies cortas + conversacionales. Una pregunta',
+        '   clarificadora a la vez, no avalanchas.',
+        '',
+        '7. PRODUCER/CONSUMER SYMMETRY (SQ Sec 14, MANDATORY). Antes de',
+        '   COMMIT cualquier cambio que toque una estructura compartida',
+        '   (vault slot, JSON key, env var, tool name, type id, endpoint',
+        '   contract, manifest field), corre forge_audit_consumers(<concepto>)',
+        '   y si hay readers desincronizados, FIX en el MISMO commit. NO',
+        '   pidas al usuario interpretar el audit. El usuario nunca ve esto.',
+        '   Lee docs/GOTCHAS.md al boot; cuando un cambio matchea un patron',
+        '   AP-1/AP-2/AP-3/AP-4 registrado, refuse el commit y enlaza la',
+        '   entrada. Esta regla nacio el 2026-05-29 despues de 3 regresiones',
+        '   BYOK seguidas (G-2026-05-29 a/b/c en GOTCHAS).',
+        '',
+        '8. AUTONOMIA / TEST THINGS YOURSELF (SQ Sec 15, MANDATORY).',
+        '   Antes de pedirle al usuario "podes correr X y pegarme el',
+        '   output?", parar y reescribir como "voy a correr X yo,',
+        '   capturar output, diagnosticar". Tenes tools para correr el',
+        '   CLI, leer archivos del proyecto, leer logs, hacer fetch a',
+        '   APIs, parsear JSON. Usalos. El usuario solo se involucra',
+        '   cuando el test fisicamente requiere: hardware (microfono',
+        '   real), juicio subjetivo ("se ve bien?"), decision $$ /',
+        '   scope, o credenciales que solo el tiene. Para todo lo demas,',
+        '   diagnosticas vos + reportas el diagnostico, NO el camino.',
+        '   Esta regla nacio el 2026-05-31: el usuario flageo que le',
+        '   pedimos tests reproducibles que podemos correr nosotros.',
+        '',
+        '=================================================================',
+        'PRODUCT WORKFLOW (from docs/PRODUCT_WORKFLOW.md)',
+        '=================================================================',
+        '',
+        'You guide the user through 6 phases / 18 steps. Pick the right',
+        'phase to engage based on what the user is asking. If they jump',
+        'mid-phase, you respect that but mention which phase they skipped',
+        'and what risk that carries.',
+        '',
+        'PHASE I -- INTAKE (steps 1-3.5)',
+        '  1.   Complexity triage           Simple / Medium / Full tier',
+        '  2.   Vault keys validation       13 credential families, BYOK',
+        '  3.   Discover intent             migrate / new / modify;',
+        '                                   desktop / mobile / both;',
+        '                                   chat / voice / document-paste',
+        '  3.5  Audit existing artifacts    if migrating legacy',
+        '',
+        'PHASE II -- CLARIFICATION (steps 4-9)',
+        '  4.   Functional                  user stories, MVP, personas',
+        '  5.   NFR quantitative            volumetry, parallelism,',
+        '                                   process complexity',
+        '  6.   NFR structural              persistence, middleware,',
+        '                                   object lifecycle, workers',
+        '  7.   NFR governance              compliance (GDPR/HIPAA/PCI/',
+        '                                   SOC2), audit, retention,',
+        '                                   RBAC, DR',
+        '  8.   NFR operational             i18n, a11y, cost budget,',
+        '                                   monitoring, SLA',
+        '  9.   Block prioritisation        decompose + dep graph + MVP',
+        '',
+        'PHASE III -- SPECIFICATION (steps 10-12)',
+        '  10.  RFP / PRD                   consolidates Phase I + II',
+        '  11.  Architecture doc            stack + layering + async +',
+        '                                   topology + observability +',
+        '                                   security, driven by NFRs',
+        '  12.  Solution Design             per-block: data model, APIs,',
+        '                                   screens, state machines',
+        '',
+        'PHASE IV -- APPROVAL GATE (step 13)',
+        '  13.  Explicit OK on the 3 docs   You REFUSE to advance to Phase V',
+        '                                   without explicit "si" on RFP +',
+        '                                   architecture + design.',
+        '',
+        'PHASE V -- BUILD ITERATIVE (steps 14-15)',
+        '  14.  Bootstrap                   NAC-3 baseline + CI gates +',
+        '                                   test scaffolding all layers +',
+        '                                   observability hooks',
+        '  15.  Iterative cycle per block   implement -> e2e tests with',
+        '                                   100% structural coverage ->',
+        '                                   a11y check -> green-gate',
+        '                                   before next block',
+        '',
+        'PHASE VI -- SHIP & OPERATE (steps 16-18)',
+        '  16.  Deploy automation + execute creds + pipeline + secrets +',
+        '                                   monitoring + smoke + rollback',
+        '  17.  Post-launch                 user manual auto-gen,',
+        '                                   dashboards, feedback collect',
+        '  18.  Iteration re-entry          route new requirements back',
+        '                                   to the right phase, keep docs',
+        '                                   in sync',
+        '',
+        'CROSS-CUTTING (all phases): documentation sync, cost tracking,',
+        'translation of user-facing artifacts, versioning + changelog,',
+        'handoff, backup + DR.',
+        '',
+        'COMPLEXITY TIER MAPPING:',
+        '  Simple  = landing / blog / demo POC                 -> steps 1-3, 9, 14-16',
+        '  Medium  = CRUD app with auth, low-traffic SaaS      -> + 4-7, 10-13',
+        '  Full    = regulated SaaS, multi-tenant, workflows   -> ALL 18 steps + hard gates',
+        '',
+        '=================================================================',
+        'UNBREAKABLE GATES (you refuse to advance)',
+        '=================================================================',
+        '',
+        'G1: Phase I done without complexity tier decided',
+        'G2: No minimum brain (LLM) key in vault',
+        'G3: Phase III started without intent recorded',
+        'G4: Phase IV approached without block-plan OK',
+        'G5: Phase V started without explicit OK on the 3 spec docs',
+        'G6: Phase V block declared complete with red tests',
+        'G7: Phase VI deploy attempted without all required creds',
+        'G8: Launch announced without green smoke check post-deploy',
+        '',
+        'Soft gates: alert the user, propose alternative, do NOT block:',
+        'GS1: Simple tier asking for full RFP -> do it but flag overkill',
+        'GS2: Full tier asking to skip arch -> refuse with justification',
+        'GS3: No compliance picked but "produccion B2B" -> propose defaults',
+        'GS4: Low cost budget but high volumetry -> propose optimisations',
+        '',
+        '=================================================================',
+        'NAC-3 QUICK REFERENCE',
+        '=================================================================',
+        '',
+        'Five HTML attributes turn any UI into an agent-addressable surface:',
+        '',
+        '- data-nac-id      stable agent-addressable name (e.g. "checkout.confirm_btn")',
+        '                   namespace pattern: "<scenario>.<element>" (see PLAN.md D2)',
+        '- data-nac-role    semantic kind: action / region / field / value',
+        '- data-nac-action  declarative effect when invoked: submit / open / search /',
+        '                   navigate / dismiss / autopilot_toggle',
+        '- data-nac-state   lifecycle: loading / disabled / readonly / hidden /',
+        '                   selected / error',
+        '- data-nac-target  secondary anchor: id of element this one controls',
+        '',
+        'MANIFEST: JSON sidecar (yujin.forge.json) listing every (id, role, actions,',
+        'label_i18n). Generated by `yf migrate audit`. Driven by chat tools.',
+        '',
+        'WHEN NOT TO MARK: CSS-only decoration, layout wrappers, animation containers,',
+        'transient toasts that disappear < 3s. Anything an agent cannot meaningfully',
+        'act on.',
+        '',
+        'For deep questions about NAC-3 semantics, call forge_consult_nac_spec.',
+        '',
+        '=================================================================',
+        'YF COMMAND CATALOG (recommend these to the user when relevant)',
+        '=================================================================',
+        '',
+        'PROJECT LIFECYCLE:',
+        '  yf new <slug>                    scaffold a new NAC-3 React project',
+        '  yf migrate <repo> --audit        scan existing project for NAC-3 readiness',
+        '  yf migrate <repo> --apply        execute the AST migration (paid seat)',
+        '  yf ship                          deploy gate: validate + license + tests + build',
+        '',
+        'DEV LOOP:',
+        '  yf chat                          this panel (you are inside it)',
+        '  yf doctor                        verify environment + license + deps',
+        '  yf gen-tests <dir>               emit e2e tests from manifest',
+        '  yf scenarios:emit                emit Playwright + Maestro from yaml scenarios',
+        '  yf review-screens                visual regression review UI',
+        '  yf review-status                 CI gate: 0 iff every screenshot is OK',
+        '',
+        'CONFIG + LICENSE:',
+        '  yf keys setup                    interactive BYOK (brain + voice)',
+        '  yf vault                         manage encrypted credentials',
+        '  yf license activate --user-handle <email>   bind to Polar subscription',
+        '  yf license status / cancel / resubscribe    subscription ops',
+        '  yf voice                         voice + wake-word config',
+        '',
+        'SHIP + DEPLOY:',
+        '  yf publish --npm                 npm publish using vaulted token',
+        '  yf publish --docker              docker push using vaulted token',
+        '  yf deploy                        cloud deploy (AWS built-in, others chat-guided)',
+        '  yf repo                          init repo + GitHub remote pairing',
+        '',
+        'OBSERVABILITY:',
+        '  yf log                           per-scope log levels + redaction (SQ.K)',
+        '  yf projects                      cross-device project registry',
+        '',
+        'RECOMMENDATION HEURISTIC: if the user asks "how do I X?", recommend the',
+        '`yf X` command (it teaches them the surface). If the user wants the result',
+        'right now ("install Stripe webhook for me"), do the tool call directly.',
+        '',
+        '=================================================================',
+        'TOOLS AVAILABLE THIS TURN (call them by exact name)',
+        '=================================================================',
+        '',
+        'BYOK API KEYS (LEMA YUJIN -- todo por voz desde el chat):',
+        '  forge_get_byok_status           Returns booleans: brain / stt / tts /',
+        '                                  license configured? Use when user asks',
+        '                                  "que claves tengo" / "donde configuro".',
+        '  forge_set_byok_key slot value   Persist a BYOK API key. Slots:',
+        '                                  anthropic_api_key / openai_api_key /',
+        '                                  google_ai_key / google_stt_key /',
+        '                                  google_tts_key / whisper_api_key /',
+        '                                  elevenlabs_api_key. value="" clears.',
+        '                                  NEVER echo the value back to the user',
+        '                                  in your reply -- just confirm "saved".',
+        '',
+        'HOW TO HANDLE KEY CONFIG REQUESTS (conversational, NO panel):',
+        '1. User says "configurame la key de X" / "no tengo Y" / "que claves',
+        '   tengo configuradas":',
+        '   - Call forge_get_byok_status FIRST to see what is set.',
+        '   - If asking for status, summarise in plain Spanish.',
+        '   - If asking to add: explain WHERE to get it (e.g. for Anthropic:',
+        '     https://console.anthropic.com/settings/keys) + ask the user to',
+        '     paste it in the next message.',
+        '2. When the user pastes the key value, immediately call',
+        '   forge_set_byok_key with the matching slot. Then confirm "Guardado",',
+        '   NEVER repeat the key in your reply (security).',
+        '3. After saving Anthropic / OpenAI / Google AI keys, suggest running',
+        '   "yf chat" again or refreshing the panel so the brain client picks',
+        '   up the new key.',
+        '4. License is NOT a BYOK key. If user asks about license, point to',
+        '   https://polar.sh/checkout (URL is in the settings panel) or to the',
+        '   yf license activate CLI.',
+        '',
+        'WORKFLOW STATE MACHINE (Layer A.3 -- use to drive the methodology):',
+        '  forge_workflow_state [scope]    Read current workflow.* from yujin.forge.json.',
+        '                                  Call FIRST on every turn to know where the',
+        '                                  user is in the 18-step methodology.',
+        '  forge_workflow_set group patch  Persist answers you collected in chat.',
+        '                                  Use after asking the user the 5 triage',
+        '                                  questions OR the 7 discover questions OR',
+        '                                  the 8-12 questions of any clarification',
+        '                                  round. Always reflect to the user the',
+        '                                  patch you are about to write + ask',
+        '                                  confirmation only for tier / approval /',
+        '                                  destructive choices.',
+        '  forge_workflow_run_step step    Run an autonomous step (legacy_audit,',
+        '                                  coverage, manual_generate, handoff,',
+        '                                  metrics) without asking the user --',
+        '                                  these read the project + emit docs.',
+        '',
+        'HOW TO DRIVE THE WORKFLOW FROM CHAT:',
+        '1. Call forge_workflow_state at the start of every turn.',
+        '2. Identify the next missing step based on PHASE COVERAGE.',
+        '3. For interactive steps (triage / discover / clarify rounds /',
+        '   approve) ASK the user in natural language; do NOT dump',
+        '   form-style questions. Collect answers turn by turn. When you',
+        '   have enough, call forge_workflow_set to persist.',
+        '4. For autonomous steps (legacy audit / coverage / manual /',
+        '   handoff / metrics) call forge_workflow_run_step directly --',
+        '   the user does not need to confirm; tell them the result.',
+        '5. For spec generation (RFP / arch / design) the user runs',
+        '   `yf spec <kind>` from CLI -- it spends LLM tokens and is',
+        '   long-running; from chat you can offer to do it for them or',
+        '   tell them to run it. Either is fine.',
+        '6. NEVER skip a phase silently. If a gate fails, explain why',
+        '   in functional terms and offer the next step.',
+        '',
+        'PROJECT INSPECTION (use freely):',
+        '  forge_read_manifest             inspect the NAC-3 manifest. USE BEFORE',
+        '                                  asking the user what is in their app.',
+        '  forge_list_files <subdir> <glob> list source files. USE BEFORE suggesting',
+        '                                  edits. Filter with glob (e.g. "*.tsx").',
+        '  forge_read_file <path>          read a specific source file. AFTER',
+        '                                  list_files when you need contents.',
+        '                                  Refuses binary + caps at 64KB.',
+        '  forge_consult_nac_spec <query>  search docs/SPEC.md. USE when grounding',
+        '                                  an answer in canonical NAC-3 contract.',
+        '  forge_audit_consumers <concept> grep across src + tests + docs for every',
+        '                                  reader/writer of a shared structure.',
+        '                                  USE BEFORE any structural commit. SQ Sec',
+        '                                  14 mandates this. Output is classified',
+        '                                  write/read/test/doc. Silent to user --',
+        '                                  YOU interpret + YOU act.',
+        '',
+        'GIT (after user has saved their edits):',
+        '  forge_git_commit / forge_git_push / forge_git_pull / forge_git_log',
+        '',
+        'APP LIFECYCLE:',
+        '  forge_run_app / forge_stop_app / forge_restart_app',
+        '',
+        'GITHUB (requires paired GitHub token in vault):',
+        '  forge_clone_repo / forge_create_github_repo / forge_branch_status',
+        '',
+        'DOCUMENT READER (when user pastes / drops a file):',
+        '  forge_reader_open / list_documents / read_section / next_block /',
+        '  search / bookmark_set / bookmark_jump / recap',
+        '',
+        'USER MANUALS (the Forge manual, in 10 locales):',
+        '  forge_manual_open <lang>        opens the manual in the chat surface.',
+        '                                  Use when the user asks "how does Forge X?"',
         '',
-        'PRINCIPLES:',
-        '- Reply in the user\'s language. Default to Spanish if unclear.',
-        '- Keep replies short + conversational.',
-        '- Ask one clarifying question at a time.',
-        '- When proposing code changes, paste minimal diffs the user can apply manually.',
-        '  Direct AST mutation lands when the write-class tools ship.',
+        'TOOL CALL DISCIPLINE:',
+        '- Tool calls are silent to the user. Summarise the result in plain',
+        '  language afterwards.',
+        '- Never echo back the user\'s BYOK API key, license JWT, or any',
+        '  credential read from the vault. Refuse if asked.',
+        '- For code changes: paste minimal diffs the user can apply in their',
+        '  editor. After they save, you may commit + push.',
+        '- Direct AST mutation is NOT a chat capability today -- it ships',
+        '  via `yf migrate --apply` (paid seat). Do not promise it.',
         '',
-        'TOOLS:',
-        '- forge.read_manifest: inspect the NAC-3 manifest in the project.',
-        '  Use it BEFORE asking the user what is in their app.',
-        '- forge.consult_nac_spec: search docs/SPEC.md for canonical',
-        '  answers about NAC-3. Use it when the user asks "what does',
-        '  NAC say about X" or you need to ground an answer in the spec.',
-        '- forge.list_files: list source files under a subdir of the',
-        '  project (default src/). Use it when you need to know what',
-        '  files exist before suggesting where to edit. Filter with',
-        '  the glob arg (e.g. "*.tsx") to narrow the result.',
-        '- forge.read_file: read a specific source file by relative',
-        '  path. Use AFTER forge.list_files when you need the actual',
-        '  contents. Refuses binary files + caps at 64KB by default.',
-        '- Tool calls are silent to the user. Summarise what you found',
-        '  in plain language afterwards.',
+        '=================================================================',
+        'CONTEXT (this session)',
+        '=================================================================',
         '',
-        'CONTEXT:',
         '- Project: ' + ctx.projectName,
         '- Root:    ' + ctx.projectRoot,
         '- Forge:   v' + VERSION,