@rosh100yx/outlier 0.7.0 → 0.10.2

package/src/aggregate.ts

@@ -0,0 +1,59 @@
+// #8 Light team/fleet aggregation — local-first, no export.
+//
+// Each developer runs `outlier --json > me.json` and drops it in a shared folder (or CI
+// collects them). `outlier aggregate <dir>` merges those JSON files into a team rollup.
+// No machine talks to another; it only reads JSON the team already produced. This is the
+// honest, minimal version of fleet view — real aggregation without a backend.
+
+import { readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+export interface TeamRollup {
+  developers: number;
+  avgAiPercent: number | null;
+  maxAiPercent: number | null;
+  totalEstUsd: number;
+  worstBlastRadius: string;
+  overLimit: number;        // how many devs are over their AI cap
+  reachWriteDeploy: number; // total write/deploy-capable tools across the team
+  notes: string[];
+}
+
+const BLAST_ORDER = ['LOW', 'MEDIUM', 'HIGH', 'CRITICAL'];
+
+export function aggregateDir(dir: string): TeamRollup {
+  const files = readdirSync(dir).filter(f => f.endsWith('.json'));
+  const audits: any[] = [];
+  for (const f of files) {
+    try {
+      const j = JSON.parse(readFileSync(join(dir, f), 'utf-8'));
+      if (j?.tool === 'outlier') audits.push(j);
+    } catch {}
+  }
+
+  const aiPcts = audits.map(a => a.authorship?.aiPercent).filter((x: any) => typeof x === 'number');
+  const spends = audits.map(a => a.cost?.estUsd || 0);
+  const blasts = audits.map(a => a.reach?.blastRadius).filter(Boolean);
+  const overs = audits.filter(a => a.policy?.status === 'over').length;
+  const writeDeploy = audits.reduce((s, a) => s + (a.reach?.writeOrDeployCount || 0), 0);
+
+  const worst = blasts.reduce((m: string, b: string) =>
+    BLAST_ORDER.indexOf(b) > BLAST_ORDER.indexOf(m) ? b : m, 'LOW');
+
+  const notes: string[] = [];
+  if (aiPcts.length && Math.max(...aiPcts) > 70) notes.push('At least one developer is over 70% AI authorship.');
+  if (worst === 'HIGH' || worst === 'CRITICAL') notes.push(`Worst-case agent blast radius across the team is ${worst}.`);
+  if (overs > 0) notes.push(`${overs} developer(s) over their AI-authorship limit.`);
+  if (audits.length === 0) notes.push('No outlier --json files found in this folder.');
+
+  return {
+    developers: audits.length,
+    avgAiPercent: aiPcts.length ? +(aiPcts.reduce((a: number, b: number) => a + b, 0) / aiPcts.length).toFixed(1) : null,
+    maxAiPercent: aiPcts.length ? Math.max(...aiPcts) : null,
+    totalEstUsd: +spends.reduce((a: number, b: number) => a + b, 0).toFixed(2),
+    worstBlastRadius: worst,
+    overLimit: overs,
+    reachWriteDeploy: writeDeploy,
+    notes,
+  };
+}

package/src/capabilities.ts

@@ -72,10 +72,15 @@ export async function getCapabilitiesStats(repoPath: string = process.cwd(), hom
   const mcpNames = new Set<string>();
 
   // MCP servers — the agent's actual tool reach. Read from every place they live.
+  // Read MCP servers from every place agents declare them (Claude, Cursor, Gemini, project).
   for (const cfg of [
     join(homeDirPath, '.claude.json'),
     join(homeDirPath, '.claude', 'settings.json'),
+    join(homeDirPath, '.cursor', 'mcp.json'),
+    join(homeDirPath, '.gemini', 'config', 'mcp_config.json'),
+    join(homeDirPath, '.gemini', 'settings.json'),
     join(repoPath, '.mcp.json'),
+    join(repoPath, '.cursor', 'mcp.json'),
     join(repoPath, '.claude', 'settings.json'),
   ]) {
     const j = readJson(cfg);

package/src/carbon.ts

@@ -117,6 +117,33 @@ function estimateUsd(output: number, cacheRead: number, total: number): number {
   return (output / 1e6) * 9 + (cacheRead / 1e6) * 0.3 + (otherInput / 1e6) * 3;
 }
 
+// #6 CodeCarbon: if the developer runs CodeCarbon, it writes a real MEASURED
+// emissions.csv (hardware energy, not a token estimate). Read the latest run.
+// Columns (codecarbon >=2): timestamp,project_name,...,duration,emissions,...,energy_consumed,...
+function readCodeCarbon(cwd: string, home: string): { energyKwh: number; co2Kg: number } | null {
+  const { readFileSync, existsSync } = require('fs');
+  const { join } = require('path');
+  for (const p of [join(cwd, 'emissions.csv'), join(home, '.codecarbon', 'emissions.csv')]) {
+    try {
+      if (!existsSync(p)) continue;
+      const lines = readFileSync(p, 'utf-8').trim().split('\n');
+      if (lines.length < 2) continue;
+      const header = lines[0].split(',');
+      const iEm = header.indexOf('emissions');           // kg CO2eq
+      const iEn = header.indexOf('energy_consumed');      // kWh
+      if (iEm === -1 && iEn === -1) continue;
+      let co2 = 0, kwh = 0;
+      for (const row of lines.slice(1)) {
+        const cols = row.split(',');
+        co2 += parseFloat(cols[iEm]) || 0;
+        kwh += parseFloat(cols[iEn]) || 0;
+      }
+      return { energyKwh: kwh, co2Kg: co2 };
+    } catch {}
+  }
+  return null;
+}
+
 function getLocalGridFactor(): { region: string, factor: number } {
   try {
     const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
@@ -147,9 +174,11 @@ export async function getCarbonStats(): Promise<CarbonStats> {
     }
   }
 
-  // Model-aware energy (replaces the single flat 0.662 coefficient).
-  const energyKwh = energyKwhByModel(outputByModel);
+  // Carbon: prefer CodeCarbon's measured hardware data; else model-aware estimate.
   const localGrid = getLocalGridFactor();
+  const measured = readCodeCarbon(process.cwd(), homedir());
+  const energyKwh = measured ? measured.energyKwh : energyKwhByModel(outputByModel);
+  const measuredCo2 = measured ? measured.co2Kg : null;
 
   // Source provenance for honest labelling in the UI.
   const sources = detectSources();
@@ -165,8 +194,8 @@ export async function getCarbonStats(): Promise<CarbonStats> {
     energyKwh,
     co2KgVietnam: (energyKwh * gridFactors.vietnam) / 1000,
     co2KgFrance: (energyKwh * gridFactors.france) / 1000,
-    localCo2Kg: (energyKwh * localGrid.factor) / 1000,
-    localRegion: localGrid.region,
+    localCo2Kg: measuredCo2 !== null ? measuredCo2 : (energyKwh * localGrid.factor) / 1000,
+    localRegion: measured ? 'CodeCarbon (measured)' : localGrid.region,
     sessions,
     estUsd,
     costIsReal,

package/src/cli.ts

@@ -5,6 +5,9 @@ import pc from 'picocolors';
 import { getAuthorshipStats } from './git';
 import { getCarbonStats } from './carbon';
 import { getCapabilitiesStats } from './capabilities';
+import { deriveInsights, type Insight } from './insights';
+import { projectEconomics } from './economics';
+import { aggregateDir } from './aggregate';
 import { writeFileSync, readFileSync, chmodSync, existsSync } from 'fs';
 import { join } from 'path';
 import { detectAgent } from './agent';
@@ -20,6 +23,40 @@ const ASCII_LOGO = `
 
 let finalReceipt = '';
 
+// Turn the left-rail receipt into a clean closed rectangle (adds the right border,
+// padding each line to a fixed inner width). Width-aware: strips ANSI and counts a few
+// known wide glyphs as 2 columns so the right edge lines up in a terminal and on GitHub.
+function closeBox(s: string, W = 66): string {
+  const wide = new Set(['⚠', '🛑', '✈', '🌱', '📸', '🔬', '💾', '💡', '✅', '❌', '😾', '😀']);
+  const chW = (ch: string) => { const cp = ch.codePointAt(0)!; return (cp >= 0x1F000 || wide.has(ch)) ? 2 : 1; };
+  const rail = '\x1b[2m│\x1b[0m';
+  // Fit a (possibly ANSI-coloured) line to exactly `totalVis` visible columns: pad with
+  // spaces, or truncate with an ellipsis — preserving colour codes either way.
+  const fit = (line: string, totalVis: number) => {
+    const parts = line.split(/(\x1b\[[0-9;]*m)/);
+    let out = '', vis = 0, cut = false;
+    for (const p of parts) {
+      if (/^\x1b\[/.test(p)) { out += p; continue; }
+      for (const ch of p) {
+        const w = chW(ch);
+        if (vis + w > totalVis - 1) { cut = true; break; }
+        out += ch; vis += w;
+      }
+      if (cut) break;
+    }
+    if (cut) { out += '…'; vis += 1; }
+    return out + ' '.repeat(Math.max(0, totalVis - vis)) + '\x1b[0m';
+  };
+  return s.split('\n').map(line => {
+    const plain = line.replace(/\x1b\[[0-9;]*m/g, '');
+    if (/^\s*┌/.test(plain)) return ' \x1b[2m┌' + '─'.repeat(W) + '┐\x1b[0m';
+    if (/^\s*├/.test(plain)) return ' \x1b[2m├' + '─'.repeat(W) + '┤\x1b[0m';
+    if (/^\s*└/.test(plain)) return ' \x1b[2m└' + '─'.repeat(W) + '┘\x1b[0m';
+    if (/^\s*│/.test(plain)) return fit(line, 2 + W) + rail; // 2 = leading space + left rail
+    return line;
+  }).join('\n');
+}
+
 // Build a stable, machine-readable audit object. This is the contract agents,
 // swarms, and CI parse — everything the human receipt shows, as plain JSON.
 async function emitJson() {
@@ -82,6 +119,8 @@ async function emitJson() {
       aiCapPercent: cap * 100,
       status: aiRatio > cap ? 'over' : 'within',
     },
+    insights: deriveInsights({ authorship: gitStats, carbon, caps, policyCap: cap }),
+    economics: projectEconomics({ aiRatio, estUsdSession: carbon ? carbon.estUsd : 0, teamSize: 1 }),
   };
 
   // Only JSON on stdout — nothing else.
@@ -143,7 +182,15 @@ async function main() {
       } catch (e) {}
     }
     if (alreadyRun) process.exit(0);
-    action = 'status';
+    // Compact once-per-day greeting (for the Claude Code plugin SessionStart hook) —
+    // a single line, fast, no full receipt.
+    const g = await getAuthorshipStats().catch(() => null);
+    const cp = await getCapabilitiesStats().catch(() => null);
+    const aiP = g ? (g.ratio * 100).toFixed(0) + '%' : '—';
+    const br = cp ? cp.blastRadius : '—';
+    const brc = br === 'HIGH' || br === 'CRITICAL' ? pc.red : br === 'MEDIUM' ? pc.yellow : pc.green;
+    console.log(`${pc.dim('[outlier]')} AI authorship ${pc.bold(aiP)} · agent reach ${brc(pc.bold(br))} ${pc.dim('· before you delegate, run: outlier preflight')}`);
+    process.exit(0);
   }
 
   // Agent / CI / swarm contract: --json emits a structured audit and nothing else
@@ -164,6 +211,7 @@ async function main() {
     console.log(pc.dim('  how much of your code AI wrote, what it cost, and how to keep your skill.\n'));
     console.log(pc.bold('COMMANDS:'));
     console.log(`  ${pc.cyan('outlier')}              Run the audit (the default — same as 'status')`);
+    console.log(`  ${pc.cyan('outlier preflight')}    Quick briefing BEFORE you start an agent (reach + skill + spend)`);
     console.log(`  ${pc.cyan('outlier status')}       Full audit: who wrote the code, what it cost, your limit`);
     console.log(`  ${pc.cyan('outlier status --save')} Save the audit to ./outlier-audit.txt`);
     console.log(`  ${pc.cyan('outlier --json')}       Machine-readable audit (for agents, CI, swarms)`);
@@ -398,6 +446,16 @@ Conservative Floor: ${color(nmPct + '%')}`,
           reachStr = `${col(pc.bold(rc))} · ${capabilities.mcps.length} tools` + (risky ? pc.dim(`, ${risky} can write/deploy`) : '');
         }
 
+        // Insight engine: turn the numbers into the top thing to actually do.
+        const insights = deriveInsights({ authorship: gitStats, carbon, caps: capabilities, policyCap: 0.70 });
+        const sevColor = (s: string) => s === 'critical' ? pc.red : s === 'warn' ? pc.yellow : s === 'good' ? pc.green : pc.cyan;
+        const sevMark = (s: string) => s === 'critical' ? '✗' : s === 'warn' ? '⚠' : s === 'good' ? '✓' : 'i';
+        const insightLines = insights.slice(0, 2).map((ins: Insight) =>
+          ` ${pc.dim('│')} ${sevColor(ins.severity)(sevMark(ins.severity))} ${pc.bold(ins.title)}\n` +
+          ` ${pc.dim('│')}   ${ins.detail.length > 56 ? ins.detail.slice(0, 55) + '…' : ins.detail}\n` +
+          ` ${pc.dim('│')}   ${pc.cyan('→ ' + ins.action)}`
+        ).join(`\n ${pc.dim('│')}\n`);
+
         // The thermal receipt below is the single canonical output for `status`.
         // (The old @clack dashboard panel was removed: it duplicated the receipt's
         // numbers in a second format, doubling the output on every run.)
@@ -471,6 +529,9 @@ Conservative Floor: ${color(nmPct + '%')}`,
  ${pc.dim('│')} ${pc.bold(pc.bgYellow(pc.black(' YOUR LIMIT ')))}
  ${pc.dim('│')} AI cap   ${pc.bold('70%')} ${pc.dim('· change with: outlier policy')}
  ${pc.dim('│')} Status   ${policyStatus} ${pc.dim('·')} ${policyAction}
+ ${pc.dim('├────────────────────────────────────────────────────────')}
+ ${pc.dim('│')} ${pc.bold(pc.bgGreen(pc.black(' WHAT TO DO ')))}
+${insightLines}
  ${pc.dim('├────────────────────────────────────────────────────────')}
  ${pc.dim('│')} ${pc.dim('Numbers are local estimates — authorship is a proxy and')}
  ${pc.dim('│')} ${pc.dim('carbon is rough. How it works: outlier --help')}
@@ -529,6 +590,62 @@ ${pc.dim('This is your attack surface. Fewer write/deploy tools per session = sm
       s.stop('Audit failed');
       console.error(pc.red(e.message));
     }
+  } else if (action === 'aggregate') {
+    // Team/fleet rollup from a folder of `outlier --json` files. Local-first, no export.
+    const dir = process.argv[3];
+    if (!dir || !existsSync(dir)) {
+      console.error(pc.red('Usage: outlier aggregate <folder-of-json-audits>'));
+      console.log(pc.dim('  Each dev: outlier --json > team/<name>.json   then: outlier aggregate team/'));
+      process.exit(1);
+    }
+    const r = aggregateDir(dir);
+    note(
+      `Developers:        ${pc.bold(String(r.developers))}
+Avg AI authorship: ${pc.bold(r.avgAiPercent !== null ? r.avgAiPercent + '%' : '—')}   Max: ${r.maxAiPercent !== null ? r.maxAiPercent + '%' : '—'}
+Over their limit:  ${r.overLimit > 0 ? pc.red(String(r.overLimit)) : pc.green('0')}
+Team spend (est):  ${pc.bold('$' + r.totalEstUsd)}
+Worst blast radius:${' '}${r.worstBlastRadius === 'HIGH' || r.worstBlastRadius === 'CRITICAL' ? pc.red(r.worstBlastRadius) : pc.yellow(r.worstBlastRadius)}   (${r.reachWriteDeploy} write/deploy tools across the team)
+${r.notes.length ? '\n' + r.notes.map(n => `${pc.yellow('•')} ${n}`).join('\n') : ''}`,
+      'Team Rollup (local-first — nothing was exported)'
+    );
+  } else if (action === 'preflight') {
+    // Forward-looking briefing — the reason to run outlier BEFORE you start an agent.
+    // Same engine as status, framed for the session you are about to begin: reach,
+    // skill, spend, and the one thing to do, ending with the handoff to your agent.
+    s.start('Pre-flight check...');
+    const gitStats = await getAuthorshipStats().catch(() => null);
+    const carbon = await getCarbonStats().catch(() => null);
+    const caps = await getCapabilitiesStats().catch(() => null);
+    s.stop('Ready for take-off');
+
+    const aiPct = gitStats ? (gitStats.ratio * 100).toFixed(0) : '—';
+    const youPct = gitStats ? (100 - gitStats.ratio * 100).toFixed(0) : '—';
+    const blast = caps ? caps.blastRadius : 'UNKNOWN';
+    const blastCol = blast === 'CRITICAL' || blast === 'HIGH' ? pc.red : blast === 'MEDIUM' ? pc.yellow : pc.green;
+    const risky = caps ? caps.mcps.filter(m => ['money','exec','deploy','write-remote','write-local'].includes(m.reach)).length : 0;
+    const spend = carbon ? `$${carbon.estUsd.toFixed(0)}` : '—';
+    const cachePct = carbon && carbon.totalTokens ? ((carbon.cacheReadTokens / carbon.totalTokens) * 100).toFixed(0) + '%' : '—';
+
+    const insights = deriveInsights({ authorship: gitStats, carbon, caps, policyCap: 0.70 });
+    const sevCol = (sv: string) => sv === 'critical' ? pc.red : sv === 'warn' ? pc.yellow : sv === 'good' ? pc.green : pc.cyan;
+    const sevMk = (sv: string) => sv === 'critical' ? '✗' : sv === 'warn' ? '⚠' : sv === 'good' ? '✓' : 'i';
+    const actionLines = insights.slice(0, 3)
+      .map(ins => ` ${sevCol(ins.severity)(sevMk(ins.severity))} ${pc.cyan('→')} ${ins.action}`)
+      .join('\n');
+
+    console.log('');
+    console.log(pc.bold(pc.cyan(' ✈  PRE-FLIGHT')) + pc.dim(`  ·  ${process.cwd().split('/').pop()}`));
+    console.log(pc.dim(' ────────────────────────────────────────────────────'));
+    console.log(`  ${pc.bold('Reach')}   ${blastCol(pc.bold(blast))}` + (caps ? pc.dim(` · ${caps.mcps.length} tools, ${risky} can write/deploy`) : ''));
+    console.log(`  ${pc.bold('Skill')}   AI wrote ${pc.bold(aiPct + '%')} · you own ${pc.bold(youPct + '%')}`);
+    console.log(`  ${pc.bold('Spend')}   ${pc.bold(spend)} · ${cachePct} re-sent context`);
+    console.log('');
+    console.log(pc.bold(' Before you delegate:'));
+    console.log(actionLines);
+    console.log('');
+    const agent = detectAgent();
+    console.log(pc.bold(pc.magenta(' ✓ Ready? ')) + 'Start your session:  ' + pc.bold(agent || 'your AI agent'));
+    console.log('');
   } else if (action === 'policy') {
     const tier = await select({
       message: 'Select the governance tier to configure:',
@@ -613,19 +730,34 @@ Enforcement:  ${pc.cyan('Local pre-commit hook installed (backup created)')}`,
         'Active Governance Policy'
       );
     } else if (tier === 'regulatory') {
-      s.start('Generating Regulatory Compliance Audit (Decree 142)...');
-      await new Promise(resolve => setTimeout(resolve, 1200));
-      
+      s.start('Generating human-oversight audit record (Decree 142)...');
+      // A real, honest compliance record from the actual local numbers — not a stub.
+      const gitStats = await getAuthorshipStats().catch(() => null);
+      const caps = await getCapabilitiesStats().catch(() => null);
+      const humanReviewRate = gitStats ? +(1 - gitStats.ratio).toFixed(3) : null;
+      const oversightOk = humanReviewRate !== null && humanReviewRate >= 0.30; // ≥30% human-authored
+      const record = {
+        timestamp: new Date().toISOString(),
+        policy: 'Vietnam Decree 142/2026 — human oversight of high-risk AI',
+        repo: process.cwd().split('/').pop(),
+        humanAuthorshipRate: humanReviewRate,
+        aiAuthorshipRate: gitStats ? +gitStats.ratio.toFixed(3) : null,
+        humanOversight: oversightOk ? 'present' : 'insufficient',
+        agentBlastRadius: caps ? caps.blastRadius : 'unknown',
+        dataExported: false,
+        note: 'Derived from local git history only. No code, prompts, or citizen data leave the machine. Authorship is a proxy for human oversight.',
+      };
       const reportPath = join(process.cwd(), 'outlier-audit-report.jsonl');
-      writeFileSync(reportPath, JSON.stringify({ timestamp: new Date().toISOString(), status: 'PREVIEW', policy: 'Decree 142', simulatedOversight: true }) + '\n');
-      s.stop('Audit Generated');
+      writeFileSync(reportPath, JSON.stringify(record) + '\n');
+      s.stop('Audit record written');
 
       note(
-        `Jurisdiction: ${pc.bold('Vietnam (Decree 142)')}
-Status:       ${pc.green('Compliant - Human oversight logged locally')}
-Privacy:      ${pc.green('Preserved - No citizen data exported')}
+        `Jurisdiction: ${pc.bold('Vietnam (Decree 142/2026)')}
+Human oversight: ${oversightOk ? pc.green('present') : pc.red('insufficient')} ${pc.dim(`(${humanReviewRate !== null ? (humanReviewRate * 100).toFixed(0) + '% human-authored' : 'no git history'})`)}
+Agent reach:  ${caps ? caps.blastRadius : 'unknown'}
+Privacy:      ${pc.green('preserved — nothing exported')}
 Artifact:     ${pc.cyan(reportPath)}`,
-        'Regulatory Compliance'
+        'Human-Oversight Audit Record'
       );
     }
   } else if (action === 'participate') {
@@ -688,6 +820,25 @@ Artifact:     ${pc.cyan(reportPath)}`,
     console.log(`  ${pc.red('Lose:')} Architectural intimacy. You become a reviewer.`);
     console.log(pc.cyan('\n■ Next 5-10 Years (The 1M+ LOC Crisis)'));
     console.log(`  When an agent introduces a fatal state bug in a monolithic architecture, human reviewers will lack the muscle memory to debug it. Outlier measures this exact sovereignty erosion.\n`);
+
+    // Economic translation: the macro shadow of your individual number.
+    const gitStats = await getAuthorshipStats().catch(() => null);
+    const carbon = await getCarbonStats().catch(() => null);
+    if (gitStats || carbon) {
+      const { projectEconomics } = await import('./economics');
+      const teamSize = (() => { const i = process.argv.indexOf('--team'); return i > -1 ? (parseInt(process.argv[i + 1] || '1') || 1) : 1; })();
+      const econ = projectEconomics({
+        aiRatio: gitStats ? gitStats.ratio : 0,
+        estUsdSession: carbon ? carbon.estUsd : 0,
+        teamSize,
+      });
+      console.log(pc.bold(pc.bgMagenta(' THE MACRO SHADOW ')) + pc.dim(`  (team of ${teamSize} — set with --team N)`));
+      for (const p of econ.projections) {
+        console.log(`  ${pc.bold(p.label.padEnd(20))} ${pc.cyan(p.value)}`);
+        console.log(`  ${pc.dim('  ' + p.note)}`);
+      }
+      console.log('\n' + pc.dim(' ' + econ.assumptions) + '\n');
+    }
   } else if (action === 'knowledge') {
     console.log('\n' + pc.bold(pc.bgBlue(' CORE LITERATURE & REFERENCES ')) + '\n');
     console.log(`1. ${pc.cyan('METR (Measuring AI Ability)')} - Evaluating AI on long-horizon software tasks.`);
@@ -699,14 +850,15 @@ Artifact:     ${pc.cyan(reportPath)}`,
   outro('Done — nothing left your machine. (How it works: outlier --help)');
 
   if (typeof finalReceipt !== 'undefined' && finalReceipt) {
-    console.log(finalReceipt);
+    const boxed = closeBox(finalReceipt);
+    console.log(boxed);
 
     // --save: write a plain-text (no color) copy of the receipt next to the repo.
     if (process.argv.includes('--save')) {
       const stripAnsi = (s: string) => s.replace(/\x1b\[[0-9;]*m/g, '');
       const savePath = join(process.cwd(), 'outlier-audit.txt');
       try {
-        writeFileSync(savePath, stripAnsi(finalReceipt).trimStart() + '\n');
+        writeFileSync(savePath, stripAnsi(boxed).trimStart() + '\n');
         console.log(pc.dim(`\n 💾 Saved to ${savePath}`));
       } catch {}
     }

package/src/economics.ts

@@ -0,0 +1,66 @@
+// Economic translation layer.
+//
+// The paper's core claim is that an individual authorship/spend number has a macro
+// shadow: at team and national scale it becomes skill-ladder erosion, offshore value
+// capture, and a hard-currency (forex) drain. This module turns the local numbers into
+// that projection — explicitly as a *projection with stated assumptions*, not a measurement.
+
+export interface EconProjection {
+  label: string;
+  value: string;
+  note: string;
+}
+
+export interface EconInput {
+  aiRatio: number;        // 0..1, share of authored output that is AI
+  estUsdSession: number;  // measured/estimated spend reflected by local logs
+  teamSize?: number;      // default 1 (solo); orgs override
+  workdaysPerYear?: number;
+}
+
+// Assumptions are surfaced in the output so nothing is hidden.
+const DEFAULTS = { teamSize: 1, workdaysPerYear: 230 };
+
+export function projectEconomics(input: EconInput): { projections: EconProjection[]; assumptions: string } {
+  const team = input.teamSize ?? DEFAULTS.teamSize;
+  const days = input.workdaysPerYear ?? DEFAULTS.workdaysPerYear;
+  const ai = Math.max(0, Math.min(1, input.aiRatio));
+
+  // Treat the local spend as a per-active-period hard-currency outflow to the AI vendor.
+  // Annualize crudely (the local logs are a sample window, not a day) and scale by team.
+  const annualOutflowPerDev = input.estUsdSession * (days / 30); // sample window ≈ a month of work
+  const annualOutflowTeam = annualOutflowPerDev * team;
+
+  const projections: EconProjection[] = [
+    {
+      label: 'Authorship shift',
+      value: `${(ai * 100).toFixed(0)}% of output → AI`,
+      note: team > 1
+        ? `≈ ${(ai * team).toFixed(1)} of ${team} dev-equivalents of authorship now machine-produced.`
+        : 'At team scale, this many dev-equivalents move to the machine.',
+    },
+    {
+      label: 'Value capture (offshore)',
+      value: `~$${Math.round(annualOutflowTeam).toLocaleString()}/yr`,
+      note: 'Hard-currency spend leaving to a foreign AI vendor — value captured offshore, not by the local worker.',
+    },
+    {
+      label: 'Skill ladder',
+      value: ai > 0.7 ? 'AT RISK' : ai > 0.4 ? 'watch' : 'intact',
+      note: ai > 0.7
+        ? 'Above ~70%, juniors stop building the skill that makes seniors — premature deprofessionalization.'
+        : 'Humans still author enough core work to keep building expertise.',
+    },
+    {
+      label: 'Forex / tax base',
+      value: `$${Math.round(annualOutflowPerDev).toLocaleString()}/dev/yr imported`,
+      note: 'Locally-taxed wages give way to foreign-billed inference: income-tax erosion + a recurring forex import.',
+    },
+  ];
+
+  const assumptions =
+    `Projection only. Assumes: team of ${team}, the local log window ≈ one month of work, ` +
+    `${days} workdays/yr. Spend is your measured/estimated local outflow scaled up — an order-of-magnitude shadow, not an audit.`;
+
+  return { projections, assumptions };
+}

package/src/emissions.ts

@@ -10,9 +10,13 @@
 // literature). We expose the method so the UI can label provenance honestly. We never
 // claim precision we don't have.
 
-// Energy per 1M OUTPUT tokens, by model class (kWh). Anchor: the paper measured ~10 kWh
-// across 15.1M output tokens on Opus-class (~0.66). Smaller/faster models use materially
-// less. These are order-of-magnitude class estimates, not vendor figures.
+// Energy per 1M OUTPUT tokens, by model class (kWh).
+// Grounded in: the paper's measured ~10 kWh / 15.1M output on Opus-class (~0.66);
+// EcoLogits (genai-impact) per-call energy methodology; and the Hugging Face AI Energy
+// Score (which ranks small/mid/large model inference energy). Larger models = more
+// active parameters per token = more energy. These remain order-of-magnitude class
+// estimates (the literature spread is ~4-20x), labelled "estimate" in the UI — not vendor
+// figures. CodeCarbon, when present, overrides these with measured hardware energy.
 const MODEL_ENERGY_KWH_PER_M_OUTPUT: Record<string, number> = {
   'opus':    0.66,  // large frontier (Claude Opus, GPT-4 class)
   'sonnet':  0.30,  // mid (Claude Sonnet, GPT-4o)

package/src/insights.ts

@@ -0,0 +1,109 @@
+// Insight rules engine — turns the raw metrics into meaning + one action.
+//
+// The numbers (75% AI, $63, blast radius HIGH) are data. Insights are what they MEAN
+// together: high AI authorship is only alarming if your agents can also deploy; a low
+// AI% next to heavy token use usually means missing trailers, not human authorship.
+// Each rule combines signals and returns a plain message + a concrete next step.
+
+import type { AuthorshipStats } from './git';
+import type { CarbonStats } from './carbon';
+import type { CapabilitiesStats } from './capabilities';
+
+export type Severity = 'critical' | 'warn' | 'info' | 'good';
+
+export interface Insight {
+  severity: Severity;
+  title: string;   // short headline
+  detail: string;  // one plain sentence of why
+  action: string;  // the one thing to do
+}
+
+const RANK: Record<Severity, number> = { critical: 0, warn: 1, info: 2, good: 3 };
+
+export interface InsightInput {
+  authorship: AuthorshipStats | null;
+  carbon: CarbonStats | null;
+  caps: CapabilitiesStats | null;
+  policyCap?: number; // 0..1, default 0.70
+}
+
+export function deriveInsights({ authorship, carbon, caps, policyCap = 0.70 }: InsightInput): Insight[] {
+  const out: Insight[] = [];
+  const ai = authorship ? authorship.ratio : null;
+  const cachePct = carbon && carbon.totalTokens ? (carbon.cacheReadTokens / carbon.totalTokens) * 100 : null;
+  const blast = caps ? caps.blastRadius : null;
+  const writeOrDeploy = caps ? caps.mcps.filter(m => ['money', 'exec', 'deploy', 'write-remote', 'write-local'].includes(m.reach)).length : 0;
+  const heavyTokens = carbon ? carbon.totalTokens > 1_000_000 : false;
+
+  // 1. The compound one: high reliance AND high reach = you may not own code that can ship.
+  if (ai !== null && ai > 0.7 && (blast === 'HIGH' || blast === 'CRITICAL')) {
+    out.push({
+      severity: 'critical',
+      title: 'High reliance + high reach',
+      detail: `AI wrote ${(ai * 100).toFixed(0)}% here and your agents can ${writeOrDeploy ? 'write/deploy' : 'reach external services'}. You may not own code that can ship to prod.`,
+      action: 'Review the core paths yourself before delegating more this session.',
+    });
+  } else if (ai !== null && ai > 0.7) {
+    // 2. High reliance alone.
+    out.push({
+      severity: 'warn',
+      title: 'You are mostly reviewing, not writing',
+      detail: `AI wrote ${(ai * 100).toFixed(0)}% of recent commits — you risk losing the skill to debug it unaided.`,
+      action: 'Read the AI-written code through, or hand-write the next core change.',
+    });
+  }
+
+  // 3. Honesty rule: low AI% next to heavy token use = missing trailers, not human authorship.
+  if (ai !== null && ai < 0.1 && heavyTokens) {
+    out.push({
+      severity: 'info',
+      title: 'Low AI% may be misleading',
+      detail: 'Heavy token use but few AI-tagged commits — your agent probably is not writing Co-Authored-By trailers.',
+      action: 'Treat the authorship number as a floor, not the truth, until trailers are on.',
+    });
+  }
+
+  // 4. Reach / blast radius, independent of authorship.
+  if (caps && (blast === 'CRITICAL' || blast === 'HIGH')) {
+    out.push({
+      severity: blast === 'CRITICAL' ? 'critical' : 'warn',
+      title: `Blast radius ${blast}`,
+      detail: `If an agent (or a prompt injection) drives your tools, it ${caps.blastReasons.slice(0, 2).join(' and ') || 'has broad reach'}.`,
+      action: 'Disable the write/deploy MCP tools you do not need this session.',
+    });
+  }
+
+  // 5. Cache waste = where the money goes.
+  if (cachePct !== null && cachePct > 80) {
+    out.push({
+      severity: 'warn',
+      title: 'Most of your spend is re-sent context',
+      detail: `${cachePct.toFixed(0)}% of your tokens just re-read old context — that is most of the bill, not new work.`,
+      action: 'Start fresh sessions for new tasks; keep context tight.',
+    });
+  }
+
+  // 6. Over the policy limit.
+  if (ai !== null && ai > policyCap) {
+    out.push({
+      severity: 'warn',
+      title: 'Over your AI-authorship limit',
+      detail: `AI authorship is ${(ai * 100).toFixed(0)}%, over your ${(policyCap * 100).toFixed(0)}% limit.`,
+      action: 'Either raise the cap deliberately, or write the next change yourself.',
+    });
+  }
+
+  // 7. Nothing wrong — say so (don't manufacture alarm).
+  if (out.length === 0) {
+    out.push({
+      severity: 'good',
+      title: 'Low risk',
+      detail: ai !== null
+        ? `You wrote most of this (${(100 - ai * 100).toFixed(0)}%) and your agents have limited reach.`
+        : 'No AI logs or git history found to flag.',
+      action: 'Carry on — re-run before your next big delegation.',
+    });
+  }
+
+  return out.sort((a, b) => RANK[a.severity] - RANK[b.severity]);
+}