@timekast/factory 2.5.0 → 2.7.0

package/dist/commands/doctor.js

@@ -10,8 +10,8 @@
  *     are local modifications not yet reconciled via `update`.
  *   - A1 WARNING: a literal security notice (design §1 + §11, decision A1) that
  *     `src/` + boilerplate deps are the derived project's responsibility
- *     post-bootstrap, and that the patch channel for `src/` is EPIC 2 (agentic
- *     update, not yet available).
+ *     post-bootstrap, and that kit fixes for `src/` arrive as retrofit guides
+ *     under `.claude/docs/retrofits/` (shipped by `update`, applied by the agent).
  *   - MISSING INITIAL MIGRATION: a derivative that ships a Drizzle schema and no
  *     generated `.sql`, so the migration step of its deploy — `vercel-build`
  *     (`pnpm build && pnpm db:migrate`) on Vercel, the pre-deploy (`pnpm db:migrate`)
@@ -78,9 +78,9 @@ export const A1_WARNING = 'Aviso de seguridad (A1): el boilerplate `src/` y sus
     'responsabilidad del proyecto derivado a partir de ahí. `factory:update` NO ' +
     'actualiza `src/` ni las dependencias: solo refresca el cerebro (`.claude/`). ' +
     'Un parche de seguridad para `src/` (un CVE en auth, middleware, headers o una ' +
-    'dependencia) NO llega por este canal. El canal de parches de `src/` es EPIC 2 ' +
-    '(update agentico con merge inteligente), aún no disponible. Mantén `src/` y tus ' +
-    'dependencias al día por tu cuenta mientras tanto.';
+    'dependencia) NO llega por este canal. Las correcciones del kit para `src/` llegan ' +
+    'como guías en `.claude/docs/retrofits/`: viajan con `update` y tu agente las aplica. ' +
+    'Mantén `src/` y tus dependencias al día por tu cuenta.';
 /**
  * The literal notice for a derivative whose schema has no generated migration.
  * Named constant (never an inline string — CODING.md §5) and built from the SAME
@@ -261,6 +261,7 @@ export function computeDoctor(deps = {}) {
     if (!hasLockfile(rootDir)) {
         return {
             orphans: [],
+            externalSkills: [],
             conflicts: [],
             formatterDrift: [],
             repoOwned: [],
@@ -285,7 +286,7 @@ export function computeDoctor(deps = {}) {
     const manifestPaths = new Set(lock.files.map((f) => f.path));
     // Orphans: files under `.claude/` on disk that the manifest does not track.
     const claudePaths = collectClaudePaths(rootDir);
-    const orphans = claudePaths.filter((p) => !manifestPaths.has(p)).sort();
+    const { orphans, externalSkills } = splitExternalSkills(claudePaths.filter((p) => !manifestPaths.has(p)).sort(), manifestPaths);
     // Pending conflicts: tracked file whose normalized on-disk hash drifted from
     // the recorded hash (a local modification not yet resolved by `update`).
     const conflicts = [];
@@ -335,6 +336,7 @@ export function computeDoctor(deps = {}) {
     }
     return {
         orphans,
+        externalSkills,
         conflicts,
         formatterDrift,
         repoOwned,
@@ -350,6 +352,37 @@ export function computeDoctor(deps = {}) {
         neonRevokePending,
     };
 }
+const SKILLS_DIR_PREFIX = '.claude/skills/';
+/**
+ * Move out of `orphans` every file that lives in a skill directory the manifest knows nothing
+ * about, and name those directories. A loose file inside a KIT skill directory stays an orphan:
+ * that one is a retired or stray kit file, not someone else's skill.
+ */
+export function splitExternalSkills(allOrphans, manifestPaths) {
+    const skillDirOf = (p) => {
+        if (!p.startsWith(SKILLS_DIR_PREFIX))
+            return null;
+        const rest = p.slice(SKILLS_DIR_PREFIX.length);
+        const slash = rest.indexOf('/');
+        return slash > 0 ? rest.slice(0, slash) : null;
+    };
+    const kitSkillDirs = new Set();
+    for (const p of manifestPaths) {
+        const dir = skillDirOf(p);
+        if (dir)
+            kitSkillDirs.add(dir);
+    }
+    const orphans = [];
+    const external = new Set();
+    for (const p of allOrphans) {
+        const dir = skillDirOf(p);
+        if (dir && !kitSkillDirs.has(dir))
+            external.add(dir);
+        else
+            orphans.push(p);
+    }
+    return { orphans, externalSkills: [...external].sort() };
+}
 /** Render the doctor result to the console. The A1 notice is ALWAYS last. */
 function renderDoctor(result, repoVault) {
     const vaultLines = renderRepoVault(repoVault, { suggestAdopt: result.suggestAdopt });
@@ -410,6 +443,13 @@ function renderDoctor(result, repoVault) {
             }
         }
     }
+    // Skills the kit does not manage (#110): informative, never a problem. Shown whatever the rest says.
+    if (result.externalSkills.length > 0) {
+        console.log('\nSkills que no gestiona el kit (propias del proyecto o add-ons con su instalador):');
+        for (const name of result.externalSkills) {
+            console.log(`  • .claude/skills/${name}/ — no es huérfana: no la borres; \`factory update\` no la toca`);
+        }
+    }
     // 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`):');

