@timekast/factory 2.3.1 → 2.5.0

package/dist/commands/usage.js

@@ -0,0 +1,303 @@
+/**
+ * `factory usage` — measure REAL Claude Code consumption from the transcripts
+ * in the developer's home (`~/.claude/projects/`), any repo, any machine.
+ *
+ * 🔴 Unlike `update` / `status` / `doctor`, this command has NO repo preflight
+ * and must never grow one: the data source is the developer's HOME, not the
+ * cwd. It runs from any folder — inside a derivative, inside an unrelated
+ * repo, or in no repo at all — and reports every project dir it finds.
+ *
+ * v1 is LOCAL-ONLY: the command reads, prints and exports JSON. Nothing leaves
+ * the machine. (A v2 fleet aggregation — where the team's numbers land, with
+ * what credential, per-developer opt-in — is a separate decision; see the
+ * Encargo C brief. Do not wire network calls into this command.)
+ *
+ * Privacy invariant (design-level, not preference): only AGGREGATES are ever
+ * printed — dates, counts, tokens, model/agent names, repo slugs. Never message
+ * content, never client project file paths, never code fragments. The repo slug
+ * itself identifies the client, so `--anon` exists for shareable reports — the
+ * developer's explicit call, never the default.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { CLIError } from '../lib/cli-error.js';
+import { aggregateUsage, scanUsage, } from '../lib/usage-scan.js';
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const MONTH_RE = /^\d{4}-(0[1-9]|1[0-2])$/;
+/** es-MX month names, index = month number - 1. */
+const MONTH_NAMES = [
+    'enero',
+    'febrero',
+    'marzo',
+    'abril',
+    'mayo',
+    'junio',
+    'julio',
+    'agosto',
+    'septiembre',
+    'octubre',
+    'noviembre',
+    'diciembre',
+];
+const eq = (name) => (a) => {
+    const p = `--${name}=`;
+    return a.startsWith(p) ? a.slice(p.length) : null;
+};
+/** Parse `factory usage` flags. Unknown flags fail loudly (no silent typos). */
+export function parseUsageFlags(argv) {
+    const flags = {
+        since: null,
+        until: null,
+        month: null,
+        repo: null,
+        agent: null,
+        json: false,
+        anon: false,
+    };
+    for (const arg of argv) {
+        if (arg === '--json')
+            flags.json = true;
+        else if (arg === '--anon')
+            flags.anon = true;
+        else if (eq('since')(arg) !== null)
+            flags.since = eq('since')(arg);
+        else if (eq('until')(arg) !== null)
+            flags.until = eq('until')(arg);
+        else if (eq('month')(arg) !== null)
+            flags.month = eq('month')(arg);
+        else if (eq('mes')(arg) !== null)
+            flags.month = eq('mes')(arg);
+        else if (eq('repo')(arg) !== null)
+            flags.repo = eq('repo')(arg);
+        else if (eq('agent')(arg) !== null)
+            flags.agent = eq('agent')(arg);
+        else {
+            throw new CLIError(`Flag desconocida para \`factory usage\`: \`${arg}\`.\n` +
+                'Uso: factory usage [--month=<mes|YYYY-MM> (alias --mes=)] [--since=YYYY-MM-DD] [--until=YYYY-MM-DD] ' +
+                '[--repo=<subcadena>] [--agent=<tipo>] [--anon] [--json]');
+        }
+    }
+    if (flags.month && (flags.since || flags.until)) {
+        throw new CLIError('`--month` y `--since`/`--until` son excluyentes: usa uno u otro.');
+    }
+    return flags;
+}
+/** Local date → `YYYY-MM-DD`. */
+const isoDay = (d) => `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+/** Last day of a (year, monthIndex0) month. */
+const monthEnd = (year, monthIdx) => isoDay(new Date(year, monthIdx + 1, 0));
+/**
+ * Resolve the report window. Precedence: `--month` (name or `YYYY-MM`) >
+ * `--since`/`--until` > default (the CURRENT calendar month, to date — the
+ * reference view of the brief). A month NAME resolves to its most recent
+ * occurrence: "julio" asked in agosto 2026 → 2026-07; asked in junio 2026 →
+ * 2025-07. `now` is injectable for tests.
+ */
+export function resolveWindow(flags, now = new Date()) {
+    if (flags.month) {
+        const raw = flags.month.toLowerCase();
+        if (MONTH_RE.test(raw)) {
+            const [y, m] = raw.split('-').map(Number);
+            return { since: `${raw}-01`, until: monthEnd(y, m - 1) };
+        }
+        const idx = MONTH_NAMES.indexOf(raw);
+        if (idx === -1) {
+            throw new CLIError(`Mes no reconocido: \`${flags.month}\`. Acepta ${MONTH_NAMES.join(', ')} o \`YYYY-MM\`.`);
+        }
+        const year = idx > now.getMonth() ? now.getFullYear() - 1 : now.getFullYear();
+        const mm = String(idx + 1).padStart(2, '0');
+        return { since: `${year}-${mm}-01`, until: monthEnd(year, idx) };
+    }
+    for (const [name, v] of [
+        ['--since', flags.since],
+        ['--until', flags.until],
+    ]) {
+        if (v && !DATE_RE.test(v)) {
+            throw new CLIError(`Fecha inválida en \`${name}\`: \`${v}\` (formato: YYYY-MM-DD).`);
+        }
+    }
+    const today = isoDay(now);
+    const firstOfMonth = `${today.slice(0, 7)}-01`;
+    const since = flags.since ?? (flags.until ? '1970-01-01' : firstOfMonth);
+    const until = flags.until ?? today;
+    if (since > until) {
+        throw new CLIError(`Ventana vacía: \`--since=${since}\` es posterior a \`--until=${until}\`.`);
+    }
+    return { since, until };
+}
+/** Default projects root: the developer's home, never the cwd. */
+export const defaultUsageRoot = () => join(homedir(), '.claude', 'projects');
+const M = (t) => (t / 1e6).toFixed(1);
+const pct = (part, total) => total ? `${((100 * part) / total).toFixed(1)}%` : '—';
+/** Proportional stacked bar: █ = main, ▓ = subagentes; width ∝ day total / max. */
+const dayBar = (main, sub, max, width = 24) => {
+    if (!max)
+        return '';
+    const total = main + sub;
+    const len = Math.max(total > 0 ? 1 : 0, Math.round((total / max) * width));
+    const mainLen = Math.round((main / Math.max(total, 1)) * len);
+    return '█'.repeat(mainLen) + '▓'.repeat(len - mainLen);
+};
+/** Render the human report (es-MX). Kept pure for tests: returns the text. */
+export function renderUsageReport(report) {
+    const L = [];
+    const t = report.totals;
+    const filterNote = [
+        report.filters.repo ? `repo~"${report.filters.repo}"` : null,
+        report.filters.agent ? `agent=${report.filters.agent}` : null,
+        report.filters.anon ? 'anon' : null,
+    ]
+        .filter(Boolean)
+        .join(' · ');
+    L.push('');
+    L.push(`📊 factory usage — ${report.window.since} → ${report.window.until}` +
+        (filterNote ? `  [${filterNote}]` : ''));
+    L.push(`   ${M(t.total)} M tokens · ${t.mainRequests.toLocaleString('en-US')} requests con usage real · ` +
+        `${t.invocations.toLocaleString('en-US')} invocaciones de subagente (${t.agentTypes} tipos) · ${t.reposScanned} repos barridos`);
+    if (t.total === 0) {
+        L.push('');
+        L.push('   (sin datos en la ventana — ¿existe ~/.claude/projects/ en esta máquina?)');
+        L.push('');
+        return L.join('\n');
+    }
+    const maxDay = Math.max(...report.byDay.map((d) => d.main + d.sub), 0);
+    L.push('');
+    L.push('DÍA × SUPERFICIE (M tokens · █ main loop · ▓ subagentes · barra ∝ día más caro)');
+    L.push('  ' + 'día'.padEnd(12) + 'main'.padStart(8) + 'subs'.padStart(8) + 'total'.padStart(8));
+    for (const d of report.byDay) {
+        L.push('  ' +
+            d.date.padEnd(12) +
+            M(d.main).padStart(8) +
+            M(d.sub).padStart(8) +
+            M(d.main + d.sub).padStart(8) +
+            '  ' +
+            dayBar(d.main, d.sub, maxDay));
+    }
+    L.push('');
+    L.push('POR MODELO');
+    for (const m of report.byModel) {
+        L.push('  ' +
+            m.model.padEnd(16) +
+            `${M(m.tokens)} M`.padStart(11) +
+            pct(m.tokens, t.total).padStart(8));
+    }
+    L.push('');
+    L.push('POR REPO' + (report.filters.anon ? ' (anonimizado)' : ''));
+    const shownRepos = report.byRepo.slice(0, 20);
+    for (const r of shownRepos) {
+        L.push('  ' +
+            r.repo.slice(0, 34).padEnd(35) +
+            `${M(r.tokens)} M`.padStart(11) +
+            pct(r.tokens, t.total).padStart(8));
+    }
+    if (report.byRepo.length > shownRepos.length) {
+        const rest = report.byRepo.slice(20);
+        const restTok = rest.reduce((a, r) => a + r.tokens, 0);
+        L.push(`  … y ${rest.length} repos más`.padEnd(37) +
+            `${M(restTok)} M`.padStart(11) +
+            pct(restTok, t.total).padStart(8) +
+            '  (completos en --json)');
+    }
+    L.push('');
+    L.push('POR AGENTE (top 12 de ' + String(t.agentTypes) + ')');
+    L.push('  ' +
+        'agente'.padEnd(26) +
+        'n'.padStart(5) +
+        'M tokens'.padStart(10) +
+        '% subs'.padStart(8) +
+        '% total'.padStart(9));
+    for (const a of report.byAgent.slice(0, 12)) {
+        L.push('  ' +
+            a.agent.slice(0, 25).padEnd(26) +
+            String(a.invocations).padStart(5) +
+            M(a.tokens).padStart(10) +
+            pct(a.tokens, t.sub).padStart(8) +
+            pct(a.tokens, t.total).padStart(9));
+    }
+    if (report.delivered.length) {
+        L.push('');
+        L.push('TOKENS POR UNIDAD ENTREGADA (agentes que escriben código; excluye colgadas)');
+        L.push('  ' +
+            'agente'.padEnd(24) +
+            'modelo'.padEnd(12) +
+            'n'.padStart(4) +
+            'M tokens'.padStart(10) +
+            'líneas'.padStart(9) +
+            'M tok/1k ln'.padStart(13));
+        for (const w of report.delivered) {
+            const perK = w.lines ? ((w.tokens / w.lines) * 1000) / 1e6 : null;
+            L.push('  ' +
+                w.agent.slice(0, 23).padEnd(24) +
+                w.model.padEnd(12) +
+                String(w.invocations).padStart(4) +
+                M(w.tokens).padStart(10) +
+                String(w.lines).padStart(9) +
+                (perK === null ? '—' : perK.toFixed(2)).padStart(13));
+        }
+        if (t.unenriched) {
+            L.push(`  ℹ️  ${t.unenriched} invocaciones sin \`toolUseResult\` del padre: cuentan en el consumo,` +
+                ' pero sin líneas — no entran a esta tabla.');
+        }
+    }
+    if (report.reviewCost.length) {
+        L.push('');
+        L.push('REVISORES — costo por veredicto (no producen líneas; se miden por invocación)');
+        L.push('  ' +
+            'agente'.padEnd(24) +
+            'modelo'.padEnd(12) +
+            'n'.padStart(4) +
+            'M tok/inv'.padStart(11) +
+            'min/inv'.padStart(9) +
+            'ctx medio'.padStart(11));
+        for (const r of report.reviewCost) {
+            L.push('  ' +
+                r.agent.slice(0, 23).padEnd(24) +
+                r.model.padEnd(12) +
+                String(r.invocations).padStart(4) +
+                (r.tokens / r.invocations / 1e6).toFixed(1).padStart(11) +
+                (r.minutes / r.invocations).toFixed(1).padStart(9) +
+                `${Math.round(r.avgCtx / 1000)}k`.padStart(11));
+        }
+        L.push('  ⚠️  compara ctx medio antes de leer diferencias: revisar epics más chicos gasta menos por razones ajenas al modelo.');
+    }
+    if (report.reviewRounds.length) {
+        L.push('');
+        L.push('RONDAS DE REVISIÓN (re-spawns del mismo revisor en la misma sesión)');
+        for (const r of report.reviewRounds.slice(0, 8)) {
+            L.push('  ' +
+                r.agent.slice(0, 23).padEnd(24) +
+                `${String(r.sessions).padStart(3)} sesiones · ${String(r.spawns).padStart(3)} spawns · ` +
+                `${(r.spawns / r.sessions).toFixed(2)} rondas/sesión`);
+        }
+        L.push('  ⚠️  un re-spawn puede ser una fase distinta del workflow, no una re-ronda del mismo veredicto — revisa los prompts antes de leerlo como indecisión.');
+    }
+    L.push('');
+    L.push('REPARTO DEL CONSUMO');
+    L.push(`  main loop:   ${M(t.main).padStart(10)} M tokens  ${pct(t.main, t.total)}`);
+    L.push(`  subagentes:  ${M(t.sub).padStart(10)} M tokens  ${pct(t.sub, t.total)}`);
+    L.push('  ✔ validación cruzada: el % de subagentes debe cuadrar con "Subagents % of usage" del panel Account & Usage de tu cliente. Si no cuadra, el número de ESTA herramienta está mal.');
+    L.push(`\n  Tokens exactos del \`usage\` de cada transcript — sin estimadores. Solo agregados: nunca contenido de mensajes ni paths de proyectos.` +
+        (report.filters.anon
+            ? ''
+            : ' Para compartir el reporte fuera del equipo: `--anon` anonimiza los repos.'));
+    L.push('');
+    return L.join('\n');
+}
+/** Entry point for `factory usage`. */
+export function runUsage(flags, root = defaultUsageRoot()) {
+    const window = resolveWindow(flags);
+    const scan = scanUsage(root, window);
+    const report = aggregateUsage(scan, window, {
+        repo: flags.repo,
+        agent: flags.agent,
+        anon: flags.anon,
+    });
+    if (flags.json) {
+        // `--json` contract (same as `doctor --launcher --json` / `status --json`):
+        // machine-readable JSON to stdout, NOTHING else, exit 0. Stable field order
+        // + deterministic array sorting → diffable between runs.
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        return;
+    }
+    console.log(renderUsageReport(report));
+}

