shakers-cli 0.0.0-stage → 0.14.1

package/src/rate-flow.js

@@ -0,0 +1,137 @@
+'use strict';
+
+// `rate` flow: view the talent's per-project pricing, and `--set` to change it
+// (interactive, explicit confirmation — it changes what clients pay).
+
+const { styleLabelPrefix } = require('./ansi');
+
+const CURRENCIES = ['EUR', 'USD', 'GBP'];
+const MAX_AMOUNT = 999999.99;
+
+function makeRateDeps(overrides = {}) {
+  const client = require('./rate-client');
+  return {
+    fetchPricingRate: (opts) => client.fetchPricingRate({}, opts),
+    savePricingRate: (opts) => client.savePricingRate({}, opts),
+    promptSelect: (opts) => require('./prompt-select').promptSelect(opts),
+    ...overrides,
+  };
+}
+
+function priceLine(fp, money) {
+  if (!money || money.amount == null) return fp.notSet;
+  return `${money.amount}${money.currency ? ` ${money.currency}` : ''}`;
+}
+
+// Empty pricing when the talent has none yet (upsert still works).
+const EMPTY_PRICING = { fullTimeSelected: false, fullTimePrice: null, partTimeSelected: false, partTimePrice: null };
+
+function parseAmount(raw) {
+  const s = String(raw == null ? '' : raw).trim().replace(',', '.');
+  if (!/^\d+(\.\d+)?$/.test(s)) return null;
+  const n = Number.parseFloat(s);
+  if (!Number.isFinite(n) || n < 0 || n > MAX_AMOUNT) return null;
+  return n;
+}
+
+// Merge the chosen modality's new price into the current pricing → the PUT body
+// (full object, so the untouched modality is preserved, never cleared).
+function buildBody(current, modality, amount, currency) {
+  const body = {
+    fullTimeProjectSelected: current.fullTimeSelected === true,
+    fullTimeProjectPrice: current.fullTimePrice ? { amount: current.fullTimePrice.amount, currency: current.fullTimePrice.currency } : null,
+    partTimeProjectSelected: current.partTimeSelected === true,
+    partTimeProjectPrice: current.partTimePrice ? { amount: current.partTimePrice.amount, currency: current.partTimePrice.currency } : null,
+  };
+  if (modality === 'full') { body.fullTimeProjectSelected = true; body.fullTimeProjectPrice = { amount, currency }; }
+  else { body.partTimeProjectSelected = true; body.partTimeProjectPrice = { amount, currency }; }
+  return body;
+}
+
+function renderView(io, fp, p) {
+  io.section(fp.title);
+  io.notify(styleLabelPrefix(fp.fullTime(priceLine(fp, p.fullTimeSelected ? p.fullTimePrice : null))));
+  if (p.partTimeSelected) io.notify(styleLabelPrefix(fp.partTime(priceLine(fp, p.partTimePrice))));
+  io.success(fp.done);
+}
+
+async function runSet({ io, ask, session, catalog, opts, deps }) {
+  const fp = catalog.rate;
+  const hubAccessToken = session ? session.hubAccessToken : null;
+  if (!opts.stdinIsTTY) {
+    io.error(fp.setNeedsInteractive);
+    return { ok: false, reason: 'non-interactive' };
+  }
+  const selOut = (s) => io.notify(s);
+
+  // Read current so we can show it, preserve the other modality, and diff.
+  const read = await io.withProgress(fp.loading, () => deps.fetchPricingRate({ hubAccessToken }));
+  if (!read.ok && read.reason !== 'not-found') {
+    io.error(fp.fetchFailed(read.reason));
+    return { ok: false, reason: read.reason };
+  }
+  const current = read.ok ? read.pricing : EMPTY_PRICING;
+
+  io.section(fp.setTitle);
+  io.notify(styleLabelPrefix(fp.fullTime(priceLine(fp, current.fullTimeSelected ? current.fullTimePrice : null))));
+  io.notify(styleLabelPrefix(fp.partTime(priceLine(fp, current.partTimeSelected ? current.partTimePrice : null))));
+
+  // Arrow-key pickers for every discrete choice (modality, currency).
+  const modItem = await deps.promptSelect({
+    ask, stdinIsTTY: opts.stdinIsTTY, out: selOut, header: fp.setWhich,
+    items: [{ label: fp.modalityFull, value: 'full' }, { label: fp.modalityPart, value: 'part' }],
+    labelFor: (x) => x.label, input: opts.input, output: opts.output,
+  });
+  if (!modItem) { io.notify(fp.setCancelled); return { ok: true, cancelled: true }; }
+  const modality = modItem.value;
+  const modalityLabel = modality === 'full' ? fp.modalityFull : fp.modalityPart;
+
+  const amount = parseAmount(await io.ask(fp.setAmount(modalityLabel)));
+  if (amount === null) { io.error(fp.setAmountInvalid); return { ok: false, reason: 'bad-amount' }; }
+
+  const currency = await deps.promptSelect({
+    ask, stdinIsTTY: opts.stdinIsTTY, out: selOut, header: fp.setCurrency,
+    items: CURRENCIES, labelFor: (x) => x, input: opts.input, output: opts.output,
+  });
+  if (!currency) { io.notify(fp.setCancelled); return { ok: true, cancelled: true }; }
+
+  const oldMoney = modality === 'full' ? (current.fullTimeSelected ? current.fullTimePrice : null) : (current.partTimeSelected ? current.partTimePrice : null);
+  const oldStr = priceLine(fp, oldMoney);
+  const newStr = `${amount} ${currency}`;
+  io.notify(fp.setDiff(modalityLabel, oldStr, newStr));
+  const confirmed = await io.confirm(fp.setConfirm);
+  if (!confirmed) { io.notify(fp.setCancelled); return { ok: true, cancelled: true }; }
+
+  const body = buildBody(current, modality, amount, currency);
+  const res = await io.withProgress(fp.setSaving, () => deps.savePricingRate({ hubAccessToken, pricing: body }));
+  if (!res.ok) { io.error(fp.setFailed(res.reason)); return { ok: false, reason: res.reason }; }
+  io.success(fp.setDone(modalityLabel, newStr));
+  return { ok: true, set: { modality, amount, currency } };
+}
+
+async function runRate({ io, rawOut, ask, session, catalog, opts = {}, deps = makeRateDeps() }) {
+  const fp = catalog.rate;
+  if (opts.set) return runSet({ io, ask, session, catalog, opts, deps });
+
+  const hubAccessToken = session ? session.hubAccessToken : null;
+  const doFetch = () => deps.fetchPricingRate({ hubAccessToken });
+  const res = opts.json ? await doFetch() : await io.withProgress(fp.loading, doFetch);
+  if (!res.ok) {
+    io.error(res.reason === 'not-found' ? fp.notFound : fp.fetchFailed(res.reason));
+    return { ok: false, reason: res.reason };
+  }
+  if (opts.json) {
+    (rawOut || ((s) => process.stdout.write(s)))(`${JSON.stringify({ ok: true, pricing: res.pricing }, null, 2)}\n`);
+    return { ok: true, pricing: res.pricing };
+  }
+  renderView(io, fp, res.pricing);
+  return { ok: true, pricing: res.pricing };
+}
+
+module.exports = {
+  makeRateDeps,
+  runRate,
+  parseAmount,
+  buildBody,
+  CURRENCIES,
+};