package/dist/commands/env.js

@@ -16,11 +16,11 @@ 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 { applyDefaultOverrides, applyWizardAnswers, applyWizardAnswersToVault, buildEnvReview, buildEnvReviewFromEnv, buildQuestionPlan, checkEnvCompleteness, generateVapidKeys, isPublicEnvKey, isQuestionActive, parseEnvBody, parseEnvExample, provisionEmailDefaults, readVaultLocalEnv, readVaultMain, writeSharedToVault, } from '../lib/env-wizard.js';
 import { defaultRail, railTokenRejectedHint, readVercelToken } from '../lib/provision-preflight.js';
-import { readProvisionState, readVaultLink } from '../lib/provision-state.js';
-import { createVaultClient } from '../lib/vault-api.js';
-import { pushEnvPlan, vercelProjectPath, VercelApiError, } from '../lib/vercel-env.js';
+import { readProvisionState, readProvisionTarget, readVaultLink, } from '../lib/provision-state.js';
+import { VAULT_ENV_DEVELOP, VAULT_ENV_MAIN, VAULT_ROOT_PATH, createVaultClient, } from '../lib/vault-api.js';
+import { listEnvVars, pushEnvPlan, readEnvVarsWithValues, upsertEnvVar, vercelProjectPath, VercelApiError, } from '../lib/vercel-env.js';
 // Re-exported so existing importers (and `cli/tests/unit/env-push.test.ts`) keep
 // resolving PROVISION_OWNED from this module after it moved to `lib/env-file.js`.
 export { PROVISION_OWNED };