package/dist/commands/vault.js

@@ -3,9 +3,11 @@
  * Contract: `fx-secrets-vault §8`. The decisions live in `lib/vault-adopt.ts`; this module runs
  * them against the real services, in the order the contract fixes:
  *
- *   Preconditions (both modes) — `core` profile → says so and does nothing; the brain up to date
- *   (the comparison of `factory status`); no fork in the files the wrapper runs (the census of
- *   `factory update --verify`).
+ *   Preconditions (both modes) — the wrapper on disk (`full` and `core` both ship it; missing →
+ *   `factory update`); the brain up to date (the comparison of `factory status`); no fork in the
+ *   files the wrapper runs (the census of `factory update --verify`). A `core` repo is accepted:
+ *   its own `dev`/`build` scripts read as customized and run without the vault until the team
+ *   prefixes them with the wrapper (Factory#76).
  *
  *   Plan (no `--apply`) — inventory by NAME and display hash of `.env.local`, Vercel production +
  *   preview and Railway; the state of each key, where the apply would write it, the confirmations
@@ -39,11 +41,10 @@ import { WITH_VAULT_SCRIPT_FILE } from '../lib/constants.js';
 import { parseEnvBody } from '../lib/env-wizard.js';
 import { hasLockfile, readLockfile } from '../lib/lockfile.js';
 import { getConnectionUri, getNeonProjectOrg, isNeonKeyFamily, listNeonApiKeys, listNeonBranches, NEON_DEVELOP_BRANCH, NeonApiKeyListError, } from '../lib/neon-api.js';
-import { detectCoreProfile } from '../lib/provision-preflight.js';
 import { readDestroyTarget, readNeonRevokePending, readVaultDeclined, readVaultLink, addNeonRevokePending, } from '../lib/provision-state.js';
 import { createRailResolver, RAIL_TIMEKAST } from '../lib/rail.js';
 import { createRailwayClient, RAILWAY_TOKEN_KEY, railwayFetchTransport, } from '../lib/railway-api.js';
-import { buildPlanEntries, classifySensitive, createDisplayHasher, describeWrite, ENV_LOCAL_BACKUP_FILE, ENV_LOCAL_FILE, FACTORY_REPO, FACTORY_SLUG, folderOfTarget, isConnectedEmptyDeploy, isFactoryIdentity, manualVaultProjectSteps, isFactoryMode, isProjectScopedNeonKey, isRailKey, isRailwayProvided, isRailwaySyncTo, listRailwayProjects, MFA_KEY, NEON_API_KEY, planAdoptionLayout, planRailwayImport, proposeRailwaySyncs, RAILWAY_VAULT_ENVS, railwaySyncDifferences, railwaySyncLabel, railwaySyncName, readRailwayInventory, readRailwayVariables, recordedAdoptionVercelId, RESEND_KEY, retiredKeys, retireEnvLocal, sealedStopExplanation, sharedCandidatesOf, SHORTIO_KEY, wrapperDrift, writeAdoptionLink, writeDeclineMark, } from '../lib/vault-adopt.js';
+import { buildPlanEntries, classifySensitive, adoptSender, createDisplayHasher, dangerousSharedTargets, describeWrite, ENV_LOCAL_BACKUP_FILE, ENV_LOCAL_FILE, FACTORY_REPO, FACTORY_SLUG, folderOfTarget, isConnectedEmptyDeploy, isFactoryIdentity, manualVaultProjectSteps, isFactoryMode, isProjectScopedNeonKey, isRailKey, isRailwayProvided, isRailwaySyncTo, listRailwayProjects, MFA_KEY, NEON_API_KEY, planAdoptionLayout, planRailwayImport, proposeRailwaySyncs, RAILWAY_VAULT_ENVS, railwaySyncDifferences, railwaySyncLabel, railwaySyncName, readRailwayInventory, readRailwayVariables, recordedAdoptionVercelId, RESEND_KEY, retiredKeys, retireEnvLocal, sealedStopExplanation, SENDER_KEYS, sharedCandidatesOf, sharedDatabaseKeys, SHORTIO_KEY, vaultWriteConflicts, wrapperDrift, writeAdoptionLink, writeDeclineMark, } from '../lib/vault-adopt.js';
 import { createVaultClient, formatLocation, VAULT_CI_PATH, VAULT_ENV_DEVELOP, VAULT_ENV_LOCAL, VAULT_ENV_MAIN, VAULT_ROOT_PATH, VAULT_TEST_ISOLATION_KEY, VaultSeamMissingError, } from '../lib/vault-api.js';
 import { LOCAL_ONLY_KEYS } from '../lib/env-file.js';
 import { buildEnvPlan, deployHostCandidates, generateAuthSecret, listEnvVarNames, listProjectDomains, locateVercelProject, readEnvVarsWithValues, relatedOriginsFor, } from '../lib/vercel-env.js';
@@ -321,6 +322,12 @@ const UNKNOWN = 'unknown';
  * reports (`resolveSuccessExitCode`), distinct from 0 so no one — person or agent — reads it as done.
  */
 export const VAULT_ADOPT_SEALED_EXIT_CODE = 3;
+/** Factory#73 — why a shared Vercel record blocks (plan and apply say it the same way). */
+const SHARED_RECORDS_REASON = 'Variables de Vercel que son UN solo registro para production y preview, y develop tendría su ' +
+    'propio valor: el sync de preview reescribiría el registro y producción terminaría con el de develop';
+/** Factory#75 — why a shared database key needs a yes. */
+const SHARED_DATABASES_REASON = 'Preview tiene la MISMA base que producción: los previews y el entorno local escribirían en la ' +
+    'base de producción';
 function realField(value) {
     return value && value !== UNKNOWN ? value : null;
 }
@@ -331,6 +338,7 @@ function vercelMaps(vars) {
     const branchScoped = [];
     const sensitive = [];
     const unreadableOther = new Set();
+    const sharedTargets = new Set();
     const note = (key, type, value, target) => {
         if (value !== null)
             return;
@@ -340,6 +348,9 @@ function vercelMaps(vars) {
             unreadableOther.add(key);
     };
     for (const env of vars) {
+        if (env.target.includes('production') && env.target.includes('preview') && !env.gitBranch) {
+            sharedTargets.add(env.key);
+        }
         if (env.target.includes('production')) {
             production.set(env.key, env.value);
             note(env.key, env.type, env.value, 'production');
@@ -359,6 +370,7 @@ function vercelMaps(vars) {
         branchScoped,
         sensitive,
         unreadableOther: [...unreadableOther].sort(),
+        sharedTargets: [...sharedTargets].sort(),
     };
 }
 /** Why a derivation needs a host, and which one. */
@@ -1011,10 +1023,14 @@ async function prepareAdoption(rootDir, flags, deps) {
     const resendTeamKey = hasResend ? await rail.getOptional(RESEND_KEY) : null;
     const replaceResend = resendTeamKey !== null &&
         [values.production, values.preview, values.local].some((m) => m.get(RESEND_KEY) === resendTeamKey);
-    const sender = values.production.get('EMAIL_FROM') ??
-        values.preview.get('EMAIL_FROM') ??
-        values.local.get('EMAIL_FROM') ??
-        PROVISION_EMAIL_FROM;
+    // Factory#74 — the repo's own sender, under any name it uses; the kit's default only when none.
+    const found = adoptSender(values);
+    if (found.sender === null && replaceResend && found.unknown.length > 0) {
+        throw new CLIError(`No encuentro el remitente del repo en ${SENDER_KEYS.join(', ')}, pero ${found.unknown.join(', ')} ` +
+            'tiene una dirección de correo. No acuño la key de Resend para el dominio del kit a ciegas: ' +
+            'agrega `EMAIL_FROM` con el remitente real al deploy y repite. No se escribió nada.');
+    }
+    const sender = found.sender ?? PROVISION_EMAIL_FROM;
     const resendDomain = sendingDomainOf(sender);
     const client = deps.vaultClient ?? createVaultClient();
     const githubSecretNames = repo
@@ -1207,6 +1223,8 @@ async function prepareAdoption(rootDir, flags, deps) {
         sealed: [],
         sealedExplanation: null,
         branchScoped: vercel.branchScoped,
+        sharedRecords: dangerousSharedTargets(vercel.sharedTargets, writes),
+        sharedDatabases: sharedDatabaseKeys(writes, neonProjectId !== null),
         confirmations: confirmations.map((c) => c.name),
         github,
         wrapper: {
@@ -1235,6 +1253,7 @@ async function prepareAdoption(rootDir, flags, deps) {
         hosts,
         hostCandidates,
         vaultProjectExists,
+        sharedTargets: vercel.sharedTargets,
         vercelToken,
         teamId,
         resendTeamKey: replaceResend ? resendTeamKey : null,
@@ -1354,6 +1373,14 @@ function printPlan(plan, apply) {
             `${plan.branchScoped.map((v) => `${v.name} (rama ${v.branch})`).join(', ')}. ` +
             'Decide en Vercel (quítales la rama o bórralas) y repite. Bloquean el --apply.');
     }
+    if (plan.sharedRecords.length > 0) {
+        out(`\n🔴 ${SHARED_RECORDS_REASON}: ${plan.sharedRecords.join(', ')}. ` +
+            'Sepáralas en Vercel (un registro por entorno) y repite. Bloquean el --apply.');
+    }
+    if (plan.sharedDatabases.length > 0) {
+        out(`\n⚠ ${SHARED_DATABASES_REASON}: ${plan.sharedDatabases.join(', ')}. ` +
+            'El --apply te pide confirmarlo; si no es lo que quieres, dale a preview su propia base en el deploy y repite.');
+    }
     if (plan.railwaySyncs.length > 0) {
         out(`\nRailway${plan.railway ? ` (proyecto \`${plan.railway.project}\`, id ${plan.railway.projectId})` : ''} — ` +
             'syncs propuestos (confirmas cada uno; el que no confirmes no se importa ni se crea): ' +
@@ -1483,6 +1510,32 @@ async function writeLayout(prepared, projectId, deps) {
     }
     return resend;
 }
+/**
+ * Factory#72 — the writes are `create-if-missing`: a key the vault already holds keeps its value,
+ * and the first sync carries THAT value to the deploy. A vault value that differs from what the
+ * deploy runs (a stale copy, a Vercel ciphertext imported by hand) stops the apply BEFORE writing.
+ */
+async function assertVaultMatchesPlan(prepared, projectId) {
+    const locations = new Map();
+    for (const write of prepared.writes) {
+        if (write.location.env !== VAULT_ENV_LOCAL) {
+            locations.set(formatLocation(write.location), write.location);
+        }
+    }
+    const existing = new Map();
+    for (const [where, location] of locations) {
+        existing.set(where, await prepared.client.readSecrets(projectId, location, { expandReferences: true }));
+    }
+    const conflicts = vaultWriteConflicts(prepared.writes, existing, createDisplayHasher());
+    if (conflicts.length === 0)
+        return;
+    throw new CLIError('La bóveda ya tiene OTRO valor en claves que el deploy usa, y el primer sync lo llevaría al deploy: ' +
+        conflicts
+            .map((c) => `${c.location} ${c.key} (bóveda ${c.vault} ≠ deploy ${c.plan})`)
+            .join(', ') +
+        '. Lo que corre hoy es el deploy: corrige o borra esas claves en la bóveda y repite. ' +
+        'No escribí ningún secreto ni creé ningún sync.');
+}
 /**
  * Right before creating the syncs: the vault folder must hold every key its Vercel target holds
  * (import first — the first sync deletes nothing), except the retirements already confirmed; and
@@ -1753,6 +1806,23 @@ async function applyAdoption(prepared, deps) {
             `${plan.railwayConflicts.join(', ')}. Una carpeta tiene un solo valor por clave y no elijo uno a ` +
             'ciegas: iguálalos en Railway, o no confirmes uno de esos syncs. No se escribió nada.');
     }
+    // Factory#73 — recomputed on the final writes: a materialized value can give develop its own.
+    const sharedRecords = dangerousSharedTargets(prepared.sharedTargets, prepared.writes);
+    if (sharedRecords.length > 0) {
+        throw new CLIError(`${SHARED_RECORDS_REASON}: ${sharedRecords.join(', ')}. Sepáralas en Vercel (un registro por ` +
+            'entorno) y repite. No se escribió nada.');
+    }
+    // Factory#75 — any provider, not only Neon: a yes before previews write to production's base.
+    const sharedDatabases = sharedDatabaseKeys(prepared.writes, prepared.neonProjectId !== null);
+    if (sharedDatabases.length > 0) {
+        prepared.questions = [
+            ...prepared.questions,
+            {
+                name: `misma base: ${sharedDatabases.join(', ')}`,
+                question: `${SHARED_DATABASES_REASON} (${sharedDatabases.join(', ')}). ¿Confirmas?`,
+            },
+        ];
+    }
     await confirmAll(prepared, deps);
     // Resolved BEFORE writing anything: without it no Railway sync can exist, so nothing is imported.
     const railwayConnection = railwaySelected.length > 0 ? await requireRailwayConnection(client) : null;
@@ -1768,6 +1838,8 @@ async function applyAdoption(prepared, deps) {
     reportDeleteProtection(layout.project.slug, layout.deleteProtection);
     for (const member of layout.members.added)
         console.log(`  ＋ bóveda: miembro ${member}`);
+    // Factory#72 — what the vault already holds must be what the deploy runs, before writing.
+    await assertVaultMatchesPlan(prepared, projectId);
     // (2) the writes — import first.
     const resend = await writeLayout(prepared, projectId, deps);
     // (2b) ADOPT-009 — the project's Neon key, minted key-only BEFORE any sync exists (so the GitHub
@@ -2129,15 +2201,6 @@ function declineVault(rootDir, deps) {
 export async function runVaultAdopt(flags, deps = {}) {
     assertAdoptSeams(deps);
     const rootDir = deps.rootDir ?? process.cwd();
-    const core = detectCoreProfile(rootDir);
-    if (core !== null) {
-        const why = core === 'lockfile'
-            ? 'el lockfile declara el perfil `core`'
-            : `no hay lockfile y falta \`${WITH_VAULT_SCRIPT_FILE}\``;
-        console.log(`ℹ️  La bóveda no se ofrece en perfil \`core\` (${why}): ese perfil no trae el wrapper que la inyecta ` +
-            'a los scripts. No hice nada.');
-        return { status: 'core' };
-    }
     if (flags.decline)
         return declineVault(rootDir, deps);
     const prepared = await prepareAdoption(rootDir, flags, deps);

package/dist/index.js

@@ -19,8 +19,10 @@ import { envWizardFlow } from './tui/env-wizard-flow.js';
 import { parseDoctorFlags, runDoctor, runLauncherDoctor } from './commands/doctor.js';
 import { parseNewFlags, runNew } from './commands/new.js';
 import { parseProvisionFlags, runProvision } from './commands/provision.js';
+import { runPruneCommand } from './commands/prune.js';
 import { parsePublishArgs, runPublish } from './commands/publish.js';
 import { parseStatusFlags, runStatus } from './commands/status.js';
+import { parseUsageFlags, runUsage } from './commands/usage.js';
 import { runTicketCommand } from './commands/ticket.js';
 import { parseUnpublishTargets, runUnpublish } from './commands/unpublish.js';
 import { maybeOfferAdopt, parseUpdateFlags, runUpdate } from './commands/update.js';
@@ -43,6 +45,8 @@ Comandos:
   status           Reporta la versión instalada vs. la última disponible
   doctor           Detecta huérfanos, conflictos y rules sin importar + aviso de seguridad
                    (--launcher: verifica el entorno — Node ≥ 22, gh, gh auth, membresía org)
+  usage            Mide el consumo real de Claude Code de TU máquina (~/.claude/projects/)
+                   — corre desde cualquier carpeta, no requiere repo
   publish <qué>    Publica el entregable (proposal|mockup|both) a proposals.timekast.mx
   unpublish [qué]  Baja del hub un entregable publicado (proposal|mockup|both; default both)
   provision        Aprovisiona la infra de un derivado (Neon, GitHub, DNS, backlog y su destino de
@@ -52,6 +56,13 @@ Comandos:
   env <sub>        push: sube product vars a Vercel (day-2) · wizard: configura las variables
                    (en la bóveda si el repo la tiene; sin bóveda, en .env.local)
   invite-admin     Crea una invitación de super_admin para un derivado (sin password en texto plano)
+  prune <sub>      Comparte el repo con colaboradores externos sin la metodología (lo guía /prune):
+                   prepare: aplica el tier (.gitignore + .timekast/prune.json) y deja de trackear
+                   lo restringido · cutover: corte a un repo cuya historia nunca tuvo la
+                   metodología (sin --confirm sólo corre el preflight) · invite <usuario>:
+                   colaborador externo con lectura · finish: archiva el -legacy y audita ·
+                   audit: revisa que la historia del repo no tenga rutas restringidas ·
+                   check-pr <n>: rechaza un PR de colaborador que toque algo fuera del producto
   vault <sub>      adopt: pasa a la bóveda un repo que nació antes de ella (sin --apply sólo
                    enseña el plan, por nombre y huella — nunca valores; con varios proyectos
                    de Vercel, --vercel-project <id> elige el principal) · sync railway: crea
@@ -157,6 +168,22 @@ Sobre \`status\` y \`doctor\`:
   gh auth, membresía del org) — termina con código 1 si falla algún check, para
   que un lanzador GUI / CI / el TUI puedan ramificar sobre el resultado.
 
+Sobre \`usage\`:
+  Mide el consumo REAL por transcripts (\`usage\` de cada request — sin estimadores),
+  barriendo TODOS los directorios de \`~/.claude/projects/\`. Local-only: nada sale
+  de tu máquina. Cortes: día × superficie (main loop vs subagentes), por modelo,
+  por repo, por agente, tokens por unidad entregada y rondas de revisión. Flags:
+    --month=<mes|YYYY-MM>  Atajo mensual ("julio" resuelve el más reciente; alias --mes=;
+                           default: mes en curso)
+    --since=YYYY-MM-DD     Inicio de ventana (excluyente con --month)
+    --until=YYYY-MM-DD     Fin de ventana inclusivo (default: hoy)
+    --repo=<subcadena>     Filtra por repo (match sobre nombre o slug)
+    --agent=<tipo>         Filtra por tipo de agente (p.ej. imp-issue-executor)
+    --anon                 Anonimiza los repos (repo-01, repo-02…) para reportes compartibles
+    --json                 Salida machine-readable estable (diffeable entre corridas)
+  Privacidad: solo agregados — fechas, conteos, tokens, nombres de modelo/agente.
+  Nunca contenido de mensajes, paths de archivos del cliente ni código.
+
 Sobre \`env\`:
   \`env push\` sube las product vars de \`.env.local\` a Vercel (production+preview),
   sin tocar las provision-owned. En un repo con bóveda (bloque \`vault\`) no escribe:
@@ -328,6 +355,13 @@ async function main(argv) {
             }
             return;
         }
+        case 'usage': {
+            // 🔴 No repo preflight — ever. The data source is `~/.claude/projects/`
+            // (the developer's home), so this command runs from ANY folder: copying
+            // the update/status/doctor preflight here breaks the whole use case.
+            runUsage(parseUsageFlags(rest));
+            return;
+        }
         case 'provision': {
             await runProvision(parseProvisionFlags(rest));
             return;
@@ -410,6 +444,12 @@ async function main(argv) {
             await runVaultCommand(rest);
             return;
         }
+        case 'prune': {
+            // `factory prune <sub>` — share a repo with outside collaborators without the
+            // methodology. Dispatch lives in the command module (testable branches).
+            await runPruneCommand(rest);
+            return;
+        }
         case 'invite-admin': {
             // Mint a single-use super_admin invite against the target branch's DB.
             // Spawns the kit script `scripts/tools/invite-admin.ts` with the resolved

package/dist/lib/backlog-mapping.js

@@ -183,7 +183,7 @@ function vaultFailureReason(error, link) {
     }
     if (error instanceof RailNotInstalledError) {
         return ('El CLI de la bóveda (`infisical`) no está instalado; instálalo con ' +
-            `\`${INFISICAL_INSTALL_HINT}\` y entra con \`${loginCommand()}\`.`);
+            `${INFISICAL_INSTALL_HINT} y entra con \`${loginCommand()}\`.`);
     }
     if (error instanceof VaultNoAccessError) {
         return (`Tu sesión de la bóveda no tiene acceso al proyecto \`${link.projectId}\` de este repo ` +

package/dist/lib/claude-paths.js

@@ -61,8 +61,14 @@ function dropGitignored(rootDir, paths) {
     return paths.filter((p) => !ignored.has(p));
 }
 /**
- * Repo-relative POSIX paths of NON-gitignored files under `.claude/`.
+ * The project's own Claude Code hooks (`fx-extension-points`): dev-owned, never shipped, so
+ * never an orphan nor an ambiguous kit file.
+ */
+export const PROJECT_HOOKS_DIR = '.claude/hooks/project/';
+/**
+ * Repo-relative POSIX paths of NON-gitignored files under `.claude/`, minus the project's own
+ * hooks ({@link PROJECT_HOOKS_DIR}).
  */
 export function collectClaudePaths(rootDir) {
-    return dropGitignored(rootDir, walkClaude(rootDir));
+    return dropGitignored(rootDir, walkClaude(rootDir)).filter((p) => !p.startsWith(PROJECT_HOOKS_DIR));
 }