@timekast/factory 2.4.0 → 2.5.0

package/dist/commands/update.js

@@ -23,8 +23,10 @@
  * Auto-register (no lockfile, pre-CLI repo, design §6.3): path-match — repo
  * paths matching the manifest are kit-owned (overwrite); `.claude/` paths absent
  * from the manifest are logged "ambiguous" and NOT deleted on the first sync;
- * an existing `CLAUDE.md` is preserved (write-if-absent). The dev is warned + sees
- * the auto-detected profile before proceeding.
+ * an existing `CLAUDE.md` is preserved (write-if-absent), and so is any other kit
+ * file outside the brain the repo already has with its own content (the kit's copy
+ * goes to `<path>.kit-example`). The dev is warned + sees the auto-detected profile
+ * before proceeding.
  *
  * `--verify`: compares disk vs lockfile and reports drift WITHOUT modifying
  * anything. `--resume`: re-applies a persisted mid-flight state without
@@ -44,8 +46,11 @@ import { collectClaudePaths } from '../lib/claude-paths.js';
 import { CLIError } from '../lib/cli-error.js';
 import { CLAUDE_MD_FILE, GITATTRIBUTES_FILE, GITIGNORE_FILE, LOCKFILE_FILE, PRETTIERIGNORE_FILE, PROFILES, TIMEKAST_DIR, } from '../lib/constants.js';
 import { decideCommit } from '../lib/commit-decision.js';
-import { extractManagedBlock, syncManagedBlock } from '../lib/gitattributes.js';
+import { syncDerivedDotfiles } from '../lib/derived-dotfiles.js';
+import { partitionInitialWrites, refreshKitExamples, reportKeptRepoFiles, writeKitExamples, } from '../lib/initial-writes.js';
+import { offerKitDeps, readKitDeps } from '../lib/kit-deps.js';
 import { diffLockfiles, hasLockfile, normalizeThenHash, planAutoRegister, readLockfile, writeLockfile, } from '../lib/lockfile.js';
+import { effectiveSettingsHash, KIT_SETTINGS_PATH, LEGACY_KIT_SETTINGS_KEYS, mergeProjectSettingsKeys, } from '../lib/claude-settings.js';
 import { detectProfile, maintainKitScripts, setAgentKitVersion } from '../lib/package-json.js';
 import { runPreflight } from '../lib/preflight.js';
 import { printProvisionPointer } from '../lib/provision-pointer.js';