package/src/register-context.js

@@ -0,0 +1,145 @@
+'use strict';
+
+// Local context SUGGESTIONS for the register flow: the environment timezone, the
+// local git identity, the GitHub login and CV candidates. These are proposals the
+// model offers the talent to confirm — they are NEVER auto-written. No file
+// content, no commit scanning, no network, no session: CV candidates are file
+// NAMES only. This is deliberately NOT the authorship/evidence path.
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { getHomeDir, tildify } = require('./env-paths');
+
+// Where a talent keeps a CV, and how deep we look under each folder. iCloud
+// Drive holds Desktop/Documents for many Mac users.
+const CV_DIRS = ['Desktop', 'Documents', 'Downloads', 'Escritorio', 'Documentos', 'Descargas', 'Library/Mobile Documents/com~apple~CloudDocs'];
+const CV_MAX_DEPTH = 3;
+const CV_MAX_RESULTS = 8;
+const CV_EXTENSIONS = /\.(pdf|docx?)$/i;
+const CV_NAME = /(^|[^a-z])(cv|curriculum|curr[ií]culum|resume|r[ée]sum[ée])([^a-z]|$)/i;
+
+function detectTimezone() {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || null;
+  } catch {
+    return null;
+  }
+}
+
+function gitConfig(key, cwd) {
+  try {
+    const out = execFileSync('git', ['config', '--get', key], {
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      cwd: cwd || process.cwd(),
+    });
+    const value = String(out || '').trim();
+    return value || null;
+  } catch {
+    return null;
+  }
+}
+
+// The login the GitHub CLI is signed in with, read from its local hosts file
+// (no network), else the conventional `github.user` git key.
+function detectGithubUser(home, cwd) {
+  try {
+    const hosts = fs.readFileSync(path.join(home, '.config', 'gh', 'hosts.yml'), 'utf8');
+    const block = hosts.split(/^github\.com:\s*$/m)[1];
+    const match = block && block.match(/^\s+user:\s*(\S+)\s*$/m);
+    if (match) return match[1];
+  } catch {
+    // no gh CLI config
+  }
+  return gitConfig('github.user', cwd);
+}
+
+const fold = (text) => String(text || '').normalize('NFD').replace(/[\u0300-\u036f]/g, '').toLowerCase();
+
+const nameTokens = (personName) => fold(personName).split(/[^a-z0-9]+/).filter((t) => t.length >= 3);
+
+// Whether a file name carries a token of the person's name. People who hire keep
+// other people's CVs in Downloads; only a name match makes a candidate theirs.
+function matchesName(fileName, personName) {
+  const file = fold(fileName);
+  return nameTokens(personName).some((t) => file.includes(t));
+}
+
+// A file named after the person but without a CV word (`Alvaro Torro.pdf`) is a
+// candidate only when it carries their full name, so one common first name does
+// not pull in every contract and invoice.
+function carriesFullName(fileName, personName) {
+  const tokens = nameTokens(personName);
+  const file = fold(fileName);
+  return tokens.length >= 2 && tokens.every((t) => file.includes(t));
+}
+
+// Words that say nothing about whose CV it is: `cv.pdf`, `Curriculum_2024_ES.pdf`,
+// `resume-final-v2.pdf`. Such a file may be the talent's own, so it is worth asking.
+const GENERIC_WORDS = /\b(cv|curriculum|curriculo|resume|vitae|mi|my|el|the|de|of|final|actualizado|updated|nuevo|new|latest|es|en|esp|eng|spanish|english|espanol|ingles|v\d+|copia|copy)\b/g;
+
+function isGenericCvName(fileName) {
+  const rest = fold(fileName.replace(/\.pdf$/i, '')).replace(/[^a-z0-9]+/g, ' ').replace(GENERIC_WORDS, ' ').replace(/\d+/g, ' ');
+  return rest.trim().length === 0;
+}
+
+// PDF/Word files whose NAME looks like a CV or carries the person's full name:
+// name matches first, then generic names, then newest. Never opens a file.
+function findCvCandidates(home, personName) {
+  // Without a name there is nothing to match: null says unknown, never a mismatch.
+  const known = nameTokens(personName).length > 0;
+  const found = [];
+  const walk = (dir, depth) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (depth < CV_MAX_DEPTH) walk(full, depth + 1);
+      } else if (entry.isFile() && CV_EXTENSIONS.test(entry.name)
+        && (CV_NAME.test(entry.name.replace(CV_EXTENSIONS, '')) || carriesFullName(entry.name, personName))) {
+        try {
+          found.push({
+            path: full,
+            nameMatch: known ? matchesName(entry.name, personName) : null,
+            generic: isGenericCvName(entry.name),
+            mtimeMs: fs.statSync(full).mtimeMs,
+          });
+        } catch {
+          // vanished between readdir and stat
+        }
+      }
+    }
+  };
+  for (const name of CV_DIRS) walk(path.join(home, name), 1);
+  return found
+    .sort((a, b) => Number(b.nameMatch) - Number(a.nameMatch) || Number(b.generic) - Number(a.generic) || b.mtimeMs - a.mtimeMs)
+    .slice(0, CV_MAX_RESULTS)
+    .map(({ path: cvPath, nameMatch, generic }) => ({ path: tildify(cvPath, { SHAKERS_CLI_HOME_DIR: home }), nameMatch, generic }));
+}
+
+// Returns the signals found, each clearly a SUGGESTION to confirm. `talentName`
+// (what the AI already knows) sharpens the CV match beyond the git name.
+function readRegisterContextSuggestions({ cwd, env = process.env, talentName } = {}) {
+  const home = getHomeDir(env);
+  const githubUser = detectGithubUser(home, cwd);
+  const gitName = gitConfig('user.name', cwd);
+  const personName = [talentName, gitName].filter((n) => typeof n === 'string' && n.trim()).join(' ');
+  return {
+    timezone: detectTimezone(),
+    gitName,
+    gitEmail: gitConfig('user.email', cwd),
+    githubUser,
+    githubUrl: githubUser ? `https://github.com/${githubUser}` : null,
+    cvCandidates: findCvCandidates(home, personName),
+  };
+}
+
+module.exports = { readRegisterContextSuggestions, detectTimezone, findCvCandidates, detectGithubUser, isGenericCvName, nameTokens, fold };

