@timekast/factory 2.4.0 → 2.5.0

package/dist/commands/add.js

@@ -12,7 +12,9 @@
  * legacy auto-register lives with its safeguards) → preflight (gh) → resolve
  * profile → download + stage + validate the manifest → install ONLY the manifest
  * files via `applyPlan` (so a `full` tarball never lays down `src/`; `track`
- * excludes it) → write `.timekast/lockfile.json` → ensure `factory:update` (H5).
+ * excludes it) → write `.timekast/lockfile.json` → sync the managed
+ * `.gitattributes` / `.prettierignore` blocks → ensure `factory:update` (H5) →
+ * offer the npm packages the kit's files need and the repo lacks (`kit-deps.ts`).
  *
  * Invariants:
  *   - `add` never touches `src/`, `pj-*`, or any file outside the manifest. It
@@ -23,8 +25,11 @@
  *     is preserved (filtered out of writes) + a warning; only written when absent.
  *   - `add` is for a repo WITHOUT the brain. A repo that already has `.claude/`
  *     or a lockfile is routed to `update` (never a raw re-install).
- *   - `add` overwrites manifest files without prompting — the conflict prompt is
- *     exclusive to `update` (DIST-005).
+ *   - `add` never prompts about FILES — the conflict prompt is exclusive to `update`
+ *     (DIST-005). Its one question is the kit-deps install offer, asked only in a terminal.
+ *     It writes the brain (`.claude/`, `scripts/tools/`) without looking; a kit file
+ *     outside it that the repo already has with its own content (`ci.yml`, `.husky/*`)
+ *     is KEPT, and the kit's copy goes to `<path>.kit-example` (`initial-writes.ts`).
  *   - Atomicity (§7.5): extract + validate in a temp dir before touching the cwd.
  *
  * Expected failures throw `CLIError`; the top-level handler prints + exits.
@@ -35,6 +40,9 @@ import path from 'node:path';
 import { applyPlan, defaultBackupDir, validateStagedManifest } from '../lib/atomic-swap.js';
 import { CLIError } from '../lib/cli-error.js';
 import { CLAUDE_MD_FILE, PROFILES } from '../lib/constants.js';
+import { syncDerivedDotfiles } from '../lib/derived-dotfiles.js';
+import { partitionInitialWrites, reportKeptRepoFiles, writeKitExamples, } from '../lib/initial-writes.js';
+import { offerKitDeps, readKitDeps } from '../lib/kit-deps.js';
 import { hasLockfile, writeInitialLockfile } from '../lib/lockfile.js';
 import { detectProfile, maintainKitScripts } from '../lib/package-json.js';
 import { runPreflight } from '../lib/preflight.js';