@@ -519,3 +519,323 @@ async function genVapidIntoVault(vault) {
         console.log('  ℹ️  Revisa VAPID_SUBJECT — puse un placeholder (correo de contacto para push).');
     }
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// `factory env get|set` (PVMCP-003) — read or change ONE public flag of ONE deploy environment.
+//
+// What `/deploy` uses to see whether the questions section is still on in production and, if the
+// developer decides so, turn it off before releasing. Two lists bound it, and both are checked
+// BEFORE any call to the vault, to Vercel or to the rail:
+//   · `get` reads only keys `isPublicEnvKey` accepts — it can never be a secret reader;
+//   · `set` writes only {@link SETTABLE_ENV_KEYS}, and only `true`/`false`. A public key is not
+//     enough for a write: `WEBAUTHN_RP_ID` or `NEXT_PUBLIC_APP_URL` are public and moving them
+//     breaks passkeys or the login, and a free value could carry a `${…}` reference that would
+//     make the vault resolve another secret into a public variable.
+//
+// With the vault it touches ONE location per environment (`main:/` or `develop:/`) through the
+// client's own read/write — never the wizard's shared-value helpers, which write `main:/` and
+// REFERENCE it from `develop:/` (a `set --env develop` must never touch production, and the other
+// way round). Without the vault it goes to Vercel (`main` → production, `develop` → preview);
+// Railway without the vault is refused: its values only arrive through the vault's sync.
+// ─────────────────────────────────────────────────────────────────────────────
+/** The only keys `factory env set` writes (SK.md §7.2: the second allowed writer of these two). */
+export const SETTABLE_ENV_KEYS = ['QUESTIONS_ENABLED', 'MCP_ENABLED'];
+/** The only values `factory env set` writes — literal, case-sensitive. */
+export const SETTABLE_ENV_VALUES = ['true', 'false'];
+/**
+ * Exit codes of `env get|set` — what `/deploy` branches on, never the text. `1` stays the generic
+ * "could not read / could not do it", which is also what an older CLI answers ("Subcomando de env
+ * desconocido"). The others avoid every code the CLI already uses (2 `update --dry-run`, 3 sealed
+ * key of `vault adopt`, 10-12 `provision --resolve-target`, 130 cancelled).
+ */
+export const ENV_GET_SET_EXIT = {
+    ok: 0,
+    error: 1,
+    /** The key does not exist in that environment (the location was read fine). */
+    notFound: 20,
+    /** The key (or, for `set`, the value) is outside what the command accepts. */
+    rejected: 21,
+    /** `get`: in that environment the key is a REFERENCE to another one — not a value of its own. */
+    reference: 22,
+};
+/** A recognized subcommand error with its own exit code. */
+function envGetSetError(message, code) {
+    return new CLIError(message, code);
+}
+export const ENV_GET_SET_USAGE = 'Uso: `factory env get <KEY> --env main|develop` · `factory env set <KEY> <true|false> --env main|develop`.';
+/**
+ * Parse `get <KEY>` / `set <KEY> <VALUE>` + `--env main|develop` (also `--env=…`). A `--help`/`-h`
+ * anywhere short-circuits: nothing else is validated and nothing runs. `--env` has no default —
+ * nobody touches production by omission.
+ *
+ * @throws {CLIError} (exit 1) on a missing/extra argument, an unknown flag or a bad `--env`.
+ */
+export function parseEnvGetSetArgs(argv, sub) {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        return { help: true, key: '', value: '', env: 'main' };
+    }
+    const positional = [];
+    let env;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--env') {
+            env = argv[i + 1];
+            i++;
+            continue;
+        }
+        if (arg.startsWith('--env=')) {
+            env = arg.slice('--env='.length);
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            throw envGetSetError(`Flag desconocido: \`${arg}\`. ${ENV_GET_SET_USAGE}`, ENV_GET_SET_EXIT.error);
+        }
+        positional.push(arg);
+    }
+    const expected = sub === 'get' ? 1 : 2;
+    if (positional.length !== expected) {
+        throw envGetSetError(`\`env ${sub}\` espera ${expected === 1 ? 'una clave' : 'una clave y un valor'}. ${ENV_GET_SET_USAGE}`, ENV_GET_SET_EXIT.error);
+    }
+    if (env === undefined) {
+        throw envGetSetError(`Falta \`--env\` (main o develop): no hay entorno por omisión. ${ENV_GET_SET_USAGE}`, ENV_GET_SET_EXIT.error);
+    }
+    if (env !== 'main' && env !== 'develop') {
+        throw envGetSetError(`\`--env\` acepta \`main\` o \`develop\`, no \`${env}\`.`, ENV_GET_SET_EXIT.error);
+    }
+    return {
+        help: false,
+        key: positional[0],
+        value: sub === 'set' ? positional[1] : '',
+        env,
+    };
+}
+/** `get`'s gate: public keys only. Runs before any call. The rejection names the key, never a value. */
+function assertReadableKey(key) {
+    if (isPublicEnvKey(key))
+        return;
+    throw envGetSetError(`No leo \`${key}\`: \`factory env get\` sólo opera claves públicas (las de public-env-keys.json). ` +
+        'Un secreto se consulta en la bóveda o en el dashboard del despliegue, nunca por este comando.', ENV_GET_SET_EXIT.rejected);
+}
+/** `set`'s gate: its own write list + `true`/`false`. Runs before any call. Never echoes the value. */
+function assertWritable(key, value) {
+    if (!SETTABLE_ENV_KEYS.includes(key)) {
+        throw envGetSetError(`No escribo \`${key}\`: \`factory env set\` sólo cambia ${SETTABLE_ENV_KEYS.map((k) => `\`${k}\``).join(' y ')}. ` +
+            'Otra clave se cambia donde vive (la bóveda, o el dashboard del despliegue sin bóveda).', ENV_GET_SET_EXIT.rejected);
+    }
+    if (!SETTABLE_ENV_VALUES.includes(value)) {
+        throw envGetSetError(`No escribo ese valor en \`${key}\`: \`factory env set\` sólo acepta \`true\` o \`false\` (literal).`, ENV_GET_SET_EXIT.rejected);
+    }
+}
+/** A raw (unexpanded) vault value that is — or contains — a `${…}` reference. */
+const VAULT_REFERENCE_RE = /\$\{[^}]*\}/;
+/** Where a `${env.KEY}` / `${env.folder.KEY}` reference points, for the message; `null` for `${KEY}`. */
+function referencedEnv(raw) {
+    const match = /\$\{([^}]*)\}/.exec(raw);
+    const parts = match?.[1]?.split('.') ?? [];
+    return parts.length >= 2 ? parts[0] : null;
+}
+const VERCEL_TARGET_OF = {
+    main: 'production',
+    develop: 'preview',
+};
+/**
+ * Vault or Vercel — decided the way `env push` and `env wizard` decide it (`readVaultLink`,
+ * fail-closed on a malformed or unreadable state file). Railway without the vault is refused
+ * here, before any call.
+ */
+function routeOf(rootDir) {
+    const link = readVaultLink(rootDir);
+    const target = readProvisionTarget(rootDir);
+    if (link)
+        return { kind: 'vault', link, railway: target === 'railway' };
+    if (target === 'railway') {
+        throw envGetSetError('Este repo despliega en Railway y no tiene bóveda: Railway exige bóveda (sus valores sólo llegan ' +
+            'por el sync de la bóveda), así que no hay a dónde leer ni escribir. Pásalo a la bóveda con ' +
+            '`factory vault adopt` (sin `--apply` sólo enseña el plan). No consulté nada.', ENV_GET_SET_EXIT.error);
+    }
+    return { kind: 'vercel' };
+}
+function vaultLocationOf(env) {
+    return { env: env === 'main' ? VAULT_ENV_MAIN : VAULT_ENV_DEVELOP, path: VAULT_ROOT_PATH };
+}
+/** What a vault read asks for: the raw value of ONE location — never expanded, never imported. */
+const RAW_READ = { expandReferences: false, includeImports: false };
+/** Map a Vercel failure to a value-free CLIError (the response body may quote the request). */
+function vercelFailure(error, operation) {
+    if (error instanceof VercelApiError) {
+        if (error.status === 401) {
+            throw new CLIError(`El \`VERCEL_TOKEN\` del rail es inválido o expiró (Vercel respondió 401 al ${operation}).\n` +
+                railTokenRejectedHint('VERCEL_TOKEN'));
+        }
+        throw new CLIError(`Vercel no respondió bien al ${operation} (status ${error.status}).`);
+    }
+    throw error;
+}
+/** The record of `key` for the whole `target` (not pinned to a git branch), if any. */
+function recordFor(records, key, target) {
+    return records.find((r) => r.key === key && !r.gitBranch && (r.target ?? []).includes(target));
+}
+/** Read the project's values from Vercel; a response without the list is an error, never "absent". */
+async function readVercelValues(rootDir, deps) {
+    const { projectId, teamId } = readProjectLink(rootDir);
+    const token = await readVercelToken(deps.rail ?? defaultRail());
+    const values = await readEnvVarsWithValues(projectId, token, teamId, deps.vercel ?? {});
+    if (values === null) {
+        throw new CLIError('Vercel respondió sin la lista de valores del proyecto: no puedo saber si la clave existe. ' +
+            'Vuelve a intentar; no escribí nada.');
+    }
+    return { projectId, teamId, token, values };
+}
+/**
+ * `factory env get <KEY> --env main|develop` — prints ONLY the value on stdout (for
+ * `$(factory env get …)`). Exit codes: {@link ENV_GET_SET_EXIT}.
+ */
+export async function runEnvGet(argv, rootDir = process.cwd(), deps = {}) {
+    const args = parseEnvGetSetArgs(argv, 'get');
+    if (args.help) {
+        console.log(ENV_GET_SET_USAGE);
+        return;
+    }
+    assertReadableKey(args.key);
+    const route = routeOf(rootDir);
+    const writeOut = deps.writeOut ?? ((text) => process.stdout.write(text));
+    if (route.kind === 'vault') {
+        const client = deps.vaultClient ?? createVaultClient();
+        const location = vaultLocationOf(args.env);
+        const raw = (await client.readSecrets(route.link.projectId, location, RAW_READ)).get(args.key);
+        if (raw === undefined) {
+            throw envGetSetError(`\`${args.key}\` no existe en \`${location.env}:/\` de la bóveda.`, ENV_GET_SET_EXIT.notFound);
+        }
+        if (VAULT_REFERENCE_RE.test(raw)) {
+            // Not a value of its own: print the reference as such and say where the value lives.
+            writeOut(`${raw}\n`);
+            const where = referencedEnv(raw);
+            console.error(`ℹ️  En \`${location.env}:/\` \`${args.key}\` es una referencia, no un valor propio` +
+                (where
+                    ? `: el valor vive en \`${where}\` (\`factory env get ${args.key} --env ${where}\`).`
+                    : '.'));
+            process.exitCode = ENV_GET_SET_EXIT.reference;
+            return;
+        }
+        writeOut(`${raw}\n`);
+        return;
+    }
+    const target = VERCEL_TARGET_OF[args.env];
+    let values;
+    try {
+        ({ values } = await readVercelValues(rootDir, deps));
+    }
+    catch (error) {
+        vercelFailure(error, 'leer los valores del proyecto');
+    }
+    const record = recordFor(values, args.key, target);
+    if (!record) {
+        throw envGetSetError(`\`${args.key}\` no existe en Vercel ${target}.`, ENV_GET_SET_EXIT.notFound);
+    }
+    if (record.value === null) {
+        throw new CLIError(`Vercel no devuelve el valor de \`${args.key}\` en ${target} (tipo ${record.type ?? 'desconocido'}).`);
+    }
+    writeOut(`${record.value}\n`);
+}
+/**
+ * `factory env set <KEY> <true|false> --env main|develop` — writes ONE environment, never the
+ * other. With the vault: one `writeSecrets` on `main:/` or `develop:/` (never a reference, never
+ * the wizard's shared-value path). Without it: Vercel, the requested target only.
+ */
+export async function runEnvSet(argv, rootDir = process.cwd(), deps = {}) {
+    const args = parseEnvGetSetArgs(argv, 'set');
+    if (args.help) {
+        console.log(ENV_GET_SET_USAGE);
+        return;
+    }
+    assertWritable(args.key, args.value);
+    const route = routeOf(rootDir);
+    if (route.kind === 'vault') {
+        const client = deps.vaultClient ?? createVaultClient();
+        const location = vaultLocationOf(args.env);
+        const current = (await client.readSecrets(route.link.projectId, location, RAW_READ)).get(args.key);
+        if (current !== undefined && VAULT_REFERENCE_RE.test(current)) {
+            const where = referencedEnv(current);
+            throw new CLIError(`No cambio \`${args.key}\` en \`${location.env}:/\`: ahí es una referencia` +
+                (where ? ` y el valor vive en \`${where}:/\`` : '') +
+                ', y pisarla en silencio separaría los entornos sin que nadie lo decidiera. ' +
+                (where
+                    ? `Para cambiar el valor compartido: \`factory env set ${args.key} <true|false> --env ${where}\` ` +
+                        '(afecta a los dos entornos). '
+                    : '') +
+                'Para un valor propio de este entorno, reemplaza la referencia en el dashboard de la bóveda.');
+        }
+        // One location, one write — the `develop:/` copy is never a reference to `main:/` here.
+        const result = await client.writeSecrets(route.link.projectId, location, { [args.key]: args.value }, 'upsert');
+        const outcome = result.created.includes(args.key)
+            ? 'creada'
+            : result.updated.includes(args.key)
+                ? 'actualizada'
+                : 'sin cambios';
+        const destination = route.railway
+            ? `Railway \`${args.env}\``
+            : `Vercel ${VERCEL_TARGET_OF[args.env]}`;
+        console.log(`✔ \`${args.key}\` en \`${location.env}:/\` de la bóveda: ${outcome}.`);
+        if (outcome !== 'sin cambios') {
+            const syncs = route.railway ? 'railway' : readVaultVercelSyncStatus(rootDir);
+            console.log(syncs === 'pending'
+                ? `ℹ️  Los syncs de la bóveda hacia Vercel están pendientes: el valor no llega a ${destination} ` +
+                    'hasta que existan (`factory provision --resume`).'
+                : `ℹ️  El sync de la bóveda lo lleva a ${destination}; aplica en el SIGUIENTE deploy ` +
+                    '(el que ya corre no cambia).');
+        }
+        return;
+    }
+    // Without the vault — Vercel, the requested target only; the other target keeps its value.
+    const target = VERCEL_TARGET_OF[args.env];
+    try {
+        const { projectId, teamId, token, values } = await readVercelValues(rootDir, deps);
+        const vercelDeps = deps.vercel ?? {};
+        const withValue = recordFor(values, args.key, target);
+        let outcome;
+        if (withValue && withValue.value === args.value) {
+            outcome = 'sin cambios';
+        }
+        else if (!withValue) {
+            // Nothing covers this target (the other one may have its own record — not touched).
+            await upsertEnvVar(projectId, token, teamId, { key: args.key, value: args.value, target: [target] }, [], vercelDeps);
+            outcome = 'creada';
+        }
+        else {
+            const withId = recordFor((await listEnvVars(projectId, token, teamId, vercelDeps)), args.key, target);
+            if (!withId) {
+                throw new CLIError(`Vercel listó \`${args.key}\` en ${target} con valor pero no con id: no escribo a ciegas. Vuelve a intentar.`);
+            }
+            const others = (withId.target ?? []).filter((t) => t !== target);
+            if (others.length === 0) {
+                // A record of this target alone: update it in place.
+                await upsertEnvVar(projectId, token, teamId, { key: args.key, value: args.value, target: [target] }, [withId], vercelDeps);
+            }
+            else {
+                // A COMBINED record (e.g. production + preview). Re-pointing it whole would drag the other
+                // target along, so it is SPLIT: the record keeps its value for the other target(s), and the
+                // requested target gets a record of its own. Needs the current value to keep it.
+                if (withValue.value === null) {
+                    throw new CLIError(`\`${args.key}\` vive en un solo registro para ${(withId.target ?? []).join(' y ')} y Vercel no ` +
+                        'devuelve su valor, así que no puedo separarlo sin perder el de los otros entornos. Sepáralo en ' +
+                        'el dashboard de Vercel (un registro por entorno) y repite. No escribí nada.');
+                }
+                await upsertEnvVar(projectId, token, teamId, { key: args.key, value: withValue.value, target: others }, [withId], vercelDeps);
+                try {
+                    await upsertEnvVar(projectId, token, teamId, { key: args.key, value: args.value, target: [target] }, [], vercelDeps);
+                }
+                catch (error) {
+                    throw new CLIError(`Separé el registro combinado de \`${args.key}\` (${others.join(', ')} conserva su valor), pero no ` +
+                        `pude crear el de ${target}: ${target} quedó SIN \`${args.key}\`. Repite el mismo comando para crearlo.` +
+                        (error instanceof VercelApiError ? ` (Vercel status ${error.status}.)` : ''));
+                }
+            }
+            outcome = 'actualizada';
+        }
+        console.log(`✔ \`${args.key}\` en Vercel ${target}: ${outcome}.`);
+        if (outcome !== 'sin cambios')
+            console.log(REDEPLOY_NOTICE);
+    }
+    catch (error) {
+        vercelFailure(error, `escribir \`${args.key}\` en ${target}`);
+    }
+}

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
@@ -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,20 +1407,23 @@ 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));
@@ -1459,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) {
@@ -2070,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.
  *
@@ -2078,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(),
@@ -2099,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),
@@ -3008,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).
@@ -3029,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 {
@@ -3629,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 });
@@ -4874,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) {
@@ -5034,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
@@ -8185,7 +8378,7 @@ export async function provisionRailway(rootDir, state, deps) {
     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/AUTH_URL, before any sync.
-    await writeRuntimeToVault(rootDir, state, vault, existingProvisionDomains(projectName, state.dns), rail, fetchImpl);
+    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.
@@ -8938,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,
@@ -8966,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;
@@ -9006,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;
     }
@@ -9039,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
@@ -9235,10 +9441,31 @@ export async function runProvision(flags, deps = {}) {
             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) {

package/dist/commands/update.js

@@ -57,6 +57,7 @@ import { printProvisionPointer } from '../lib/provision-pointer.js';
 import { planPruneMaintenance } from '../lib/prune-update.js';
 import { isRestricted, PRUNE_MARKER_PATH } from '../lib/prune-tiers.js';
 import { printRetrofitReminder } from '../lib/retrofit-reminder.js';
+import { printWhatsNew } from '../lib/whats-new.js';
 import { hasProvisionState } from '../lib/provision-state.js';
 import { loginCommand } from '../lib/rail.js';
 import { resolveBrainRoot } from '../lib/repo-detection.js';
@@ -1017,6 +1018,10 @@ export async function runUpdate(flags, deps = {}) {
         // `oldLock.version` is the version BEFORE this update, which is what separates the guides
         // that just arrived from the ones that were already sitting there. A legacy repo carries
         // `0.0.0`, so every guide reads as new — correct: it has seen none of them.
+        // What changed first, then what still needs hands: the headlines of every kit release
+        // this update crossed, from the changelog that just arrived. Same reasons as the reminder
+        // for printing on every outcome and headless.
+        printWhatsNew({ rootDir, fromVersion: oldLock.version });
         printRetrofitReminder({ rootDir, fromVersion: oldLock.version, guiSignal: flags.launcher });
         await maybeOfferEmptyE2EBranch(rootDir, flags);
         // End-pointer to the next step (PVSKILL-002). Reached only after a clean apply;

package/dist/index.js

@@ -13,7 +13,7 @@ import { CLIError } from './lib/cli-error.js';
 import { resolveSuccessExitCode } from './lib/exit-code.js';
 import { parseAddFlags, runAdd } from './commands/add.js';
 import { parseBacklogPushFlags, parseBacklogSyncFlags, runBacklogPush, runBacklogSync, } from './commands/backlog.js';
-import { parseEnvPushFlags, parseEnvWizardFlags, runEnvPush, runEnvWizardApply, runEnvWizardGenVapid, runEnvWizardPlan, runEnvWizardReview, } from './commands/env.js';
+import { parseEnvPushFlags, parseEnvWizardFlags, runEnvGet, runEnvPush, runEnvSet, runEnvWizardApply, runEnvWizardGenVapid, runEnvWizardPlan, runEnvWizardReview, } from './commands/env.js';
 import { parseInviteAdminFlags, runInviteAdmin } from './commands/invite-admin.js';
 import { envWizardFlow } from './tui/env-wizard-flow.js';
 import { parseDoctorFlags, runDoctor, runLauncherDoctor } from './commands/doctor.js';
@@ -54,7 +54,8 @@ Comandos:
   backlog <sub>    push: refleja el backlog local en backlog.timekast.mx · sync: status + self-healing
   ticket <sub>     push: entrega un factory-ticket de project/factory/ al repo del Factory
   env <sub>        push: sube product vars a Vercel (day-2) · wizard: configura las variables
-                   (en la bóveda si el repo la tiene; sin bóveda, en .env.local)
+                   (en la bóveda si el repo la tiene; sin bóveda, en .env.local) · get/set:
+                   lee o cambia un flag público de UN entorno (main|develop)
   invite-admin     Crea una invitación de super_admin para un derivado (sin password en texto plano)
   prune <sub>      Comparte el repo con colaboradores externos sin la metodología (lo guía /prune):
                    prepare: aplica el tier (.gitignore + .timekast/prune.json) y deja de trackear
@@ -142,6 +143,9 @@ Sobre \`provision\`:
                      completo (revoca la vigente, sube los 3 secrets de E2E y la
                      reescribe en develop:/ci de la bóveda — sin bóveda, en .env.local).
                      Para una key revocada por fuera
+    --mcp            El proyecto lleva servidor MCP: prende MCP_ENABLED y escribe .mcp.json
+                     (una entrada a producción, en su propio commit). Queda guardado: un
+                     --resume no necesita repetirlo
     --domain=<dom>   Dominio definitivo del cliente (diferible; standalone o inicial)
     --dns=<ruta>     Ruta DNS para --domain: org (default) | cliente-cf | registrar
     --verify-timeout=<min>  Timeout del sondeo de verificación de Vercel (default 10)
@@ -196,6 +200,16 @@ Sobre \`env\`:
                      \`--push\` no aplica: los despliegues las reciben de la bóveda)
     --review [--json] Resumen enmascarado (con bóveda: del entorno \`local\`)
     --gen-vapid      Genera las llaves VAPID (con bóveda, se guardan ahí; la privada no se imprime)
+  \`env get <KEY> --env main|develop\` imprime en stdout SOLO el valor de una clave pública
+  (public-env-keys.json; un secreto se rechaza antes de consultar nada). \`env set <KEY>
+  <true|false> --env main|develop\` cambia SOLO QUESTIONS_ENABLED o MCP_ENABLED, y sólo a
+  true/false, en ese entorno y nada más. \`--env\` es obligatorio (sin default). Con bóveda
+  operan main:/ o develop:/ (el sync lleva el valor; aplica en el siguiente deploy); sin
+  bóveda, Vercel (main → production, develop → preview; el otro target conserva su valor);
+  Railway sin bóveda se rechaza (\`factory vault adopt\`). Sin prompts. Salida:
+    0  ok · 1  no se pudo leer/escribir (o un CLI viejo que no conoce get/set) ·
+    20 la clave no existe en ese entorno · 21 clave (o valor de set) rechazado ·
+    22 (get) en ese entorno la clave es una referencia a otro, no un valor propio
 
 Sobre \`backlog\`:
   \`backlog push\` refleja el backlog local (\`project/backlog/*\`) en
@@ -435,8 +449,17 @@ async function main(argv) {
                 await envWizardFlow();
                 return;
             }
+            // `factory env get|set` (PVMCP-003) — one public flag of one deploy environment.
+            if (sub === 'get') {
+                await runEnvGet(rest.slice(1));
+                return;
+            }
+            if (sub === 'set') {
+                await runEnvSet(rest.slice(1));
+                return;
+            }
             throw new CLIError(`Subcomando de env desconocido: \`${sub ?? '(ninguno)'}\`. ` +
-                'Uso: `factory env push` o `factory env wizard`.');
+                'Uso: `factory env push`, `factory env wizard`, `factory env get` o `factory env set`.');
         }
         case 'vault': {
             // `factory vault adopt [--apply]` (ADOPT-001) — move a repo born before the vault into it.

package/dist/lib/env-file.js

@@ -51,6 +51,10 @@ export const PROVISION_OWNED = new Set([
     // both; provision writes them per-derivative to the gitignored `.env.local`.
     'BACKLOG_API_KEY',
     'BACKLOG_PROJECT_ID',
+    // Per-env feature flags (PVMCP-001): they differ by environment — `/deploy` turns the
+    // questions section off in production only — so only provision (and `env set`) writes them.
+    'MCP_ENABLED',
+    'QUESTIONS_ENABLED',
 ]);
 /**
  * The LOCAL-ONLY subset of {@link PROVISION_OWNED}: keys that must NEVER land in a vault folder

package/dist/lib/env-wizard.js

@@ -224,7 +224,7 @@ export function applyWizardAnswers(rootDir, answers) {
  *    their suffix looks like (`NEXT_PUBLIC_AUTH_PASSWORD` is a boolean feature flag).
  *  - `RATE_LIMIT_` is a growing FAMILY of tuning numbers; a derivative that adds
  *    `RATE_LIMIT_CHECKOUT_REQUESTS` should not have to edit a list to see its value.
- * The 22 explicit keys ARE judgement, one name at a time — which is why they are
+ * The explicit keys ARE judgement, one name at a time — which is why they are
  * enumerated instead of matched.
  */
 export function isPublicEnvKey(key) {

package/dist/lib/public-env-keys.json

@@ -13,10 +13,12 @@
         "EMAIL_SERVER_PORT",
         "EMAIL_SERVER_SECURE",
         "EMAIL_SERVER_USER",
+        "MCP_ENABLED",
         "MFA_ENABLED",
         "MFA_REQUIRED_ALL",
         "NEXTAUTH_URL",
         "NODE_ENV",
+        "QUESTIONS_ENABLED",
         "SENTRY_ORG",
         "SENTRY_PROJECT",
         "SUPPORT_EMAIL",

package/dist/lib/vercel-env.js

@@ -849,6 +849,14 @@ export function buildEnvPlan(input) {
         { key: 'NEXT_PUBLIC_APP_URL', value: `https://${input.prodHost}`, target: ['production'] },
         { key: 'NEXT_PUBLIC_APP_URL', value: `https://${input.previewHost}`, target: ['preview'] },
     ];
+    // Per-env feature flags (PVMCP-001) — one record PER TARGET, like NEXT_PUBLIC_APP_ENV, so a later
+    // change in one target (`/deploy` turns questions off in production) never drags the other.
+    // Without MCP, `MCP_ENABLED` is not written at all: absent means off.
+    const flags = ['QUESTIONS_ENABLED', ...(input.mcp ? ['MCP_ENABLED'] : [])];
+    for (const key of flags) {
+        plan.push({ key, value: 'true', target: ['production'] });
+        plan.push({ key, value: 'true', target: ['preview'] });
+    }
     for (const [key, value] of Object.entries(input.shared ?? {})) {
         if (!value)
             continue; // skip empty shared values

package/dist/lib/whats-new.js

@@ -0,0 +1,123 @@
+/**
+ * The "what's new" block printed after every applied `factory update`.
+ *
+ * WHY IT EXISTS. A version number tells the dev that something changed, not what. The kit's
+ * changelog already travels with the brain (`.claude/docs/CHANGELOG.md`, tracked), but nobody
+ * opens it after an update: the dev reads "✔ v14.0.0" and moves on without knowing the kit
+ * now has a client-questions section or a new rule they are expected to follow. This block
+ * puts the headline of every release they just crossed in front of them, before the retrofit
+ * reminder — first what changed, then what still needs hands.
+ *
+ * Read from disk AFTER the apply, like the retrofit reminder: the changelog that just arrived
+ * is the source, never a list baked into this binary. Headless too — an agent running the
+ * update is the reader who has to relay it to the dev.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { compareVersions } from './retrofit-reminder.js';
+/** Where the kit's changelog lives inside the derivative. */
+export const KIT_CHANGELOG = '.claude/docs/CHANGELOG.md';
+/** Releases shown in full; older ones crossed by the same update collapse into one line. */
+export const MAX_RELEASES = 5;
+/** Headlines shown per release; the rest collapse into "+N más". */
+export const MAX_ITEMS_PER_RELEASE = 8;
+/** How much of a headline survives — enough to understand, short enough to scan. */
+const ITEM_MAX = 110;
+/** `## [13.6.0] - 2026-10-14 — Title` → version + title. `[Unreleased]` and junk → null. */
+function parseHeading(line) {
+    const match = line.match(/^##\s+\[(\d+\.\d+\.\d+)\]\s*(.*)$/);
+    if (!match)
+        return null;
+    const rest = match[2];
+    const dash = rest.indexOf('—');
+    const title = dash === -1 ? null : rest.slice(dash + 1).trim() || null;
+    return { version: match[1], title };
+}
+/** Markdown inline marks out: the block is plain terminal text. */
+function plain(text) {
+    return text
+        .replace(/\*\*/g, '')
+        .replace(/`/g, '')
+        .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/** A bullet's headline: its leading bold span, else its first sentence. Capped. */
+export function headline(bullet) {
+    const body = bullet.replace(/^-\s+/, '');
+    const bold = body.match(/^\*\*(.+?)\*\*/);
+    let text = plain(bold ? bold[1] : (body.match(/^(.+?[.!?])(\s|$)/)?.[1] ?? body));
+    text = text.replace(/[.:]$/, '');
+    return text.length > ITEM_MAX ? `${text.slice(0, ITEM_MAX - 1)}…` : text;
+}
+/**
+ * Every numbered release in the changelog, newest first, with its top-level bullets.
+ * Sub-bullets, `###` group headings and prose are skipped: the headline is the bullet itself.
+ */
+export function parseChangelog(markdown) {
+    const releases = [];
+    let current = null;
+    for (const line of markdown.split('\n')) {
+        if (line.startsWith('## ')) {
+            const heading = parseHeading(line);
+            current = heading ? { ...heading, items: [] } : null;
+            if (current)
+                releases.push(current);
+            continue;
+        }
+        if (current && /^-\s+\S/.test(line))
+            current.items.push(headline(line));
+    }
+    return releases.sort((a, b) => compareVersions(b.version, a.version));
+}
+/**
+ * The releases this update crossed: newer than `fromVersion`. Without a `fromVersion` (first
+ * install) there is nothing to compare against and the block stays silent — "everything is
+ * new" helps nobody. A legacy `0.0.0` lockfile crosses every release, and the cap handles it.
+ */
+export function releasesSince(releases, fromVersion) {
+    if (!fromVersion)
+        return [];
+    return releases.filter((r) => compareVersions(r.version, fromVersion) > 0);
+}
+/** Render the block, or `null` when the update crossed no documented release. */
+export function renderWhatsNew(crossed) {
+    if (crossed.length === 0)
+        return null;
+    const rule = '═'.repeat(74);
+    const lines = ['', rule, '  ✨  NOVEDADES DEL KIT EN ESTE UPDATE', rule, ''];
+    for (const release of crossed.slice(0, MAX_RELEASES)) {
+        lines.push(`  ▸ v${release.version}${release.title ? ` — ${release.title}` : ''}`, '');
+        for (const item of release.items.slice(0, MAX_ITEMS_PER_RELEASE))
+            lines.push(`    · ${item}`);
+        const extra = release.items.length - MAX_ITEMS_PER_RELEASE;
+        if (extra > 0)
+            lines.push(`    · +${extra} más`);
+        lines.push('');
+    }
+    const older = crossed.length - MAX_RELEASES;
+    if (older > 0) {
+        const oldest = crossed[crossed.length - 1].version;
+        lines.push(`  ▸ Y ${older} versión(es) anteriores, hasta v${oldest}.`, '');
+    }
+    lines.push(`  El detalle de cada punto está en ${KIT_CHANGELOG}.`, '  Si trabajas con un agente, pídele que te explique qué cambia para tu proyecto.', rule, '');
+    return lines.join('\n');
+}
+/**
+ * Print the block. A missing or unreadable changelog prints nothing — a `core` derivative may
+ * not carry it, and a notice must never break the update that already succeeded.
+ */
+export function printWhatsNew(opts) {
+    const readFile = opts.readFile ?? ((file) => readFileSync(file, 'utf8'));
+    const log = opts.log ?? ((m) => console.log(m));
+    let markdown;
+    try {
+        markdown = readFile(join(opts.rootDir, KIT_CHANGELOG));
+    }
+    catch {
+        return;
+    }
+    const rendered = renderWhatsNew(releasesSince(parseChangelog(markdown), opts.fromVersion));
+    if (rendered)
+        log(rendered);
+}

package/package.json

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