@timekast/factory 2.3.1 → 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

@@ -44,6 +44,7 @@ import { RAIL_TIMEKAST, RailError, RailKeyMissingError } from '../lib/rail.js';
 import { classifyDeploymentState, connectedProjects, createRailwayClient, RailwayApiError, RailwayNameTakenError, RAILWAY_SERVICE_NAME, sameRepo as sameRailwayRepo, } from '../lib/railway-api.js';
 import { isRailwayProvided, isRailwaySyncTo, railwaySyncDifferences, railwaySyncLabel, railwaySyncName, } from '../lib/vault-adopt.js';
 import { createVaultClient, formatLocation, VAULT_CI_PATH, VAULT_ENV_DEVELOP, VAULT_ENV_LOCAL, VAULT_ENV_MAIN, VAULT_LAYOUT_ENVIRONMENTS, VAULT_ROOT_PATH, VAULT_TEST_ISOLATION_KEY, } from '../lib/vault-api.js';
+import { readValueFlag } from '../lib/flags.js';
 import { wireVaultWrapper } from '../lib/wrapper-wiring.js';
 /**
  * The THREE GitHub Secrets the E2E runner (`pnpm test:e2e` → `e2e-runner.ts` +
@@ -143,20 +144,6 @@ const KNOWN_DNS_ROUTES = ['org', 'cliente-cf', 'registrar'];
 /** Default verification-poll timeout (minutes) and interval (seconds) — issue §4. */
 export const DEFAULT_VERIFY_TIMEOUT_MIN = 10;
 export const VERIFY_POLL_INTERVAL_SEC = 30;
-/** Read the value of a `--key=value` or `--key value` flag from an argv slice. */
-function readValueFlag(argv, name) {
-    const prefix = `--${name}=`;
-    const inline = argv.find((arg) => arg.startsWith(prefix));
-    if (inline)
-        return inline.slice(prefix.length);
-    const idx = argv.indexOf(`--${name}`);
-    if (idx !== -1) {
-        const next = argv[idx + 1];
-        if (next && !next.startsWith('-'))
-            return next;
-    }
-    return undefined;
-}
 /**
  * Parse `--services=a,b,c` into the typed service list, rejecting unknown tokens
  * with a `CLIError` (a typo must not silently provision nothing). An empty/absent
@@ -345,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)`);
         }
@@ -1412,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']);
@@ -3537,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
@@ -3574,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)');
@@ -3585,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
@@ -5162,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
@@ -7623,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
@@ -7633,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;
@@ -8149,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 = [];
@@ -9190,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) {