@timekast/factory 1.24.0 → 1.25.0

package/dist/commands/doctor.js

@@ -12,15 +12,26 @@
  *     `src/` + boilerplate deps are the derived project's responsibility
  *     post-bootstrap, and that the patch channel for `src/` is EPIC 2 (agentic
  *     update, not yet available).
+ *   - MISSING INITIAL MIGRATION: a derivative that ships a Drizzle schema and no
+ *     generated `.sql`, so its `vercel-build` (`pnpm db:migrate && pnpm build`)
+ *     would migrate an empty database. INFORMATIONAL — see below.
  *
  * No lockfile (pre-CLI repo) → delegate to the "run factory:update" advice, exit
  * 0, never abort (same pattern as `status` / the §8 edge case).
+ *
+ * 🔴 EVERY CHECK HERE IS ADVISORY. `runDoctor` always exits 0 by contract; the
+ * sibling entrypoint {@link runLauncherDoctor} is the one that throws `CLIError(1)`
+ * on any `status: 'fail'`. A report-only finding therefore belongs in
+ * `computeDoctor`/`renderDoctor` and NOWHERE ELSE — moving it to the launcher would
+ * turn a notice into a blocked command through the back door. If it ever has to
+ * live there, it goes as `warn` (`LauncherCheckStatus`), which never trips the exit.
  */
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { CLIError } from '../lib/cli-error.js';
 import { collectClaudePaths } from '../lib/claude-paths.js';
 import { CLAUDE_MD_FILE } from '../lib/constants.js';
+import { MIGRATIONS_DIR, SCHEMA_DIR, needsInitialMigration, readMigrationFacts, } from '../lib/initial-migration.js';
 import { hasLockfile, normalizeThenHash, readLockfile } from '../lib/lockfile.js';
 import { runLauncherPreflight, } from '../lib/preflight.js';
 import { detectRepo } from '../lib/repo-detection.js';
@@ -46,6 +57,18 @@ export const A1_WARNING = 'Aviso de seguridad (A1): el boilerplate `src/` y sus
     'dependencia) NO llega por este canal. El canal de parches de `src/` es EPIC 2 ' +
     '(update agentico con merge inteligente), aún no disponible. Mantén `src/` y tus ' +
     'dependencias al día por tu cuenta mientras tanto.';
