@timekast/factory 2.4.0 → 2.6.0

package/dist/commands/provision.js

@@ -255,6 +255,7 @@ export function parseProvisionFlags(argv) {
         repo: parseRepoFlag(readValueFlag(argv, 'repo')),
         domain,
         clientMail,
+        mcp: argv.includes('--mcp'),
         dns: parseDnsRoute(readValueFlag(argv, 'dns')),
         verifyTimeout: parseVerifyTimeout(readValueFlag(argv, 'verify-timeout')),
         confirm: argv.includes('--confirm'),
@@ -296,6 +297,17 @@ function buildPlan(services, state, opts = {}) {
             : {}),
     }));
 }
+/**
+ * PVMCP-002 — the `--dry-run` line of the project's `.mcp.json`: the file and the URL its entry
+ * would carry, never written. With a `--domain` in the same run, the URL moves to the client's
+ * domain only if it goes `live`.
+ */
+function printMcpJsonPlan(plan, clientDomain) {
+    console.log(`  ＋ ${plan.file} (servidor MCP del proyecto, commit propio): ${plan.url}` +
+        (clientDomain
+            ? ` — pasa a https://${clientDomain}${MCP_SERVER_PATH} si el dominio queda live`
+            : ''));
+}
 /** Print the plain-text plan (the `--dry-run` and pre-run narration). */
 /**
  * `plan` — before anything runs (`--dry-run`): what WOULD be created. `summary` — the closing
@@ -332,7 +344,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)`);
         }
@@ -537,6 +549,8 @@ export function readCloudflareApiKey(rail = defaultRail()) {
  * `context` names the step that failed so the dev knows where the run stopped.
  */
 function neonErrorToCliError(error, projectName, context) {
+    // A full org is the common quota hit, and another org the key reaches is the way out.
+    const otherOrgHint = 'Si la org llegó a su tope de proyectos, créalo en otra que alcance la key: `--neon-org "<nombre>"`.';
     switch (error.status) {
         case 401:
             return new CLIError(`El \`NEON_API_KEY\` del rail es inválido o expiró (Neon respondió 401 en ${context}).\n` +
@@ -544,12 +558,14 @@ function neonErrorToCliError(error, projectName, context) {
         case 402:
         case 429:
             return new CLIError(`Neon rechazó la operación por cuota/facturación (respondió ${error.status} en ${context}).\n` +
-                'Revisa el plan/cuota de proyectos Neon de la org y reintenta con `--resume`.');
+                'Revisa el plan/cuota de proyectos Neon de la org y reintenta con `--resume`.\n' +
+                otherOrgHint);
         case 409:
             return new CLIError(`Ya existe un proyecto Neon con un nombre que choca con \`${projectName}\` (Neon respondió 409 en ${context}).\n` +
                 'Usa `--force` para descartar el estado y empezar de cero con otro nombre, o elimina el proyecto previo.');
         default:
-            return new CLIError(`Falló la llamada a Neon en ${context}: ${error.message}`);
+            return new CLIError(`Falló la llamada a Neon en ${context}: ${error.message}` +
+                (/project.*limit|limit.*project/i.test(error.message) ? `\n${otherOrgHint}` : ''));
     }
 }
 /**
@@ -1358,12 +1374,22 @@ const VAULT_LOCAL_SHARED_REFS = [
  * preview each got an independent `AUTH_SECRET`; the vault keeps it.
  */
 const VAULT_PER_ENV_MINTED = ['AUTH_SECRET'];
+/**
+ * The per-environment feature flags (PVMCP-001): `main:/` and `develop:/` each hold their OWN
+ * value — never a reference, which would make them shared — because `/deploy` turns the questions
+ * section off in production only. `local` references develop's, like {@link VAULT_PER_ENV_MINTED}.
+ * `QUESTIONS_ENABLED` is born on; `MCP_ENABLED` exists only with MCP (absent = off, and an absent
+ * key is what lets a later `--mcp --resume` turn it on under `create-if-missing`).
+ */
+export function perEnvFlagsFor(opts = {}) {
+    return { QUESTIONS_ENABLED: 'true', ...(opts.mcp ? { MCP_ENABLED: 'true' } : {}) };
+}
 /**
  * The vault plan for a run (names only — `--dry-run`, `--json`, and the pre-run narration).
  * Which keys each destination gets depends on the services the run includes: `neon` writes the
  * connection strings and the CI keys, `vercel` the runtime values, `backlog` its local creds.
  */
-export function buildVaultPlan(projectName, services, target) {
+export function buildVaultPlan(projectName, services, target, opts = {}) {
     const keys = {};
     const references = {};
     const add = (loc, names, asRef = false) => {
@@ -1381,24 +1407,29 @@ export function buildVaultPlan(projectName, services, target) {
     }
     // RWAY-004: the `railway` step writes the same runtime values the `vercel` step does.
     if (services.includes('vercel') || services.includes('railway')) {
+        const flags = Object.keys(perEnvFlagsFor(opts));
         add(VAULT_MAIN_ROOT, [
             ...VAULT_PER_ENV_MINTED,
             ...VAULT_SHARED_KEYS,
             'NEXT_PUBLIC_APP_URL',
             'NEXT_PUBLIC_APP_ENV',
+            ...flags,
         ]);
         add(VAULT_DEVELOP_ROOT, [
             ...VAULT_PER_ENV_MINTED,
             'NEXT_PUBLIC_APP_URL',
             'NEXT_PUBLIC_APP_ENV',
+            ...flags,
         ]);
         add(VAULT_DEVELOP_ROOT, [...VAULT_SHARED_KEYS], true);
         add(VAULT_LOCAL_ROOT, ['NEXT_PUBLIC_APP_URL', 'WEBAUTHN_RP_ID']);
-        add(VAULT_LOCAL_ROOT, [...VAULT_PER_ENV_MINTED, ...VAULT_LOCAL_SHARED_REFS], true);
+        add(VAULT_LOCAL_ROOT, [...VAULT_PER_ENV_MINTED, ...VAULT_LOCAL_SHARED_REFS, ...flags], true);
     }
     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']);
@@ -1457,6 +1488,18 @@ async function vaultWrite(ctx, location, entries, mode) {
         return;
     reportVaultWrite(location, await ctx.client.writeSecrets(ctx.projectId, location, entries, mode));
 }
+/**
+ * Write the per-env feature flags (PVMCP-001): each deploy environment its own value,
+ * `create-if-missing` — a re-run or `--resume` never reverts what `/deploy` or `env set` left
+ * (e.g. production's `QUESTIONS_ENABLED=false`) — and `local` references develop's.
+ * Self-contained on purpose: it is also the write a `--resume` over a finished alta needs.
+ */
+export async function writePerEnvFlagsToVault(ctx, opts = {}) {
+    const flags = perEnvFlagsFor(opts);
+    await vaultWrite(ctx, VAULT_MAIN_ROOT, flags, 'create-if-missing');
+    await vaultWrite(ctx, VAULT_DEVELOP_ROOT, flags, 'create-if-missing');
+    await vaultReference(ctx, VAULT_LOCAL_ROOT, Object.keys(flags), VAULT_DEVELOP_ROOT);
+}
 /** Reference each `keys` from `location` to the same key in `target`, and narrate. */
 async function vaultReference(ctx, location, keys, target) {
     for (const key of keys) {
@@ -2068,6 +2111,9 @@ async function ensureProjectResendKey(rootDir, state, ctx, rail, fetchImpl, pers
  *     `EMAIL_PROVIDER=resend` (without it the runtime defaults to `'none'`: mail OFF in the
  *     deploys) — plus its own `NEXT_PUBLIC_APP_URL`/`_ENV`;
  *   - `develop:/` holds its own `NEXT_PUBLIC_APP_URL`/`_ENV` and REFERENCES the shared ones;
+ *   - `main:/` and `develop:/` each hold their own per-env feature flags (`QUESTIONS_ENABLED`, and
+ *     `MCP_ENABLED` only with `opts.mcp`), which `local` references from develop
+ *     ({@link writePerEnvFlagsToVault});
  *   - `local` holds only the machine's own values (`NEXT_PUBLIC_APP_URL` and `WEBAUTHN_RP_ID` of
  *     localhost) and references the rest.
  *
@@ -2076,7 +2122,7 @@ async function ensureProjectResendKey(rootDir, state, ctx, rail, fetchImpl, pers
  * MFA key would leave every stored TOTP secret unreadable — and never moves a live rpID. The
  * values are READ BACK from `main:/`, so the Vercel push below carries the vault's values.
  */
-async function writeRuntimeToVault(rootDir, state, ctx, hosts, rail, fetchImpl) {
+async function writeRuntimeToVault(rootDir, state, ctx, hosts, rail, fetchImpl, opts = {}) {
     await vaultWrite(ctx, VAULT_MAIN_ROOT, {
         AUTH_SECRET: generateAuthSecret(),
         MFA_ENCRYPTION_KEY: generateMfaEncryptionKey(),
@@ -2097,6 +2143,7 @@ async function writeRuntimeToVault(rootDir, state, ctx, hosts, rail, fetchImpl)
         NEXT_PUBLIC_APP_ENV: 'preview',
     }, 'create-if-missing');
     await vaultReference(ctx, VAULT_DEVELOP_ROOT, sharedKeysFor(VAULT_SHARED_KEYS, Boolean(resendKey)), VAULT_MAIN_ROOT);
+    await writePerEnvFlagsToVault(ctx, opts);
     const local = {
         NEXT_PUBLIC_APP_URL: exampleDefault(rootDir, 'NEXT_PUBLIC_APP_URL', LOCAL_APP_URL_FALLBACK),
         WEBAUTHN_RP_ID: exampleDefault(rootDir, 'WEBAUTHN_RP_ID', LOCAL_RP_ID_FALLBACK),
@@ -3006,7 +3053,9 @@ export async function provisionVercel(rootDir, state, teamId, deps = {}) {
     const fetchImpl = deps.fetchImpl ?? fetch;
     const resendCarrier = deps.resendCarrier ?? {};
     const vaultValues = deps.vault
-        ? await writeRuntimeToVault(rootDir, state, deps.vault, rpDomains, rail, fetchImpl)
+        ? await writeRuntimeToVault(rootDir, state, deps.vault, rpDomains, rail, fetchImpl, {
+            mcp: state.mcp === true,
+        })
         : null;
     // The project's own Resend key — from the vault, or (no vault) minted for this run. The rail's
     // TEAM key only mints: it never reaches a deploy nor `.env.local` (fx-secrets-vault §2).
@@ -3027,6 +3076,7 @@ export async function provisionVercel(rootDir, state, teamId, deps = {}) {
             prodHost: rpDomains.prod,
             previewHost: rpDomains.dev,
             shared: resendKey ? { RESEND_API_KEY: resendKey, EMAIL_PROVIDER: RESEND_EMAIL_PROVIDER } : {},
+            mcp: state.mcp === true,
         });
         let result;
         try {
@@ -3524,23 +3574,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 +3597,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 +3613,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
@@ -3607,22 +3677,161 @@ async function commitAndPushWorkflows(rootDir, runGit) {
  * the full state (all service IDs) is on disk. Best-effort + idempotent: an unchanged
  * state stages nothing → skips.
  */
-async function commitProvisionState(rootDir) {
+async function commitProvisionState(rootDir, runGit = gitInDir) {
     const statePath = join(PROVISION_DIR, PROVISION_STATE_FILE);
     try {
-        await gitInDir(['add', statePath], rootDir);
-        const staged = (await gitInDir(['diff', '--cached', '--name-only'], rootDir)).stdout.trim();
+        await runGit(['add', statePath], rootDir);
+        const staged = (await runGit(['diff', '--cached', '--name-only'], rootDir)).stdout.trim();
         if (!staged)
             return;
-        await gitInDir(['commit', '-m', 'chore: persist provision state'], rootDir);
-        await gitInDir(['push', 'origin', 'main'], rootDir);
-        await gitInDir(['push', 'origin', 'main:develop'], rootDir);
+        await runGit(['commit', '-m', 'chore: persist provision state'], rootDir);
+        await runGit(['push', 'origin', 'main'], rootDir);
+        await runGit(['push', 'origin', 'main:develop'], rootDir);
         console.log('  ↑ .timekast/provision.json commiteado (main + develop)');
     }
     catch {
         // Non-fatal: the local state is intact; the dev can commit it later.
     }
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// PVMCP-002 — `--mcp`: the project's `.mcp.json` (one entry, production only)
+// ─────────────────────────────────────────────────────────────────────────────
+/** Claude Code's project-scope MCP config — what `claude mcp add --scope project` writes. */
+export const MCP_JSON_FILE = '.mcp.json';
+/** The path the boilerplate serves its MCP server on. */
+export const MCP_SERVER_PATH = '/api/mcp';
+/** The subject of the `.mcp.json` commit (English — GIT.md §3.1). */
+export const MCP_JSON_COMMIT = 'chore: declare mcp server';
+/** Does this run treat the project as carrying MCP? The flag, or the decision saved by the alta. */
+export function resolveMcpDecision(flags, state) {
+    return flags.mcp === true || state?.mcp === true;
+}
+/**
+ * The URL of the project's MCP server — ALWAYS production (one entry, decision CP1): the client's
+ * domain once it is `live`, else the interim production host the state records (or derives,
+ * when the alta has no `dns` block yet). Never the develop host; a `pending-verification` client
+ * domain does not count.
+ */
+export function mcpServerUrl(projectName, dns) {
+    const host = dns?.clientDomainStatus === 'live' && dns.clientDomain
+        ? dns.clientDomain
+        : existingProvisionDomains(projectName, dns).prod;
+    return `https://${host}${MCP_SERVER_PATH}`;
+}
+/**
+ * Write (or merge) the project's entry in `.mcp.json`: `mcpServers.<slug> = { type: 'http', url }`.
+ * Every other entry — and any other field of the project's own entry — is kept. A file that is not
+ * a JSON object (or whose `mcpServers` is not one) is NOT touched: one warning naming the manual
+ * action, and the run goes on. An entry that already says the same thing writes nothing.
+ */
+export function writeMcpJson(rootDir, projectName, dns) {
+    const file = join(rootDir, MCP_JSON_FILE);
+    const url = mcpServerUrl(projectName, dns);
+    let doc = {};
+    const existed = existsSync(file);
+    if (existed) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(file, 'utf8'));
+        }
+        catch {
+            parsed = null;
+        }
+        const servers = parsed?.mcpServers;
+        const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+        if (!isObject(parsed) || (servers !== undefined && !isObject(servers))) {
+            console.warn(`⚠ \`${MCP_JSON_FILE}\` existe pero no es un JSON válido con \`mcpServers\` como objeto: no lo toqué. ` +
+                `Agrega a mano, dentro de \`mcpServers\`, la entrada \`${projectName}\` → ` +
+                `{ "type": "http", "url": "${url}" }.`);
+            return 'invalid';
+        }
+        doc = parsed;
+    }
+    const servers = doc.mcpServers ?? {};
+    const current = servers[projectName];
+    if (current && current.type === 'http' && current.url === url)
+        return 'unchanged';
+    const next = {
+        ...doc,
+        mcpServers: { ...servers, [projectName]: { ...(current ?? {}), type: 'http', url } },
+    };
+    writeFileSync(file, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+    if (current) {
+        console.log(`  ↻ ${MCP_JSON_FILE}: el servidor \`${projectName}\` ahora apunta a ${url}`);
+        return 'updated';
+    }
+    console.log(`  ＋ ${MCP_JSON_FILE}: servidor \`${projectName}\` → ${url}` +
+        (existed ? ' (las demás entradas se conservan)' : ''));
+    return existed ? 'updated' : 'created';
+}
+/**
+ * Commit `.mcp.json` in its OWN commit (after the state's) and push it to `main` and `develop`, the
+ * way {@link commitProvisionState} does. By pathspec (GIT.md §3.6.1): `git add` first only when the
+ * file is new (a pathspec cannot reach an untracked file), and nothing else of the index can slip
+ * in. Never `--no-verify`. A file git already holds unchanged → no commit. Best-effort: a git
+ * failure never fails the provisioning — it is narrated and the file stays written.
+ */
+export async function commitMcpJson(rootDir, runGit = gitInDir) {
+    if (!existsSync(join(rootDir, MCP_JSON_FILE)))
+        return 'absent';
+    try {
+        const tracked = (await runGit(['ls-files', '--', MCP_JSON_FILE], rootDir)).stdout.trim();
+        if (tracked) {
+            const pending = (await runGit(['status', '--porcelain', '--', MCP_JSON_FILE], rootDir)).stdout.trim();
+            if (!pending)
+                return 'unchanged';
+        }
+        else {
+            await runGit(['add', MCP_JSON_FILE], rootDir);
+        }
+        await runGit(['commit', '-m', MCP_JSON_COMMIT, '--', MCP_JSON_FILE], rootDir);
+        await runGit(['push', 'origin', 'main'], rootDir);
+        await runGit(['push', 'origin', 'main:develop'], rootDir);
+        console.log(`  ↑ ${MCP_JSON_FILE} commiteado (main + develop)`);
+        return 'committed';
+    }
+    catch (error) {
+        console.warn(`⚠ No pude commitear o pushear \`${MCP_JSON_FILE}\` (${error?.message ?? 'error de git'}): ` +
+            'el archivo quedó escrito en el repo. Commitéalo a mano o repite con `--resume`.');
+        return 'failed';
+    }
+}
+/**
+ * `--mcp` over an alta that is ALREADY complete (its `vercel`/`railway` step is skipped, so the step
+ * that writes the flags never runs): turn `MCP_ENABLED` on here. Never reverts a value someone set:
+ *   · with a vault → {@link writePerEnvFlagsToVault} (`create-if-missing` in `main:/` and
+ *     `develop:/`; `local` references develop's) — its syncs carry it to the deploys;
+ *   · without one, destination Vercel → one record per target (production, preview), created only
+ *     where the key is missing;
+ *   · Railway without a vault does not exist (Railway requires the vault).
+ */
+export async function ensureMcpFlagsOnFinishedAlta(state, deps) {
+    if (deps.vault) {
+        await writePerEnvFlagsToVault(deps.vault, { mcp: true });
+        return;
+    }
+    // A repo in the vault whose run has no vault client: the deploys belong to the syncs.
+    if (state.vault !== undefined || state.target === 'railway')
+        return;
+    const projectId = state.vercel?.projectId;
+    if (!projectId || !deps.teamId) {
+        console.warn('⚠ No prendí `MCP_ENABLED` en Vercel: falta el proyecto de Vercel o el team en esta corrida. ' +
+            'Repite con `--resume --mcp` cuando el paso `vercel` esté hecho.');
+        return;
+    }
+    const token = await readVercelToken(deps.rail ?? defaultRail());
+    const vercelDeps = provisionVercelApiDeps(deps.fetchImpl, { vault: null, state });
+    const existing = await listEnvVarNames(projectId, token, deps.teamId, vercelDeps);
+    for (const target of ['production', 'preview']) {
+        const has = existing.some((env) => env.key === 'MCP_ENABLED' && env.target.includes(target));
+        if (has) {
+            console.log(`  = Vercel MCP_ENABLED [${target}] (ya estaba — no lo toco)`);
+            continue;
+        }
+        await upsertEnvVar(projectId, token, deps.teamId, { key: 'MCP_ENABLED', value: 'true', target: [target] }, [], vercelDeps);
+        console.log(`  ＋ Vercel MCP_ENABLED [${target}]`);
+    }
+}
 /** Default `pnpm db:generate` runner — `execa` in the derived dir, no shell. */
 async function drizzleGenerate(cwd) {
     await execa('pnpm', ['db:generate'], { cwd });
@@ -4852,6 +5061,9 @@ export async function provisionClientDomain(rootDir, state, teamId, domain, deps
         clientDomainStatus: 'live',
     }, clientMail);
     writeProvisionState(rootDir, state);
+    // PVMCP-002 — the MCP entry follows production to the client's domain (committed by the run).
+    if (state.mcp === true)
+        writeMcpJson(rootDir, state.projectName, state.dns);
 }
 /** RWAY-005 — the two records the owner creates by hand for `--dns=registrar` on Railway. */
 function printRailwayManualRecords(dns) {
@@ -5012,6 +5224,9 @@ async function provisionRailwayClientDomain(rootDir, state, domain, deps) {
     // 7. Live.
     state.dns = withMailChoice({ ...dnsBlock(), clientDomainStatus: 'live' }, clientMail);
     writeProvisionState(rootDir, state);
+    // PVMCP-002 — the MCP entry follows production to the client's domain (committed by the run).
+    if (state.mcp === true)
+        writeMcpJson(rootDir, state.projectName, state.dns);
 }
 /**
  * Retire the interim prod domain (`{slug}.timekast.mx`) AFTER the client domain
@@ -5149,7 +5364,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 +7826,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 +7845,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 +8370,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.
-    await writeRuntimeToVault(rootDir, state, vault, existingProvisionDomains(projectName, state.dns), rail, fetchImpl);
+    // 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, { mcp: state.mcp === true });
     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 = [];
@@ -8892,6 +9131,11 @@ export async function runProvision(flags, deps = {}) {
         ? await resolveRepoSlug(rootDir, projectName, state?.github?.repo, flags.repo, gitInDir)
         : undefined;
     const steps = buildPlan(flags.services, state, { remint: flags.remint });
+    // PVMCP-002 — MCP: the flag, or the decision the alta saved (a `--resume` need not repeat it).
+    const mcp = resolveMcpDecision(flags, state);
+    // Whether the step that writes the per-env flags had ALREADY finished before this run: then it
+    // does not run again (skip, or Railway's early return on `done`), and `--mcp` needs its own write.
+    const flagsStepDoneBefore = target === 'railway' ? state?.railway?.done === true : isServiceComplete(state, 'vercel');
     const result = {
         projectName,
         lifecycle: state?.lifecycle ?? lifecycle,
@@ -8920,7 +9164,10 @@ export async function runProvision(flags, deps = {}) {
         };
     }
     if (flags.services.includes('vault')) {
-        result.vault = buildVaultPlan(projectName, flags.services, target);
+        result.vault = buildVaultPlan(projectName, flags.services, target, { mcp });
+    }
+    if (mcp) {
+        result.mcpJson = { file: MCP_JSON_FILE, url: mcpServerUrl(projectName, state?.dns) };
     }
     if (vaultDecision.skipped) {
         result.vaultSkipped = vaultDecision.skipped;
@@ -8960,6 +9207,8 @@ export async function runProvision(flags, deps = {}) {
                 const dev = onRailway && !hasRailwayKitDomain(state, 'develop') ? undefined : hosts.dev;
                 printClientDomainPlan(flags.domain, { interim, dev }, flags.dns, flags.confirm, target, flags.clientMail === true);
             }
+            if (result.mcpJson)
+                printMcpJsonPlan(result.mcpJson, hasDomain ? flags.domain : undefined);
         }
         return result;
     }
@@ -8993,6 +9242,9 @@ export async function runProvision(flags, deps = {}) {
     // RWAY-003 — the destination goes with the state (the `--force` restart keeps the saved one).
     if (target)
         runState.target = target;
+    // PVMCP-002 — the MCP decision goes with the state too, before any step reads it.
+    if (mcp)
+        runState.mcp = true;
     // BOOT-001: record the resolved repo BEFORE the steps run, so the Neon E2E-secret
     // push (`neonSecretRepo`, which runs before the github step) targets the resolved
     // repo — not the historical `${FACTORY_ORG}/${projectName}` fallback. Never
@@ -9177,10 +9429,43 @@ 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,
+        });
+    }
+    // 5b.2. PVMCP-002 — `--mcp` over an alta whose flags step had already finished: that step does not
+    //       run again, so `MCP_ENABLED` is turned on here (create-if-missing — never reverts a value).
+    if (mcp && flagsStepDoneBefore) {
+        await ensureMcpFlagsOnFinishedAlta(runState, {
+            vault: runCtx.vault ?? null,
+            teamId: flags.team,
+            rail,
+            fetchImpl: deps.sync?.fetchImpl,
+        });
+    }
+    // 5b.3. PVMCP-002 — the project's `.mcp.json`, after the go-live: a domain that went `live` in
+    //       this same run already gives the client's URL, and one commit covers both.
+    const mcpJson = mcp && !remintOverAdopted ? writeMcpJson(rootDir, projectName, runState.dns) : null;
     // 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.
+    //     The `.mcp.json` follows in its OWN commit, under the same condition.
+    const runGit = deps.runGit ?? gitInDir;
     if (runState.github?.done) {
-        await commitProvisionState(rootDir);
+        await commitProvisionState(rootDir, runGit);
+        if (mcpJson && mcpJson !== 'invalid')
+            await commitMcpJson(rootDir, runGit);
+    }
+    else if (mcpJson && mcpJson !== 'invalid') {
+        console.log(`  · ${MCP_JSON_FILE} quedó escrito sin commit: el repo todavía no tiene su sustrato de git ` +
+            '(paso `github`). Se commitea en la corrida que lo cree.');
     }
     // 6. Report.
     if (flags.json) {