@@ -125,6 +133,9 @@ export async function runAdd(flags = { core: false, full: false }) {
     process.once('SIGINT', onSignal);
     process.once('SIGTERM', onSignal);
     let version;
+    // The packages the kit's files need (Factory#78), read from the staged tarball before the
+    // `finally` deletes it; offered at the very end, once the brain is in place.
+    let kitDeps = null;
     try {
         const tarball = await downloadProfileTarball(profile, tmpDir);
         const { stagedDir, manifestRaw } = await stageProfileTarball(tarball, tmpDir);
@@ -138,19 +149,26 @@ export async function runAdd(flags = { core: false, full: false }) {
         }
         version = manifest.version;
         // Install ONLY the manifest's files (never the raw tarball payload — so a
-        // `full` tarball cannot lay down `src/`). CLAUDE.md is dev-owned: filtered out
-        // if it already exists on disk (write-if-absent + warning).
+        // `full` tarball cannot lay down `src/`). The brain is always written; CLAUDE.md
+        // only when absent; any other kit file the repo already has with its OWN content
+        // is kept, and the kit's copy lands next to it as `<path>.kit-example` (#76).
         const claudeMdExists = existsSync(path.join(root, CLAUDE_MD_FILE));
-        const writes = manifest.files
-            .map((f) => f.path)
-            .filter((p) => !(p === CLAUDE_MD_FILE && claudeMdExists));
+        const { writes, kept } = partitionInitialWrites(root, manifest);
         applyPlan(root, stagedDir, { writes, deletes: [] }, defaultBackupDir(tmpDir));
+        writeKitExamples(root, stagedDir, kept);
         // Write the lockfile = the tarball's embedded manifest (no hash recompute).
         writeInitialLockfile(root, manifestRaw);
+        // The managed `.gitattributes` / `.prettierignore` blocks, the same sync `update` runs. Here,
+        // inside the `try`, because `stagedDir` (their source) is deleted by the `finally`. Without
+        // it the repo's first commit ran its own `prettier --write` over every kit file and drifted
+        // them all from the lockfile it had just written.
+        syncDerivedDotfiles(root, stagedDir, manifest);
+        kitDeps = readKitDeps(stagedDir);
         if (claudeMdExists) {
             console.log('Conservé tu `CLAUDE.md` (no se sobrescribió). Verifica que importe las rules del kit ' +
                 '(`@.claude/rules/*`); corre `factory doctor` para detectar rules sin importar.');
         }
+        reportKeptRepoFiles(kept);
     }
     finally {
         process.removeListener('SIGINT', onSignal);
@@ -205,4 +223,7 @@ export async function runAdd(flags = { core: false, full: false }) {
         console.log('Para actualizar: `npx @timekast/factory update` desde la raíz del repo,');
         console.log('o instala el CLI una vez (`npm i -g @timekast/factory`) y corre `factory update`.');
     }
+    // Factory#78 — the packages the kit's files import that this repo does not declare. A
+    // terminal is asked; without one only the exact install command is printed.
+    await offerKitDeps(root, kitDeps);
 }

package/dist/commands/doctor.js

@@ -45,8 +45,10 @@ import path from 'node:path';
 import { CLIError } from '../lib/cli-error.js';
 import { KIT_RULE_PATH_RE, RULES_DIR, bareImportPaths, resolveImportFrom, } from '../lib/claude-md.js';
 import { collectClaudePaths } from '../lib/claude-paths.js';
-import { CLAUDE_MD_FILE } from '../lib/constants.js';
+import { effectiveSettingsHash, KIT_SETTINGS_PATH } from '../lib/claude-settings.js';
+import { BRAIN_PREFIXES, CLAUDE_MD_FILE } from '../lib/constants.js';
 import { MIGRATIONS_DIR, SCHEMA_DIR, needsInitialMigration, readMigrationFacts, } from '../lib/initial-migration.js';
+import { kitExamplePath } from '../lib/initial-writes.js';
 import { hasLockfile, normalizeThenHash, readLockfile } from '../lib/lockfile.js';
 import { LAUNCHER_RAIL_TIMEOUT_MS, runLauncherPreflight, } from '../lib/preflight.js';
 import { readNeonRevokePending } from '../lib/provision-state.js';
@@ -260,6 +262,8 @@ export function computeDoctor(deps = {}) {
         return {
             orphans: [],
             conflicts: [],
+            formatterDrift: [],
+            repoOwned: [],
             unimportedRules: [],
             claudeMdMissing: false,
             a1Warning: A1_WARNING,
@@ -285,16 +289,26 @@ export function computeDoctor(deps = {}) {
     // Pending conflicts: tracked file whose normalized on-disk hash drifted from
     // the recorded hash (a local modification not yet resolved by `update`).
     const conflicts = [];
+    const repoOwned = [];
     for (const entry of lock.files) {
         const abs = path.join(rootDir, entry.path);
         if (!existsSync(abs) || !statSync(abs).isFile())
             continue;
-        const localHash = normalizeThenHash(readFileSync(abs, 'utf8'));
+        const raw = readFileSync(abs, 'utf8');
+        // settings.json: only the kit's keys count (the project's own are not a conflict).
+        const localHash = entry.path === KIT_SETTINGS_PATH
+            ? effectiveSettingsHash(raw, [entry])
+            : normalizeThenHash(raw);
         if (localHash !== entry.hash) {
-            conflicts.push(entry.path);
+            if (existsSync(path.join(rootDir, kitExamplePath(entry.path))))
+                repoOwned.push(entry.path);
+            else
+                conflicts.push(entry.path);
         }
     }
     conflicts.sort();
+    repoOwned.sort();
+    const formatterDrift = conflicts.filter((p) => p !== CLAUDE_MD_FILE && !BRAIN_PREFIXES.some((prefix) => p.startsWith(prefix)));
     // Unimported kit rules: a kit-shipped always-on rule (`.claude/rules/*.md`)
     // that is NOT `@import`ed by CLAUDE.md → it does NOT load at runtime. The check
     // is strict on the `@import` directive (a prose mention does NOT count — a
@@ -322,6 +336,8 @@ export function computeDoctor(deps = {}) {
     return {
         orphans,
         conflicts,
+        formatterDrift,
+        repoOwned,
         unimportedRules,
         claudeMdMissing,
         a1Warning: A1_WARNING,
@@ -373,6 +389,12 @@ function renderDoctor(result, repoVault) {
             for (const p of result.conflicts) {
                 console.log(`  • ${p} — modificado localmente respecto al lockfile`);
             }
+            if (result.formatterDrift.length > 0) {
+                console.log(`  Pista: ${result.formatterDrift.map((p) => `\`${p}\``).join(', ')} ` +
+                    'vive(n) fuera de `.claude/` y `scripts/tools/`. Si solo cambió el formato, ' +
+                    'probablemente lo reformateó el prettier del repo. Guía: ' +
+                    '.claude/docs/retrofits/prettier-drifted-kit-files.md');
+            }
             console.log('  Sugerencia: corre `factory:update --verify` para re-chequear, o `factory:update` para reconciliar.');
         }
         if (result.unimportedRules.length > 0) {
@@ -388,6 +410,13 @@ function renderDoctor(result, repoVault) {
             }
         }
     }
+    // Repo-owned kit files (#76): informative, never a conflict. Shown whatever the rest says.
+    if (result.repoOwned.length > 0) {
+        console.log('\nArchivos propios del repo (el kit dejó su versión al lado, en `.kit-example`):');
+        for (const p of result.repoOwned) {
+            console.log(`  • ${p} — archivo propio del repo; compáralo con \`${kitExamplePath(p)}\``);
+        }
+    }
     // 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`.

package/dist/commands/env.js

@@ -14,6 +14,7 @@
 import { chmodSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { CLIError } from '../lib/cli-error.js';
+import { senderAddressOf } from '../lib/email-from.js';
 import { PER_ENV_MARKER, PER_ENV_REGISTRY_FILE, PROVISION_OWNED, addToPerEnvRegistry, findInlinePerEnvMarkers, findPerEnvMarkedKeys, listEnvKeys, readPerEnvRegistry, setEnvLine, } from '../lib/env-file.js';
 import { applyDefaultOverrides, applyWizardAnswers, applyWizardAnswersToVault, buildEnvReview, buildEnvReviewFromEnv, buildQuestionPlan, checkEnvCompleteness, generateVapidKeys, isQuestionActive, parseEnvBody, parseEnvExample, provisionEmailDefaults, readVaultLocalEnv, readVaultMain, writeSharedToVault, } from '../lib/env-wizard.js';
 import { defaultRail, railTokenRejectedHint, readVercelToken } from '../lib/provision-preflight.js';
@@ -479,16 +480,27 @@ export function runEnvWizardGenVapid(rootDir = process.cwd(), deps = {}) {
     const subjectMissing = !env['VAPID_SUBJECT'];
     if (subjectMissing) {
         const from = env['EMAIL_FROM'];
-        body = setEnvLine(body, 'VAPID_SUBJECT', from ? `mailto:${from}` : 'mailto:admin@example.com');
+        body = setEnvLine(body, 'VAPID_SUBJECT', vapidSubjectFor(from));
     }
     writeFileSync(localPath, body, 'utf8');
     chmodSync(localPath, 0o600); // holds VAPID_PRIVATE_KEY → owner-only.
     console.log('✔ Llaves VAPID generadas y escritas a `.env.local` (la privada queda oculta).');
     console.log(`  NEXT_PUBLIC_VAPID_PUBLIC_KEY=${publicKey}`);
-    if (subjectMissing && !env['EMAIL_FROM']) {
+    if (subjectMissing && vapidSubjectFor(env['EMAIL_FROM']) === VAPID_SUBJECT_PLACEHOLDER) {
         console.log('  ℹ️  Revisa VAPID_SUBJECT — puse un placeholder (correo de contacto para push).');
     }
 }
+/** Placeholder push contact when there is no sender to derive one from. */
+const VAPID_SUBJECT_PLACEHOLDER = 'mailto:admin@example.com';
+/**
+ * The push contact (`VAPID_SUBJECT`) derived from `EMAIL_FROM`. RFC 8292 wants a `mailto:` URL,
+ * so only the bare address goes in: the display-name form (`Name <addr>`) would yield
+ * `mailto:Name <addr>`, which push services reject (Factory#62).
+ */
+export function vapidSubjectFor(emailFrom) {
+    const address = emailFrom ? senderAddressOf(emailFrom) : '';
+    return address.includes('@') ? `mailto:${address}` : VAPID_SUBJECT_PLACEHOLDER;
+}
 /**
  * `--gen-vapid` in a vault repo (VAULT-002): the keypair is upserted (a new pair per run, as on
  * the file path) and `VAPID_SUBJECT` is seeded only when missing, from `main:/EMAIL_FROM`.
@@ -499,11 +511,11 @@ async function genVapidIntoVault(vault) {
     const main = await readVaultMain(vault);
     const subjectMissing = !main['VAPID_SUBJECT'];
     const from = main['EMAIL_FROM'];
-    await writeSharedToVault(vault, { VAPID_SUBJECT: from ? `mailto:${from}` : 'mailto:admin@example.com' }, 'create-if-missing');
+    await writeSharedToVault(vault, { VAPID_SUBJECT: vapidSubjectFor(from) }, 'create-if-missing');
     console.log('✔ Llaves VAPID generadas y escritas en la bóveda (main:/, referenciadas desde develop:/ y local; ' +
         'la privada queda oculta).');
     console.log(`  NEXT_PUBLIC_VAPID_PUBLIC_KEY=${publicKey}`);
-    if (subjectMissing && !from) {
+    if (subjectMissing && vapidSubjectFor(from) === VAPID_SUBJECT_PLACEHOLDER) {
         console.log('  ℹ️  Revisa VAPID_SUBJECT — puse un placeholder (correo de contacto para push).');
     }
 }

package/dist/commands/provision.js

@@ -332,7 +332,7 @@ function printPlan(result, mode = 'plan') {
         if (step.service === 'railway' && step.action === 'create') {
             console.log(`        · proyecto \`${result.projectName}\` · entornos main + develop · servicio \`${RAILWAY_SERVICE_NAME}\` sin fuente`);
             console.log(`        · build → pre-deploy → start: ${RAILWAY_BUILD_COMMAND} · ${RAILWAY_PREDEPLOY_COMMAND} · ${RAILWAY_START_COMMAND}`);
-            console.log('        · la bóveda escribe PORT + AUTH_TRUST_HOST y sincroniza main:/ y develop:/ a Railway; ' +
+            console.log('        · la bóveda escribe PORT + AUTH_TRUST_HOST + AUTH_URL y sincroniza main:/ y develop:/ a Railway; ' +
                 'el repo se conecta cuando llegaron los nombres');
             console.log(`        · un primer deploy por entorno + sonda anónima de ${RAILWAY_HEALTH_PATH} (healthcheck)`);
         }
@@ -1399,6 +1399,8 @@ export function buildVaultPlan(projectName, services, target) {
     if (services.includes('railway')) {
         add(VAULT_MAIN_ROOT, Object.keys(RAILWAY_VAULT_VALUES));
         add(VAULT_DEVELOP_ROOT, Object.keys(RAILWAY_VAULT_VALUES), true);
+        add(VAULT_MAIN_ROOT, [RAILWAY_AUTH_URL_KEY], true);
+        add(VAULT_DEVELOP_ROOT, [RAILWAY_AUTH_URL_KEY], true);
     }
     if (services.includes('backlog')) {
         add(VAULT_LOCAL_ROOT, ['BACKLOG_API_KEY', 'BACKLOG_PROJECT_ID']);
@@ -3524,23 +3526,9 @@ export async function provisionGithubVercel(rootDir, state, teamId, deps = {}) {
     //    AFTER building (in Vercel `build` goes first; Railway's pre-deploy runs once the
     //    build finished), so a failed build never touches the DB — no migrate.yml, no
     //    Deploy Hook, no manual step.
-    const e2e = writeE2eWorkflow(rootDir);
-    if (e2e === 'activated') {
-        console.log(`  ＋ ${E2E_WORKFLOW_PATH} (E2E activado — dispara en main: push + PRs)`);
-    }
-    else if (e2e === 'no-playwright') {
-        console.log('  ⏭ E2E no activado (el proyecto no usa @playwright/test)');
-    }
-    else {
-        console.log('  ⏭ E2E no activado (no se encontró e2e.yml.example en el repo)');
-    }
-    // 7. Commit + push the activated E2E workflow. `factory new` pushed the initial
-    //    scaffold commit BEFORE this workflow existed, so it lives only in the working
-    //    tree until committed here. Idempotent: a `--resume` with it already committed
-    //    stages nothing → skips.
-    if (e2e === 'activated') {
-        await commitAndPushWorkflows(rootDir, runGit);
-    }
+    //    It is NOT pushed here: the push triggers the workflow, and CI's secrets reach GitHub
+    //    later in the run — `pushE2eWorkflowWhenReady` pushes it once they did.
+    logE2eActivation(writeE2eWorkflow(rootDir));
     // 8. Mark the github step DONE — the substrate, Vercel project, git connect,
     //    workflows and secrets are all in place. The early returns above (e.g. the
     //    GitHub-App-not-installed HITL pause) never reach here, so a step that did
@@ -3561,10 +3549,15 @@ export async function provisionGithubSubstrate(rootDir, state, deps = {}) {
     state.github = { repo: repoSlug };
     writeProvisionState(rootDir, state);
     await buildGitSubstrate(rootDir, repoSlug, runGit, deps.force ?? false);
-    const e2e = writeE2eWorkflow(rootDir);
+    // Written, not pushed: `pushE2eWorkflowWhenReady` pushes it once CI's secrets are in GitHub.
+    logE2eActivation(writeE2eWorkflow(rootDir));
+    state.github = { repo: repoSlug, done: true };
+    writeProvisionState(rootDir, state);
+}
+function logE2eActivation(e2e) {
     if (e2e === 'activated') {
-        console.log(`  ＋ ${E2E_WORKFLOW_PATH} (E2E activado — dispara en main: push + PRs)`);
-        await commitAndPushWorkflows(rootDir, runGit);
+        console.log(`  ＋ ${E2E_WORKFLOW_PATH} (E2E activado — dispara en main: push + PRs; se pushea al cierre, ` +
+            'cuando CI ya tenga sus secrets)');
     }
     else if (e2e === 'no-playwright') {
         console.log('  ⏭ E2E no activado (el proyecto no usa @playwright/test)');
@@ -3572,8 +3565,37 @@ export async function provisionGithubSubstrate(rootDir, state, deps = {}) {
     else {
         console.log('  ⏭ E2E no activado (no se encontró e2e.yml.example en el repo)');
     }
-    state.github = { repo: repoSlug, done: true };
-    writeProvisionState(rootDir, state);
+}
+/**
+ * Push the activated `e2e.yml` only once CI can run it. Pushing it triggers the workflow on
+ * `main`, and its preflight aborts without `DATABASE_URL` / `NEON_API_KEY` / `NEON_PROJECT_ID`:
+ * pushed before they reach GitHub, the project's first day opens with a red "E2E failed" that
+ * is not a defect of the app. With a vault, the proof is the `develop:/ci` sync's delivery
+ * ({@link waitForGithubDelivery}, bounded); without one, the `neon` step having set the secrets.
+ * No proof → the file stays in the working tree, unpushed, and a `--resume` pushes it.
+ * Never pushes blind. Idempotent: an already committed workflow is left alone.
+ */
+export async function pushE2eWorkflowWhenReady(rootDir, options) {
+    const runGit = options.runGit ?? gitInDir;
+    if (!existsSync(join(rootDir, E2E_WORKFLOW_PATH)))
+        return 'nothing';
+    const pending = (await runGit(['status', '--porcelain', '--', E2E_WORKFLOW_PATH], rootDir)).stdout.trim();
+    if (!pending)
+        return 'nothing';
+    const ready = options.vault
+        ? await waitForGithubDelivery(options.vault, {}, options.repo, options.sync)
+        : !options.secretsPending;
+    if (!ready) {
+        console.warn(`⚠ ${E2E_WORKFLOW_PATH} queda sin pushear: los secrets de E2E todavía no llegan a GitHub ` +
+            (options.vault
+                ? `(el sync ${syncLabels(['github-ci'])} no ha entregado). `
+                : '(el paso `neon` no pudo escribirlos). ') +
+            'Pushearlo ahora haría fallar la primera corrida de E2E. Repite con `--resume` y se pushea ' +
+            'en cuanto lleguen.');
+        return 'held';
+    }
+    await commitAndPushWorkflows(rootDir, runGit);
+    return 'pushed';
 }
 /**
  * Commit the activated E2E workflow (`e2e.yml`) and push it to BOTH `main` and
@@ -5149,7 +5171,8 @@ export async function updateDomainEnv(projectId, token, teamId, domain, deps, ho
         ...(clientMail
             ? [{ key: 'EMAIL_FROM', value: emailFrom, target: ['production', 'preview'] }]
             : []),
-        // 🔴 AUTH_URL / NEXTAUTH_URL are DELIBERATELY ABSENT — do not re-add them.
+        // 🔴 AUTH_URL / NEXTAUTH_URL are DELIBERATELY ABSENT on Vercel — do not re-add them here.
+        // (Railway is the opposite case and lives apart: see RAILWAY_AUTH_URL_KEY.)
         // `next-auth/lib/env.js` rewrites the origin of every auth request to their value,
         // so scoping either to `preview` pins all branch deployments' callbacks to this one
         // host and kills their sign-in. `trustHost` (auth.config.ts) already infers the
@@ -7610,7 +7633,16 @@ export const RAILWAY_LEGACY_HEALTH_PATH = '/api/health';
  */
 export const RAILWAY_BUILD_COMMAND = 'TK_VAULT=off pnpm build';
 export const RAILWAY_PREDEPLOY_COMMAND = 'TK_VAULT=off pnpm db:migrate';
-export const RAILWAY_START_COMMAND = 'TK_VAULT=off pnpm start';
+/**
+ * Next as the container's main process — no shell, no `pnpm`, no wrapper. A start with a prepended
+ * assignment runs in a shell and `pnpm` adds a `sh -c`; Railway's SIGTERM never reaches Next through
+ * that chain, so a graceful shutdown (closing streams, releasing leases) never runs (Factory#66). The
+ * wrapper adds nothing here: it already passes through on Railway. `railway.json` is not a way out —
+ * Railway deprecated config-as-code and ignores it; the setting lives on the service instance.
+ */
+export const RAILWAY_START_COMMAND = 'node node_modules/next/dist/bin/next start';
+/** Time Railway gives the old deployment between SIGTERM and SIGKILL, so it can shut down. */
+export const RAILWAY_DRAINING_SECONDS = 30;
 /**
  * What the VAULT writes for Railway (Decision 10) — one copy in `main:/`, referenced from
  * `develop:/`; the vault stays the only writer of the deploys. Never written with destination
@@ -7620,6 +7652,15 @@ export const RAILWAY_VAULT_VALUES = {
     PORT: String(RAILWAY_APP_PORT),
     AUTH_TRUST_HOST: 'true',
 };
+/**
+ * Behind Railway's proxy `next start` sees the container's bind host, so even with `trustHost`
+ * Auth.js would build its URLs on `localhost:3000` (Factory#60). `AUTH_URL` pins them to the public
+ * origin: written in `main:/` and `develop:/` as a reference to `NEXT_PUBLIC_APP_URL` of the SAME
+ * folder, so the go-live moving that origin moves this one too. Never with destination Vercel,
+ * where it would pin every branch preview to one host (`sk-security § trustHost`).
+ */
+export const RAILWAY_AUTH_URL_KEY = 'AUTH_URL';
+const RAILWAY_AUTH_URL_SOURCE_KEY = 'NEXT_PUBLIC_APP_URL';
 /** Budget and poll interval of the wait for NAMES before the repo is connected. */
 export const RAILWAY_NAMES_TIMEOUT_MS = FIRST_SYNC_TIMEOUT_MS;
 export const RAILWAY_NAMES_POLL_MS = FIRST_SYNC_POLL_MS;
@@ -8136,16 +8177,21 @@ export async function provisionRailway(rootDir, state, deps) {
                 buildCommand: RAILWAY_BUILD_COMMAND,
                 preDeployCommand: RAILWAY_PREDEPLOY_COMMAND,
                 startCommand: RAILWAY_START_COMMAND,
+                drainingSeconds: RAILWAY_DRAINING_SECONDS,
                 ...(region ? { region } : {}),
             },
         });
     }
-    console.log(`  ＋ Railway: build → pre-deploy (\`db:migrate\`) → start con TK_VAULT=off` +
+    console.log(`  ＋ Railway: build → pre-deploy (\`db:migrate\`) → start (Next directo, ${RAILWAY_DRAINING_SECONDS} s para apagarse)` +
         (region ? ` · región ${region}` : ''));
-    // 8. The vault is the only writer: runtime values + PORT/AUTH_TRUST_HOST, before any sync.
+    // 8. The vault is the only writer: runtime values + PORT/AUTH_TRUST_HOST/AUTH_URL, before any sync.
     await writeRuntimeToVault(rootDir, state, vault, existingProvisionDomains(projectName, state.dns), rail, fetchImpl);
     await vaultWrite(vault, VAULT_MAIN_ROOT, { ...RAILWAY_VAULT_VALUES }, 'create-if-missing');
     await vaultReference(vault, VAULT_DEVELOP_ROOT, Object.keys(RAILWAY_VAULT_VALUES), VAULT_MAIN_ROOT);
+    // `create-if-missing`: an AUTH_URL a team already set by hand is never replaced.
+    for (const location of [VAULT_MAIN_ROOT, VAULT_DEVELOP_ROOT]) {
+        reportVaultWrite(location, await vault.client.writeReference(vault.projectId, location, RAILWAY_AUTH_URL_KEY, { ...location, key: RAILWAY_AUTH_URL_SOURCE_KEY }, 'create-if-missing'));
+    }
     // 9. The two vault → Railway syncs (ADOPT-002's primitive), ids recorded.
     const ids = { ...rw.syncs?.ids };
     const pending = [];
@@ -9177,6 +9223,18 @@ export async function runProvision(flags, deps = {}) {
             railway: runCtx.railway,
         });
     }
+    // 5b.1. The E2E workflow, pushed only now that CI's secrets are in GitHub (#96): the
+    //       `github` step wrote it, and pushing it there triggered a run that failed for lack of
+    //       them. Held (never pushed blind) when there is no proof yet; `--resume` retries.
+    if (!flags.dryRun && runState.github?.done) {
+        await pushE2eWorkflowWhenReady(rootDir, {
+            ...(runCtx.railway?.runGit ? { runGit: runCtx.railway.runGit } : {}),
+            vault: runCtx.vault ?? null,
+            repo: runState.github.repo,
+            secretsPending: runState.neon?.apiKeySecretPending === true,
+            sync: deps.sync,
+        });
+    }
     // 5c. Persist the provision state to the repo (resource IDs) so a `--resume` from
     //     a fresh clone has them. Only when the git substrate exists; best-effort.
     if (runState.github?.done) {

package/dist/commands/prune.js

@@ -18,12 +18,15 @@ import { GITIGNORE_FILE } from '../lib/constants.js';
 import { readValueFlag } from '../lib/flags.js';
 import { commitWithPrivateIndex, trackedFiles } from '../lib/prune-git.js';
 import { checkPr, REJECTED_PACKAGE_FIELDS } from '../lib/prune-pr-check.js';
+import { BRANCH_DEPLOY_RULE, VERCEL_JSON, ensureBranchDeployRule, hasBranchDeployRule, pruneVercelRelink, resolveVercelProject, } from '../lib/prune-vercel.js';
+import { readVercelToken } from '../lib/provision-preflight.js';
 import { applyTierFiles, defaultPruneDeps, originRepo, pruneAudit, pruneCutover, pruneFinish, pruneInvite, } from '../lib/prune-remote.js';
 import { DEFAULT_PRUNE_TIER, PRUNE_MARKER_PATH, getTier, isRestricted, readPruneMarker, readPruneTiers, } from '../lib/prune-tiers.js';
 import { detectRepo } from '../lib/repo-detection.js';
 const PRUNE_USAGE = 'Uso: `factory prune prepare [--tier=collab] [--skip-verify]` · ' +
     '`factory prune cutover [--confirm] [--discard-develop] [--resume] [--repo=owner/nombre]` · ' +
-    '`factory prune invite <usuario-github> [--repo=owner/nombre]` · ' +
+    '`factory prune vercel [--confirm] [--repo=owner/nombre] [--project=prj_…] [--team=team_…]` · ' +
+    '`factory prune invite <usuario-github> [--read] [--repo=owner/nombre]` · ' +
     '`factory prune finish [--repo=owner/nombre]` · `factory prune audit [--repo=owner/nombre]` · ' +
     '`factory prune check-pr <número> [--repo=owner/nombre] [--json]`.';
 export function parsePrunePrepareFlags(argv) {
@@ -48,25 +51,29 @@ export async function prunePrepare(rootDir, flags) {
     const tier = getTier(readPruneTiers(rootDir), flags.tier);
     // The two files this command owns must not carry someone's uncommitted work: the commit
     // below takes them whole.
-    const dirty = await execa('git', ['status', '--porcelain', '--', GITIGNORE_FILE, PRUNE_MARKER_PATH], { cwd: rootDir, reject: false });
+    const dirty = await execa('git', ['status', '--porcelain', '--', GITIGNORE_FILE, PRUNE_MARKER_PATH, VERCEL_JSON], { cwd: rootDir, reject: false });
     if (dirty.stdout.trim() !== '') {
-        throw new CLIError(`\`${GITIGNORE_FILE}\` o \`${PRUNE_MARKER_PATH}\` tienen cambios sin commitear. ` +
+        throw new CLIError(`\`${GITIGNORE_FILE}\`, \`${PRUNE_MARKER_PATH}\` o \`${VERCEL_JSON}\` tienen cambios sin commitear. ` +
             'Commitéalos o descártalos y vuelve a correr `factory prune prepare`.');
     }
     // 1. The block and the switch — `at` survives a re-run with the same tier, so a re-run
     // changes nothing.
     const prior = readPruneMarker(rootDir);
     const legacyBlockRemoved = applyTierFiles(rootDir, flags.tier, tier, prior?.tier === flags.tier ? prior.at : new Date().toISOString());
-    // 2. Untrack what the tier restricts, and commit it with the block and the switch.
+    // 2. On Vercel, only `main` and `develop` deploy on push: a collaborator's branch would
+    //    start a deployment Vercel blocks (author without a seat).
+    const branchDeployRuleAdded = ensureBranchDeployRule(rootDir) === 'added';
+    // 3. Untrack what the tier restricts, and commit it with the block, the switch and the rule.
     const untracked = (await trackedFiles(rootDir)).filter((p) => isRestricted(tier, p));
     const commit = await commitWithPrivateIndex(rootDir, {
         remove: untracked,
-        add: [GITIGNORE_FILE, PRUNE_MARKER_PATH],
+        add: [GITIGNORE_FILE, PRUNE_MARKER_PATH, ...(branchDeployRuleAdded ? [VERCEL_JSON] : [])],
         message: `chore(prune): keep the methodology local (tier ${flags.tier})`,
     });
     return {
         tier: flags.tier,
         untracked,
+        branchDeployRuleAdded,
         legacyBlockRemoved,
         ...(commit.committed ? { commit: commit.sha } : {}),
     };
@@ -94,6 +101,10 @@ async function runPrunePrepare(flags) {
             `Dejé de trackear ${result.untracked.length} archivo(s); siguen en tu disco:`);
         for (const line of summarizePaths(result.untracked))
             console.log(line);
+        if (result.branchDeployRuleAdded) {
+            console.log(`✔ \`${VERCEL_JSON}\`: sólo \`main\` y \`develop\` despliegan con cada push — las ramas de ` +
+                'los colaboradores no intentan un deploy que Vercel bloquearía.');
+        }
     }
     if (flags.skipVerify)
         return;
@@ -155,7 +166,7 @@ async function runPruneCutover(flags, deps) {
         for (const line of result.notMigrated)
             console.log(`  • ${line}`);
     }
-    console.log('\nSiguiente: reconecta el proyecto de Vercel al repo nuevo en el dashboard (Settings → Git), ' +
+    console.log('\nSiguiente: reconecta el proyecto de Vercel al repo nuevo (`factory prune vercel`), ' +
         'pide a los socios volver a clonar, y corre `factory prune finish` cuando Production despliegue.');
 }
 function printAudit(repo, audit) {
@@ -188,7 +199,7 @@ async function repoFrom(argv) {
     return readValueFlag(argv, 'repo') ?? (await originRepo(requireRepoRoot()));
 }
 /** `factory prune <sub> [...]` — dispatch lives here so every branch is testable. */
-export async function runPruneCommand(args, deps = defaultPruneDeps) {
+export async function runPruneCommand(args, deps = defaultPruneDeps, vercel = {}) {
     const sub = args[0];
     const rest = args.slice(1);
     switch (sub) {
@@ -203,9 +214,48 @@ export async function runPruneCommand(args, deps = defaultPruneDeps) {
             if (!user)
                 throw new CLIError(`Falta el usuario de GitHub del colaborador. ${PRUNE_USAGE}`);
             const repo = await repoFrom(rest);
-            await pruneInvite(repo, user, deps);
-            console.log(`✔ Invité a \`${user}\` a \`${repo}\` con lectura. Tiene que aceptar la invitación; ` +
-                'después forkea y abre PRs a la rama de trabajo.');
+            const read = rest.includes('--read');
+            await pruneInvite(repo, user, deps, read ? 'pull' : 'push');
+            console.log(read
+                ? `✔ Invité a \`${user}\` a \`${repo}\` con lectura. Tiene que aceptar la invitación; ` +
+                    'después forkea y abre PRs a la rama de trabajo.'
+                : `✔ Invité a \`${user}\` a \`${repo}\` con escritura. Tiene que aceptar la invitación; ` +
+                    'después trabaja en ramas del repo y abre PRs a la rama de trabajo. El hook `pre-push` ' +
+                    'del repo le rechaza el push a `main` y `develop` (no cubre la web de GitHub).');
+            return;
+        }
+        case 'vercel': {
+            const repo = await repoFrom(rest);
+            const { projectId, teamId } = resolveVercelProject(requireRepoRoot(), {
+                project: readValueFlag(rest, 'project'),
+                team: readValueFlag(rest, 'team'),
+            });
+            const token = await (vercel.token ?? (() => readVercelToken()))();
+            const result = await pruneVercelRelink({ repo, projectId, teamId, token, confirm: rest.includes('--confirm') }, { gh: deps.gh, ...(vercel.fetchImpl ? { fetchImpl: vercel.fetchImpl } : {}) });
+            if (hasBranchDeployRule(requireRepoRoot()) === false) {
+                console.warn(`⚠ \`${VERCEL_JSON}\` no limita los deploys por push: cada rama de un colaborador intentará ` +
+                    'un deploy que Vercel bloquea (autor sin asiento). Agrega y commitea:\n' +
+                    `    "git": { "deploymentEnabled": ${JSON.stringify(BRANCH_DEPLOY_RULE)} }`);
+            }
+            if (result.status === 'already-linked') {
+                console.log(`✔ El proyecto de Vercel ya despliega desde \`${result.link.repo}\`. Nada que hacer.`);
+            }
+            else if (result.status === 'plan') {
+                console.log([
+                    `Plan: el proyecto de Vercel (\`${projectId}\`) despliega desde ` +
+                        `${result.from ? `\`${result.from.repo}\`` : 'ningún repo'}.`,
+                    `  1. Desconectarlo${result.from ? ` de \`${result.from.repo}\`` : ''} (variables, dominios y deploys se quedan).`,
+                    `  2. Conectarlo a \`${result.to}\` y releer el vínculo para confirmarlo.`,
+                    '  No dispara ningún deploy.',
+                    '',
+                    'Para ejecutarlo: `factory prune vercel --confirm`.',
+                ].join('\n'));
+            }
+            else {
+                console.log(`✔ El proyecto de Vercel ahora despliega desde \`${result.to.repo}\`` +
+                    `${result.from ? ` (antes: \`${result.from.repo}\`)` : ''}. ` +
+                    'El primer deploy sale con el siguiente push a `main` (p. ej. un commit vacío).');
+            }
             return;
         }
         case 'finish': {