@timekast/factory 2.4.0 → 2.5.0

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

@@ -22,6 +22,7 @@ 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';
@@ -44,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
@@ -165,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:
@@ -336,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;

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

package/dist/lib/claude-settings.js

@@ -0,0 +1,104 @@
+/**
+ * `.claude/settings.json` is shared: the kit owns the top-level keys ITS file declares (today
+ * `$schema`, `hooks`, `permissions`); every other top-level key belongs to the project
+ * (`enabledPlugins`, `extraKnownMarketplaces`, `env`, `statusLine`…). `update` compares only
+ * the kit's keys, by CONTENT — a project that only added its own keys, or whose tools
+ * reformatted the file (prettier, `/plugin install --scope project`), is not "edited" — and
+ * after writing the kit's file it puts the project's keys back.
+ *
+ * The manifest entry of this path carries `keys` (the kit's keys in that version) and a
+ * {@link settingsContentHash} instead of the raw-bytes hash. Lockfiles written before that
+ * carry the raw hash; {@link KIT_SETTINGS_HISTORY} maps it to the content hash of the same file.
+ * Contract: `fx-extension-points` §3.
+ */
+import { createHash } from 'node:crypto';
+import KIT_SETTINGS_HISTORY_JSON from './kit-settings-history.json' with { type: 'json' };
+import { normalizeThenHash } from './lockfile.js';
+export const KIT_SETTINGS_PATH = '.claude/settings.json';
+/** The kit's top-level keys in every `settings.json` published before entries carried `keys`. */
+export const LEGACY_KIT_SETTINGS_KEYS = ['$schema', 'hooks', 'permissions'];
+/**
+ * Raw-bytes hash (`normalizeThenHash`) → content hash over {@link LEGACY_KIT_SETTINGS_KEYS}, for
+ * every distinct `settings.json` the kit published before content hashes. Frozen: generated once
+ * from the `v*` tags (every later release records a content hash with its `keys`).
+ */
+export const KIT_SETTINGS_HISTORY = KIT_SETTINGS_HISTORY_JSON;
+/** JSON with object keys sorted at every level and no whitespace — arrays keep their order. */
+export function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (value !== null && typeof value === 'object') {
+        const obj = value;
+        return `{${Object.keys(obj)
+            .sort()
+            .map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function parseObject(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * SHA-256 of the canonical JSON of the `keys` subset of `raw` (absent keys are left out).
+ * `null` when `raw` is not a JSON object. Parity-locked with `distribution/build-dist.ts`.
+ */
+export function settingsContentHash(raw, keys) {
+    const obj = parseObject(raw);
+    if (!obj)
+        return null;
+    const subset = {};
+    for (const key of keys)
+        if (key in obj)
+            subset[key] = obj[key];
+    return createHash('sha256').update(canonicalJson(subset), 'utf8').digest('hex');
+}
+/** Whether `raw` holds the kit's keys of `entry` unchanged (the project's own keys aside). */
+function matchesEntry(raw, entry) {
+    if (normalizeThenHash(raw) === entry.hash)
+        return true;
+    const keys = entry.keys ?? (KIT_SETTINGS_HISTORY[entry.hash] ? LEGACY_KIT_SETTINGS_KEYS : null);
+    const expected = entry.keys ? entry.hash : KIT_SETTINGS_HISTORY[entry.hash];
+    return keys !== null && expected !== undefined && settingsContentHash(raw, keys) === expected;
+}
+/**
+ * The hash `diffLockfiles` sees for `settings.json` on disk: the old or the new entry's hash when
+ * the kit's keys match it, the raw hash otherwise (= edited, as for any other file).
+ */
+export function effectiveSettingsHash(raw, entries) {
+    for (const entry of entries)
+        if (entry && matchesEntry(raw, entry))
+            return entry.hash;
+    return normalizeThenHash(raw);
+}
+/**
+ * The kit's file plus the project's keys of `previousRaw` (every top-level key the kit does not
+ * declare). `content` is `null` when there is nothing to carry over — the kit's file stays byte
+ * for byte. `replaced` names the project keys the kit now declares (the kit wins).
+ *
+ * @param previousKitKeys the kit's keys BEFORE this update (old entry's `keys`, or the legacy
+ *   ones): a previous key outside them was the project's.
+ */
+export function mergeProjectSettingsKeys(kitRaw, previousRaw, previousKitKeys) {
+    const kit = parseObject(kitRaw);
+    const previous = parseObject(previousRaw);
+    if (!kit || !previous)
+        return { content: null, kept: [], replaced: [] };
+    const projectKeys = Object.keys(previous).filter((k) => !previousKitKeys.includes(k));
+    const kept = projectKeys.filter((k) => !(k in kit));
+    const replaced = projectKeys.filter((k) => k in kit);
+    if (kept.length === 0)
+        return { content: null, kept, replaced };
+    const merged = { ...kit };
+    for (const key of kept)
+        merged[key] = previous[key];
+    return { content: `${JSON.stringify(merged, null, 2)}\n`, kept, replaced };
+}

package/dist/lib/constants.js

@@ -65,6 +65,12 @@ export const PROFILES = {
 export const TIMEKAST_DIR = '.timekast';
 export const MANIFEST_FILE = 'manifest.json';
 export const LOCKFILE_FILE = 'lockfile.json';
+/**
+ * The npm packages the kit's tracked files need (Factory#78), embedded by the builder next to
+ * `manifest.json`: `{ version, profile, packages: { name: range } }`. Read from the STAGED
+ * tarball by `add`/`update` (`kit-deps.ts`); never left in a derived repo.
+ */
+export const KIT_DEPS_FILE = 'kit-deps.json';
 /**
  * Repo-root path of the runtime entrypoint markdown. It is a tracked manifest
  * file (via `track` + the `core` rename `CLAUDE.core.md → CLAUDE.md`), so it
@@ -86,6 +92,21 @@ export const CLAUDE_MD_FILE = 'CLAUDE.md';
  * split as `.husky/pre-commit` → `.husky/pre-commit.project`.
  */
 export const VITEST_SETUP_FILE = 'vitest.setup.ts';
+/**
+ * Path prefixes of the brain proper: the two trees the kit's `.prettierignore` block has always
+ * covered whole. Every other path the manifest tracks (`CLAUDE.md`, `.husky/*`,
+ * `.github/workflows/*`, `vitest.setup.ts`) lives among the repo's own files, so the block lists
+ * those one by one, generated from the manifest at sync time (`renderPrettierignoreBlock`).
+ * Trailing slash so a prefix match cannot catch a sibling (`scripts/tools-extra/`).
+ */
+export const BRAIN_PREFIXES = ['.claude/', 'scripts/tools/'];
+/**
+ * Suffix of the kit's copy of a file the repo already had with its own content (`add` keeps the
+ * repo's and writes the kit's next to it). APPENDED to the whole name, never inserted before the
+ * extension: GitHub Actions runs every `*.yml` under `.github/workflows/`, so `ci.kit-example.yml`
+ * would run as a second CI, while `ci.yml.kit-example` is inert.
+ */
+export const KIT_EXAMPLE_SUFFIX = '.kit-example';
 /**
  * Repo-root `.gitattributes`. NOT a tracked manifest file (absent from `track`),
  * so it never flows through the diff/lockfile engine — a derived repo's own rules
@@ -144,6 +165,10 @@ export const UNPUBLISH_SCRIPT_CMD = 'npx @timekast/factory unpublish';
 // through `npx` so it resolves without a global install.
 export const ENV_PUSH_SCRIPT_NAME = 'env:push';
 export const ENV_PUSH_SCRIPT_CMD = 'npx @timekast/factory env push';
+// Agentic Dashboard: the team's local usage dashboard. It reads this machine's Claude Code
+// transcripts, not the repo, so it needs nothing the brain ships and goes to every derivative.
+export const DASHBOARD_SCRIPT_NAME = 'dashboard';
+export const DASHBOARD_SCRIPT_CMD = 'npx -y @timekast/agentic-dashboard --open';
 /**
  * All convenience scripts the installer ensures in a Node derivative's
  * package.json (each: add if missing, never overwrite a divergent value). Keyed
@@ -157,6 +182,7 @@ export const FACTORY_SCRIPTS = {
     [PUBLISH_SCRIPT_NAME]: PUBLISH_SCRIPT_CMD,
     [UNPUBLISH_SCRIPT_NAME]: UNPUBLISH_SCRIPT_CMD,
     [ENV_PUSH_SCRIPT_NAME]: ENV_PUSH_SCRIPT_CMD,
+    [DASHBOARD_SCRIPT_NAME]: DASHBOARD_SCRIPT_CMD,
 };
 /**
  * The local wrapper that injects the vault's environment into the kit's scripts (VAULT-003).

package/dist/lib/derived-dotfiles.js

@@ -0,0 +1,165 @@
+/**
+ * The derived project's dual-owned dotfiles — `.gitattributes` and `.prettierignore` — synced
+ * from the staged tarball after the brain lands. Shared by `add` and the three `update` paths
+ * (main, legacy auto-register, resume): `add` used to skip them, so the first commit of a fresh
+ * install ran the repo's `prettier --write` over every kit file and drifted them all from the
+ * lockfile hashes (Factory#83/#78).
+ *
+ * The generic block engine lives in `gitattributes.ts` (`extractManagedBlock`,
+ * `syncManagedBlock`); this module only decides WHICH block goes into WHICH file and reports it.
+ * Both syncs are best-effort: a tarball without the file (pre-block releases) is a silent no-op,
+ * and a write failure never fails an install that already happened.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { BRAIN_PREFIXES, CLAUDE_MD_FILE, GITATTRIBUTES_FILE, KIT_EXAMPLE_SUFFIX, MANAGED_BLOCK_END, PRETTIERIGNORE_FILE, } from './constants.js';
+import { extractManagedBlock, syncManagedBlock } from './gitattributes.js';
+import { MIGRATIONS_DIR } from './initial-migration.js';
+/** Config files drizzle-kit reads, in the order it would pick them. */
+const DRIZZLE_CONFIG_FILES = [
+    'drizzle.config.ts',
+    'drizzle.config.mts',
+    'drizzle.config.js',
+    'drizzle.config.mjs',
+    'drizzle.config.cjs',
+];
+/** The `out` key of a drizzle config, as a string literal. */
+const DRIZZLE_OUT_RE = /\bout\s*:\s*['"`]([^'"`]+)['"`]/;
+/** The kit's migration line inside the canonical block (`src/lib/db/migrations/`). */
+const KIT_MIGRATIONS_LINE = `${MIGRATIONS_DIR}/`;
+/**
+ * Where THIS repo keeps its drizzle migrations, as an ignore line (`lib/db/migrations/`), or
+ * `null` to keep the kit's. The `out` of the repo's drizzle config wins; without one, a repo with
+ * no `src/` gets the kit path without its `src/` prefix — the adjustment a derivative born before
+ * `src/` makes by hand, which the sync used to revert on every update (Factory#83).
+ */
+export function resolveMigrationsLine(root) {
+    for (const name of DRIZZLE_CONFIG_FILES) {
+        const file = path.join(root, name);
+        if (!existsSync(file))
+            continue;
+        const match = DRIZZLE_OUT_RE.exec(readFileSync(file, 'utf8'));
+        if (!match)
+            break;
+        const out = match[1].trim().replace(/^\.\//, '').replace(/\/+$/, '');
+        // An absolute path or one that climbs out of the repo is nothing prettier could match.
+        if (out === '' || out === '.' || path.isAbsolute(out) || out.split('/').includes('..'))
+            break;
+        return `${out}/`;
+    }
+    if (!existsSync(path.join(root, 'src')))
+        return KIT_MIGRATIONS_LINE.replace(/^src\//, '');
+    return null;
+}
+/**
+ * The kit files this repo's formatter must leave alone that live OUTSIDE the brain prefixes:
+ * every manifest path not under `BRAIN_PREFIXES`, minus `CLAUDE.md` (dev-owned content) and
+ * minus any path with a `<path>.kit-example` beside it — there the file on disk is the repo's
+ * own, and formatting it is the repo's business. Sorted, so the block is stable across runs.
+ */
+export function kitFilesOutsideBrain(manifestPaths, root) {
+    return [...new Set(manifestPaths)]
+        .filter((p) => !BRAIN_PREFIXES.some((prefix) => p.startsWith(prefix)))
+        .filter((p) => p !== CLAUDE_MD_FILE)
+        .filter((p) => !existsSync(path.join(root, `${p}${KIT_EXAMPLE_SUFFIX}`)))
+        .sort();
+}
+/**
+ * Render the `.prettierignore` block for THIS repo from the canonical one the tarball ships.
+ * The canonical block only knows the Factory's own layout and covers `.claude/` and
+ * `scripts/tools/`; two things are generated at sync time, the same precedent as
+ * `renderGitignoreBlock` in `prune`:
+ *
+ *   - the migrations line follows the repo's real drizzle `out` (`resolveMigrationsLine`);
+ *   - a section lists the kit files tracked outside the brain prefixes (`ci.yml`,
+ *     `vitest.setup.ts`, `.husky/*`). Prettier reformatted them in every derivative whose style
+ *     differs from the kit's, and each one became a false conflict on the next update.
+ *
+ * Reads the repo (drizzle config, `src/`, `.kit-example` files) but writes nothing. The same
+ * inputs always give the same block, so a second sync is a no-op.
+ */
+export function renderPrettierignoreBlock(canonical, ctx) {
+    const migrations = resolveMigrationsLine(ctx.root);
+    const lines = canonical
+        .replace(/\r\n/g, '\n')
+        .split('\n')
+        .map((line) => (migrations && line.trim() === KIT_MIGRATIONS_LINE ? migrations : line));
+    const present = new Set(lines.map((l) => l.trim()));
+    const extra = kitFilesOutsideBrain(ctx.manifestPaths, ctx.root).filter((p) => !present.has(p));
+    if (extra.length === 0)
+        return lines.join('\n');
+    const section = [
+        '# Kit files tracked outside .claude/ and scripts/tools/, generated from the manifest by',
+        '# factory add/update. A reformat drifts them from the lockfile just like the brain.',
+        ...extra,
+    ];
+    const end = lines.findIndex((l) => l.trimStart().startsWith(MANAGED_BLOCK_END));
+    if (end === -1)
+        return [...lines, ...section].join('\n');
+    return [...lines.slice(0, end), ...section, ...lines.slice(end)].join('\n');
+}
+/**
+ * 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).
+ */
+export 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.
+ * The block is rendered for this repo (`renderPrettierignoreBlock`); otherwise the
+ * same contract as `syncDerivedGitattributes`.
+ */
+export function syncDerivedPrettierignore(rootDir, stagedDir, manifestPaths) {
+    try {
+        const srcPath = path.join(stagedDir, PRETTIERIGNORE_FILE);
+        if (!existsSync(srcPath))
+            return;
+        const canonical = extractManagedBlock(readFileSync(srcPath, 'utf8'));
+        if (!canonical)
+            return;
+        const block = renderPrettierignoreBlock(canonical, { manifestPaths, root: rootDir });
+        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.');
+    }
+}
+/**
+ * Sync both managed blocks. `manifest` is the profile's manifest just installed (the
+ * `.prettierignore` block lists its files outside the brain prefixes). Must run while
+ * `stagedDir` still exists (it is the source of the blocks) and BEFORE any commit of the brain,
+ * so the ignore lands before a pre-commit hook could reformat the freshly-installed kit files.
+ */
+export function syncDerivedDotfiles(rootDir, stagedDir, manifest) {
+    syncDerivedGitattributes(rootDir, stagedDir);
+    syncDerivedPrettierignore(rootDir, stagedDir, manifest.files.map((f) => f.path));
+}

package/dist/lib/email-from.js

@@ -16,10 +16,7 @@
  * 🔒 TOTAL (never throws): it runs on values read from a deploy, which the CLI does not control.
  */
 export function sendingDomainOf(emailFrom) {
-    const value = emailFrom.trim();
-    const open = value.lastIndexOf('<');
-    const close = value.lastIndexOf('>');
-    const address = open !== -1 && close > open ? value.slice(open + 1, close) : value;
+    const address = senderAddressOf(emailFrom);
     const at = address.lastIndexOf('@');
     return at === -1
         ? ''
@@ -28,3 +25,14 @@ export function sendingDomainOf(emailFrom) {
             .trim()
             .toLowerCase();
 }
+/**
+ * The bare address of an `EMAIL_FROM` value: the part inside the LAST `<…>` when there is one,
+ * else the whole value, trimmed (`Agent Fleet <noreply@x.com>` → `noreply@x.com`). Same rule as
+ * {@link sendingDomainOf}. 🔒 TOTAL (never throws).
+ */
+export function senderAddressOf(emailFrom) {
+    const value = emailFrom.trim();
+    const open = value.lastIndexOf('<');
+    const close = value.lastIndexOf('>');
+    return (open !== -1 && close > open ? value.slice(open + 1, close) : value).trim();
+}