+/**
+ * The literal notice for a derivative whose schema has no generated migration.
+ * Named constant (never an inline string — CODING.md §5) and built from the SAME
+ * directory constants the provision step uses, so a path can never drift between
+ * what `provision` writes and what `doctor` reports. Exported for the tests.
+ */
+export const MISSING_INITIAL_MIGRATION_NOTICE = `⚠ Falta la migración inicial: hay schema en \`${SCHEMA_DIR}/\` y ningún \`.sql\` en ` +
+    `\`${MIGRATIONS_DIR}/\`.\n` +
+    '  El deploy corre `pnpm db:migrate && pnpm build`, así que el primer build migraría una ' +
+    'base vacía. Genera la migración con `pnpm db:generate` y commitéala antes del próximo ' +
+    'deploy.\n' +
+    '  (Aviso informativo: `factory doctor` no bloquea — sale con éxito de todos modos.)';
 /** Parse `doctor`'s argv slice into flags. Unknown flags are ignored. */
 export function parseDoctorFlags(argv) {
     return {
@@ -114,6 +137,10 @@ export function computeDoctor(deps = {}) {
     // `doctor` from a subdir of a managed repo reports the real state instead of
     // "no lockfile" (consistency with `add`/`update`). Tests inject `rootDir`.
     const rootDir = deps.rootDir ?? detectRepo(process.cwd()).repoRoot ?? process.cwd();
+    // Initial-migration gap (GAP-002). Delegated WHOLE to the provision predicate —
+    // facts read from disk, decision (Factory exception included) taken there. Doctor
+    // does not re-derive "is this the Factory": one copy of that rule, in one place.
+    const missingInitialMigration = needsInitialMigration(readMigrationFacts(rootDir));
     if (!hasLockfile(rootDir)) {
         return {
             orphans: [],
@@ -121,6 +148,9 @@ export function computeDoctor(deps = {}) {
             unimportedRules: [],
             claudeMdMissing: false,
             a1Warning: A1_WARNING,
+            // Always false on this branch, and by the predicate rather than by a literal:
+            // no lockfile IS the Factory signal, which `needsInitialMigration` short-circuits.
+            missingInitialMigration,
             noLockfile: true,
             beta: false,
         };
@@ -174,6 +204,7 @@ export function computeDoctor(deps = {}) {
         unimportedRules,
         claudeMdMissing,
         a1Warning: A1_WARNING,
+        missingInitialMigration,
         noLockfile: false,
         beta,
     };
@@ -181,6 +212,8 @@ export function computeDoctor(deps = {}) {
 /** Render the doctor result to the console. The A1 notice is ALWAYS last. */
 function renderDoctor(result) {
     if (result.noLockfile) {
+        // Nothing to say about migrations here: no lockfile IS the Factory signal, so
+        // `missingInitialMigration` is false by construction on this branch.
         console.log('Sin lockfile detectado.');
         console.log('Ejecuta `factory:update` para inicializar el tracking de versión.');
         // The A1 notice is emitted even without a lockfile (always present).
@@ -223,6 +256,12 @@ function renderDoctor(result) {
             }
         }
     }
+    // Initial-migration gap (GAP-002): reported, never enforced. It sits outside the
+    // orphans/conflicts block because it is about the derivative's `src/`, not about
+    // brain drift — a repo with a spotless brain can still be missing its `0000`.
+    if (result.missingInitialMigration) {
+        console.log(`\n${MISSING_INITIAL_MIGRATION_NOTICE}`);
+    }
     // The A1 security notice is always emitted at the end (design §1 + §11).
     console.log(`\n${result.a1Warning}`);
 }

package/dist/commands/provision.js

@@ -29,7 +29,8 @@ import { apexZoneOf, CloudflareApiError, CLOUDFLARE_API_BASE, deleteDnsRecord, e
 import { createDevelopBranch, createNeonProject, createProjectApiKey, deleteNeonApiKeysByName, deleteNeonProject, getConnectionUri, listNeonBranches, listNeonProjects, NeonApiError, NEON_API_BASE, NEON_DEVELOP_BRANCH, } from '../lib/neon-api.js';
 import { createBacklogProject, deleteBacklogProject, mintBacklogKey, BacklogApiError, } from '../lib/backlog-api.js';
 import { defaultEnvPath, readEnvKeyNames, readVercelToken, runProvisionPreflight, } from '../lib/provision-preflight.js';
-import { addVercelDomain, buildEnvPlan, createVercelProject, generateAuthSecret, generateMfaEncryptionKey, getLinkedRepoId, getVercelDomainStatus, getVercelProjectByName, GitHubAppNotInstalledError, linkGitRepo, listProjectDomains, listVercelProjects, patchProjectSettings, pushEnvPlan, removeVercelDomain, triggerDeployment, upsertEnvVar, listEnvVars, VercelApiError, VERCEL_AUTO_APEX, writeVercelProjectJson, } from '../lib/vercel-env.js';
+import { addVercelDomain, buildEnvPlan, createVercelProject, generateAuthSecret, generateMfaEncryptionKey, getLinkedRepoId, getVercelDomainStatus, getVercelProjectByName, GitHubAppNotInstalledError, linkGitRepo, listProjectDomains, listVercelProjects, patchProjectSettings, pushEnvPlan, removeVercelDomain, removeVercelProject, triggerDeployment, upsertEnvVar, listEnvVars, VercelApiError, VERCEL_AUTO_APEX, writeVercelProjectJson, } from '../lib/vercel-env.js';
+import { decideInitialMigration, hasGeneratedMigrations, MIGRATION_SKIP_MESSAGES, MIGRATIONS_DIR, } from '../lib/initial-migration.js';
 import { writeBacklogLocalCreds, writeE2eLocalCreds, writeEmailLocalCreds, writeEnvLocal, } from '../lib/env-file.js';
 import { adoptState, ADOPT_UNKNOWN, clearProvisionState, clearState, hasProvisionState, isServiceComplete, PROVISION_DIR, PROVISION_STATE_FILE, readDestroyTarget, readProvisionState, writeProvisionState, } from '../lib/provision-state.js';
 /**
@@ -257,6 +258,12 @@ function printPlan(result) {
             console.log(`        · Resend env: RESEND_API_KEY [production, preview] + EMAIL_FROM=${PROVISION_EMAIL_FROM}`);
         }
     }
+    // GAP-001: the initial migration is not a service, it is a step of the bootstrap —
+    // announced with the plan so a `--dry-run` states it without generating anything.
+    if (result.initialMigration) {
+        console.log(`  ＋ crear  ${INITIAL_MIGRATION_LABEL}`);
+        console.log('        · se commitea con pathspec propio antes del primer deploy');
+    }
     if (result.dryRun) {
         console.log('\n(`--dry-run`) No se ejecutó ninguna llamada a API ni se escribió estado.');
     }
@@ -834,6 +841,28 @@ function readSharedVercelEnv(envPath) {
 async function pnpmInstall(cwd) {
     await execa('pnpm', ['install'], { cwd });
 }
+/**
+ * The roots this PROCESS already installed. A provision run targets ONE root, so this
+ * is the run-scoped flag the initial-migration step and the `vercel` step share: the
+ * first of the two pays for `pnpm install`, the second is a no-op.
+ *
+ * 🔴 It is NOT `existsSync('node_modules')`. Having the directory does not mean having
+ * the dependencies at their current versions, and the `vercel` step installs
+ * unconditionally today — gating on presence would be a silent regression of that
+ * guarantee (GAP-001 §8). A failed install is deliberately NOT recorded, so the next
+ * caller retries it.
+ */
+const installedRoots = new Set();
+/**
+ * `pnpm install` in the derived dir, at most ONCE per process per root. The seam is the
+ * caller's `runInstall` (tests never run a real install); the default is {@link pnpmInstall}.
+ */
+export async function ensureDeps(rootDir, runInstall = pnpmInstall) {
+    if (installedRoots.has(rootDir))
+        return;
+    await runInstall(rootDir);
+    installedRoots.add(rootDir);
+}
 /**
  * PROV-003 — sync env into the Vercel project: thread `teamId` on EVERY REST call,
  * push variables PER TARGET (production vs preview), mint an INDEPENDENT
@@ -949,9 +978,11 @@ export async function provisionVercel(rootDir, state, teamId, deps = {}) {
     // `pnpm install` the derived dir (issue §4). A missing package.json (non-Node
     // derivative) is reported, NOT fatal (issue §8).
     if (existsSync(join(rootDir, 'package.json'))) {
-        const runInstall = deps.runInstall ?? pnpmInstall;
         try {
-            await runInstall(rootDir);
+            // Run-scoped (GAP-001): a no-op when the initial-migration step already
+            // installed this root in the same run — never twice, never skipped by a
+            // `node_modules` that happens to exist.
+            await ensureDeps(rootDir, deps.runInstall);
         }
         catch (error) {
             console.warn(`⚠ \`pnpm install\` falló en el directorio del derivado (${error?.message ?? 'error'}).\n` +
@@ -1334,8 +1365,10 @@ export async function provisionGithubVercel(rootDir, state, teamId, deps = {}) {
  * Commit the activated E2E workflow (`e2e.yml`) and push it to BOTH `main` and
  * `develop` in the derived repo. `factory new` pushed the initial scaffold commit
  * before provision activated this workflow, so it lives only in the working tree
- * until committed here. (Migrations run in the Vercel build via `vercel-build`, not a
- * workflow — there is nothing to commit for them.) Idempotent — when a `--resume`
+ * until committed here. (Migrations are not part of THIS commit, but they do have one:
+ * `ensureInitialMigration` commits the `0000` earlier in the run, with its own pathspec.
+ * The Vercel build only APPLIES it — `vercel-build` runs `pnpm db:migrate && pnpm build`,
+ * there is no migration workflow.) Idempotent — when a `--resume`
  * finds it already committed, `git add` stages nothing and the commit/push is skipped.
  */
 async function commitAndPushWorkflows(rootDir, runGit) {
@@ -1375,6 +1408,329 @@ async function commitProvisionState(rootDir) {
         // Non-fatal: the local state is intact; the dev can commit it later.
     }
 }
+/** Default `pnpm db:generate` runner — `execa` in the derived dir, no shell. */
+async function drizzleGenerate(cwd) {
+    await execa('pnpm', ['db:generate'], { cwd });
+}
+/** The commit subject of the generated migration (English — GIT.md §3.1). */
+const INITIAL_MIGRATION_COMMIT = 'chore(db): add the initial database migration';
+/** The plan label of the step (es-MX), printed by {@link printPlan}. */
+const INITIAL_MIGRATION_LABEL = 'Migración inicial de la base (0000 de Drizzle)';
+/**
+ * The branch the step commits on and pushes: the one `vercel-build` runs
+ * `pnpm db:migrate && pnpm build` from for PRODUCTION. Named, never inlined
+ * (CODING.md §5) — it appears in the checkout guard, in both pushes and in the
+ * remote confirmation, and those four have to mean the same branch.
+ */
+const MIGRATION_BRANCH = 'main';
+/** The secondary branch the same commit is fast-forwarded onto (the working branch). */
+const MIGRATION_DEV_BRANCH = 'develop';
+/**
+ * The pre-`main` default branch name. `buildGitSubstrate` renames it to
+ * {@link MIGRATION_BRANCH} before pushing, which is why the checkout guard below treats
+ * a repo sitting on it as reaching `main` after all — when that step is in the plan.
+ */
+const LEGACY_DEFAULT_BRANCH = 'master';
+/**
+ * The GREENFIELD guard: the run creates BIRTH infrastructure.
+ *
+ * 🔴 Not merely "there is no `.sql` yet". Without this guard any other door into
+ * provision — a `--services=dns` for a deferred go-live, a standalone `--domain`, a
+ * `--resume` — would generate a `0000` on one of the LIVE derivatives that have no
+ * migrations, commit it, and (with no `github` step to push it) push it too. The next
+ * deploy would run `CREATE TABLE` against a populated database and the build would die.
+ *
+ * 🔴 And the SHAPE OF THE PLAN is not birth either — that was the first version of this
+ * guard, and it left two doors open onto exactly the derivatives it was written to
+ * protect:
+ *
+ *   1. **`--force` NEVER counts as greenfield.** `runProvision` calls
+ *      `clearProvisionState` before `buildPlan`, so with `--force` there is no state to
+ *      read and the plan comes back with EVERY service in `create` — the shape of a
+ *      bootstrap, produced by a flag whose whole job is to destroy the only evidence that
+ *      this project already went through provisioning. A `--services=neon,github --force`
+ *      over a live derivative would have generated and pushed a `0000` on it.
+ *   2. **`github: create` only counts WITH a prior state.** A live derivative provisioned
+ *      before the CLI existed has no `.timekast/provision.json`, so nothing throws, the
+ *      state is `null` and the substrate reads as missing. `github` still counts — that is
+ *      the interrupted-bootstrap case retaken with `--resume`, where `neon` is already in
+ *      `skip` while the substrate is not there yet — but only when a prior state PROVES
+ *      the bootstrap started. Without it, `github: create` proves nothing.
+ *
+ *   3. **`neon: create` needs corroboration too**, and this is the subtlest of the three.
+ *      "A database is being created, so it is empty" conflates two different facts: that
+ *      a NEW database exists, and that the database THE DEPLOY WILL MIGRATE is that one.
+ *      `provisionNeon` only creates the project and uploads E2E secrets — production's
+ *      connection string is written by the `vercel` step. So on a derivative that is
+ *      already live, a new Neon project changes nothing about where the deploy points,
+ *      and the `0000` would be applied against the populated database it has always used.
+ *      Creating a database therefore counts only alongside the run also wiring the app
+ *      up: `vercel` (which writes that connection string) or `github` (which creates the
+ *      substrate carrying the code).
+ *
+ * The population this protects is specific and real: a derivative born before the kit
+ * generated migrations has its tables and its data from a `db:push`, and NO `.sql` at
+ * all — so the "already has migrations" latch does not catch it. What such a project
+ * needs is its `0000` recorded as ALREADY APPLIED (a per-environment baseline), never
+ * executed: drizzle emits `CREATE TABLE` without `IF NOT EXISTS`, so running it fails
+ * with `relation "users" already exists` and the build stops deploying. That baseline is
+ * deliberately out of this step's scope.
+ *
+ * The cost of the third rule is one degraded case, and it is the right way to be wrong:
+ * an interrupted bootstrap missing ONLY the database will not generate the migration by
+ * itself. The dev runs `pnpm db:generate`, and both `factory doctor` and `pnpm preflight`
+ * now say so. A false negative costs one command; a false positive costs a client's
+ * deploy.
+ */
+export function isGreenfieldRun({ steps, force, hadPriorState }) {
+    if (force)
+        return false;
+    const creates = (service) => steps.some((step) => step.service === service && step.action === 'create');
+    // A new database does NOT prove birth on its own — see the docblock. It needs the run
+    // to also be wiring the app up: `vercel` writes production's connection string, and
+    // `github` creates the substrate that carries the code.
+    if (creates('neon'))
+        return creates('vercel') || creates('github');
+    // No new database, but the substrate is being born and a prior state proves the
+    // bootstrap already started — the interrupted run, retaken.
+    return creates('github') && hadPriorState;
+}
+/**
+ * Will the initial-migration step do work on this run? Greenfield guard (the plan + the
+ * run's own evidence) AND the disk decision (`decideInitialMigration`). Read-only — safe
+ * to evaluate while the plan is assembled, i.e. under `--dry-run`.
+ */
+export function shouldRunInitialMigration(rootDir, evidence) {
+    return isGreenfieldRun(evidence) && decideInitialMigration(rootDir).run;
+}
+/**
+ * The branch `HEAD` points at, or `null` when git cannot name one.
+ *
+ * 🔴 Why the step reads it at all: `git add` / `git commit -- <pathspec>` land on the
+ * CURRENT branch, while the push names a REF (`push origin main`). Nothing used to read
+ * the branch, so a dev standing on `develop` — or on a detached `HEAD` — got the commit
+ * on that branch and a push of a `main` that does NOT carry the `.sql`: a green exit code
+ * over exactly the failure this step exists to prevent.
+ *
+ * Never throws, and a detached `HEAD` (which `--abbrev-ref` reports as the literal
+ * `HEAD`) is `null` too: both are "not the migration branch", which is the fail-closed
+ * answer for the push.
+ */
+async function readCurrentBranch(rootDir, runGit) {
+    try {
+        const branch = (await runGit(['rev-parse', '--abbrev-ref', 'HEAD'], rootDir)).stdout.trim();
+        return branch && branch !== 'HEAD' ? branch : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The commit `HEAD` points at, or `null` when git cannot say. Only read for the detached
+ * warning: there the hash is the ONLY handle the dev has on the commit that was just
+ * made, so the message has to carry it.
+ */
+async function readHeadSha(rootDir, runGit) {
+    try {
+        return (await runGit(['rev-parse', 'HEAD'], rootDir)).stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Confirm the just-pushed commit actually reached the remote, and SAY SO. A push that
+ * silently did not land is the failure this whole step exists to prevent, so an
+ * unconfirmable remote is a NOISY warning, never an assumption. Non-fatal: the commit
+ * is already durable locally.
+ */
+async function confirmMigrationOnRemote(rootDir, runGit) {
+    try {
+        const local = (await runGit(['rev-parse', 'HEAD'], rootDir)).stdout.trim();
+        const remoteLine = (await runGit(['ls-remote', 'origin', `refs/heads/${MIGRATION_BRANCH}`], rootDir)).stdout
+            .trim()
+            .split(/\s+/)[0];
+        if (local && remoteLine && local === remoteLine) {
+            console.log(`  ✔ Migración inicial confirmada en el remoto (origin/main ${local.slice(0, 7)}).`);
+            return;
+        }
+        console.warn('⚠ No pude confirmar que la migración inicial esté en el remoto ' +
+            `(origin/main = \`${remoteLine || 'sin respuesta'}\`, local = \`${local || 'desconocido'}\`).\n` +
+            '  Revisa `git log origin/main` ANTES del primer deploy: si el `.sql` no está en el ' +
+            'remoto, el build migrará una base vacía.');
+    }
+    catch (error) {
+        console.warn(`⚠ No pude confirmar la migración inicial en el remoto (${error?.message ?? 'error'}).\n` +
+            '  Revisa `git log origin/main` ANTES del primer deploy.');
+    }
+}
+/**
+ * Generate the initial Drizzle migration, commit it with its OWN pathspec and get it to
+ * the remote BEFORE Vercel builds the tree (PROV-004 pushes `main`; `vercel-build` runs
+ * `pnpm db:migrate && pnpm build`). Without this a fresh derivative deploys against an
+ * empty database.
+ *
+ * Order and its reasons:
+ *   1. Guard + decision — greenfield run AND a derivative that needs it (see
+ *      {@link isGreenfieldRun} / `decideInitialMigration`). Anything else returns.
+ *   2. `ensureDeps` — `drizzle-kit` has to exist. Run-scoped, shared with the `vercel` step.
+ *   3. `pnpm db:generate` — writes `0000_*.sql`. No DB connection needed
+ *      (`drizzle.config.ts` reads `process.env.DATABASE_URL!` without throwing).
+ *   4. `git rev-parse --abbrev-ref HEAD` + `git add` + `git status` +
+ *      `git commit -- <pathspec>` — NEVER a bare commit: with a shared index it would
+ *      swallow whatever else is staged (GIT.md §3.6.1). The branch is read because the
+ *      commit lands on it while the push names a ref (see {@link readCurrentBranch}).
+ *   5. Push, DISCRIMINATED by the plan: when the `github` step runs it pushes `main`
+ *      itself (`buildGitSubstrate`), so pushing here would be redundant; when it does not,
+ *      this step is the only thing that can get the `.sql` to the remote.
+ *
+ * Failure policy: `install`/`generate` ABORT with a `CLIError` — the step runs before the
+ * `github` step, so aborting here means nothing was pushed and nothing was deployed. A git
+ * IDENTITY failure while committing is a non-fatal warning (the `.sql` is already on disk),
+ * mirroring `new.ts`'s precedent. A commit on a branch that is not `main`, and a failed
+ * push, are warnings too — and each push is judged on its own (step 5 below).
+ */
+export async function ensureInitialMigration(rootDir, evidence, deps = {}) {
+    const { steps } = evidence;
+    if (!isGreenfieldRun(evidence)) {
+        // Silence would be wrong in ONE case, and it is one the CLI itself recommends:
+        // `--force` is the flag this command suggests for restarting a failed bootstrap
+        // ("descártalo y empieza de cero"), and a dev who follows that advice would end up
+        // with a derivative that has no `0000` and no word about it. The step still stands
+        // down — `--force` cannot prove birth — but it says so and hands over the remedy.
+        if (evidence.force) {
+            console.log('  ⏭ Con `--force` no genero la migración inicial: el flag descarta el estado de ' +
+                'provision, que es la única evidencia de si este proyecto ya nació — y sobre un ' +
+                'derivado vivo la generaría contra una base poblada.\n' +
+                '     Si esto ES un bootstrap: retómalo con `--resume`, o genera la migración a mano ' +
+                '(`pnpm db:generate`) y commitéala antes del primer deploy. `factory doctor` te lo ' +
+                'recuerda si falta.');
+        }
+        return;
+    }
+    const decision = decideInitialMigration(rootDir);
+    if (!decision.run) {
+        console.log(`  ⏭ ${MIGRATION_SKIP_MESSAGES[decision.reason]}`);
+        return;
+    }
+    const runGenerate = deps.runGenerate ?? drizzleGenerate;
+    const runGit = deps.runGit ?? gitInDir;
+    // 2. Dependencies (drizzle-kit). Run-scoped — the `vercel` step reuses this install.
+    try {
+        await ensureDeps(rootDir, deps.runInstall);
+    }
+    catch (error) {
+        throw new CLIError(`No se pudieron instalar las dependencias del derivado (${error?.message ?? 'error'}).\n` +
+            'Sin ellas no hay `drizzle-kit` para generar la migración inicial, y el primer deploy ' +
+            'correría contra una base vacía. Corre `pnpm install` a mano y reintenta con `--resume`.');
+    }
+    // 3. Generate the `0000`.
+    try {
+        await runGenerate(rootDir);
+    }
+    catch (error) {
+        throw new CLIError(`\`pnpm db:generate\` falló en el derivado (${error?.message ?? 'error'}).\n` +
+            'Sin la migración inicial el primer deploy correría contra una base vacía. Revisa el ' +
+            'schema en `src/lib/db/schema/`, genera a mano y reintenta con `--resume`.');
+    }
+    if (!hasGeneratedMigrations(rootDir)) {
+        console.warn(`⚠ \`pnpm db:generate\` terminó sin escribir ningún \`.sql\` en \`${MIGRATIONS_DIR}/\`.\n` +
+            '  Revisa el schema antes del primer deploy: no hay migración inicial que commitear.');
+        return;
+    }
+    console.log(`  ＋ ${MIGRATIONS_DIR}/ (migración inicial generada)`);
+    // 4. Commit with its OWN pathspec, preceded by a status of that same path. The branch
+    //    is read BEFORE the commit — that is the only thing that says where the commit
+    //    will actually land (`readCurrentBranch`).
+    const branch = await readCurrentBranch(rootDir, runGit);
+    try {
+        await runGit(['add', '--', MIGRATIONS_DIR], rootDir);
+        const pending = (await runGit(['status', '--porcelain', '--', MIGRATIONS_DIR], rootDir)).stdout.trim();
+        if (!pending) {
+            console.log('  ⏭ La migración inicial ya estaba commiteada — nada que pushear.');
+            return;
+        }
+        await runGit(['commit', '-m', INITIAL_MIGRATION_COMMIT, '--', MIGRATIONS_DIR], rootDir);
+    }
+    catch (error) {
+        // Precedent `new.ts`: a git identity failure is a warning, not an abort — the
+        // migration is on disk and the dev can commit it.
+        //
+        // UNSTAGE FIRST. The `add` above already staged the path, and leaving it there hands
+        // the `.sql` to whatever commits next: `commitProvisionState` reads the WHOLE index
+        // and commits bare, so the migration would ride into the run's own state commit
+        // under an unrelated subject. Failing to unstage is not fatal either — the file is
+        // on disk regardless, which is the guarantee this catch exists to state.
+        try {
+            await runGit(['reset', '--', MIGRATIONS_DIR], rootDir);
+        }
+        catch {
+            /* best-effort: the warning below is still true */
+        }
+        console.warn(`⚠ No pude commitear la migración inicial (${error?.message ?? 'error'}).\n` +
+            `  El \`.sql\` quedó en \`${MIGRATIONS_DIR}/\`: commitéalo y pushéalo ANTES del primer deploy ` +
+            '(configura tu identidad con `git config user.email` si ese fue el motivo).');
+        return;
+    }
+    // 5. Push — discriminated by whether the `github` step runs in THIS run.
+    const githubPushes = steps.some((step) => step.service === 'github' && step.action === 'create');
+    // 4b. The commit landed on `branch`, not necessarily on the branch the push names.
+    //     A mismatch is NOISY and stops the push: pushing `main` from here would send a
+    //     `main` that does NOT carry the `.sql` and exit 0 — the very failure this step
+    //     exists to prevent, in green. The `.sql` is on disk and committed where the dev is.
+    //
+    //     ONE exception, and it is not a loophole: a repo still on `master` when the
+    //     `github` step is about to run. That step RENAMES `master` → `main` before
+    //     pushing (`buildGitSubstrate`, step 1), so the commit does reach `main` with the
+    //     `.sql` inside — warning there would be alarmist about a case that works.
+    const substrateWillRename = githubPushes && branch === LEGACY_DEFAULT_BRANCH;
+    if (branch !== MIGRATION_BRANCH && !substrateWillRename) {
+        // A detached HEAD has no branch to merge, so the commit is reachable ONLY by its
+        // hash — naming it is the difference between an actionable warning and a scavenger
+        // hunt through the reflog.
+        const headSha = branch === null ? await readHeadSha(rootDir, runGit) : null;
+        console.warn(`⚠ La migración inicial se commiteó en \`${branch ?? `HEAD desprendido (${headSha ?? 'sha desconocido'})`}\`, no en ` +
+            `\`${MIGRATION_BRANCH}\` — no la pusheo.\n` +
+            `  El push nombra la rama \`${MIGRATION_BRANCH}\` y el commit quedó en otra: pushear ` +
+            `mandaría un \`${MIGRATION_BRANCH}\` SIN el \`.sql\` y el build migraría una base vacía.\n` +
+            (branch === null
+                ? `  Con \`HEAD\` desprendido no hay rama que mergear: el commit \`${headSha ?? '(desconocido)'}\` ` +
+                    `solo es alcanzable por su hash. Recupéralo con \`git branch <nombre> ${headSha ?? '<sha>'}\`, ` +
+                    `mergéalo a \`${MIGRATION_BRANCH}\` y pushea a mano ANTES del primer deploy.\n`
+                : `  Pásate a \`${MIGRATION_BRANCH}\` (o mergea esa rama ahí) y pushea a mano ANTES del ` +
+                    'primer deploy.\n'));
+        return;
+    }
+    if (githubPushes) {
+        console.log('  ↑ Migración inicial commiteada (el push de `main` lo hace el paso de GitHub).');
+        return;
+    }
+    // Un `try` por push, y no uno compartido: `main` es el que le importa a producción
+    // (`vercel-build` = `pnpm db:migrate && pnpm build`) y `develop` puede fallar solo
+    // (non-fast-forward con un remoto divergido). Con un `try` compartido, esa falla de
+    // `develop` imprimía "no pude pushear la migración" y se saltaba la confirmación —
+    // un diagnóstico falso justo cuando `main` SÍ había llegado.
+    try {
+        await runGit(['push', 'origin', MIGRATION_BRANCH], rootDir);
+    }
+    catch (error) {
+        console.warn(`⚠ No pude pushear la migración inicial (${error?.message ?? 'error'}).\n` +
+            '  Pushéala a mano ANTES del primer deploy: el build corre `pnpm db:migrate` contra el ' +
+            'árbol remoto.');
+        return;
+    }
+    try {
+        await runGit(['push', 'origin', `${MIGRATION_BRANCH}:${MIGRATION_DEV_BRANCH}`], rootDir);
+        console.log(`  ↑ Migración inicial commiteada + pusheada (${MIGRATION_BRANCH} + ${MIGRATION_DEV_BRANCH}).`);
+    }
+    catch (error) {
+        console.warn(`⚠ La migración inicial SÍ llegó a \`${MIGRATION_BRANCH}\`, pero no pude pushearla a ` +
+            `\`${MIGRATION_DEV_BRANCH}\` (${error?.message ?? 'error'}).\n` +
+            `  El deploy de producción está cubierto (\`vercel-build\` migra desde \`${MIGRATION_BRANCH}\`); ` +
+            `sincroniza \`${MIGRATION_DEV_BRANCH}\` a mano cuando puedas.`);
+    }
+    await confirmMigrationOnRemote(rootDir, runGit);
+}
 /** Map a Cloudflare REST failure to an actionable, es-MX `CLIError` (issue §8 edges). */
 function cloudflareErrorToCliError(error, context) {
     switch (error.status) {
@@ -2678,7 +3034,7 @@ function describeDestroyPlan(target) {
         lines.push(`  － CNAME Cloudflare ${domain} — DELETE /zones/.../dns_records`);
     }
     if (target.vercelProjectId) {
-        lines.push(`  － Proyecto Vercel ${target.vercelProjectId} — \`vercel remove\` (sesión del dev)`);
+        lines.push(`  － Proyecto Vercel ${target.vercelProjectId} — DELETE /v9/projects (token del rail)`);
     }
     if (target.githubRepo) {
         lines.push(`  － Repo GitHub ${target.githubRepo} — \`gh repo delete\` (sesión del dev)`);
@@ -2807,36 +3163,44 @@ async function destroyCloudflareRecord(domain, zoneId, token, fetchImpl) {
     }
 }
 /**
- * Remove the Vercel PROJECT via the dev's `vercel` CLI (`vercel remove <slug>
- * --yes`) — issue §4: the project delete uses the DEV's session, never a shared org
- * token (the shared org Vercel token is create/configure-only). A "not found" stderr
- * is treated as already-removed (§8).
+ * Remove the Vercel PROJECT over REST, with the rail token that created it.
+ *
+ * 🔴 It used to shell out to the dev's `vercel remove <slug> --yes`, on the principle that a
+ * delete should use the DEV's session and never a shared org token. Measured teardown of a
+ * real ephemeral stack (2026-08-17) showed the principle unreachable in practice: the project
+ * is created by the rail token WITH a `teamId`, so it lives in the team, while the dev's CLI
+ * session sits in whatever scope they last logged into. The delete failed with
+ * `Not authorized … under scope "…"` and left a live, billable project behind — exactly the
+ * outcome `--ephemeral` exists to prevent.
+ *
+ * The REST path also removes the whole class of shell-argument hazards the old code had to
+ * guard against (a slug from the low-trust state file becoming a positional arg), and it
+ * targets the project by ID rather than by name.
+ *
+ * Consistency note: {@link destroyVercelDomain}, called from the same teardown, ALREADY
+ * deleted over REST with this token. The project delete was the outlier, not the rule.
  */
-async function destroyVercelProject(target, runVercel) {
+async function destroyVercelProject(target, token, fetchImpl) {
     const resource = `Proyecto Vercel ${target.slug}`;
-    // FIX 2: the slug came from the low-trust state file and is about to become a
-    // positional arg to `vercel remove`. A malformed slug (leading `-` = flag
-    // smuggling, or a non-subdomain shape) is NEVER passed to the command. It is a
-    // `failed` (not a silent skip) because a Vercel project IS recorded but cannot be
-    // torn down — so `hadFailures` keeps the state (no orphan), per FIX 3.
-    if (!isValidSubdomainSlug(target.slug)) {
+    if (!target.vercelProjectId) {
         return {
             resource: 'Proyecto Vercel',
             status: 'failed',
-            detail: `slug malformado en el estado (\`${target.slug}\`) — bórralo a mano en Vercel`,
+            detail: 'el estado no registró `vercel.projectId` — bórralo a mano en Vercel',
         };
     }
     try {
-        // `--` ends option parsing so the slug can never be read as a flag.
-        await runVercel(['remove', '--yes', '--', target.slug]);
-        return { resource, status: 'removed', detail: 'eliminado vía `vercel remove`' };
+        const outcome = await removeVercelProject(target.vercelProjectId, token, target.scope ?? '', {
+            fetchImpl,
+        });
+        return {
+            resource,
+            status: 'removed',
+            detail: outcome === 'absent' ? 'ya no existía (404)' : 'eliminado',
+        };
     }
     catch (error) {
-        const message = error?.message ?? '';
-        if (/not found|no such|does not exist|404/i.test(message)) {
-            return { resource, status: 'removed', detail: 'ya no existía (vercel)' };
-        }
-        return { resource, status: 'failed', detail: message || 'error en `vercel remove`' };
+        return { resource, status: 'failed', detail: error?.message ?? 'error' };
     }
 }
 /**
@@ -3017,9 +3381,21 @@ async function teardownProviders(target, deps) {
             }
         }
     }
-    // 3. Vercel PROJECT — the dev's `vercel remove` (NEVER a shared org token).
+    // 3. Vercel PROJECT — REST with the rail token, the same one that created it (and the same
+    //    one the domain removal above already uses). The dev's `vercel` session cannot be
+    //    assumed to sit in the team the project lives in; when it does not, the delete fails
+    //    and leaves a billable orphan.
     if (target.vercelProjectId) {
-        outcomes.push(await destroyVercelProject(target, deps.runVercel));
+        if (!vercelToken) {
+            outcomes.push({
+                resource: `Proyecto Vercel ${target.slug}`,
+                status: 'failed',
+                detail: 'sin `VERCEL_TOKEN` en el rail — bórralo a mano en Vercel',
+            });
+        }
+        else {
+            outcomes.push(await destroyVercelProject(target, vercelToken, deps.fetchImpl));
+        }
     }
     // 4. GitHub repo — the dev's `gh repo delete` (NEVER a shared org token).
     if (target.githubRepo) {
@@ -3209,6 +3585,12 @@ export async function runProvision(flags) {
     // patch — it cannot clobber, so it is treated like `--resume` for state-reading.
     const standaloneDomain = hasDomain && flags.services.length === 0;
     // 2. Resolve state. `--force` wins over `--resume` (issue §8): discard + restart.
+    //    🔴 GAP-001: capture whether this project had a provision state BEFORE the discard.
+    //    `clearProvisionState` runs ahead of `buildPlan`, so after it every service reads as
+    //    `create` and the plan is indistinguishable from a bootstrap. That fact is the only
+    //    evidence the greenfield guard has that this project already went through
+    //    provisioning, and this line is the last moment it exists (see `isGreenfieldRun`).
+    const hadPriorState = hasProvisionState(rootDir);
     if (flags.force) {
         clearProvisionState(rootDir);
     }
@@ -3251,6 +3633,14 @@ export async function runProvision(flags) {
     if (repoSlug) {
         result.repo = repoSlug;
     }
+    // GAP-001: decide the initial-migration step WITH the plan (read-only: the greenfield
+    // guard reads the plan + this run's own evidence, the rest reads disk), so `--dry-run`
+    // announces it below and the execution further down uses the very same predicate over
+    // the very same evidence object.
+    const greenfield = { steps, force: flags.force, hadPriorState };
+    if (shouldRunInitialMigration(rootDir, greenfield)) {
+        result.initialMigration = true;
+    }
     if (hasDomain) {
         result.clientDomain = { domain: flags.domain, route: flags.dns };
     }
@@ -3296,6 +3686,11 @@ export async function runProvision(flags) {
     // Ensure the state dir exists + a baseline file before the first step, so a
     // step failure on the very first service still leaves a resumable state.
     writeProvisionState(rootDir, runState);
+    // 5.0. Initial migration (GAP-001) — BEFORE the steps, so the `.sql` is committed
+    //      before the `github` step pushes `main` and Vercel builds the remote tree
+    //      (`vercel-build` = `pnpm db:migrate && pnpm build`). A failed generate/install
+    //      aborts here, with nothing pushed and nothing deployed.
+    await ensureInitialMigration(rootDir, greenfield);
     for (const step of steps) {
         if (step.action === 'skip')
             continue;

package/dist/commands/update.js

@@ -48,6 +48,7 @@ import { diffLockfiles, hasLockfile, normalizeThenHash, planAutoRegister, readLo
 import { detectProfile, maintainKitScripts, setAgentKitVersion } from '../lib/package-json.js';
 import { runPreflight } from '../lib/preflight.js';
 import { printProvisionPointer } from '../lib/provision-pointer.js';
+import { printRetrofitReminder } from '../lib/retrofit-reminder.js';
 import { hasProvisionState } from '../lib/provision-state.js';
 import { detectRepo } from '../lib/repo-detection.js';
 import { downloadBetaProfileTarball, downloadProfileTarball, stageProfileTarball, } from '../lib/unpack.js';
@@ -849,6 +850,16 @@ export async function runUpdate(flags, deps = {}) {
         // 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);
+        // 🔴 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
+        // the tree it is allowed to touch. Deliberately NOT suppressed headless, unlike the
+        // pointer below: an agent updating unattended is the reader least able to notice a
+        // missing manual step on its own. Read from disk, so it lists what just arrived.
+        // `oldLock.version` is the version BEFORE this update, which is what separates the guides
+        // that just arrived from the ones that were already sitting there. A legacy repo carries
+        // `0.0.0`, so every guide reads as new — correct: it has seen none of them.
+        printRetrofitReminder({ rootDir, fromVersion: oldLock.version });
         // End-pointer to the next step (PVSKILL-002). Reached only after a clean apply;
         // `--verify`/`--resume` short-circuit above (verify NEVER prints), an error path
         // throws earlier, and headless `--yes` is suppressed (CI noise).

package/dist/lib/initial-migration.js

@@ -0,0 +1,131 @@
+/**
+ * The initial-migration predicate and the canonical "is this checkout the Factory"
+ * signal (GAP-001, fixed by `project/planning/decisions/ADR-003-factory-signal.md`).
+ *
+ * WHY THIS MODULE EXISTS. `factory provision` never ran `db:generate`, so a fresh
+ * derivative was born with a schema and no migrations while its `vercel-build`
+ * (`pnpm db:migrate && pnpm build`) migrated an empty database on the first deploy.
+ * The provision step that closes that gap has to decide, from disk alone, whether
+ * generating and committing a `0000` is the right thing to do — and the cost of a
+ * wrong "yes" is asymmetric.
+ *
+ * 🔴 THE SIGNAL FAILS TOWARD "DO NOT TOUCH". `.timekast/lockfile.json` is written by
+ * `new`/`add`/`update` in every derivative and does NOT exist in the Factory, so its
+ * ABSENCE means "this is the Factory, or a checkout that cannot be identified" and the
+ * predicate answers `false`. A false positive INSIDE the Factory would commit a `0000`
+ * here, and since the `full` distribution profile is `include: ["**"]` without excluding
+ * `src/lib/db/migrations/`, that `.sql` would ride the tarball into every new derivative
+ * — breaking BR-FACTORY-005 from the origin. A false negative only leaves the migration
+ * ungenerated, which the dev fixes with one `pnpm db:generate`.
+ *
+ * If this signal ever disagrees with the markdown detection `/deploy` uses (`is_factory`
+ * in `project/planning/project-config.md`), the ABSENCE OF THE LOCKFILE WINS and nothing
+ * is mutated — see ADR-003, which is the SSOT of that tie-break, not this comment.
+ *
+ * The predicate is intentionally PURE (it takes resolved facts, not a directory), so the
+ * `scripts/tools/` side of the distribution frontier can CALQUE it — never import it —
+ * the same way `backlog-parse.ts` calques `update-board.ts`.
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { hasLockfile } from './lockfile.js';
+/** Drizzle schema directory of a kit derivative (`drizzle.config.ts` `schema`). */
+export const SCHEMA_DIR = 'src/lib/db/schema';
+/**
+ * Drizzle migrations output directory (`drizzle.config.ts` `out`). Doubles as the
+ * COMMIT PATHSPEC of the provision step: with a shared index (multi-agent, `--resume`,
+ * `--adopt` over a live repo) a bare `git commit` would swallow whatever else is staged
+ * (GIT.md §3.6.1).
+ */
+export const MIGRATIONS_DIR = 'src/lib/db/migrations';
+/** Manifest of a Node derivative — its absence means there is nothing to install. */
+export const PACKAGE_JSON_FILE = 'package.json';
+/** The kit's package manager. Its lockfile is the positive signal for a pnpm project. */
+export const PNPM_LOCKFILE = 'pnpm-lock.yaml';
+/** Lockfiles of the other package managers — present WITHOUT pnpm's means "not ours". */
+export const FOREIGN_LOCKFILES = ['package-lock.json', 'yarn.lock', 'bun.lockb'];
+/** Extension of a generated drizzle migration. */
+export const MIGRATION_SQL_EXT = '.sql';
+/**
+ * Should the initial migration be generated for this checkout?
+ *
+ * PURE by design (see the module header): the caller resolves the facts, this decides.
+ * `isFactory` is checked FIRST and unconditionally — the fail-closed rule outranks
+ * every other consideration, including a project-config that claims otherwise.
+ */
+export function needsInitialMigration({ hasSchema, hasMigrations, isFactory, }) {
+    if (isFactory)
+        return false; // fail-closed: absence of the lockfile always wins
+    if (!hasSchema)
+        return false; // nothing to generate from
+    return !hasMigrations; // idempotence: an existing `.sql` means it was already done
+}
+/**
+ * The canonical machine signal (ADR-003): a derivative HAS `.timekast/lockfile.json`
+ * (written by `new`/`add`/`update`); the Factory does not. Absent → treat as Factory.
+ */
+export function isFactoryCheckout(rootDir) {
+    return !hasLockfile(rootDir);
+}
+/** True when the derivative ships a Drizzle schema directory. */
+export function hasSchemaDir(rootDir) {
+    return existsSync(join(rootDir, SCHEMA_DIR));
+}
+/** True when at least one generated `.sql` already lives in the migrations directory. */
+export function hasGeneratedMigrations(rootDir) {
+    const dir = join(rootDir, MIGRATIONS_DIR);
+    if (!existsSync(dir))
+        return false;
+    try {
+        return readdirSync(dir).some((entry) => entry.toLowerCase().endsWith(MIGRATION_SQL_EXT));
+    }
+    catch {
+        return false; // unreadable directory reads as "cannot confirm" → do not generate
+    }
+}
+/** Resolve the three facts from disk, ready for {@link needsInitialMigration}. */
+export function readMigrationFacts(rootDir) {
+    return {
+        hasSchema: hasSchemaDir(rootDir),
+        hasMigrations: hasGeneratedMigrations(rootDir),
+        isFactory: isFactoryCheckout(rootDir),
+    };
+}
+/**
+ * The es-MX narration per skip reason. Kept next to the reasons (and not inlined at the
+ * call site) so the copy is a named constant, never a magic string (CODING.md §5).
+ */
+export const MIGRATION_SKIP_MESSAGES = {
+    factory: 'No hay `.timekast/lockfile.json`: este checkout no se identifica como derivado ' +
+        '(podría ser el Factory) — omito la migración inicial.',
+    'no-schema': `No hay \`${SCHEMA_DIR}/\` en el repo — omito la migración inicial.`,
+    'has-migrations': `Ya hay migraciones en \`${MIGRATIONS_DIR}/\` — no genero otra.`,
+    'no-package-json': `No hay \`${PACKAGE_JSON_FILE}\` en el repo — omito la migración inicial.`,
+    'not-pnpm': 'El repo usa otro gestor de paquetes (no hay `pnpm-lock.yaml`) — omito la migración ' +
+        'inicial; genérala con el tooling del proyecto.',
+};
+/**
+ * Resolve {@link needsInitialMigration} plus the two tolerance edges the kit owes a
+ * divergent derivative (BR-FACTORY-006): no `package.json`, or a non-pnpm project. Both
+ * warn and continue — they never abort the provisioning.
+ *
+ * This does NOT evaluate the greenfield guard (whether the RUN creates birth
+ * infrastructure): that one reads the plan, not the disk, and lives with the plan.
+ */
+export function decideInitialMigration(rootDir) {
+    const facts = readMigrationFacts(rootDir);
+    if (facts.isFactory)
+        return { run: false, reason: 'factory' };
+    if (!facts.hasSchema)
+        return { run: false, reason: 'no-schema' };
+    if (facts.hasMigrations)
+        return { run: false, reason: 'has-migrations' };
+    if (!existsSync(join(rootDir, PACKAGE_JSON_FILE))) {
+        return { run: false, reason: 'no-package-json' };
+    }
+    const foreign = FOREIGN_LOCKFILES.some((lock) => existsSync(join(rootDir, lock)));
+    if (foreign && !existsSync(join(rootDir, PNPM_LOCKFILE))) {
+        return { run: false, reason: 'not-pnpm' };
+    }
+    return { run: true };
+}

package/dist/lib/retrofit-reminder.js

@@ -0,0 +1,228 @@
+/**
+ * The retrofit reminder printed at the tail of every applied `factory update`.
+ *
+ * WHY IT EXISTS. `update` refreshes the brain mechanically: it copies files, and when a file
+ * conflicts it asks and applies whichever side the dev picked. What it CANNOT do is the work
+ * that lives outside the tracked tree — a step to paste into a workflow the kit is not allowed
+ * to touch, a config the derivative owns, a decision only the project can make. Those ship as
+ * retrofit guides, and a guide nobody is told about is a guide nobody reads: the update ends
+ * "✔ actualizado", the dev moves on, and the half of the change that needed hands never lands.
+ *
+ * 🔴 PRINTED ON EVERY OUTCOME, unlike its sibling {@link printProvisionPointer}. `--theirs-all`,
+ * `--mine-all`, per-file choices, or no conflicts at all — the reminder does not depend on any
+ * of that, because a retrofit is not a conflict: it is work the update never attempted. And it
+ * is NOT suppressed headless. The pointer suppresses there to keep CI logs quiet; this one does
+ * the opposite, because the agent running the update unattended is precisely the reader who
+ * cannot notice a missing step on its own, and an agent reads the transcript it is handed.
+ *
+ * The list is read from disk AFTER the apply, so it reflects the guides that just arrived
+ * rather than a list baked into this binary that would drift from what the kit ships.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Where the kit ships its retrofit guides, inside the derivative. */
+export const RETROFITS_DIR = '.claude/docs/retrofits';
+/**
+ * The blockquote fields a guide uses to say who it is for, in the order they are tried.
+ *
+ * The corpus is heterogeneous by history — some guides lead with `Aplica si:`, older ones with
+ * `Para quién:` or `Audience:`. Rather than rewrite ten documents to satisfy a parser, the
+ * parser accepts what they already say, and a guide matching none of these is still LISTED,
+ * just without its one-liner. Silence about a guide would be the one failure that matters.
+ */
+const APPLICABILITY_FIELDS = [
+    'Aplica si:',
+    'Aplica a:',
+    'Para quién:',
+    'Para:',
+    'Audience:',
+    'Qué es:',
+    'Para quien:',
+];
+/** How much of the applicability line survives — enough to decide, short enough to scan. */
+const SUMMARY_MAX = 96;
+/**
+ * The field every guide declares: the first kit release that shipped it.
+ *
+ * Normalized across the corpus in v11.9 by asking git which release tag CONTAINS the commit
+ * that created each file (`git tag --contains`), rather than inferring it from dates. It is
+ * what lets the reminder separate "arrived in THIS update" from "was already here".
+ */
+const SHIPPED_SINCE_FIELD = 'Disponible desde:';
+/**
+ * Compare two dotted versions. Returns >0 when `a` is newer.
+ *
+ * Deliberately naive — no pre-release handling: these are kit release numbers, and a guide is
+ * never stamped with a beta. Non-numeric junk sorts as 0 rather than throwing, because a
+ * malformed field must degrade to "cannot tell", never break the reminder.
+ */
+export function compareVersions(a, b) {
+    const pa = a.split('.').map((n) => Number.parseInt(n, 10) || 0);
+    const pb = b.split('.').map((n) => Number.parseInt(n, 10) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+/** Pull the `Disponible desde: kit vX.Y.Z` version out of a guide's header. */
+export function extractSince(markdown) {
+    for (const line of markdown.split('\n').slice(0, 20)) {
+        const at = line.indexOf(SHIPPED_SINCE_FIELD);
+        if (at === -1)
+            continue;
+        const match = line.slice(at).match(/v?(\d+\.\d+(?:\.\d+)?)/);
+        if (match)
+            return match[1];
+    }
+    return null;
+}
+/**
+ * Strip markdown emphasis and links down to the words, for a terminal line.
+ *
+ * 🔴 Only `**` and backticks come out. A lone `_` or `*` is left alone, because in this corpus
+ * both are punctuation of an IDENTIFIER far more often than emphasis: stripping them turned
+ * `NEXT_PUBLIC_AUTH_*` into `NEXTPUBLICAUTH` inside the very guide about that variable. Leaving
+ * a stray emphasis marker on screen is the cheaper mistake. These guides bold with `**`.
+ */
+function plainText(raw) {
+    return raw
+        .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1') // [text](link) → text
+        .replace(/\*\*/g, '') // bold — the only emphasis these headers use
+        .replace(/`/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/**
+ * Pull the applicability one-liner out of a guide's header.
+ *
+ * Only the first lines are scanned: every guide states this in its opening blockquote, and
+ * reading further would start matching prose from the body.
+ */
+export function extractApplicability(markdown) {
+    const head = markdown.split('\n').slice(0, 12);
+    for (const field of APPLICABILITY_FIELDS) {
+        for (const line of head) {
+            const at = line.indexOf(field);
+            if (at === -1)
+                continue;
+            const text = plainText(line.slice(at + field.length));
+            if (!text)
+                continue;
+            return text.length > SUMMARY_MAX ? `${text.slice(0, SUMMARY_MAX - 1)}…` : text;
+        }
+    }
+    // The "Retrofit shipped (…) — aplica a X" shape of the older guides.
+    for (const line of head) {
+        const dash = line.match(/—\s*(aplica a .+)$/i);
+        if (dash) {
+            const text = plainText(dash[1]);
+            return text.length > SUMMARY_MAX ? `${text.slice(0, SUMMARY_MAX - 1)}…` : text;
+        }
+    }
+    return null;
+}
+/**
+ * The guides present in this checkout, alphabetical. An absent or empty directory yields `[]`
+ * — a `core`-profile derivative does not receive them, and it must not be told to read a
+ * directory it does not have.
+ */
+export function listRetrofits(rootDir, deps = {}) {
+    const readDir = deps.readDir ?? ((dir) => readdirSync(dir));
+    const readFile = deps.readFile ?? ((file) => readFileSync(file, 'utf8'));
+    let names;
+    try {
+        names = readDir(join(rootDir, RETROFITS_DIR));
+    }
+    catch {
+        return []; // no directory → nothing to remind about
+    }
+    return names
+        .filter((n) => n.endsWith('.md'))
+        .sort()
+        .map((name) => {
+        const path = `${RETROFITS_DIR}/${name}`;
+        let applies = null;
+        let since = null;
+        try {
+            const markdown = readFile(join(rootDir, RETROFITS_DIR, name));
+            applies = extractApplicability(markdown);
+            since = extractSince(markdown);
+        }
+        catch {
+            // unreadable → still listed, just bare
+        }
+        return { slug: name.replace(/\.md$/, ''), path, applies, since };
+    });
+}
+/**
+ * Split the guides into the ones this update just brought and the ones already there.
+ *
+ * `fromVersion` is the lockfile's version BEFORE the update. Without it — a first install, or
+ * a lockfile too old to say — everything lands in `carried`, which reads as "review them all"
+ * and is the honest answer: the reminder cannot know what you already saw.
+ *
+ * 🔴 A guide whose header states no version also lands in `carried`, NEVER in `arrived`. Both
+ * buckets are shown, so nothing is hidden either way; putting an unknown in `arrived` would
+ * cry wolf on every single update forever, which is how a notice trains people to skip it.
+ */
+export function splitByArrival(entries, fromVersion) {
+    if (!fromVersion)
+        return { arrived: [], carried: entries };
+    const arrived = entries.filter((e) => e.since && compareVersions(e.since, fromVersion) > 0);
+    const carried = entries.filter((e) => !arrived.includes(e));
+    return { arrived, carried };
+}
+/** Render the reminder, or `null` when this checkout ships no guides. */
+export function renderRetrofitReminder(entries, fromVersion = null) {
+    if (entries.length === 0)
+        return null;
+    const { arrived, carried } = splitByArrival(entries, fromVersion);
+    const rule = '═'.repeat(74);
+    const lines = [
+        '',
+        rule,
+        '  ⚠️   REVISA LAS GUÍAS DE RETROFIT ANTES DE DAR EL UPDATE POR TERMINADO',
+        rule,
+        '',
+        '  El update mueve archivos. Lo que NO puede mover es lo que vive fuera del árbol',
+        '  que el kit controla: un step en TU workflow, un config que es tuyo, una decisión',
+        '  que solo tu proyecto puede tomar. Eso viaja como guía, y NADA de esto se aplicó.',
+        '',
+    ];
+    const describe = (entry) => {
+        const out = [`  · ${entry.slug}`];
+        if (entry.applies)
+            out.push(`      ${entry.applies}`);
+        return out;
+    };
+    if (arrived.length > 0) {
+        lines.push(`  ▸ NUEVAS EN ESTE UPDATE (${arrived.length}) — empieza por aquí:`, '');
+        for (const entry of arrived)
+            lines.push(...describe(entry));
+        lines.push('');
+    }
+    if (carried.length > 0) {
+        // The heading changes with what we can claim: with no `fromVersion` there is no "already
+        // had", only "here they are".
+        lines.push(arrived.length > 0
+            ? `  ▸ Ya estaban (${carried.length}) — por si nunca las aplicaste:`
+            : `  ▸ Guías disponibles (${carried.length}):`, '');
+        for (const entry of carried)
+            lines.push(...describe(entry));
+        lines.push('');
+    }
+    lines.push(`  No todas te aplican: cada una abre diciendo a quién le toca. En ${RETROFITS_DIR}/`, '  Si trabajas con un agente, pídele que las lea y te diga cuáles te aplican.', rule, '');
+    return lines.join('\n');
+}
+/**
+ * Print the reminder. Called on EVERY applied update — see the module header for why this one
+ * has no headless guard and no outcome condition.
+ */
+export function printRetrofitReminder(opts) {
+    const log = opts.log ?? ((m) => console.log(m));
+    const rendered = renderRetrofitReminder(listRetrofits(opts.rootDir, opts), opts.fromVersion ?? null);
+    if (rendered)
+        log(rendered);
+}

package/dist/lib/vercel-env.js

@@ -303,6 +303,37 @@ export async function removeVercelDomain(projectId, name, token, teamId, deps =
         throw error;
     }
 }
+/**
+ * Delete a Vercel PROJECT over REST, with the same token that created it.
+ *
+ * 🔴 Why REST and not the dev's `vercel remove`. The project is CREATED by
+ * {@link createVercelProject} with the rail token and a `teamId`, so it lives inside the
+ * team. `vercel remove` runs against whatever scope the dev's CLI session happens to be
+ * authenticated to — in a measured teardown that was a personal scope, so the delete failed
+ * with "Not authorized … under scope" and left a live project nobody was going to look for.
+ * Create and delete have to be able to reach the same place.
+ *
+ * This is not a widening of the rail token's blast radius, and it is not a new policy either:
+ * {@link removeVercelDomain}, called from the very same teardown, already deletes over REST
+ * with this token. The project delete was the outlier.
+ *
+ * Idempotency (same contract as its domain sibling): a 404 means it is already gone and
+ * resolves to `'absent'`, so a re-run after a partial teardown is a no-op.
+ *
+ * @throws {VercelApiError} on any non-2xx EXCEPT 404 (which → `'absent'`).
+ */
+export async function removeVercelProject(projectId, token, teamId, deps = {}) {
+    try {
+        await vercelApi('DELETE', `/v9/projects/${encodeURIComponent(projectId)}`, token, teamId, deps);
+        return 'removed';
+    }
+    catch (error) {
+        if (error instanceof VercelApiError && error.status === 404) {
+            return 'absent';
+        }
+        throw error;
+    }
+}
 /** Page size for the project listing — Vercel's documented maximum (`limit` ≤ 100). */
 const VERCEL_PROJECTS_PAGE_SIZE = 100;
 /** Hard stop on the pagination loop — 20 full pages is 2000 projects, far past any team. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timekast/factory",
-  "version": "1.24.0",
+  "version": "1.25.0",
   "description": "Public, thin CLI to bootstrap and maintain TimeKast Factory derived projects.",
   "type": "module",
   "license": "UNLICENSED",