@@ -100,16 +105,52 @@ async function acquireFromBeta(profile) {
  * Hash the disk content (normalized) of every path in `paths` that exists.
  * A missing file is simply absent from the returned map.
  */
-function hashDiskPaths(rootDir, paths) {
+function hashDiskPaths(rootDir, paths, settingsEntries = []) {
     const map = new Map();
     for (const rel of paths) {
         const abs = path.join(rootDir, rel);
         if (existsSync(abs) && statSync(abs).isFile()) {
-            map.set(rel, normalizeThenHash(readFileSync(abs, 'utf8')));
+            const raw = readFileSync(abs, 'utf8');
+            // settings.json: only the kit's keys count, by content (the project's are its own).
+            map.set(rel, rel === KIT_SETTINGS_PATH
+                ? effectiveSettingsHash(raw, settingsEntries)
+                : normalizeThenHash(raw));
         }
     }
     return map;
 }
+/** The `settings.json` the project had before this apply: the run's backup, else the disk. */
+function readPreviousSettings(rootDir, backupDir) {
+    for (const abs of [
+        path.join(backupDir, KIT_SETTINGS_PATH),
+        path.join(rootDir, KIT_SETTINGS_PATH),
+    ]) {
+        if (existsSync(abs) && statSync(abs).isFile())
+            return readFileSync(abs, 'utf8');
+    }
+    return null;
+}
+/**
+ * After the kit's `settings.json` was written, put the project's own keys back (every top-level
+ * key the kit does not declare) and say so. No-op when the kit's file was not written.
+ */
+function restoreProjectSettingsKeys(rootDir, written, previous, previousKitKeys) {
+    if (previous === null || !written.includes(KIT_SETTINGS_PATH))
+        return;
+    const abs = path.join(rootDir, KIT_SETTINGS_PATH);
+    const merged = mergeProjectSettingsKeys(readFileSync(abs, 'utf8'), previous, previousKitKeys);
+    if (merged.content !== null) {
+        writeFileSync(abs, merged.content, 'utf8');
+        console.log(`  ✔ ${KIT_SETTINGS_PATH}: conservé tus llaves (${merged.kept.join(', ')})`);
+    }
+    for (const key of merged.replaced) {
+        console.warn(`  ⚠ ${KIT_SETTINGS_PATH}: \`${key}\` ahora la declara el kit — tu valor se reemplazó por el suyo.`);
+    }
+}
+/** The kit's keys recorded for `settings.json` in a lockfile (the legacy set when absent). */
+function kitSettingsKeysOf(lock) {
+    return lock?.files.find((f) => f.path === KIT_SETTINGS_PATH)?.keys ?? LEGACY_KIT_SETTINGS_KEYS;
+}
 /** Unchanged lines kept around each change in the `[3] Ver diff` view. */
 const DIFF_CONTEXT_LINES = 3;
 /**
@@ -301,7 +342,7 @@ function runVerify(rootDir) {
         throw new CLIError('No hay lockfile que verificar. Corre `factory update` primero.');
     }
     const lock = readLockfile(rootDir);
-    const disk = hashDiskPaths(rootDir, lock.files.map((f) => f.path));
+    const disk = hashDiskPaths(rootDir, lock.files.map((f) => f.path), [lock.files.find((f) => f.path === KIT_SETTINGS_PATH)]);
     const missing = [];
     const drifted = [];
     for (const entry of lock.files) {
@@ -465,20 +506,32 @@ async function runResume(rootDir, flags) {
     const claudeMd = priorLock
         ? assessClaudeMd(rootDir, priorLock)
         : undefined;
+    const previousSettings = readPreviousSettings(rootDir, state.backupDir);
     applyPlan(rootDir, state.stagedDir, state.plan, state.backupDir);
+    restoreProjectSettingsKeys(rootDir, state.plan.writes, previousSettings, kitSettingsKeysOf(priorLock));
     writeLockfile(rootDir, newLock);
     clearUpdateState(rootDir);
     const claudeMdInserted = claudeMd ? applyClaudeMdRetrofit(rootDir, claudeMd) : false;
+    const kitExamples = refreshKitExamples(rootDir, state.stagedDir, newLock.files.map((f) => f.path));
     // Maintain dotfiles BEFORE removing the staged dir (the .gitattributes source).
-    const pkgMutations = maintainDerivedDotfiles(rootDir, state.stagedDir, newLock.version);
+    const pkgMutations = maintainDerivedDotfiles(rootDir, state.stagedDir, newLock);
     const prune = await planPruneMaintenance(rootDir, state.stagedDir, newLock.files.map((f) => f.path));
-    await maybeCommitBrain(rootDir, newLock.version, [...state.plan.writes, ...state.plan.deletes, ...(claudeMdInserted ? [CLAUDE_MD_FILE] : [])], flags, prune);
+    await maybeCommitBrain(rootDir, newLock.version, [
+        ...state.plan.writes,
+        ...state.plan.deletes,
+        ...kitExamples,
+        ...(claudeMdInserted ? [CLAUDE_MD_FILE] : []),
+    ], flags, prune);
+    const kitDeps = readKitDeps(state.stagedDir);
     rmSync(state.stagedDir, { recursive: true, force: true });
     // A resumed update maintains package.json exactly like a normal one, so it owes the dev the
     // same account of what it moved there (`BND-004`).
     reportPkgMutations(pkgMutations);
     if (claudeMd)
         reportClaudeMd(claudeMd, 'applied', claudeMdInserted);
+    // AFTER the brain commit: an install changes package.json and the package lockfile, which
+    // stay out of that commit (Factory#78).
+    await offerKitDeps(rootDir, kitDeps, { assumeYes: flags.yes });
     console.log('✔ `update` retomado y completado.');
     // A resumed update that succeeds completed the setup → show the end-pointer
     // (PVSKILL-002 §8 edge: `--resume` SÍ lo muestra). Suppressed only in headless
@@ -522,10 +575,9 @@ function warnOnScriptConflict(action, _pkgPath) {
  * the managed blocks. Runs BEFORE any brain commit, so the blocks land before a
  * pre-commit hook could reformat the freshly-installed kit files.
  */
-function maintainDerivedDotfiles(rootDir, stagedDir, agentKitVersion) {
-    const pkgMutations = maintainDerivedPkg(rootDir, agentKitVersion);
-    syncDerivedGitattributes(rootDir, stagedDir);
-    syncDerivedPrettierignore(rootDir, stagedDir);
+function maintainDerivedDotfiles(rootDir, stagedDir, manifest) {
+    const pkgMutations = maintainDerivedPkg(rootDir, manifest.version);
+    syncDerivedDotfiles(rootDir, stagedDir, manifest);
     return pkgMutations;
 }
 /** A run that mutated nothing (no package.json, or the maintenance failed and warned). */
@@ -574,63 +626,6 @@ function maintainDerivedPkg(rootDir, agentKitVersion) {
         return emptyPkgMutations();
     }
 }
-/**
- * Sync the Factory's managed `.gitattributes` block (the EOL/binary rules that
- * keep the kit's committed binaries from being corrupted by CRLF→LF normalization)
- * into the derived repo, preserving the dev's own rules. The canonical block is
- * READ from the staged tarball (single SSOT), so the rules are never duplicated in
- * the CLI. Runs even without package.json (a non-Node derivative needs the rules
- * too). Best-effort like the package.json mirror: a tarball that predates the
- * managed block (no markers → no block) is a silent no-op, and a write failure
- * never fails an already-applied update.
- */
-function syncDerivedGitattributes(rootDir, stagedDir) {
-    try {
-        const srcPath = path.join(stagedDir, GITATTRIBUTES_FILE);
-        if (!existsSync(srcPath))
-            return;
-        const block = extractManagedBlock(readFileSync(srcPath, 'utf8'));
-        if (!block)
-            return;
-        const { action } = syncManagedBlock(rootDir, block);
-        if (action === 'unchanged')
-            return;
-        console.log(action === 'created'
-            ? '✔ `.gitattributes` creado con las reglas de normalización del kit.'
-            : '✔ `.gitattributes`: bloque de reglas del kit sincronizado.');
-    }
-    catch {
-        console.warn('Aviso: no se pudo sincronizar `.gitattributes`; el cerebro se instaló igual.');
-    }
-}
-/**
- * Sync the Factory's managed `.prettierignore` block (keeps the derived repo's
- * formatter away from `.claude/**` — a pre-commit `prettier --write` over the kit
- * files drifts disk from the lockfile hashes and turns every later update into
- * false conflicts) into the derived repo, preserving the dev's own ignore rules.
- * Same contract as `syncDerivedGitattributes`: canonical block READ from the
- * staged tarball (single SSOT), best-effort, tarball without the file (pre-block
- * releases) → silent no-op, a write failure never fails an applied update.
- */
-function syncDerivedPrettierignore(rootDir, stagedDir) {
-    try {
-        const srcPath = path.join(stagedDir, PRETTIERIGNORE_FILE);
-        if (!existsSync(srcPath))
-            return;
-        const block = extractManagedBlock(readFileSync(srcPath, 'utf8'));
-        if (!block)
-            return;
-        const { action } = syncManagedBlock(rootDir, block, PRETTIERIGNORE_FILE);
-        if (action === 'unchanged')
-            return;
-        console.log(action === 'created'
-            ? '✔ `.prettierignore` creado con el ignore del cerebro (`.claude/`) — evita falsos conflictos por formato en futuros updates.'
-            : '✔ `.prettierignore`: bloque del kit sincronizado (`.claude/` fuera del formatter).');
-    }
-    catch {
-        console.warn('Aviso: no se pudo sincronizar `.prettierignore`; el cerebro se instaló igual.');
-    }
-}
 /**
  * The kit's own test folder. It stopped shipping to derivatives (`BND-003`): those tests
  * validate KIT tooling, and inside a derivative they ran against a `src/` that may have
@@ -928,10 +923,11 @@ export async function runUpdate(flags, deps = {}) {
             if (flags.dryRun) {
                 console.log('\n🔍 Vista previa: este repo aún no tiene lockfile. El primer `factory update` ' +
                     'registra el cerebro; en el primer sync no hay conflictos posibles.');
+                await offerKitDeps(rootDir, readKitDeps(stagedDir), { dryRun: true });
                 process.exitCode = 0;
                 return;
             }
-            await applyLegacy(rootDir, stagedDir, manifest);
+            await applyLegacy(rootDir, stagedDir, manifest, flags.yes);
             // Legacy auto-register succeeded → end-pointer (PVSKILL-002).
             printProvisionPointer({ assumeYes: flags.yes });
             return;
@@ -942,13 +938,17 @@ export async function runUpdate(flags, deps = {}) {
             ...oldLock.files.map((f) => f.path),
             ...manifest.files.map((f) => f.path),
         ]);
-        const disk = hashDiskPaths(rootDir, trackedPaths);
+        const disk = hashDiskPaths(rootDir, trackedPaths, [
+            oldLock.files.find((f) => f.path === KIT_SETTINGS_PATH),
+            manifest.files.find((f) => f.path === KIT_SETTINGS_PATH),
+        ]);
         const diff = diffLockfiles(oldLock, manifest, disk);
         // --dry-run: preview + STOP. No prompts, no apply, no lockfile, no commit.
         // Exit 2 when conflicts exist so the GUI branches on it (0 otherwise). `return`
         // runs the finally → tmpRoot is cleaned (no update-state was written).
         if (flags.dryRun) {
             reportDryRun(diff, manifest);
+            await offerKitDeps(rootDir, readKitDeps(stagedDir), { dryRun: true });
             process.exitCode = diff.conflicts.length > 0 ? DRY_RUN_CONFLICTS_EXIT : 0;
             return;
         }
@@ -978,7 +978,9 @@ export async function runUpdate(flags, deps = {}) {
         // (first entry from a stable lockfile, where `priorLock.beta` is absent).
         const stateManifest = flags.beta ? { ...manifest, beta: true } : manifest;
         writeUpdateState(rootDir, { stagedDir, backupDir, plan, newManifest: stateManifest });
+        const previousSettings = readPreviousSettings(rootDir, backupDir);
         applyPlan(rootDir, stagedDir, plan, backupDir);
+        restoreProjectSettingsKeys(rootDir, plan.writes, previousSettings, kitSettingsKeysOf(oldLock));
         // Lockfile written ONLY after a clean apply. The birth stamp is preserved
         // (agentKitVersion advances; factoryVersion stays frozen). With `--beta`,
         // `stampBeta` composes `stampBirth` and adds `beta:true`; a stable/plain
@@ -989,14 +991,23 @@ export async function runUpdate(flags, deps = {}) {
         // same commit as the rest of the update (and `CLAUDE.md` joins the staged paths —
         // in case B it is in `ignoreLocal`, so the plan never names it).
         const claudeMdInserted = applyClaudeMdRetrofit(rootDir, claudeMd);
-        const pkgMutations = maintainDerivedDotfiles(rootDir, stagedDir, manifest.version);
+        const kitExamples = refreshKitExamples(rootDir, stagedDir, manifest.files.map((f) => f.path));
+        const pkgMutations = maintainDerivedDotfiles(rootDir, stagedDir, manifest);
         const prune = await planPruneMaintenance(rootDir, stagedDir, manifest.files.map((f) => f.path));
-        await maybeCommitBrain(rootDir, manifest.version, [...plan.writes, ...plan.deletes, ...(claudeMdInserted ? [CLAUDE_MD_FILE] : [])], flags, prune);
+        await maybeCommitBrain(rootDir, manifest.version, [
+            ...plan.writes,
+            ...plan.deletes,
+            ...kitExamples,
+            ...(claudeMdInserted ? [CLAUDE_MD_FILE] : []),
+        ], flags, prune);
         // `theirsConflicts` IS the overwritten-local list: same source whether the dev answered
         // the prompt, passed `--theirs-all`, or ran headless — there is no second path. The
         // package.json mutations ride the SAME closing summary, not three loose notices.
         reportSummary(diff, manifest, theirsConflicts, pkgMutations);
         reportClaudeMd(claudeMd, 'applied', claudeMdInserted);
+        // AFTER the brain commit: an install changes package.json and the package lockfile, which
+        // stay out of that commit (Factory#78).
+        await offerKitDeps(rootDir, readKitDeps(stagedDir), { assumeYes: flags.yes });
         // 🔴 The retrofit reminder, on EVERY applied update and regardless of how conflicts
         // were resolved — `--theirs-all`, `--mine-all`, per-file answers or none at all. A
         // retrofit is not a conflict: it is work this command never attempted, living outside
@@ -1074,7 +1085,8 @@ async function confirmLegacy(profile, assumeYes) {
         name: 'proceed',
         message: `Este repo no tiene lockfile. Se hará un auto-registro por paths (perfil \`${profile}\`).\n` +
             `${detected}\nLos archivos del cerebro que coincidan se sobrescribirán con la última ` +
-            'versión; tu `CLAUDE.md` se conserva si ya existe. ¿Continuar?',
+            'versión; tu `CLAUDE.md` se conserva si ya existe, y también tus archivos fuera de ' +
+            '`.claude/` y `scripts/tools/` (la versión del kit queda al lado como `.kit-example`). ¿Continuar?',
         initial: false,
     });
     if (!proceed) {
@@ -1087,26 +1099,30 @@ async function confirmLegacy(profile, assumeYes) {
  * NOT deleted on the first sync (design §6.3). Builds the lockfile from the
  * normalized hashes of the installed files.
  */
-async function applyLegacy(rootDir, stagedDir, manifest) {
+async function applyLegacy(rootDir, stagedDir, manifest, assumeYes) {
     const repoPaths = new Set(collectClaudePaths(rootDir));
     const plan = planAutoRegister(manifest, repoPaths);
-    // Everything in the manifest is written (kit-owned overwrite + adds). No
-    // deletes on the first sync. CLAUDE.md is dev-owned (rama B / write-if-absent):
-    // if it already exists on disk it is preserved (filtered out of writes); only
-    // written when absent. The lockfile still records the manifest's CLAUDE.md hash,
-    // so a preserved dev CLAUDE.md reads as "locally edited" on future updates →
-    // always ignoreLocal (rama A), never silently clobbered.
+    // The brain is written whole (kit-owned overwrite + adds). No deletes on the
+    // first sync. CLAUDE.md is dev-owned (rama B / write-if-absent): if it already
+    // exists on disk it is preserved (filtered out of writes); only written when
+    // absent. The lockfile still records the manifest's CLAUDE.md hash, so a
+    // preserved dev CLAUDE.md reads as "locally edited" on future updates → always
+    // ignoreLocal (rama A), never silently clobbered. The other kit files outside
+    // the brain get the same treatment as in `add` (#76): one the repo already has
+    // with its own content is kept, the kit's copy goes to `<path>.kit-example`, and
+    // the lockfile records the kit hash (ignoreLocal until the kit changes it).
     const claudeMdExists = existsSync(path.join(rootDir, CLAUDE_MD_FILE));
-    const writes = manifest.files
-        .map((f) => f.path)
-        .filter((p) => !(p === CLAUDE_MD_FILE && claudeMdExists));
+    const { writes, kept } = partitionInitialWrites(rootDir, manifest);
     const backupDir = defaultBackupDir(path.dirname(stagedDir));
+    const previousSettings = readPreviousSettings(rootDir, backupDir);
     applyPlan(rootDir, stagedDir, { writes, deletes: [] }, backupDir);
+    restoreProjectSettingsKeys(rootDir, writes, previousSettings, LEGACY_KIT_SETTINGS_KEYS);
+    writeKitExamples(rootDir, stagedDir, kept);
     // The lockfile = the manifest (its hashes are already the normalized hashes of
     // the just-installed files) PLUS the birth stamp. A legacy auto-register is the
     // first sync this repo records, so the birth seal = the manifest's version.
     writeLockfile(rootDir, { ...manifest, factoryVersion: manifest.version });
-    const pkgMutations = maintainDerivedDotfiles(rootDir, stagedDir, manifest.version);
+    const pkgMutations = maintainDerivedDotfiles(rootDir, stagedDir, manifest);
     // No brain commit on this path; the block is still kept in step (the index is left to
     // `prune prepare`, which the pending notice names).
     reportPendingPrune(await planPruneMaintenance(rootDir, stagedDir, manifest.files.map((f) => f.path)));
@@ -1115,6 +1131,7 @@ async function applyLegacy(rootDir, stagedDir, manifest) {
         console.log('\nConservé tu `CLAUDE.md` (no se sobrescribió). Verifica que importe las rules del kit ' +
             '(`@.claude/rules/*`); corre `factory doctor` para detectar rules sin importar.');
     }
+    reportKeptRepoFiles(kept);
     if (plan.ambiguous.length > 0) {
         console.log('\nArchivos en `.claude/` que no están en el manifest (revisar manualmente):');
         for (const p of plan.ambiguous)
@@ -1122,4 +1139,6 @@ async function applyLegacy(rootDir, stagedDir, manifest) {
     }
     console.log(`\n✔ Auto-registro completo (v${manifest.version}, perfil ${manifest.profile}): ` +
         `${plan.kitOwned.length} kit-owned, ${plan.toAdd.length} agregados, ${plan.ambiguous.length} ambiguos.`);
+    // No brain commit on this path, so nothing to keep the install out of (Factory#78).
+    await offerKitDeps(rootDir, readKitDeps(stagedDir), { assumeYes });
 }

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));
+}