package/src/render-ai-fluency.js

@@ -0,0 +1,266 @@
+'use strict';
+
+// Renders the "My work with AI" preview (3x3 matrix + vision E + howIWork F +
+// traction), terminal + HTML. Copy is inlined for the spike; promote to i18n later.
+
+const { SETUP_CODE, CELL_NAMES } = require('./ai-fluency-cell');
+const { detectedToolNames } = require('./detected-tools');
+
+const SETUP_ORDER = ['ASSISTED', 'EXTENDED', 'ORCHESTRATED'];
+const USAGE_ORDER = ['REACTIVE', 'DELIBERATE', 'RIGOROUS'];
+
+const COPY = {
+  es: {
+    title: 'Tu trabajo con IA (Setup x Uso)',
+    usage: { REACTIVE: 'Reactivo', DELIBERATE: 'Deliberado', RIGOROUS: 'Riguroso' },
+    setup: { ASSISTED: 'Asistido', EXTENDED: 'Extendido', ORCHESTRATED: 'Orquestado' },
+    aiNative: 'AI Native',
+    pending: 'Tu perfil se está evaluando; míralo en un momento en "Mi trabajo con IA".',
+    matrixUpdating: 'Tu matriz Setup x Uso se está actualizando; aparecerá en breve.',
+    setupOnly: 'Disponible en tu perfil tras iniciar sesión y compartir el informe.',
+    visionLabel: 'Mi visión sobre la IA',
+    howIWorkLabel: 'Cómo trabajo con IA',
+    howIWorkMissing: 'Se genera tras la entrevista de onboarding.',
+    tractionLabel: 'Actividad',
+    sessions90d: 'sesiones (90d)',
+    daysPerWeek: 'días/semana',
+    agents: (d, p) => `${d} agentes detectados${p != null ? ` · ${p} en tu perfil` : ''}`,
+    toolsLabel: 'herramientas',
+    axisSetup: 'Setup',
+    axisUsage: 'Uso',
+    agentsLabel: 'Agentes',
+  },
+  en: {
+    title: 'Your work with AI (Setup x Usage)',
+    usage: { REACTIVE: 'Reactive', DELIBERATE: 'Deliberate', RIGOROUS: 'Rigorous' },
+    setup: { ASSISTED: 'Assisted', EXTENDED: 'Extended', ORCHESTRATED: 'Orchestrated' },
+    aiNative: 'AI Native',
+    pending: 'Your profile is being evaluated; check "My work with AI" shortly.',
+    matrixUpdating: 'Your Setup x Usage matrix is updating; it will appear shortly.',
+    setupOnly: 'Available on your profile after you log in and share the report.',
+    visionLabel: 'My vision on AI',
+    howIWorkLabel: 'How I work with AI',
+    howIWorkMissing: 'Generated after the onboarding interview.',
+    tractionLabel: 'Traction',
+    sessions90d: 'sessions (90d)',
+    daysPerWeek: 'days/week',
+    agents: (d, p) => `${d} agents detected${p != null ? ` · ${p} on your profile` : ''}`,
+    toolsLabel: 'tools',
+    axisSetup: 'Setup',
+    axisUsage: 'Usage',
+    agentsLabel: 'Agents',
+  },
+};
+
+function copyFor(lang) {
+  return COPY[lang === 'es' ? 'es' : 'en'];
+}
+
+// The matrix band can lag behind E/F (independent projection). When absent, render
+// E/F/traction anyway and swap the 3x3 grid for a short "updating" note.
+function matrixReady(matrix) {
+  return !!(matrix && (matrix.setupLevel || matrix.usageLevel || matrix.cell));
+}
+
+const noColor = new Proxy({}, { get: () => '' });
+
+const esc = (s) => String(s).replace(/[&<>"]/g, (ch) =>
+  ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[ch]));
+
+// Traction metrics as compact "label: value" fragments, omitting null fields.
+function tractionParts(traction, t) {
+  if (!traction) return [];
+  const parts = [];
+  if (traction.sessions90d != null) parts.push(`${traction.sessions90d} ${t.sessions90d}`);
+  if (traction.activeDaysPerWeek != null) parts.push(`${traction.activeDaysPerWeek} ${t.daysPerWeek}`);
+  if (traction.agentsDetected != null) parts.push(t.agents(traction.agentsDetected, traction.agentsOnProfile));
+  const tools = detectedToolNames(traction.tools);
+  if (tools.length) parts.push(`${t.toolsLabel}: ${tools.join(', ')}`);
+  return parts;
+}
+
+function matrixTerminalLines(matrix, t, c) {
+  // Column widths from the longest label (incl. current-cell brackets). Pad BEFORE
+  // colorizing: padEnd counts ANSI escape bytes, so padding a colored string misaligns.
+  const rowLabels = SETUP_ORDER.map((s) => `${SETUP_CODE[s]} ${t.setup[s]}`);
+  const rowW = Math.max(...rowLabels.map((s) => s.length)) + 2;
+  const cellLabels = SETUP_ORDER.flatMap((s) => USAGE_ORDER.map((u) => CELL_NAMES[s][u]));
+  const headerLabels = USAGE_ORDER.map((u) => t.usage[u]);
+  const colW = Math.max(...cellLabels.map((x) => x.length), ...headerLabels.map((x) => x.length)) + 4;
+
+  const lines = [`  ${c.bold}${t.title}${c.reset}`];
+  lines.push(`  ${c.dim}${' '.repeat(rowW) + headerLabels.map((u) => u.padEnd(colW)).join('')}${c.reset}`);
+  for (const s of SETUP_ORDER) {
+    const rowLabel = `${SETUP_CODE[s]} ${t.setup[s]}`.padEnd(rowW);
+    const cells = USAGE_ORDER.map((u) => {
+      const name = CELL_NAMES[s][u];
+      const isCurrent = matrix.setupLevel === s && matrix.usageLevel === u;
+      if (isCurrent) return `${c.accent}${c.bold}${`[${name}]`.padEnd(colW)}${c.reset}`;
+      return `${c.muted}${name.padEnd(colW)}${c.reset}`;
+    }).join('');
+    lines.push(`  ${c.dim}${rowLabel}${c.reset}${cells}`);
+  }
+  return lines;
+}
+
+function buildProfileSections(preview, t) {
+  const sections = [];
+  const m = (preview && preview.matrix) || {};
+  const setupExp = preview.setup && preview.setup.explanation ? preview.setup.explanation : null;
+  if (m.setupLevel) {
+    const value = [m.setupCode, t.setup[m.setupLevel]].filter(Boolean).join(' ');
+    sections.push({ kind: 'axis', label: t.axisSetup, value, explanation: setupExp });
+  }
+  const usageExp = preview.usage && preview.usage.explanation ? preview.usage.explanation : null;
+  if (m.usageLevel) {
+    sections.push({ kind: 'axis', label: t.axisUsage, value: t.usage[m.usageLevel] || m.usageLevel, explanation: usageExp });
+  }
+  if (preview.vision) sections.push({ kind: 'narrative', label: t.visionLabel, body: preview.vision });
+  if (preview.howIWork) sections.push({ kind: 'narrative', label: t.howIWorkLabel, body: preview.howIWork });
+  return sections;
+}
+
+const axisBody = (s) => (s.explanation ? `${s.value} — ${s.explanation}` : s.value);
+
+// Full "My work with AI" preview, terminal. `preview` is the normalized shape from
+// resolveAiProfilePreview; `status` drives the fallbacks.
+function renderAiProfileTerminal({ status, preview } = {}, { lang = 'en', c = noColor } = {}) {
+  const t = copyFor(lang);
+  // Non-fatal notices (not-yet-judged / setup-only) → yellow.
+  if (status === 'unavailable') return `  ${c.warning || c.muted}${t.setupOnly}${c.reset}`;
+  if (status !== 'ready' || !preview) return `  ${c.warning || c.muted}${t.pending}${c.reset}`;
+
+  const lines = matrixReady(preview.matrix)
+    ? matrixTerminalLines(preview.matrix, t, c)
+    : [`  ${c.bold}${t.title}${c.reset}`, `  ${c.warning || c.muted}${t.matrixUpdating}${c.reset}`];
+  const sections = buildProfileSections(preview, t);
+  const axes = sections.filter((s) => s.kind === 'axis');
+  if (axes.length) {
+    lines.push('');
+    for (const a of axes) lines.push(`  ${c.bold}${a.label}:${c.reset} ${c.muted}${axisBody(a)}${c.reset}`);
+  }
+  for (const n of sections.filter((s) => s.kind === 'narrative')) {
+    lines.push('', `  ${c.bold}${n.label}${c.reset}`, `  ${c.muted}${n.body}${c.reset}`);
+  }
+  // Traction now lives in the Activity section (terminal-agents#printActivity).
+  return lines.join('\n');
+}
+
+function plainAgentLines(agents) {
+  if (!Array.isArray(agents) || agents.length === 0) return [];
+  return agents.map((a) => {
+    const bits = [a.category, a.role].filter(Boolean);
+    return bits.length ? `- ${a.name} — ${bits.join(' · ')}` : `- ${a.name}`;
+  });
+}
+
+// Full "My work with AI" report as plain markdown (NO ANSI), for the MCP tool so a chat client shows the same report the CLI terminal prints.
+function renderAiProfilePlain({ status, preview } = {}, { lang = 'en', agents = [] } = {}) {
+  const t = copyFor(lang);
+  const out = [];
+  if (status === 'unavailable') {
+    out.push(t.setupOnly);
+  } else if (status !== 'ready' || !preview) {
+    out.push(t.pending);
+  } else {
+    if (matrixReady(preview.matrix)) {
+      const gridLines = matrixTerminalLines(preview.matrix, t, noColor).slice(1);
+      out.push(`## ${t.title}`, '', '```', ...gridLines, '```');
+    } else {
+      out.push(`## ${t.title}`, '', t.matrixUpdating);
+    }
+    const sections = buildProfileSections(preview, t);
+    const axes = sections.filter((s) => s.kind === 'axis');
+    if (axes.length) {
+      out.push('');
+      for (const a of axes) out.push(`${a.label}: ${axisBody(a)}`);
+    }
+    for (const n of sections.filter((s) => s.kind === 'narrative')) {
+      out.push('', `**${n.label}**`, n.body);
+    }
+    const tp = tractionParts(preview.traction, t);
+    if (tp.length) out.push('', `**${t.tractionLabel}:** ${tp.join(' · ')}`);
+  }
+  const agentLines = plainAgentLines(agents);
+  if (agentLines.length) out.push('', `**${t.agentsLabel}**`, ...agentLines);
+  return out.join('\n');
+}
+
+// Full "My work with AI" preview, HTML. '' when there is nothing to show inline.
+function renderAiProfileHtml({ status, preview } = {}, { lang = 'en' } = {}) {
+  const t = copyFor(lang);
+  if (status === 'unavailable') return `<p class="ai-fluency-note">${esc(t.setupOnly)}</p>`;
+  if (status !== 'ready' || !preview) return `<p class="ai-fluency-note">${esc(t.pending)}</p>`;
+
+  const m = preview.matrix;
+  const out = [
+    `<section class="ai-fluency" aria-label="${esc(t.title)}">`,
+    `<h3>${esc(t.title)}</h3>`,
+  ];
+  if (matrixReady(m)) {
+    const rows = SETUP_ORDER.map((s) => {
+      const cells = USAGE_ORDER.map((u) => {
+        const current = m.setupLevel === s && m.usageLevel === u;
+        return `<td class="ai-fluency-cell${current ? ' is-current' : ''}">${esc(CELL_NAMES[s][u])}</td>`;
+      }).join('');
+      return `<tr><th scope="row">${esc(SETUP_CODE[s])} ${esc(t.setup[s])}</th>${cells}</tr>`;
+    }).join('');
+    const head = USAGE_ORDER.map((u) => `<th scope="col">${esc(t.usage[u])}</th>`).join('');
+    out.push(
+      '<table class="ai-fluency-matrix">',
+      `<thead><tr><th></th>${head}</tr></thead>`,
+      `<tbody>${rows}</tbody>`,
+      '</table>',
+    );
+  } else {
+    out.push(`<p class="ai-fluency-note">${esc(t.matrixUpdating)}</p>`);
+  }
+  if (m.cell) {
+    out.push(`<p class="ai-fluency-current">${esc(m.setupCode)}·${esc(t.usage[m.usageLevel] || m.usageLevel)} → <strong>${esc(m.cell)}</strong>${m.isAiNative ? ` <span class="ai-native">★ ${esc(t.aiNative)}</span>` : ''}</p>`);
+  }
+  if (preview.vision) {
+    out.push(`<div class="ai-vision"><h4>${esc(t.visionLabel)}</h4><p>${esc(preview.vision)}</p></div>`);
+  }
+  out.push(`<div class="ai-howiwork"><h4>${esc(t.howIWorkLabel)}</h4><p>${preview.howIWork ? esc(preview.howIWork) : `<em>${esc(t.howIWorkMissing)}</em>`}</p></div>`);
+  const parts = tractionParts(preview.traction, t);
+  if (parts.length) {
+    out.push(`<p class="ai-traction"><strong>${esc(t.tractionLabel)}:</strong> ${esc(parts.join(' · '))}</p>`);
+  }
+  out.push('</section>');
+  return out.join('');
+}
+
+// Matrix-only HTML (kept for render-sheet.js; the HTML report is a separate iteration).
+function renderAiFluencyMatrixHtml({ status, usage } = {}, { lang = 'en' } = {}) {
+  const t = copyFor(lang);
+  if (status === 'unavailable') return `<p class="ai-fluency-note">${esc(t.setupOnly)}</p>`;
+  if (status !== 'ready' || !usage || !usage.cell) return `<p class="ai-fluency-note">${esc(t.pending)}</p>`;
+  const rows = SETUP_ORDER.map((s) => {
+    const cells = USAGE_ORDER.map((u) => {
+      const current = usage.setupLevel === s && usage.usageLevel === u;
+      return `<td class="ai-fluency-cell${current ? ' is-current' : ''}">${esc(CELL_NAMES[s][u])}</td>`;
+    }).join('');
+    return `<tr><th scope="row">${esc(SETUP_CODE[s])} ${esc(t.setup[s])}</th>${cells}</tr>`;
+  }).join('');
+  const head = USAGE_ORDER.map((u) => `<th scope="col">${esc(t.usage[u])}</th>`).join('');
+  return [
+    `<section class="ai-fluency" aria-label="${esc(t.title)}">`,
+    `<h3>${esc(t.title)}</h3>`,
+    '<table class="ai-fluency-matrix">',
+    `<thead><tr><th></th>${head}</tr></thead>`,
+    `<tbody>${rows}</tbody></table>`,
+    `<p class="ai-fluency-current">${esc(usage.setupCode)}·${esc(t.usage[usage.usageLevel] || usage.usageLevel)} → <strong>${esc(usage.cell)}</strong>${usage.isAiNative ? ` <span class="ai-native">★ ${esc(t.aiNative)}</span>` : ''}</p>`,
+    '</section>',
+  ].join('');
+}
+
+module.exports = {
+  renderAiProfileTerminal,
+  renderAiProfilePlain,
+  renderAiProfileHtml,
+  renderAiFluencyMatrixHtml,
+  copyFor,
+  tractionParts,
+  SETUP_ORDER,
+  USAGE_ORDER,
+};