@timekast/factory 1.12.0 → 1.14.2

package/dist/commands/provision.js

@@ -0,0 +1,2487 @@
+/**
+ * `factory provision` — scaffold of the derived-project onboarding command (PROV-001).
+ *
+ * This issue ships ONLY the command skeleton: flag dispatch, the atomic state
+ * model (`provision-state.ts`), and the fail-closed preflight
+ * (`provision-preflight.ts`). The REAL resource creation lives in later issues —
+ * Neon (PROV-002), Vercel/GitHub (PROV-003/004), DNS+Resend (PROV-005) — so each
+ * service step here is a CLEAR stub that those issues fill in. The command is
+ * already wired end-to-end (flags → preflight → resumable per-step state) so the
+ * next issues only drop their REST call into the marked stub.
+ *
+ * Headless / flag-driven contract: NO interactive prompts (the interactivity is
+ * EPIC-17's `tk-provision` skill + `/provision`). Every input is a flag; `--json`
+ * emits a machine-readable result; `--dry-run` prints the plan and mutates
+ * nothing (no REST, no state write); without tokens it degrades cleanly via the
+ * preflight's typed errors.
+ *
+ * All expected failures throw `CLIError` / `PreflightError` — never a raw
+ * `throw new Error()` — so the top-level handler in `index.ts` prints a clean,
+ * actionable line and exits with the right code.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { execa } from 'execa';
+import prompts from 'prompts';
+import { FACTORY_ORG } from '../lib/constants.js';
+import { CLIError } from '../lib/cli-error.js';
+import { apexZoneOf, CloudflareApiError, CLOUDFLARE_API_BASE, ensureCnameRecord, findCnameRecord, resolveZoneId, resolveZoneIdForName, CNAME_VERCEL_TARGET, TIMEKAST_ZONE_NAME, provisionDomains, } from '../lib/cloudflare-api.js';
+import { createDevelopBranch, createNeonProject, createProjectApiKey, deleteNeonApiKeysByName, deleteNeonProject, getConnectionUri, listNeonBranches, listNeonProjects, NeonApiError, NEON_API_BASE, NEON_DEVELOP_BRANCH, } from '../lib/neon-api.js';
+import { defaultEnvPath, readVercelToken, runProvisionPreflight, } from '../lib/provision-preflight.js';
+import { addVercelDomain, buildEnvPlan, createVercelProject, generateAuthSecret, getLinkedRepoId, getVercelDomainStatus, GitHubAppNotInstalledError, linkGitRepo, listVercelProjects, patchProjectSettings, pushEnvPlan, removeVercelDomain, triggerDeployment, upsertEnvVar, listEnvVars, VercelApiError, writeVercelProjectJson, } from '../lib/vercel-env.js';
+import { adoptState, ADOPT_UNKNOWN, clearProvisionState, clearState, hasProvisionState, isServiceComplete, PROVISION_DIR, PROVISION_STATE_FILE, readDestroyTarget, readProvisionState, writeProvisionState, } from '../lib/provision-state.js';
+/**
+ * The THREE GitHub Secrets the E2E runner (`pnpm test:e2e` → `e2e-runner.ts` +
+ * `setup:e2e`) reads to create an ISOLATED Neon branch per CI run. provision sets
+ * all three so a provisioned repo runs E2E with zero manual `setup:e2e`:
+ *   - NEON_API_KEY    — the project-scoped key (creates/deletes the per-run branch)
+ *   - NEON_PROJECT_ID — the Neon project the per-run branch is created under
+ *   - DATABASE_URL    — the (non-prod develop) connection string the runner falls
+ *     back to before it swaps in the per-run branch's own connection.
+ * Names MUST match what `e2e.yml` reads — a mismatch silently breaks CI E2E.
+ */
+export const NEON_KEY_SECRET = 'NEON_API_KEY';
+export const NEON_PROJECT_ID_SECRET = 'NEON_PROJECT_ID';
+export const E2E_DATABASE_URL_SECRET = 'DATABASE_URL';
+/**
+ * The label of the DEDICATED transactional-mail subdomain. Resend sends from
+ * `${MAIL_SUBDOMAIN}.<base>` — NEVER the apex `<base>`, which holds the org's (or a
+ * client's) corporate MX/SPF (Google Workspace, M365, …). Verifying Resend on the
+ * apex would collide with that mail; an isolated subdomain keeps both working. Same
+ * convention for the org (`updates.timekast.mx`) and every client (`updates.<client>`).
+ */
+export const MAIL_SUBDOMAIN = 'updates';
+/** Build the transactional-mail domain for a base domain: `updates.<base>`. */
+export function mailDomainFor(base) {
+    return `${MAIL_SUBDOMAIN}.${base}`;
+}
+/**
+ * The canonical, ORG-LEVEL sender for transactional mail on provisioned stacks
+ * (issue §4 + §5). Sends from `noreply@updates.timekast.mx` — the dedicated subdomain
+ * verified in Resend, NOT the apex `timekast.mx` (which is on Google Workspace). The
+ * client's own sender is set in the `--domain` flow (PROV-006), using the same
+ * `updates.<client>` convention. The unit test pins this value.
+ */
+export const PROVISION_EMAIL_FROM = `noreply@${mailDomainFor(TIMEKAST_ZONE_NAME)}`;
+// `provisionDomains` moved to `cloudflare-api.ts` (next to TIMEKAST_ZONE_NAME) so
+// `provision-state.ts`'s `--destroy` target can re-derive the dev domain from the
+// slug without a circular import. Re-exported here to keep the public surface (and
+// the existing `provision-slug` test import) stable.
+export { provisionDomains };
+/**
+ * Validate a slug as a DNS subdomain label BEFORE any REST call (issue §8). A
+ * label may contain only lowercase letters, digits and hyphens, may not start or
+ * end with a hyphen, and is ≤63 chars (the DNS label limit, with margin for the
+ * `-dev` suffix). An invalid slug (e.g. an underscore, uppercase, a leading dot)
+ * is rejected with a clear `CLIError` so no malformed domain ever reaches Vercel
+ * or Cloudflare.
+ *
+ * @throws {CLIError} when the slug cannot be a valid subdomain label.
+ */
+export function assertValidSubdomainSlug(slug) {
+    if (!isValidSubdomainSlug(slug)) {
+        throw new CLIError(`El slug \`${slug}\` no es un subdominio válido para \`${TIMEKAST_ZONE_NAME}\`.\n` +
+            'Usa solo minúsculas, dígitos y guiones (sin guion al inicio/fin, sin guion bajo ni puntos, ≤59 chars).');
+    }
+}
+/**
+ * Predicate form of {@link assertValidSubdomainSlug} — `true` when `slug` is a
+ * valid DNS subdomain label (lowercase/digits/hyphens, no leading/trailing hyphen,
+ * ≤59 chars so `-dev` fits the 63-char label limit). Used to GUARD a low-trust
+ * slug read from the state file before it reaches a shell command (FIX 2), without
+ * throwing — the caller skips + reports a malformed value instead.
+ */
+export function isValidSubdomainSlug(slug) {
+    // A leading `-` is excluded by the regex anchor, but check explicitly too so the
+    // intent (anti flag-smuggling) is unmistakable.
+    if (slug.length === 0 || slug.length > 59 || slug.startsWith('-'))
+        return false;
+    return /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(slug);
+}
+/**
+ * The services `--services` understands, in canonical provisioning order. `github`
+ * precedes `vercel`: PROV-004 (the `github` step) builds the git substrate AND
+ * creates the Vercel PROJECT, whose `projectId` PROV-003 (the `vercel` env-sync
+ * step) then consumes. The order is normalized regardless of `--services` input.
+ */
+const KNOWN_SERVICES = ['neon', 'github', 'vercel', 'dns'];
+/** The known `--dns` route tokens, for validation. */
+const KNOWN_DNS_ROUTES = ['org', 'cliente-cf', 'registrar'];
+/** Default verification-poll timeout (minutes) and interval (seconds) — issue §4. */
+export const DEFAULT_VERIFY_TIMEOUT_MIN = 10;
+export const VERIFY_POLL_INTERVAL_SEC = 30;
+/** Read the value of a `--key=value` or `--key value` flag from an argv slice. */
+function readValueFlag(argv, name) {
+    const prefix = `--${name}=`;
+    const inline = argv.find((arg) => arg.startsWith(prefix));
+    if (inline)
+        return inline.slice(prefix.length);
+    const idx = argv.indexOf(`--${name}`);
+    if (idx !== -1) {
+        const next = argv[idx + 1];
+        if (next && !next.startsWith('-'))
+            return next;
+    }
+    return undefined;
+}
+/**
+ * Parse `--services=a,b,c` into the typed service list, rejecting unknown tokens
+ * with a `CLIError` (a typo must not silently provision nothing). An empty/absent
+ * flag yields an empty list — the command turns that into a "nothing to do" error
+ * so the failure is explicit.
+ */
+export function parseServices(raw) {
+    if (!raw)
+        return [];
+    const tokens = raw
+        .split(',')
+        .map((t) => t.trim())
+        .filter(Boolean);
+    const services = [];
+    for (const token of tokens) {
+        if (!KNOWN_SERVICES.includes(token)) {
+            throw new CLIError(`Servicio desconocido en \`--services\`: \`${token}\`. ` +
+                `Válidos: ${KNOWN_SERVICES.join(', ')}.`);
+        }
+        const service = token;
+        if (!services.includes(service))
+            services.push(service);
+    }
+    // Normalize to canonical provisioning order regardless of input order.
+    return KNOWN_SERVICES.filter((s) => services.includes(s));
+}
+/**
+ * Parse `--dns=<route>` into a typed {@link DnsRoute}, defaulting to `org` when
+ * absent and rejecting an unknown token with a `CLIError` (a typo must not silently
+ * pick the wrong route — `--dns=registar` would skip CNAME creation by accident).
+ */
+export function parseDnsRoute(raw) {
+    if (!raw)
+        return 'org';
+    const token = raw.trim();
+    if (!KNOWN_DNS_ROUTES.includes(token)) {
+        throw new CLIError(`Ruta de DNS desconocida en \`--dns\`: \`${token}\`. ` +
+            `Válidas: ${KNOWN_DNS_ROUTES.join(', ')}.`);
+    }
+    return token;
+}
+/**
+ * Parse `--verify-timeout=<min>` into a positive integer of MINUTES, defaulting to
+ * {@link DEFAULT_VERIFY_TIMEOUT_MIN}. A non-numeric or non-positive value is a
+ * `CLIError` (a `0`/negative timeout would never poll).
+ */
+export function parseVerifyTimeout(raw) {
+    if (raw === undefined)
+        return DEFAULT_VERIFY_TIMEOUT_MIN;
+    const minutes = Number(raw);
+    if (!Number.isFinite(minutes) || !Number.isInteger(minutes) || minutes <= 0) {
+        throw new CLIError(`\`--verify-timeout\` debe ser un entero positivo de minutos (recibí \`${raw}\`).`);
+    }
+    return minutes;
+}
+/** Parse `provision`'s argv slice into typed flags. */
+export function parseProvisionFlags(argv) {
+    return {
+        services: parseServices(readValueFlag(argv, 'services')),
+        team: readValueFlag(argv, 'team'),
+        orgId: readValueFlag(argv, 'org-id'),
+        slug: readValueFlag(argv, 'slug'),
+        domain: readValueFlag(argv, 'domain'),
+        dns: parseDnsRoute(readValueFlag(argv, 'dns')),
+        verifyTimeout: parseVerifyTimeout(readValueFlag(argv, 'verify-timeout')),
+        confirm: argv.includes('--confirm'),
+        dryRun: argv.includes('--dry-run'),
+        ephemeral: argv.includes('--ephemeral'),
+        resume: argv.includes('--resume'),
+        force: argv.includes('--force'),
+        json: argv.includes('--json'),
+        adopt: argv.includes('--adopt'),
+        destroy: argv.includes('--destroy'),
+    };
+}
+/** Human label for a service (es-MX), for the plain-text plan. */
+const SERVICE_LABEL = {
+    neon: 'Neon (proyecto + branch develop)',
+    vercel: 'Vercel (env sync por target)',
+    github: 'GitHub + Vercel (sustrato git + proyecto + env + E2E)',
+    dns: 'DNS + Resend (dominio del entorno)',
+};
+/** Build the ordered plan: each requested service is `skip` if complete, else `create`. */
+function buildPlan(services, state) {
+    return services.map((service) => ({
+        service,
+        action: isServiceComplete(state, service) ? 'skip' : 'create',
+    }));
+}
+/** Print the plain-text plan (the `--dry-run` and pre-run narration). */
+function printPlan(result) {
+    console.log(`Plan de provision para \`${result.projectName}\` (lifecycle: ${result.lifecycle}):`);
+    for (const step of result.steps) {
+        const mark = step.action === 'skip' ? '⏭  (ya completado)' : '＋ crear';
+        console.log(`  ${mark}  ${SERVICE_LABEL[step.service]}`);
+        // For the DNS step, list the EXACT domains + records the run would create
+        // (issue §4 AC: `--dry-run` lists the two domains and the two DNS records).
+        if (step.service === 'dns' && step.action === 'create') {
+            const { dev, prod } = provisionDomains(result.projectName);
+            console.log(`        · Vercel dominio  ${dev}  (gitBranch: develop)`);
+            console.log(`        · Vercel dominio  ${prod}  (producción)`);
+            console.log(`        · Cloudflare CNAME ${dev}  → cname.vercel-dns.com (proxied:false)`);
+            console.log(`        · Cloudflare CNAME ${prod}  → cname.vercel-dns.com (proxied:false)`);
+            console.log(`        · Resend env: RESEND_API_KEY [production, preview] + EMAIL_FROM=${PROVISION_EMAIL_FROM}`);
+        }
+    }
+    if (result.dryRun) {
+        console.log('\n(`--dry-run`) No se ejecutó ninguna llamada a API ni se escribió estado.');
+    }
+}
+/**
+ * Derive the project name for the state. Until a `--name` flag exists (out of
+ * scope here — the interactive layer supplies it, EPIC-17), default to the
+ * `--org-id`/`--team` scope or a placeholder so the scaffold has a stable key.
+ */
+function deriveProjectName(flags, rootDir) {
+    // `--slug` is the canonical stack identifier (drives domains + resource names);
+    // it wins over the dir name. Validate it as a subdomain label when given,
+    // since it flows into `{slug}.timekast.mx` downstream (PROV-005).
+    if (flags.slug) {
+        const slug = flags.slug.toLowerCase(); // every resource is lowercase (repo/dir/domains)
+        assertValidSubdomainSlug(slug);
+        return slug;
+    }
+    // No `--slug`: the project name is the directory provision runs in (the scaffold
+    // dir), NOT the org/team scope. A team id like `team_ldqH...` is neither a real
+    // project name nor a valid subdomain, and falling back to it produced a confusing
+    // `repo TimeKast/team_ldqH... no existe` error. Validate it like an explicit slug.
+    // Lowercased so a dir created with mixed case (e.g. `Edmond/`) yields a valid slug
+    // instead of being rejected for the uppercase — matches the `new` normalization.
+    const fromDir = basename(rootDir).toLowerCase();
+    assertValidSubdomainSlug(fromDir);
+    return fromDir;
+}
+/**
+ * Read the VALUE of `NEON_API_KEY` (the shared org key) from the rail
+ * (`~/.claude/.env`). Mirrors `readVercelToken`: split on the FIRST `=`, strip a
+ * single matched pair of surrounding quotes, return `null` when absent. This is
+ * the ONE place the org key VALUE is read; it is handed straight to the Neon
+ * `Authorization` header and never logged.
+ */
+export function readNeonApiKey(envPath = defaultEnvPath()) {
+    if (!existsSync(envPath))
+        return null;
+    let text;
+    try {
+        text = readFileSync(envPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    for (const line of text.split('\n')) {
+        const trimmed = line.trimStart();
+        if (trimmed === '' || trimmed.startsWith('#'))
+            continue;
+        const eq = line.indexOf('=');
+        if (eq === -1)
+            continue;
+        if (line.slice(0, eq).trim() !== 'NEON_API_KEY')
+            continue;
+        let value = line.slice(eq + 1).replace(/\s+$/, '');
+        if (value.length >= 2 &&
+            ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'")))) {
+            value = value.slice(1, -1);
+        }
+        return value === '' ? null : value;
+    }
+    return null;
+}
+/**
+ * Read the VALUE of a single rail key from the rail (`~/.claude/.env`), with the
+ * same first-`=` split + matched-quote strip as {@link readNeonApiKey} /
+ * `readVercelToken`. Returns `null` when the file or the key is absent/empty. The
+ * value is handed straight to an `Authorization` header by the caller and never
+ * logged (no-echo). Centralized so the Cloudflare token reader does not become a
+ * fourth copy of the same parse loop.
+ */
+function readGateValue(key, envPath) {
+    if (!existsSync(envPath))
+        return null;
+    let text;
+    try {
+        text = readFileSync(envPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    for (const line of text.split('\n')) {
+        const trimmed = line.trimStart();
+        if (trimmed === '' || trimmed.startsWith('#'))
+            continue;
+        const eq = line.indexOf('=');
+        if (eq === -1)
+            continue;
+        if (line.slice(0, eq).trim() !== key)
+            continue;
+        let value = line.slice(eq + 1).replace(/\s+$/, '');
+        if (value.length >= 2 &&
+            ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'")))) {
+            value = value.slice(1, -1);
+        }
+        return value === '' ? null : value;
+    }
+    return null;
+}
+/**
+ * Read the VALUE of `CLOUDFLARE_API_TOKEN` (the shared org zone-scoped DNS-edit token)
+ * from the rail. This is the ONE place the Cloudflare token VALUE is read; it is
+ * handed straight to the Cloudflare `Authorization` header and never logged.
+ */
+export function readCloudflareApiKey(envPath = defaultEnvPath()) {
+    return readGateValue('CLOUDFLARE_API_TOKEN', envPath);
+}
+/**
+ * Map a Neon REST failure to an actionable, es-MX `CLIError` (issue §8 edges).
+ * `context` names the step that failed so the dev knows where the run stopped.
+ */
+function neonErrorToCliError(error, projectName, context) {
+    switch (error.status) {
+        case 401:
+            return new CLIError(`El \`NEON_API_KEY\` del archivo de secretos es inválido o expiró (Neon respondió 401 en ${context}).\n` +
+                'Ejecuta `factory secrets <archivo>` para renovarlo y reintenta con `--resume`.');
+        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`.');
+        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}`);
+    }
+}
+/** The GitHub repo (`owner/name`) the project-scoped secret is pushed to. */
+function neonSecretRepo(state) {
+    // PROV-004 records the created repo in `state.github.repo`; before it runs we
+    // fall back to the canonical `org/projectName` so the secret push is attempted
+    // (a non-existent repo → §8 pending path, never an abort).
+    return state.github?.repo ?? `${FACTORY_ORG}/${state.projectName}`;
+}
+/**
+ * Push a GitHub Secret. `gh secret set` reads the VALUE from STDIN when `--body`
+ * is omitted (no-echo: the value never lands in argv / the process list / a log —
+ * same discipline as `secrets.ts`). NOTE: `gh secret set` has NO `--body-file`
+ * flag (only `--body`/`--env-file`); passing one makes gh exit 1 ("unknown flag"),
+ * which silently failed every secret push before — stdin is the correct seam.
+ */
+async function setGithubSecret(key, value, repo) {
+    await execa('gh', ['secret', 'set', key, '--repo', repo], { input: value });
+}
+/**
+ * PROV-002 — provision Neon: create the project (its primary branch = production
+ * `main`), create a CLEAN `develop` branch, read POOLED connection strings for
+ * both, mint a PROJECT-SCOPED API key, and store the E2E GitHub Secrets
+ * (NEON_API_KEY + NEON_PROJECT_ID + DATABASE_URL) so CI E2E works with zero manual
+ * `setup:e2e`. State is written ATOMICALLY after the project create and again
+ * after `develop`, so a mid-step failure leaves a resumable partial state
+ * (issue §6 + §8 Gherkin).
+ *
+ * Endpoint order (asserted by the unit test): POST /projects → POST branches
+ * (develop) → GET connection_uri (main) → GET connection_uri (develop) →
+ * POST /api_keys → `gh secret set`.
+ *
+ * `--resume` short-circuits ENTIRELY when `state.neon.projectId` already exists
+ * (caller skips the step via `isServiceComplete`; this is a defensive guard too).
+ *
+ * @throws {CLIError} mapping the Neon §8 edges (401/402/409/429) and a `develop`
+ *   failure (state saved partial → resumable). A failed `gh secret set` does NOT
+ *   abort: it records `apiKeySecretPending` and reports (issue §8).
+ */
+export async function provisionNeon(rootDir, state, deps = {}) {
+    // Fully complete only when the FINAL step landed (key minted + stored as the GH
+    // secret). developBranchId alone is NOT "done": re-entering must finish the
+    // remaining steps WITHOUT re-minting the key. Every sub-step below is idempotent.
+    if (state.neon?.apiKeySecretDone)
+        return;
+    const envPath = deps.envPath ?? defaultEnvPath();
+    const apiKey = readNeonApiKey(envPath);
+    if (!apiKey) {
+        throw new CLIError('No se pudo leer `NEON_API_KEY` de `~/.claude/.env`.\n' +
+            'Ejecuta `factory secrets <archivo>` para bajar la key del archivo de secretos y reintenta.');
+    }
+    const setSecret = deps.setSecret ?? setGithubSecret;
+    const apiDeps = { fetchImpl: deps.fetchImpl };
+    // Neon org-id from the rail (`NEON_ORGANIZATION_ID`), like the Vercel team-id —
+    // org-fixed config, not hardcoded. Neon REQUIRES it for org-scoped API keys.
+    const orgId = readGateValue('NEON_ORGANIZATION_ID', envPath) ?? undefined;
+    // 1. Reuse the project from a partial run; create it only if missing. Persist it
+    //    immediately so a branch failure leaves projectId + mainBranchId durable.
+    let projectId;
+    let mainBranchId;
+    if (state.neon?.projectId && state.neon?.mainBranchId) {
+        projectId = state.neon.projectId;
+        mainBranchId = state.neon.mainBranchId;
+    }
+    else {
+        let project;
+        try {
+            project = await createNeonProject(apiKey, state.projectName, orgId, apiDeps);
+        }
+        catch (error) {
+            if (error instanceof NeonApiError) {
+                throw neonErrorToCliError(error, state.projectName, 'crear el proyecto');
+            }
+            throw error;
+        }
+        projectId = project.projectId;
+        mainBranchId = project.mainBranchId;
+        state.neon = { projectId, mainBranchId, developBranchId: '' };
+        writeProvisionState(rootDir, state);
+    }
+    // 2. CLEAN `develop` branch — reuse the recorded id; else create it (idempotent
+    //    on a 409: createDevelopBranch reuses an existing develop) and persist the id
+    //    IMMEDIATELY (FIX 6 — it was saved only at step 3, so a connection-string
+    //    failure lost it and the resume re-created → 409).
+    let developBranchId = state.neon?.developBranchId ?? '';
+    if (!developBranchId) {
+        try {
+            developBranchId = await createDevelopBranch(apiKey, projectId, mainBranchId, apiDeps);
+        }
+        catch (error) {
+            // Save the partial state (issue §8 Gherkin: "guarda el state parcial").
+            // IDs only — never a connection string (those are re-derived from Neon on demand).
+            state.neon = { projectId, mainBranchId, developBranchId: '' };
+            writeProvisionState(rootDir, state);
+            if (error instanceof NeonApiError) {
+                throw new CLIError(`El proyecto Neon se creó pero falló la creación del branch \`develop\` (${error.message}).\n` +
+                    'El estado parcial se guardó; reintenta con `--resume` para crear solo el branch develop.');
+            }
+            throw error;
+        }
+        state.neon = { projectId, mainBranchId, developBranchId };
+        writeProvisionState(rootDir, state);
+    }
+    // 3. Read the develop branch's POOLED connection string (idempotent GET) — the
+    //    ONLY string this step needs, for the E2E `DATABASE_URL` secret below. provision
+    //    writes NO credentials file: the runtime/.env.local/migrate strings are
+    //    re-derived on demand from Neon by their own steps (`resolveNeonSecrets`), since
+    //    Neon is the source of truth.
+    let developDatabaseUrl;
+    try {
+        developDatabaseUrl = await getConnectionUri(apiKey, projectId, developBranchId, true, apiDeps);
+    }
+    catch (error) {
+        if (error instanceof NeonApiError) {
+            throw neonErrorToCliError(error, state.projectName, 'leer el connection string del branch develop');
+        }
+        throw error;
+    }
+    // 4. Mint a PROJECT-SCOPED API key (blast radius = this project only). Only the
+    //    `apiKeySecretDone` guard above prevents re-minting; a resume after a pending
+    //    secret push DOES re-mint (the prior key value was never persisted — it is a
+    //    credential) and the old key is left orphaned. Acceptable: it only happens
+    //    when the GH secret push keeps failing (e.g. the repo does not exist yet).
+    let projectKey;
+    try {
+        projectKey = await createProjectApiKey(apiKey, projectId, `${state.projectName}-e2e`, apiDeps);
+    }
+    catch (error) {
+        if (error instanceof NeonApiError) {
+            throw neonErrorToCliError(error, state.projectName, 'crear la API key project-scoped');
+        }
+        throw error;
+    }
+    // 5. Store the THREE GitHub Secrets the E2E runner needs (NEON_API_KEY +
+    //    NEON_PROJECT_ID + DATABASE_URL) so `pnpm test:e2e` works in CI with zero
+    //    manual `setup:e2e`. On success mark Neon done so a resume short-circuits
+    //    (and never re-mints). A failure is NON-fatal (issue §8): the repo may not
+    //    exist yet — record pending and report; a `--resume` retries once it does.
+    try {
+        const repo = neonSecretRepo(state);
+        await setSecret(NEON_KEY_SECRET, projectKey, repo);
+        await setSecret(NEON_PROJECT_ID_SECRET, projectId, repo);
+        await setSecret(E2E_DATABASE_URL_SECRET, developDatabaseUrl, repo);
+        state.neon = { projectId, mainBranchId, developBranchId, apiKeySecretDone: true };
+        writeProvisionState(rootDir, state);
+    }
+    catch {
+        state.neon = { projectId, mainBranchId, developBranchId, apiKeySecretPending: true };
+        writeProvisionState(rootDir, state);
+        console.warn(`⚠ No se pudieron guardar los secrets de E2E ` +
+            `(\`${NEON_KEY_SECRET}\`/\`${NEON_PROJECT_ID_SECRET}\`/\`${E2E_DATABASE_URL_SECRET}\`) ` +
+            `en \`${neonSecretRepo(state)}\` (¿el repo no existe aún o falta permiso?).\n` +
+            '  La API key project-scoped se creó; reintenta con `--resume` cuando el repo exista.');
+    }
+}
+/**
+ * Resolve the four pooled+direct Neon connection strings, ALWAYS by re-deriving
+ * fresh from Neon — provision persists NO credentials file (Neon is the source of
+ * truth). Uses the rail `NEON_API_KEY` + the branch ids in the committed state.
+ * Returns `null` only when the key or the branch ids are missing, so the caller can
+ * raise an actionable error.
+ *
+ * The re-derive is the NORMAL path now (not a clone/resume fallback): every
+ * top-level step that needs the strings (vercel env + `.env.local`, migrate secrets)
+ * calls this independently, so a full run re-derives a few times — a handful of fast
+ * GETs, deliberately un-cached (KISS: no ambiguous in-memory cache lifetime).
+ *
+ * `deps` mirrors `provisionVercel`'s injectable seams so the unit test drives the
+ * re-derive with a mock `fetchImpl`.
+ */
+async function resolveNeonSecrets(state, envPath, deps = {}) {
+    const projectId = state.neon?.projectId;
+    const mainBranchId = state.neon?.mainBranchId;
+    const developBranchId = state.neon?.developBranchId;
+    if (!projectId || !mainBranchId || !developBranchId)
+        return null;
+    const apiKey = readNeonApiKey(envPath);
+    if (!apiKey)
+        return null;
+    const apiDeps = { fetchImpl: deps.fetchImpl };
+    // pooled → serverless/concurrent runtime (Vercel app); direct → single-process
+    // migrations + tooling (`.env.local`, CI migrate). See `getConnectionUri`.
+    const mainPooled = await getConnectionUri(apiKey, projectId, mainBranchId, true, apiDeps);
+    const mainDirect = await getConnectionUri(apiKey, projectId, mainBranchId, false, apiDeps);
+    const developPooled = await getConnectionUri(apiKey, projectId, developBranchId, true, apiDeps);
+    const developDirect = await getConnectionUri(apiKey, projectId, developBranchId, false, apiDeps);
+    return { mainPooled, mainDirect, developPooled, developDirect };
+}
+/**
+ * Map a Vercel REST failure to an actionable, es-MX `CLIError` (issue §8 edges).
+ * `context` names what failed so the dev knows where the run stopped.
+ */
+function vercelErrorToCliError(error, teamId, context) {
+    switch (error.status) {
+        case 401:
+            return new CLIError(`El \`VERCEL_TOKEN\` del archivo de secretos es inválido o expiró (Vercel respondió 401 en ${context}).\n` +
+                'Ejecuta `factory secrets <archivo>` para renovarlo y reintenta con `--resume`.');
+        case 403:
+            return new CLIError(`El \`VERCEL_TOKEN\` no tiene acceso al team \`${teamId}\` (Vercel respondió 403 en ${context}).\n` +
+                'Verifica que el token está scopeado al team del org y reintenta con `--resume`.');
+        case 402:
+        case 429:
+            return new CLIError(`Vercel rechazó la operación por cuota/facturación (respondió ${error.status} en ${context}).\n` +
+                'Revisa el plan del team y reintenta con `--resume`.');
+        default:
+            return new CLIError(`Falló la llamada a Vercel en ${context}: ${error.message}`);
+    }
+}
+/** Read the shared, non-environment-specific env values from the rail (no-echo). */
+function readSharedVercelEnv(envPath) {
+    const shared = {};
+    if (!existsSync(envPath))
+        return shared;
+    let text;
+    try {
+        text = readFileSync(envPath, 'utf8');
+    }
+    catch {
+        return shared;
+    }
+    // Shared (cross-environment) keys the provision step propagates when present.
+    const SHARED_KEYS = new Set(['RESEND_API_KEY', 'EMAIL_FROM', 'CLOUDFLARE_API_TOKEN']);
+    for (const line of text.split('\n')) {
+        const trimmed = line.trimStart();
+        if (trimmed === '' || trimmed.startsWith('#'))
+            continue;
+        // First-`=` split (env-merge.ts rule): a value may itself contain `=`.
+        const eq = line.indexOf('=');
+        if (eq === -1)
+            continue;
+        const key = line.slice(0, eq).trim();
+        if (!SHARED_KEYS.has(key))
+            continue;
+        let value = line.slice(eq + 1).replace(/\s+$/, '');
+        if (value.length >= 2 &&
+            ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'")))) {
+            value = value.slice(1, -1);
+        }
+        if (value !== '')
+            shared[key] = value;
+    }
+    return shared;
+}
+/** Default `pnpm install` runner — `execa` in the derived dir, no shell. */
+async function pnpmInstall(cwd) {
+    await execa('pnpm', ['install'], { cwd });
+}
+/**
+ * PROV-003 — sync env into the Vercel project: thread `teamId` on EVERY REST call,
+ * push variables PER TARGET (production vs preview), mint an INDEPENDENT
+ * `AUTH_SECRET` per environment, write `.vercel/project.json` (WITHOUT `vercel
+ * link`/`pull`), and `pnpm install` the derived dir.
+ *
+ * Requires `state.neon` (the pooled connection strings) and `state.vercel.projectId`
+ * — the project itself is created by PROV-004. When `projectId` is absent, this
+ * throws a clear `CLIError` telling the dev to run the Vercel project create first.
+ *
+ * No-echo: secret VALUES never reach stdout — only KEY NAMES + targets are printed.
+ */
+export async function provisionVercel(rootDir, state, teamId, deps = {}) {
+    const projectId = state.vercel?.projectId;
+    if (!projectId) {
+        throw new CLIError('Falta el `projectId` de Vercel en el estado: el proyecto Vercel lo crea PROV-004.\n' +
+            'Corre el paso de creación del proyecto Vercel primero, luego reintenta con `--resume`.');
+    }
+    const envPath = deps.envPath ?? defaultEnvPath();
+    const token = readVercelToken(envPath);
+    if (!token) {
+        throw new CLIError('No se pudo leer `VERCEL_TOKEN` de `~/.claude/.env`.\n' +
+            'Ejecuta `factory secrets <archivo>` para bajar el token del archivo de secretos y reintenta.');
+    }
+    // Re-derive the Neon connection strings fresh from Neon (provision keeps NO
+    // credentials file — Neon is the source of truth). Returns null only when the rail
+    // key or the branch ids are missing.
+    let neonSecrets;
+    try {
+        neonSecrets = await resolveNeonSecrets(state, envPath, { fetchImpl: deps.fetchImpl });
+    }
+    catch (error) {
+        if (error instanceof NeonApiError) {
+            throw neonErrorToCliError(error, state.projectName, 're-derivar los connection strings de Neon');
+        }
+        throw error;
+    }
+    if (!neonSecrets) {
+        throw new CLIError('No se pudieron re-derivar los connection strings de Neon: aprovisiona Neon primero ' +
+            '(`--services=neon,...`) con `NEON_API_KEY` en el rail y reintenta con `--resume`.');
+    }
+    // Write the project link FIRST (no vercel link/pull) so downstream steps and a
+    // `--resume` can read `{ projectId, orgId, teamId }` even if the push fails.
+    writeVercelProjectJson(rootDir, { projectId, orgId: teamId, teamId }, { force: deps.force });
+    // Mint an INDEPENDENT AUTH_SECRET per environment (issue §4 — never shared).
+    // POOLED strings → the Vercel runtime DATABASE_URL (serverless/concurrent).
+    const plan = buildEnvPlan({
+        mainDatabaseUrl: neonSecrets.mainPooled,
+        developDatabaseUrl: neonSecrets.developPooled,
+        authSecretProd: generateAuthSecret(),
+        authSecretPreview: generateAuthSecret(),
+        shared: readSharedVercelEnv(envPath),
+    });
+    let result;
+    try {
+        result = await pushEnvPlan(projectId, token, teamId, plan, { fetchImpl: deps.fetchImpl });
+    }
+    catch (error) {
+        if (error instanceof VercelApiError) {
+            throw vercelErrorToCliError(error, teamId, 'sincronizar las variables de entorno');
+        }
+        throw error;
+    }
+    // Record the Vercel state with envSynced — the env push (this step) is done, so a
+    // resume short-circuits here. `projectId` was set by the github step (PROV-004).
+    state.vercel = { projectId, envSynced: true };
+    writeProvisionState(rootDir, state);
+    // No-echo: print only KEY NAMES + targets, never the values.
+    for (const v of result.created) {
+        console.log(`  ＋ ${v.key} [${v.target.join(', ')}]`);
+    }
+    for (const v of result.updated) {
+        console.log(`  ↻ ${v.key} [${v.target.join(', ')}]`);
+    }
+    // Generate the gitignored `.env.local` so the dev can run the app, migrations and
+    // seeds locally (`pnpm dev`/`db:migrate`/`db:seed:admin` read `.env.local`). Uses
+    // the DIRECT strings (single-process tooling/migrations, never the pooler).
+    // DATABASE_URL → develop (safe default), DATABASE_URL_MAIN → main (db:query:main).
+    const envLocal = writeEnvLocal(rootDir, neonSecrets, { force: deps.force });
+    if (envLocal === 'written') {
+        console.log('  ＋ .env.local (DATABASE_URL=develop · DATABASE_URL_MAIN=main · AUTH_SECRET)');
+    }
+    else if (envLocal === 'skipped') {
+        console.log('  ⏭ .env.local ya existía (no se sobrescribe — usa --force para regenerarlo)');
+    }
+    // `pnpm install` the derived dir (issue §4). A missing package.json (non-Node
+    // derivative) is reported, NOT fatal (issue §8).
+    if (existsSync(join(rootDir, 'package.json'))) {
+        const runInstall = deps.runInstall ?? pnpmInstall;
+        try {
+            await runInstall(rootDir);
+        }
+        catch (error) {
+            console.warn(`⚠ \`pnpm install\` falló en el directorio del derivado (${error?.message ?? 'error'}).\n` +
+                '  Las variables de Vercel ya se sincronizaron; corre `pnpm install` a mano y reintenta el deploy.');
+        }
+    }
+    else {
+        console.warn('⚠ No hay `package.json` en el directorio del derivado — omito `pnpm install` ' +
+            '(derivado non-Node). Las variables de Vercel ya se sincronizaron.');
+    }
+    // First deployment. provision links the repo to Vercel AFTER `factory new`/
+    // provision already pushed `main` + `develop`, so Vercel sees no push event and
+    // builds nothing (the project sits at 0 deployments). Fire one production build
+    // (`main`) + one preview build (`develop`) from the git refs — AFTER the env
+    // sync above, so the build has its DATABASE_URL. NON-FATAL and we do NOT wait
+    // for the build: a failure must not abort a provision whose project + env are
+    // already done.
+    try {
+        const repoId = await getLinkedRepoId(projectId, token, teamId, { fetchImpl: deps.fetchImpl });
+        if (repoId === null) {
+            console.warn('⚠ El proyecto Vercel no está ligado a un repo — omito el primer deployment. ' +
+                'Conéctalo y pushea, o redeploya a mano.');
+        }
+        else {
+            await triggerDeployment(token, teamId, { projectId, name: state.projectName, repoId, ref: 'main', production: true }, { fetchImpl: deps.fetchImpl });
+            await triggerDeployment(token, teamId, { projectId, name: state.projectName, repoId, ref: 'develop', production: false }, { fetchImpl: deps.fetchImpl });
+            console.log('  ↑ deployments disparados: main (production) · develop (preview)');
+        }
+    }
+    catch (error) {
+        console.warn(`⚠ No se pudo disparar el primer deployment (${error?.message ?? 'error'}). ` +
+            'El proyecto + las env vars ya están listos; pushea o redeploya a mano.');
+    }
+}
+/**
+ * Generate the gitignored `.env.local` from the derivative's `.env.example`, filling
+ * the two Neon connection strings + a fresh AUTH_SECRET. Without this the dev cannot
+ * run `pnpm dev`/`db:migrate`/`db:seed:admin` locally — those read `.env.local`, which
+ * provision otherwise never creates (it only syncs env to Vercel).
+ *
+ * Uses the DIRECT (non-pooler) strings: `.env.local` drives single-process tooling
+ * (`drizzle-kit migrate`/`generate`, `db:seed`, `db:query`) + local `pnpm dev` — none
+ * of which want the PgBouncer pooler (the pooled host is only for the serverless
+ * runtime on Vercel). Do NOT swap these back to the pooled variants.
+ *
+ * DATABASE_URL → the develop branch (safe default for local work); DATABASE_URL_MAIN
+ * → the main branch (read by `pnpm db:query:main`). NEVER clobbers an existing
+ * `.env.local` (the dev may have edited it) unless `--force`. The `.env.example` stays
+ * the SSOT of which keys exist; the keys are appended if absent (older scaffolds).
+ */
+export function writeEnvLocal(rootDir, neon, opts = {}) {
+    const examplePath = join(rootDir, '.env.example');
+    if (!existsSync(examplePath))
+        return 'no-example';
+    const localPath = join(rootDir, '.env.local');
+    if (existsSync(localPath) && !opts.force)
+        return 'skipped';
+    let body = readFileSync(examplePath, 'utf8');
+    body = setEnvLine(body, 'DATABASE_URL', neon.developDirect);
+    body = setEnvLine(body, 'DATABASE_URL_MAIN', neon.mainDirect);
+    body = setEnvLine(body, 'AUTH_SECRET', generateAuthSecret());
+    writeFileSync(localPath, body, 'utf8');
+    return 'written';
+}
+/**
+ * Replace the value of `KEY=...` in an env-file body, preserving every other line.
+ * Appends `KEY="value"` when the key is absent (so an older `.env.example` without
+ * `DATABASE_URL_MAIN` still gets it). The value is double-quoted — Neon URLs (pooled
+ * or direct) carry `?`/`&` query params that an unquoted dotenv value would truncate.
+ */
+function setEnvLine(body, key, value) {
+    const re = new RegExp(`^${key}=.*$`, 'm');
+    const line = `${key}="${value}"`;
+    return re.test(body) ? body.replace(re, line) : `${body.trimEnd()}\n${line}\n`;
+}
+/**
+ * The HTTPS git URL of the repo `gh repo create` made (`new.ts` creates
+ * `${FACTORY_ORG}/${name}` — the canonical remote is its `.git` HTTPS URL). Never
+ * SSH: the remote is added with the dev's `gh`-authenticated HTTPS credential.
+ */
+function repoHttpsUrl(repoSlug) {
+    return `https://github.com/${repoSlug}.git`;
+}
+/** Default git runner — `execa` in the derived dir, no shell. */
+async function gitInDir(args, cwd) {
+    const { stdout } = await execa('git', args, { cwd });
+    return { stdout };
+}
+/**
+ * Read the current `origin` remote URL (or `null` when there is none). Tolerates
+ * the `git remote get-url` exit-1 of a repo without `origin` (the common fresh
+ * case — `new.ts` does `git init` but never adds a remote).
+ */
+async function readOriginUrl(runGit, cwd) {
+    try {
+        const { stdout } = await runGit(['remote', 'get-url', 'origin'], cwd);
+        const url = stdout.trim();
+        return url === '' ? null : url;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build the git substrate in the documented, asserted ORDER (issue §6):
+ *   1. rename `master` → `main` (only when the current branch is `master`)
+ *   2. `git remote add origin <https-url>` (idempotent — `factory new` usually set
+ *      it already; skipped when present, reset only under `--force`)
+ *   3. create the `develop` branch off `main`
+ *   4. `git push origin main`  — MUST run BEFORE the Vercel project create + link,
+ *      so the repo has a `main` branch for Vercel to track as production (the git
+ *      link reads the repo's default branch). A no-op when `factory new` already
+ *      pushed `main`; the guarantee here.
+ *   5. `git push origin develop` — provision OWNS the develop branch (created when
+ *      infra is set up); Vercel attaches the preview deployment to it.
+ *
+ * The first `main` push is `factory new`'s job (so the docs pipeline can push before
+ * provision); steps 2+4 are the completeness layer (no-ops when `new` succeeded),
+ * step 5 (`develop`) is provision's own responsibility.
+ *
+ * Edge case (issue §8): an `origin` already pointing at a DIFFERENT URL (directory
+ * reuse) → without `--force`, throw a clear `CLIError` (headless-safe). With
+ * `--force`, the remote is reset to the canonical URL.
+ */
+async function buildGitSubstrate(rootDir, repoSlug, runGit, force) {
+    const url = repoHttpsUrl(repoSlug);
+    // 1. Normalize the default branch to `main` if the repo arrived on `master`.
+    let currentBranch = '';
+    try {
+        currentBranch = (await runGit(['rev-parse', '--abbrev-ref', 'HEAD'], rootDir)).stdout.trim();
+    }
+    catch {
+        currentBranch = '';
+    }
+    if (currentBranch === 'master') {
+        await runGit(['branch', '-m', 'master', 'main'], rootDir);
+    }
+    // 2. Add (or reset, under --force) the `origin` remote → the HTTPS repo URL.
+    const existingOrigin = await readOriginUrl(runGit, rootDir);
+    if (existingOrigin && existingOrigin !== url) {
+        // GitHub repo URLs are case-insensitive: an `origin` differing ONLY by case
+        // (e.g. `TimeKast/Edmond.git` vs the canonical lowercase `TimeKast/edmond.git`)
+        // points at the SAME repo. Re-case it to the canonical URL silently — no `--force`
+        // needed. A difference BEYOND case is a genuinely different repo → throw unless
+        // `--force` resets it.
+        const sameRepoDifferentCase = existingOrigin.toLowerCase() === url.toLowerCase();
+        if (!sameRepoDifferentCase && !force) {
+            throw new CLIError(`El repo ya tiene un remote \`origin\` apuntando a otro URL (\`${existingOrigin}\` ≠ \`${url}\`).\n` +
+                'Usa `--force` para sobrescribirlo, o limpia el remote si reutilizas este directorio.');
+        }
+        await runGit(['remote', 'set-url', 'origin', url], rootDir);
+    }
+    else if (!existingOrigin) {
+        await runGit(['remote', 'add', 'origin', url], rootDir);
+    }
+    // 3. Create the `develop` branch off `main` (idempotent: ignore "already exists").
+    try {
+        await runGit(['branch', 'develop', 'main'], rootDir);
+    }
+    catch {
+        // `develop` may already exist (resume / reused dir) — non-fatal.
+    }
+    // 4. Push `main` to the remote — BEFORE the Vercel project create (§8 ordering).
+    //    A no-op when `factory new` already pushed it; the guarantee main is on the
+    //    remote (a fresh push uses the dev's gh-authenticated HTTPS credential).
+    await runGit(['push', 'origin', 'main'], rootDir);
+    // 5. Push `develop` — provision owns this branch (the dev domain tracks it for
+    //    Vercel preview deployments). `-u` sets the upstream so the dev's coding-phase
+    //    pushes to `develop` just work.
+    await runGit(['push', '-u', 'origin', 'develop'], rootDir);
+}
+/** Map a Vercel project-create/link/patch failure to an actionable es-MX `CLIError`. */
+function vercelProjectErrorToCliError(error, teamId, projectName, context) {
+    if (error.status === 409) {
+        return new CLIError(`Ya existe un proyecto Vercel con el nombre \`${projectName}\` en el team \`${teamId}\` (409 en ${context}).\n` +
+            'Con `--resume` el CLI adopta el `projectId` del estado existente; o usa `--force` para empezar de cero con otro nombre.');
+    }
+    return vercelErrorToCliError(error, teamId, context);
+}
+/** Shipped E2E workflow template + the activated target it overwrites (the disabled placeholder). */
+export const E2E_WORKFLOW_EXAMPLE = '.github/workflows/e2e.yml.example';
+export const E2E_WORKFLOW_PATH = '.github/workflows/e2e.yml';
+/**
+ * Resolve the installed `@playwright/test` version for the E2E container tag —
+ * lockfile preferred (exact, matches a published container), package.json range
+ * as fallback. Returns null when Playwright is not a dependency (the project does
+ * not use E2E → activation is simply skipped). NEVER throws.
+ */
+export function resolvePlaywrightVersion(rootDir) {
+    const lockfile = join(rootDir, 'pnpm-lock.yaml');
+    if (existsSync(lockfile)) {
+        // Resolved line `      '@playwright/test': 1.58.2` — NOT the `specifier:` range.
+        const match = readFileSync(lockfile, 'utf8').match(/^\s+'@playwright\/test':\s+(\d+\.\d+\.\d+(?:-[\w.]+)?)\s*$/m);
+        if (match)
+            return match[1];
+    }
+    const pkgPath = join(rootDir, 'package.json');
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+            const spec = pkg.devDependencies?.['@playwright/test'] ?? pkg.dependencies?.['@playwright/test'];
+            if (typeof spec === 'string') {
+                const stripped = spec.replace(/^[\^~]/, '');
+                if (/^\d+\.\d+\.\d+/.test(stripped))
+                    return stripped;
+            }
+        }
+        catch {
+            // malformed package.json → treat as "no Playwright" (skip activation)
+        }
+    }
+    return null;
+}
+/**
+ * ACTIVATE the E2E workflow in the derived repo: read the shipped `e2e.yml.example`,
+ * substitute the Playwright container version, and PIN the trigger to `main` ONLY —
+ * so `develop` stays fast and unguarded and the E2E suite is the LAST line of
+ * defense on the way into production (push to `main` + PRs INTO `main`, which gate
+ * the merge). Overwrites the disabled placeholder. Returns a status the caller
+ * narrates. NON-fatal: a missing template or absent Playwright dep skips activation.
+ */
+export function writeE2eWorkflow(rootDir) {
+    const templatePath = join(rootDir, E2E_WORKFLOW_EXAMPLE);
+    if (!existsSync(templatePath))
+        return 'no-template';
+    const version = resolvePlaywrightVersion(rootDir);
+    if (!version)
+        return 'no-playwright';
+    const activated = readFileSync(templatePath, 'utf8')
+        .replace(/__PLAYWRIGHT_VERSION__/g, version)
+        // Pin EVERY trigger to `main` (last line of defense) — never the working branch.
+        .replace(/branches: \[[^\]]*\] # __TRIGGER_BRANCH__/g, 'branches: [main]');
+    const target = join(rootDir, E2E_WORKFLOW_PATH);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, activated, 'utf8');
+    return 'activated';
+}
+/**
+ * PROV-004 — the `github` step: build the git substrate, create the Vercel PROJECT,
+ * connect the GitHub repo (GitHub App gate), confirm `productionBranch: main`,
+ * write `.vercel/project.json`, and activate the E2E workflow. Migrations run in the
+ * Vercel build (`vercel-build`: `pnpm db:migrate && pnpm build`), NOT a GitHub Actions
+ * workflow. HIGH-risk: every failure is recoverable via `--resume`.
+ *
+ * Order (asserted by the unit test): git substrate (rename → remote add → push
+ * main) runs ENTIRELY before `POST /v9/projects`. The project create is skipped on
+ * `--resume` when `state.vercel.projectId` already exists (also the 409 path).
+ *
+ * Never runs `vercel link` / `vercel pull` — the `.vercel/project.json` is written
+ * directly (SK.md §7.1). `gh secret set` values go over STDIN (no-echo).
+ */
+export async function provisionGithubVercel(rootDir, state, teamId, deps = {}) {
+    const envPath = deps.envPath ?? defaultEnvPath();
+    const token = readVercelToken(envPath);
+    if (!token) {
+        throw new CLIError('No se pudo leer `VERCEL_TOKEN` de `~/.claude/.env`.\n' +
+            'Ejecuta `factory secrets <archivo>` para bajar el token del archivo de secretos y reintenta.');
+    }
+    const runGit = deps.runGit ?? gitInDir;
+    const apiDeps = { fetchImpl: deps.fetchImpl };
+    const repoSlug = `${FACTORY_ORG}/${state.projectName}`;
+    // Record the repo on the state up-front so the Neon secret push (PROV-002) and a
+    // `--resume` target it; this is durable even if a later REST step fails.
+    state.github = { repo: repoSlug };
+    writeProvisionState(rootDir, state);
+    // 1. Git substrate — push `main` BEFORE the Vercel project create (§8 ordering).
+    //    Skipped on resume when the Vercel project already exists (substrate done).
+    if (!state.vercel?.projectId) {
+        await buildGitSubstrate(rootDir, repoSlug, runGit, deps.force ?? false);
+    }
+    // 2. Create the Vercel PROJECT (resume: adopt the existing projectId, skip POST).
+    let projectId = state.vercel?.projectId;
+    if (!projectId) {
+        try {
+            const project = await createVercelProject(token, teamId, { name: state.projectName, repo: repoSlug }, apiDeps);
+            projectId = project.projectId;
+        }
+        catch (error) {
+            if (error instanceof VercelApiError) {
+                throw vercelProjectErrorToCliError(error, teamId, state.projectName, 'crear el proyecto Vercel');
+            }
+            throw error;
+        }
+        // Persist the projectId ATOMICALLY right after the create (issue §6 + AC).
+        state.vercel = { projectId };
+        writeProvisionState(rootDir, state);
+    }
+    // 3. Connect the GitHub repo. A 403 means Vercel's GitHub App is not installed —
+    //    print the install URL + pause (HITL), do NOT abort the whole run (§8).
+    try {
+        await linkGitRepo(projectId, token, teamId, repoSlug, apiDeps);
+    }
+    catch (error) {
+        if (error instanceof GitHubAppNotInstalledError) {
+            console.warn('⚠ La GitHub App de Vercel no está instalada sobre la org/repo (Vercel respondió 403 al conectar el git).\n' +
+                `  Instálala aquí: https://github.com/apps/vercel/installations/new (selecciona \`${repoSlug}\`),\n` +
+                '  y reintenta con `--resume` para terminar la conexión y el resto del paso.');
+            return; // HITL pause — the projectId is already durable for --resume.
+        }
+        if (error instanceof VercelApiError) {
+            throw vercelProjectErrorToCliError(error, teamId, state.projectName, 'conectar el git al proyecto');
+        }
+        throw error;
+    }
+    // 4. Apply the project SETTINGS via PATCH (ssoProtection:null + autoExposeSystemEnvs)
+    //    — POST /v9/projects refuses them as additional props. NOT productionBranch:
+    //    that one is not a property of this endpoint (Vercel 400s + drops the whole
+    //    PATCH); the git link already tracks the repo's `main` as production.
+    //    NON-FATAL: a rejected setting just means the default stands — warn and continue.
+    try {
+        await patchProjectSettings(projectId, token, teamId, apiDeps);
+    }
+    catch (error) {
+        const detail = error instanceof VercelApiError
+            ? `Vercel respondió ${error.status}: ${error.body || '(sin cuerpo)'}`
+            : error?.message;
+        console.warn(`⚠ No se pudieron aplicar los settings del proyecto Vercel vía PATCH (${detail}).\n` +
+            '  Vercel usa defaults (producción = main del repo) — continúo.');
+    }
+    // 5. Write `.vercel/project.json` directly (NEVER vercel link/pull — SK.md §7.1).
+    writeVercelProjectJson(rootDir, { projectId, orgId: teamId, teamId }, { force: deps.force });
+    // 6. ACTIVATE the E2E workflow PINNED TO `main` (the last line of defense before
+    //    production; `develop` stays unguarded). Without this it ships disabled and
+    //    nobody turns it on. Non-fatal: skipped when the project has no Playwright or
+    //    the template is absent. It lands in the working tree and is committed below.
+    //
+    //    Migrations are NOT a GitHub Actions workflow: they run in the Vercel build
+    //    (`vercel-build`: `pnpm db:migrate && pnpm build`, shipped in package.json),
+    //    so every deployment migrates ITS target's DB (production←main, preview←develop)
+    //    before building — 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);
+    }
+    // 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
+    //    NOT fully complete stays resumable (isServiceComplete reads this flag).
+    state.github = { repo: repoSlug, done: true };
+    writeProvisionState(rootDir, state);
+}
+/**
+ * Commit the activated E2E workflow (`e2e.yml`) and push it to BOTH `main` and
+ * `develop` in the derived repo. `factory new` pushed the initial scaffold commit
+ * before provision activated this workflow, so it lives only in the working tree
+ * until committed here. (Migrations run in the Vercel build via `vercel-build`, not a
+ * workflow — there is nothing to commit for them.) Idempotent — when a `--resume`
+ * finds it already committed, `git add` stages nothing and the commit/push is skipped.
+ */
+async function commitAndPushWorkflows(rootDir, runGit) {
+    await runGit(['add', E2E_WORKFLOW_PATH], rootDir);
+    const staged = (await runGit(['diff', '--cached', '--name-only'], rootDir)).stdout.trim();
+    if (!staged) {
+        console.log('  ⏭ e2e.yml ya commiteado (resume) — sin cambios que pushear');
+        return;
+    }
+    await runGit(['commit', '-m', 'ci: wire the E2E workflow'], rootDir);
+    // `main:develop` lands the same commit on develop too (fast-forward — both branches
+    // sat on the initial commit).
+    await runGit(['push', 'origin', 'main'], rootDir);
+    await runGit(['push', 'origin', 'main:develop'], rootDir);
+    console.log('  ↑ e2e.yml commiteado + pusheado (main + develop)');
+}
+/**
+ * Commit `.timekast/provision.json` (the resource-ID state — no credentials ever
+ * touch it) to main + develop, so a `--resume` from a fresh clone has the IDs (the
+ * connection strings are re-derived from Neon). Runs at the END of provision, when
+ * the full state (all service IDs) is on disk. Best-effort + idempotent: an unchanged
+ * state stages nothing → skips.
+ */
+async function commitProvisionState(rootDir) {
+    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();
+        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);
+        console.log('  ↑ .timekast/provision.json commiteado (main + develop)');
+    }
+    catch {
+        // Non-fatal: the local state is intact; the dev can commit it later.
+    }
+}
+/** Map a Cloudflare REST failure to an actionable, es-MX `CLIError` (issue §8 edges). */
+function cloudflareErrorToCliError(error, context) {
+    switch (error.status) {
+        case 401:
+            return new CLIError(`El \`CLOUDFLARE_API_TOKEN\` del archivo de secretos es inválido o expiró (Cloudflare respondió 401 en ${context}).\n` +
+                'Ejecuta `factory secrets <archivo>` para renovarlo y reintenta con `--resume`.');
+        case 403:
+            return new CLIError(`El \`CLOUDFLARE_API_TOKEN\` no tiene scope sobre la zona \`${TIMEKAST_ZONE_NAME}\` ` +
+                `(Cloudflare respondió 403 en ${context}).\n` +
+                'El token del archivo de secretos debe estar scopeado a esa zona con permiso DNS-edit (no account-wide).\n' +
+                'Pídele al admin que lo re-minte con ese scope en el archivo de secretos compartido, re-impórtalo con `factory secrets <archivo>` y reintenta con `--resume`.');
+        case 429:
+            return new CLIError(`Cloudflare rechazó la operación por rate-limit (429 en ${context}). Reintenta en un momento con \`--resume\`.`);
+        default:
+            return new CLIError(`Falló la llamada a Cloudflare en ${context}: ${error.message}`);
+    }
+}
+/**
+ * PROV-005 — the `dns` step. Attach the two interim domains to the Vercel project,
+ * create their `proxied: false` Cloudflare CNAMEs, and wire Resend's env vars
+ * (`RESEND_API_KEY` from the rail + the fixed `EMAIL_FROM`) into the project.
+ *
+ * Order:
+ *   1. Validate the slug as a subdomain BEFORE any REST (issue §8).
+ *   2. Vercel: `POST /domains` for `{slug}-dev` (gitBranch: develop) then `{slug}`
+ *      (production, no gitBranch). A 409 (already attached) is idempotent.
+ *   3. Cloudflare: resolve the `timekast.mx` zone id, then ensure a `proxied:false`
+ *      CNAME for BOTH domains (create, or PATCH a manually-proxied record).
+ *   4. Resend: upsert `RESEND_API_KEY` (production+preview) + the org
+ *      `EMAIL_FROM=noreply@updates.timekast.mx` (mail subdomain) — no-echo.
+ *   5. Record `state.dns = { domain, devDomain }` (prod + the dev domain) and persist.
+ *
+ * Requires `state.vercel.projectId` (PROV-004). No-echo: the Cloudflare token and
+ * the Resend key never reach stdout — only domain NAMES + key NAMES are printed.
+ * Vercel's SSL provisioning can take minutes; this step does NOT block on it (§8).
+ *
+ * @throws {CLIError} on a missing projectId / invalid slug / missing token, and on
+ *   any mapped Vercel/Cloudflare REST failure (issue §8). On any throw, `state.dns`
+ *   is left unwritten (rollback of the step — issue §5 Gherkin).
+ */
+export async function provisionDns(rootDir, state, teamId, deps = {}) {
+    const projectId = state.vercel?.projectId;
+    if (!projectId) {
+        throw new CLIError('Falta el `projectId` de Vercel en el estado: el proyecto Vercel lo crea PROV-004.\n' +
+            'Corre el paso de Vercel/GitHub primero (`--services=github,...`) y reintenta con `--resume`.');
+    }
+    // 1. Validate the slug as a subdomain label BEFORE any REST call (issue §8).
+    const slug = state.projectName;
+    assertValidSubdomainSlug(slug);
+    const { dev, prod } = provisionDomains(slug);
+    const envPath = deps.envPath ?? defaultEnvPath();
+    const vercelToken = readVercelToken(envPath);
+    if (!vercelToken) {
+        throw new CLIError('No se pudo leer `VERCEL_TOKEN` de `~/.claude/.env`.\n' +
+            'Ejecuta `factory secrets <archivo>` para bajar el token del archivo de secretos y reintenta.');
+    }
+    const cloudflareToken = readCloudflareApiKey(envPath);
+    if (!cloudflareToken) {
+        throw new CLIError('No se pudo leer `CLOUDFLARE_API_TOKEN` de `~/.claude/.env`.\n' +
+            'Ejecuta `factory secrets <archivo>` para bajar el token del archivo de secretos (scoped a la zona) y reintenta.');
+    }
+    const vercelDeps = { fetchImpl: deps.fetchImpl };
+    const cloudflareDeps = { fetchImpl: deps.fetchImpl };
+    // 2. Vercel — attach the DEV domain (gitBranch: develop) then PROD (no gitBranch).
+    try {
+        const devOutcome = await addVercelDomain(projectId, vercelToken, teamId, { name: dev, gitBranch: 'develop' }, vercelDeps);
+        console.log(`  ${devOutcome === 'exists' ? '↻ (ya existía)' : '＋'} dominio Vercel ${dev} → branch develop`);
+        const prodOutcome = await addVercelDomain(projectId, vercelToken, teamId, { name: prod }, vercelDeps);
+        console.log(`  ${prodOutcome === 'exists' ? '↻ (ya existía)' : '＋'} dominio Vercel ${prod} → producción`);
+    }
+    catch (error) {
+        if (error instanceof VercelApiError) {
+            throw vercelErrorToCliError(error, teamId, 'agregar el dominio al proyecto Vercel');
+        }
+        throw error;
+    }
+    // 3. Cloudflare — resolve the zone, then ensure a `proxied:false` CNAME for both.
+    let zoneId;
+    try {
+        zoneId = await resolveZoneId(cloudflareToken, cloudflareDeps);
+    }
+    catch (error) {
+        if (error instanceof CloudflareApiError) {
+            throw cloudflareErrorToCliError(error, `resolver la zona \`${TIMEKAST_ZONE_NAME}\``);
+        }
+        throw error; // resolveZoneId's own CLIError (zone not found) propagates as-is.
+    }
+    for (const name of [dev, prod]) {
+        try {
+            const outcome = await ensureCnameRecord(zoneId, name, cloudflareToken, cloudflareDeps);
+            const mark = outcome === 'created'
+                ? '＋'
+                : outcome === 'unproxied'
+                    ? '↻ (proxied→false)'
+                    : '⏭ (ya estaba)';
+            console.log(`  ${mark} CNAME ${name} → cname.vercel-dns.com (proxied:false)`);
+        }
+        catch (error) {
+            if (error instanceof CloudflareApiError) {
+                throw cloudflareErrorToCliError(error, `crear el CNAME de \`${name}\``);
+            }
+            throw error;
+        }
+    }
+    // 4. Resend — wire RESEND_API_KEY (rail) + the FIXED EMAIL_FROM into Vercel env.
+    await wireResendEnv(projectId, vercelToken, teamId, envPath, vercelDeps);
+    // 5. Record BOTH interim domains in state — prod is canonical, dev tracks `develop`.
+    //    The dev domain is derivable from the slug, but persisting it keeps the state
+    //    file transparent about every domain provision created (not just prod).
+    state.dns = { domain: prod, devDomain: dev };
+    writeProvisionState(rootDir, state);
+}
+/**
+ * Wire the Resend env vars into the Vercel project (issue §4 + §5), idempotently
+ * and per-target, with `?teamId=` on every call (via `upsertEnvVar`). No-echo: the
+ * `RESEND_API_KEY` VALUE never reaches stdout — only the KEY NAME + targets print.
+ *
+ *   - `RESEND_API_KEY` ← the rail value → targets `production` + `preview`
+ *   - `EMAIL_FROM`     ← the org `noreply@updates.timekast.mx` → `production` + `preview`
+ *
+ * `RESEND_API_KEY` absent from the rail is a WARNING (mail just stays unconfigured
+ * — `isEmailReady()` guards it in the kit), never an abort (the domains are the
+ * critical path; Resend is additive and re-runnable with `--resume`).
+ */
+async function wireResendEnv(projectId, token, teamId, envPath, deps) {
+    const plan = [];
+    const resendKey = readGateValue('RESEND_API_KEY', envPath);
+    if (resendKey) {
+        plan.push({ key: 'RESEND_API_KEY', value: resendKey, target: ['production', 'preview'] });
+    }
+    else {
+        console.warn('⚠ No hay `RESEND_API_KEY` en `~/.claude/.env` — omito esa env var (el correo queda sin ' +
+            'configurar hasta que la bajes con `factory secrets <archivo>` y reintentes con `--resume`).');
+    }
+    // EMAIL_FROM is the FIXED org sender — never read from the rail, never echoed value-wise.
+    plan.push({ key: 'EMAIL_FROM', value: PROVISION_EMAIL_FROM, target: ['production', 'preview'] });
+    const existing = await listEnvVars(projectId, token, teamId, deps);
+    for (const entry of plan) {
+        const outcome = await upsertEnvVar(projectId, token, teamId, entry, existing, deps);
+        // No-echo: print the KEY NAME + targets only (EMAIL_FROM's value is the public
+        // literal, but RESEND_API_KEY's must never be printed — so we print neither).
+        console.log(`  ${outcome === 'created' ? '＋' : '↻'} ${entry.key} [${entry.target.join(', ')}]`);
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// PROV-006 — the deferrable `--domain` (client's definitive domain)
+// ─────────────────────────────────────────────────────────────────────────────
+/** Base URL of the Resend REST API (named constant — never an inline literal). */
+export const RESEND_API_BASE = 'https://api.resend.com';
+/** Timeout (ms) for the Resend REST call — a dead network must not hang provision. */
+const RESEND_API_TIMEOUT_MS = 30_000;
+/** Default poll delay — a real `setTimeout`-backed sleep (tests inject a no-op). */
+function realSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Default interim-retire confirm — a `prompts` y/n (aborts/Esc → false, never retire). */
+async function promptConfirm(message) {
+    const { ok } = await prompts({ type: 'confirm', name: 'ok', message, initial: false });
+    return ok === true;
+}
+/**
+ * Register the client domain in Resend — `POST /domains { name }` (PROV-006 §4),
+ * reusing the rail's `RESEND_API_KEY`. Idempotency (issue §8): Resend returns an
+ * error when the domain is already verified on ANOTHER account; that is a WARNING,
+ * not an abort — `EMAIL_FROM` is updated regardless. An absent `RESEND_API_KEY` is
+ * also a warning (mail stays unconfigured). No-echo: the key never reaches stdout.
+ */
+async function registerResendDomain(domain, envPath, fetchImpl) {
+    const resendKey = readGateValue('RESEND_API_KEY', envPath);
+    if (!resendKey) {
+        console.warn('⚠ No hay `RESEND_API_KEY` en `~/.claude/.env` — omito el alta del dominio en Resend ' +
+            '(bájala con `factory secrets <archivo>` y reintenta con `--resume`).');
+        return;
+    }
+    try {
+        const response = await fetchImpl(`${RESEND_API_BASE}/domains`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${resendKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ name: domain }),
+            signal: AbortSignal.timeout(RESEND_API_TIMEOUT_MS),
+        });
+        if (!response.ok) {
+            // Already verified elsewhere / validation error → warn + continue (issue §8).
+            console.warn(`⚠ Resend rechazó el alta de \`${domain}\` (status ${response.status}). ` +
+                'Quizá ya está verificado en otra cuenta — `EMAIL_FROM` se actualiza igual; ' +
+                'verifica el dominio a mano en Resend si hace falta.');
+            return;
+        }
+        console.log(`  ＋ Resend: dominio ${domain} registrado (verifica los records DNS en Resend)`);
+    }
+    catch (error) {
+        // A network/timeout failure on Resend is non-fatal — the domain switch already
+        // happened on Vercel; Resend verification is re-runnable with `--resume`.
+        console.warn(`⚠ No se pudo dar de alta \`${domain}\` en Resend (${error?.message ?? 'error'}). ` +
+            'Reintenta con `--resume`; `EMAIL_FROM` ya se actualizó.');
+    }
+}
+/** Print the exact DNS records the owner must create for the `--dns=registrar` path. */
+function printManualRecords(domain, verification) {
+    console.log(`\n  Crea estos registros DNS para \`${domain}\` en tu registrar:`);
+    if (verification.length === 0) {
+        // Vercel has not yet returned verification records (e.g. first poll) — print the
+        // canonical CNAME the kit always uses so the dev is never left without guidance.
+        console.log(`    · CNAME  ${domain}  →  ${CNAME_VERCEL_TARGET}`);
+    }
+    else {
+        for (const v of verification) {
+            console.log(`    · ${v.type.toUpperCase()}  ${v.domain}  →  ${v.value}`);
+        }
+    }
+    console.log('  (El CLI NO crea estos registros en modo `--dns=registrar`.)\n');
+}
+/**
+ * Poll `GET /v9/projects/{id}/domains/{name}` until Vercel reports `verified:true`
+ * or the timeout budget runs out (PROV-006 §4). Returns `true` once verified; on
+ * timeout returns `false` (the caller records `pending-verification` — resumable).
+ * The `sleep`/`now` seams are injected so the unit test never waits 30s for real.
+ */
+async function pollDomainVerification(projectId, domain, token, teamId, deps, fetchImpl) {
+    const sleep = deps.sleep ?? realSleep;
+    const now = deps.now ?? Date.now;
+    const timeoutMs = (deps.verifyTimeoutMin ?? DEFAULT_VERIFY_TIMEOUT_MIN) * 60_000;
+    const intervalMs = VERIFY_POLL_INTERVAL_SEC * 1_000;
+    const deadline = now() + timeoutMs;
+    const vercelDeps = { fetchImpl };
+    // First check immediately (the domain may already be verified — idempotent re-run).
+    for (;;) {
+        const status = await getVercelDomainStatus(projectId, domain, token, teamId, vercelDeps);
+        if (status.verified)
+            return true;
+        // For the registrar path, surface the exact records every poll while pending.
+        if (deps.dnsRoute === 'registrar')
+            printManualRecords(domain, status.verification);
+        if (now() >= deadline)
+            return false;
+        console.log(`  … esperando verificación de \`${domain}\` (reintento en ${VERIFY_POLL_INTERVAL_SEC}s)`);
+        await sleep(intervalMs);
+    }
+}
+/**
+ * Resolve which Cloudflare token + zone the client-domain CNAME is created under
+ * (PROV-006 §4 tree). `registrar` returns `null` (no CNAME created — manual). For
+ * `org` the shared org token (`CLOUDFLARE_API_TOKEN`) is scoped to the client zone; for
+ * `cliente-cf` the CLIENT's own key is used (read from the rail under
+ * `CLIENT_CLOUDFLARE_API_TOKEN`, or prompted when absent and a TTY is present).
+ */
+async function resolveDnsToken(route, envPath, headless) {
+    if (route === 'registrar')
+        return null;
+    if (route === 'org') {
+        const token = readCloudflareApiKey(envPath);
+        if (!token) {
+            throw new CLIError('No se pudo leer `CLOUDFLARE_API_TOKEN` de `~/.claude/.env` para `--dns=org`.\n' +
+                'Ejecuta `factory secrets <archivo>` para bajar el token del archivo de secretos (scoped a la zona) y reintenta.');
+        }
+        return token;
+    }
+    // cliente-cf — the client's own key. Prefer the rail; prompt only with a TTY.
+    const fromRail = readGateValue('CLIENT_CLOUDFLARE_API_TOKEN', envPath);
+    if (fromRail)
+        return fromRail;
+    if (headless) {
+        throw new CLIError('`--dns=cliente-cf` requiere la API key de Cloudflare del cliente, pero no está en ' +
+            '`~/.claude/.env` (`CLIENT_CLOUDFLARE_API_TOKEN`) y no hay terminal interactiva.\n' +
+            'Agrégala al rail o corre con TTY para que el CLI la pida.');
+    }
+    const { key } = await prompts({
+        type: 'password',
+        name: 'key',
+        message: 'API key de Cloudflare del cliente (scoped a su zona, DNS-edit):',
+    });
+    const value = typeof key === 'string' ? key.trim() : '';
+    if (value === '') {
+        throw new CLIError('No se proporcionó la API key de Cloudflare del cliente. Operación cancelada.');
+    }
+    return value;
+}
+/**
+ * PROV-006 — attach the client's DEFINITIVE domain to the Vercel project, create
+ * (or print, for `registrar`) its DNS record, poll Vercel until verified, and on
+ * success: retire the interim prod domain (with explicit confirmation), update
+ * `EMAIL_FROM` + `AUTH_URL`/`NEXTAUTH_URL`, and register the domain in Resend.
+ *
+ * Standalone-safe: runnable as a PATCH over an existing provision (the `dns` step
+ * of PROV-005 already attached the interim domains) or inside the initial run. It
+ * requires `state.vercel.projectId` (PROV-004).
+ *
+ * Idempotency (issue §8):
+ *   - domain already attached to Vercel (409) → only polls, never re-adds.
+ *   - interim retire fails → WARNING, the step is NOT marked failed (interim stays).
+ *   - Resend already verified elsewhere → warning + continue.
+ *   - `AUTH_URL`/`NEXTAUTH_URL` already correct → the upsert PATCH is omitted.
+ *
+ * On timeout the state is left `clientDomainStatus: pending-verification` (resumable);
+ * on success it is `live`.
+ *
+ * @throws {CLIError} on a missing projectId / token, a mapped Vercel/Cloudflare
+ *   REST failure, or a verification timeout (the partial state is persisted first).
+ */
+export async function provisionClientDomain(rootDir, state, teamId, domain, deps = {}) {
+    const projectId = state.vercel?.projectId;
+    if (!projectId) {
+        throw new CLIError('Falta el `projectId` de Vercel en el estado: el proyecto Vercel lo crea PROV-004.\n' +
+            'Corre el paso de Vercel/GitHub primero (`--services=github,...`) y reintenta con `--resume`.');
+    }
+    const route = deps.dnsRoute ?? 'org';
+    const envPath = deps.envPath ?? defaultEnvPath();
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const vercelToken = readVercelToken(envPath);
+    if (!vercelToken) {
+        throw new CLIError('No se pudo leer `VERCEL_TOKEN` de `~/.claude/.env`.\n' +
+            'Ejecuta `factory secrets <archivo>` para bajar el token del archivo de secretos y reintenta.');
+    }
+    const vercelDeps = { fetchImpl };
+    // 1. Attach the client domain to Vercel (409 → already attached, idempotent §8).
+    try {
+        const outcome = await addVercelDomain(projectId, vercelToken, teamId, { name: domain }, vercelDeps);
+        console.log(`  ${outcome === 'exists' ? '↻ (ya existía)' : '＋'} dominio Vercel ${domain} → producción`);
+    }
+    catch (error) {
+        if (error instanceof VercelApiError) {
+            throw vercelErrorToCliError(error, teamId, 'agregar el dominio del cliente a Vercel');
+        }
+        throw error;
+    }
+    // 2. DNS record: org/cliente-cf CREATE the CNAME; registrar only PRINTS it (§4).
+    if (route === 'registrar') {
+        // Print the canonical record now; the poll loop re-prints Vercel's verification.
+        printManualRecords(domain, []);
+    }
+    else {
+        const cfToken = await resolveDnsToken(route, envPath, deps.headless ?? false);
+        const zoneName = apexZoneOf(domain);
+        const cloudflareDeps = { fetchImpl };
+        let zoneId;
+        try {
+            zoneId = await resolveZoneIdForName(zoneName, cfToken, cloudflareDeps);
+        }
+        catch (error) {
+            if (error instanceof CloudflareApiError) {
+                throw cloudflareErrorToCliError(error, `resolver la zona \`${zoneName}\``);
+            }
+            throw error; // resolveZoneIdForName's own CLIError (zone not found) propagates.
+        }
+        try {
+            const cnameOutcome = await ensureCnameRecord(zoneId, domain, cfToken, cloudflareDeps);
+            const mark = cnameOutcome === 'created'
+                ? '＋'
+                : cnameOutcome === 'unproxied'
+                    ? '↻ (proxied→false)'
+                    : '⏭ (ya estaba)';
+            console.log(`  ${mark} CNAME ${domain} → ${CNAME_VERCEL_TARGET} (proxied:false, vía ${route})`);
+        }
+        catch (error) {
+            if (error instanceof CloudflareApiError) {
+                throw cloudflareErrorToCliError(error, `crear el CNAME de \`${domain}\``);
+            }
+            throw error;
+        }
+    }
+    // 3. Poll Vercel for verification (seam-injected sleep/clock — never 30s for real).
+    const verified = await pollDomainVerification(projectId, domain, vercelToken, teamId, { ...deps, dnsRoute: route }, fetchImpl);
+    if (!verified) {
+        // Timeout: persist the pending state (resumable) and stop with a clear error (§5).
+        state.dns = {
+            ...(state.dns ?? {
+                domain: provisionDomains(state.projectName).prod,
+                devDomain: provisionDomains(state.projectName).dev,
+            }),
+            clientDomain: domain,
+            clientDomainStatus: 'pending-verification',
+        };
+        writeProvisionState(rootDir, state);
+        throw new CLIError(`\`${domain}\` no se verificó dentro del timeout (${deps.verifyTimeoutMin ?? DEFAULT_VERIFY_TIMEOUT_MIN} min).\n` +
+            'El estado quedó en `domain: pending-verification`; reintenta con `--resume` para seguir sondeando.');
+    }
+    console.log(`  ✔ ${domain} verificado por Vercel`);
+    // 4. Retire the interim prod domain — ONLY with explicit confirmation (§4 + §8).
+    await retireInterimDomain(projectId, vercelToken, teamId, state, deps, fetchImpl);
+    // 5. Update EMAIL_FROM + AUTH callbacks in Vercel env (idempotent — §8).
+    await updateDomainEnv(projectId, vercelToken, teamId, domain, vercelDeps);
+    // 6. Register the client's MAIL SUBDOMAIN (`updates.<domain>`) in Resend — NOT the
+    //    apex, which holds the client's corporate MX/SPF (Google Workspace, M365, …).
+    //    Verifying Resend on a dedicated subdomain keeps the client's own mail intact.
+    await registerResendDomain(mailDomainFor(domain), envPath, fetchImpl);
+    // 7. Record the client domain as LIVE and persist.
+    state.dns = {
+        ...(state.dns ?? {
+            domain: provisionDomains(state.projectName).prod,
+            devDomain: provisionDomains(state.projectName).dev,
+        }),
+        clientDomain: domain,
+        clientDomainStatus: 'live',
+    };
+    writeProvisionState(rootDir, state);
+}
+/**
+ * Retire the interim prod domain (`{slug}.timekast.mx`) AFTER the client domain
+ * verifies — but ONLY with explicit confirmation (PROV-006 §4). `--confirm`
+ * pre-approves; otherwise a TTY prompt asks (headless without `--confirm` → NOT
+ * retired). The DEV domain (`{slug}-dev.timekast.mx`) is ALWAYS conserved. A
+ * removal failure is a WARNING, never a step failure (issue §8 — interim stays up).
+ */
+async function retireInterimDomain(projectId, token, teamId, state, deps, fetchImpl) {
+    const interim = provisionDomains(state.projectName).prod;
+    let approved = deps.preConfirmed === true;
+    if (!approved) {
+        if (deps.headless) {
+            console.warn(`⚠ No se retira el dominio interino \`${interim}\` en headless sin \`--confirm\` ` +
+                '(queda activo; retíralo a mano o reintenta con `--confirm`).');
+            return;
+        }
+        const confirm = deps.confirm ?? promptConfirm;
+        approved = await confirm(`¿Retirar el dominio interino \`${interim}\` de Vercel?`);
+    }
+    if (!approved) {
+        console.log(`  ⏭ Conservo el dominio interino \`${interim}\` (sin confirmación de retiro).`);
+        return;
+    }
+    try {
+        const outcome = await removeVercelDomain(projectId, interim, token, teamId, { fetchImpl });
+        console.log(`  ${outcome === 'absent' ? '⏭ (ya no estaba)' : '－'} dominio interino ${interim} retirado`);
+    }
+    catch (error) {
+        // §8: a 5xx (or any non-404) on the retire is a WARNING — the interim stays up,
+        // the step is NOT marked failed, the dev retires it manually later.
+        console.warn(`⚠ No se pudo retirar el dominio interino \`${interim}\` (${error?.message ?? 'error'}).\n` +
+            '  Queda activo; retíralo a mano en Vercel o reintenta con `--resume`. El paso NO falla por esto.');
+    }
+    // The DEV domain is intentionally never touched (issue §4 — conserved).
+}
+/**
+ * Update `EMAIL_FROM` + `AUTH_URL`/`NEXTAUTH_URL` to the client domain in the
+ * Vercel env, per-target and idempotently (PROV-006 §4). Lists the existing vars
+ * once; an `AUTH_URL`/`NEXTAUTH_URL`/`EMAIL_FROM` already set to the target value
+ * has its PATCH omitted (issue §8 — second run is a no-op). No-echo: only KEY
+ * NAMES + targets print (the values here are public, but the discipline holds).
+ */
+async function updateDomainEnv(projectId, token, teamId, domain, deps) {
+    const authUrl = `https://${domain}`;
+    const plan = [
+        // EMAIL_FROM uses the dedicated mail subdomain (`updates.<domain>`), NOT the apex
+        // — the apex carries the client's corporate mail. AUTH_URL stays the app domain.
+        {
+            key: 'EMAIL_FROM',
+            value: `noreply@${mailDomainFor(domain)}`,
+            target: ['production', 'preview'],
+        },
+        { key: 'AUTH_URL', value: authUrl, target: ['production', 'preview'] },
+        { key: 'NEXTAUTH_URL', value: authUrl, target: ['production', 'preview'] },
+    ];
+    const existing = await listEnvVars(projectId, token, teamId, deps);
+    for (const entry of plan) {
+        const outcome = await upsertEnvVar(projectId, token, teamId, entry, existing, deps);
+        console.log(`  ${outcome === 'created' ? '＋' : '↻'} ${entry.key} [${entry.target.join(', ')}]`);
+    }
+}
+/**
+ * Print the resolved client-domain operation tree for `--domain --dry-run`
+ * (PROV-006 §8): the exact domain, the DNS route, whether the CNAME is created or
+ * printed, the interim-retire intent, and the env updates — mutating NOTHING.
+ */
+function printClientDomainPlan(domain, interim, route, confirm) {
+    console.log(`\nPlan de \`--domain=${domain}\` (ruta DNS: ${route}):`);
+    console.log(`  ＋ dominio Vercel ${domain} → producción`);
+    if (route === 'registrar') {
+        console.log(`  · (registrar) imprime CNAME ${domain} → ${CNAME_VERCEL_TARGET} — NO lo crea`);
+    }
+    else {
+        const zone = apexZoneOf(domain);
+        console.log(`  ＋ Cloudflare CNAME ${domain} → ${CNAME_VERCEL_TARGET} (proxied:false, zona ${zone}, vía ${route})`);
+    }
+    console.log(`  … sondea GET /v9/projects/.../domains/${domain} hasta verified:true (o timeout)`);
+    console.log(`  ${confirm ? '－' : '? (requiere --confirm o prompt)'} retira el interino ${interim} ` +
+        `(el dev ${domain}-dev se conserva)`);
+    console.log(`  ↻ EMAIL_FROM=noreply@${mailDomainFor(domain)} · AUTH_URL=https://${domain} · NEXTAUTH_URL=https://${domain}`);
+    console.log(`  ＋ Resend: POST /domains { name: ${mailDomainFor(domain)} } (subdominio mail, no el apex)`);
+    console.log('\n(`--dry-run`) No se ejecutó ninguna llamada a API ni se escribió estado.');
+}
+/**
+ * Execute one service's create step. `neon` (PROV-002), `github` (PROV-004),
+ * `vercel` (PROV-003) and `dns` (PROV-005) are implemented. `teamId` is required
+ * for the Vercel + GitHub + DNS steps (validated upstream).
+ */
+async function runServiceStep(service, rootDir, state, flags) {
+    switch (service) {
+        case 'neon':
+            await provisionNeon(rootDir, state);
+            break;
+        case 'vercel':
+            // PROV-003: push env (teamId on every call) + write .vercel/project.json +
+            // pnpm install. The Vercel PROJECT itself is created by PROV-004.
+            await provisionVercel(rootDir, state, flags.team, { force: flags.force });
+            break;
+        case 'github':
+            // PROV-004: git substrate (rename → remote add → push main) + create the
+            // Vercel project + connect git (GitHub App) + PATCH production-branch +
+            // .vercel/project.json + activate E2E. Migrations run in vercel-build, not a workflow.
+            await provisionGithubVercel(rootDir, state, flags.team, { force: flags.force });
+            break;
+        case 'dns':
+            // PROV-005: attach the interim domains to Vercel (dev → develop, prod →
+            // production) + create their Cloudflare CNAMEs (proxied:false) + wire Resend
+            // (RESEND_API_KEY + the fixed EMAIL_FROM), then `state.dns = { domain, devDomain }`.
+            await provisionDns(rootDir, state, flags.team);
+            break;
+        default:
+            throw new CLIError(`Paso de provision no implementado: \`${service}\`.`);
+    }
+}
+/** Print the optional neonctl warning when the preflight flagged it (non-fatal). */
+function warnNeonctl(report) {
+    if (report.status === 'warn')
+        console.warn(`⚠ ${report.message}`);
+}
+/** Default interactive disambiguation — a numbered `prompts` select (name + id + url). */
+async function promptSelectCandidate(provider, candidates) {
+    console.log(`\nVarios candidatos para ${provider}:`);
+    candidates.forEach((c, i) => {
+        console.log(`  ${i + 1}. ${c.name}  ·  ${c.id}  ·  ${c.url}`);
+    });
+    const { idx } = await prompts({
+        type: 'select',
+        name: 'idx',
+        message: `¿Cuál es el ${provider} de este proyecto?`,
+        choices: candidates.map((c, i) => ({ title: `${c.name} (${c.id})`, value: i })),
+    });
+    if (typeof idx !== 'number')
+        return null; // cancelled (Esc) → unknown
+    return candidates[idx] ?? null;
+}
+/** Default `gh` runner — read-only `gh` via execa (never a write subcommand). */
+async function ghRun(args) {
+    const { stdout } = await execa('gh', args);
+    return { stdout };
+}
+/**
+ * Resolve ONE provider's candidate list down to a single id (issue §4):
+ *   - 0 candidates → `null` (caller records `unknown`)
+ *   - 1 candidate  → that id (no prompt — but the AMBIGUITY edge always prompts:
+ *     the caller decides whether to force a prompt; here a lone match is taken)
+ *   - 2+ candidates → prompt (interactive) or record the candidate list for the
+ *     `--json`/headless path and return `null` (→ `unknown` until resolved).
+ *
+ * `forcePrompt` (issue §8: "el CLI siempre presenta el prompt si hay más de un
+ * candidato, incluso si parece obvio") makes the caller pass the full list through
+ * even for a single near-obvious match when there is genuine ambiguity upstream.
+ */
+async function resolveCandidate(provider, candidates, deps, recordAmbiguity) {
+    if (candidates.length === 0)
+        return null;
+    if (candidates.length === 1)
+        return candidates[0].id;
+    // More than one candidate → ambiguity. In `--json`/headless we cannot prompt:
+    // surface the list for external resolution and leave the field `unknown`.
+    recordAmbiguity(candidates);
+    if (deps.headless)
+        return null;
+    const select = deps.selectCandidate ?? promptSelectCandidate;
+    const chosen = await select(provider, candidates);
+    return chosen?.id ?? null;
+}
+/** Reconstruct the Vercel project id (read-only) — filter by name/slug. */
+async function adoptVercel(slug, teamId, token, deps, recordAmbiguity) {
+    const projects = await listVercelProjects(token, teamId, { fetchImpl: deps.fetchImpl });
+    const candidates = projectsToCandidates(projects, slug, teamId);
+    return resolveCandidate('Vercel', candidates, deps, recordAmbiguity);
+}
+/** Map Vercel project summaries to candidates, keeping only slug-name matches. */
+function projectsToCandidates(projects, slug, teamId) {
+    const matches = projects.filter((p) => p.name === slug || p.name.includes(slug) || slug.includes(p.name));
+    // Prefer an EXACT name match alone (unambiguous); otherwise surface all matches.
+    const exact = matches.filter((p) => p.name === slug);
+    const pool = exact.length === 1 ? exact : matches;
+    return pool.map((p) => ({
+        id: p.id,
+        name: p.name,
+        url: `https://vercel.com/${teamId}/${p.name}`,
+    }));
+}
+/**
+ * Reconstruct the Neon project id + `develop` branch id (read-only). Filters the
+ * org's projects by slug; once the project resolves, lists its branches to find
+ * the `develop` one. A branch lookup failure leaves the branch id `unknown`
+ * without failing the whole adopt (issue §4).
+ */
+async function adoptNeon(slug, apiKey, deps, recordAmbiguity) {
+    const projects = await listNeonProjects(apiKey, { fetchImpl: deps.fetchImpl });
+    const matches = projects.filter((p) => p.name === slug || p.name.includes(slug) || slug.includes(p.name));
+    const exact = matches.filter((p) => p.name === slug);
+    const pool = exact.length === 1 ? exact : matches;
+    const candidates = pool.map((p) => ({
+        id: p.id,
+        name: p.name,
+        url: `https://console.neon.tech/app/projects/${p.id}`,
+    }));
+    const projectId = await resolveCandidate('Neon', candidates, deps, recordAmbiguity);
+    if (!projectId)
+        return { projectId: null, branchDevId: null };
+    // Resolve the develop branch (best-effort — a failure → unknown, not a hard stop).
+    let branchDevId = null;
+    try {
+        const branches = await listNeonBranches(apiKey, projectId, { fetchImpl: deps.fetchImpl });
+        branchDevId = branches.find((b) => b.name === NEON_DEVELOP_BRANCH)?.id ?? null;
+    }
+    catch {
+        branchDevId = null;
+    }
+    return { projectId, branchDevId };
+}
+/**
+ * Reconstruct the GitHub repo (read-only) via `gh repo view {org}/{slug} --json
+ * name,url`. A missing repo (`gh` exit ≠ 0) → `null` (recorded `unknown`), never a
+ * hard failure (issue §4). The canonical org/slug is the only candidate, so no
+ * disambiguation is needed here.
+ */
+async function adoptGithub(slug, deps) {
+    const runGh = deps.runGh ?? ghRun;
+    const repo = `${FACTORY_ORG}/${slug}`;
+    try {
+        const { stdout } = await runGh(['repo', 'view', repo, '--json', 'name,url']);
+        const parsed = JSON.parse(stdout);
+        // A successful view confirms the repo exists; record the canonical `org/slug`.
+        return parsed.name ? repo : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reconstruct the interim domains' DNS presence (read-only). The domain NAMES are
+ * always derivable from the slug (never `unknown`); this only CONFIRMS the CNAMEs
+ * exist (a missing/unauthorized Cloudflare token logs a notice and continues — the
+ * domains are still recorded by name). Returns the `{ dev, prod }` names regardless.
+ */
+async function adoptDns(slug, deps) {
+    const domains = provisionDomains(slug);
+    const cfToken = readCloudflareApiKey(deps.envPath ?? defaultEnvPath());
+    if (!cfToken) {
+        console.warn('⚠ No hay `CLOUDFLARE_API_TOKEN` en el rail — registro los dominios por nombre sin ' +
+            'confirmar sus CNAMEs (es read-only; corre `factory secrets <archivo>` si quieres la verificación).');
+        return domains;
+    }
+    try {
+        const cfDeps = { fetchImpl: deps.fetchImpl };
+        const zoneId = await resolveZoneId(cfToken, cfDeps);
+        for (const name of [domains.dev, domains.prod]) {
+            const record = await findCnameRecord(zoneId, name, cfToken, cfDeps);
+            console.log(record
+                ? `  ✔ CNAME ${name} encontrado (${record.content})`
+                : `  · CNAME ${name} no encontrado (lo registro por nombre igual)`);
+        }
+    }
+    catch {
+        // A read-only DNS check failure must never fail the adopt (issue §4).
+        console.warn(`⚠ No se pudo verificar los CNAMEs en Cloudflare (read-only) — continúo.`);
+    }
+    return domains;
+}
+/** Print the reconstructed adopt state in plain es-MX (the non-`--json` narration). */
+function printAdoptState(result) {
+    const s = result.state;
+    console.log(`\nEstado reconstruido para \`${s.slug}\` (lifecycle: ${s.lifecycle}):`);
+    console.log(`  Vercel project:   ${s.vercelProjectId}`);
+    console.log(`  Neon project:     ${s.neonProjectId}`);
+    console.log(`  Neon develop:     ${s.neonBranchDevId}`);
+    console.log(`  GitHub repo:      ${s.githubRepo}`);
+    console.log(`  Dominio dev:      ${s.domains.dev}`);
+    console.log(`  Dominio prod:     ${s.domains.prod}`);
+    if (result.dryRun) {
+        console.log('\n(`--dry-run`) No se escribió `.timekast/provision.json`.');
+    }
+}
+/**
+ * `factory provision --adopt` (PROV-007). Reconstruct `.timekast/provision.json`
+ * for an EXISTING derived project by querying the providers STRICTLY read-only —
+ * never a POST/DELETE/PATCH. The slug is the project dir name; each provider is
+ * queried via its GET endpoint, ambiguities are resolved by a numbered prompt
+ * (interactive) or surfaced in `--json` (external resolution), a provider with no
+ * token/access/response is recorded `unknown` and the run continues, and the final
+ * state is written with `lifecycle: 'live'` + `adoptedAt`. `--dry-run` runs all the
+ * GETs and prints the state WITHOUT writing the file.
+ *
+ * Existence guard (issue §4): a state file already present → without `--force`,
+ * throw a clear `CLIError`; with `--force`, overwrite.
+ *
+ * @throws {CLIError} when a state already exists and `--force` was not passed.
+ */
+export async function runAdopt(flags, deps = {}) {
+    const rootDir = process.cwd();
+    // Existence guard up-front (friendlier message than the writer's last-line guard).
+    if (!flags.dryRun && hasProvisionState(rootDir) && !flags.force) {
+        throw new CLIError('Ya existe `.timekast/provision.json` (este proyecto ya fue adoptado o provisionado). ' +
+            'Usa `--force` para sobrescribirlo con un nuevo adopt, o déjalo como está.');
+    }
+    // The slug is the dir name — a LOW-TRUST identifier that flows into provider
+    // lookups + the persisted state. Re-validate it as a subdomain label BEFORE any
+    // use (FIX 2): a malformed dir name (leading `-`, underscore, …) is rejected,
+    // never passed to a REST query or recorded.
+    const slug = basename(rootDir);
+    assertValidSubdomainSlug(slug);
+    const envPath = deps.envPath ?? defaultEnvPath();
+    // Headless detection keys off STDIN (whether a human can answer), not STDOUT
+    // (which is redirected by pipes) — unify with `--destroy` (FIX 3).
+    const headless = deps.headless ?? !process.stdin.isTTY;
+    const adeps = { ...deps, envPath, headless };
+    const candidates = {};
+    // Vercel (GET /v9/projects) — needs the team scope + the rail token. No token /
+    // no team / a REST failure → `unknown`, continue (issue §4).
+    let vercelProjectId = null;
+    const vercelToken = readVercelToken(envPath);
+    if (vercelToken && flags.team) {
+        try {
+            vercelProjectId = await adoptVercel(slug, flags.team, vercelToken, adeps, (list) => {
+                candidates.vercel = list;
+            });
+        }
+        catch {
+            console.warn('⚠ No se pudo consultar Vercel (read-only) — registro `vercelProjectId: unknown`.');
+        }
+    }
+    else {
+        console.warn('⚠ Sin `VERCEL_TOKEN` en el rail o sin `--team` — omito Vercel (`vercelProjectId: unknown`). ' +
+            'Corre `factory secrets <archivo>` y pasa `--team` para completarlo con otro `--adopt`.');
+    }
+    // Neon (GET /projects + branches) — needs the rail key. Absent → `unknown` (the
+    // Gherkin "Provider Neon sin token disponible" path).
+    let neonProjectId = null;
+    let neonBranchDevId = null;
+    const neonApiKey = readNeonApiKey(envPath);
+    if (neonApiKey) {
+        try {
+            const neon = await adoptNeon(slug, neonApiKey, adeps, (list) => {
+                candidates.neon = list;
+            });
+            neonProjectId = neon.projectId;
+            neonBranchDevId = neon.branchDevId;
+        }
+        catch {
+            console.warn('⚠ No se pudo consultar Neon (read-only) — registro `neonProjectId: unknown`.');
+        }
+    }
+    else {
+        console.warn('⚠ Sin `NEON_API_KEY` en el rail — omito Neon (`neonProjectId: unknown`). ' +
+            'Completa con `factory provision --adopt` después de `factory secrets <archivo>`.');
+    }
+    // GitHub (gh repo view) — uses the dev's gh auth (no rail token needed).
+    const githubRepo = await adoptGithub(slug, adeps);
+    // DNS (GET dns_records) — domain names always derivable; CNAME check best-effort.
+    const domains = await adoptDns(slug, adeps);
+    const partial = {
+        slug,
+        vercelProjectId: vercelProjectId ?? ADOPT_UNKNOWN,
+        neonProjectId: neonProjectId ?? ADOPT_UNKNOWN,
+        neonBranchDevId: neonBranchDevId ?? ADOPT_UNKNOWN,
+        githubRepo: githubRepo ?? ADOPT_UNKNOWN,
+        domains,
+    };
+    // Build the state object (the writer also stamps these; for `--dry-run` we build
+    // it here so the printed/returned shape matches exactly what WOULD be written).
+    const now = deps.now ?? (() => new Date());
+    const state = {
+        lifecycle: 'live',
+        slug,
+        vercelProjectId: partial.vercelProjectId,
+        neonProjectId: partial.neonProjectId,
+        neonBranchDevId: partial.neonBranchDevId,
+        githubRepo: partial.githubRepo,
+        domains,
+        adoptedAt: now().toISOString(),
+    };
+    const result = { state, dryRun: flags.dryRun, candidates };
+    // `--dry-run`: print/emit the reconstructed state, write NOTHING (issue §4).
+    if (flags.dryRun) {
+        if (flags.json)
+            console.log(JSON.stringify(result, null, 2));
+        else
+            printAdoptState(result);
+        return result;
+    }
+    // Persist atomically with lifecycle:'live' + adoptedAt (the writer re-stamps the
+    // clock; pass the same `now` so the written state matches the returned one).
+    const written = adoptState(rootDir, partial, { force: flags.force, now });
+    result.state = written;
+    if (flags.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        printAdoptState(result);
+        console.log('\n✔ `.timekast/provision.json` escrito (lifecycle: live).');
+    }
+    return result;
+}
+/** Default `gh` runner — the dev's gh session (never a shared org token) via execa. */
+async function ghDelete(args) {
+    const { stdout } = await execa('gh', args);
+    return { stdout };
+}
+/** Default `vercel` runner — the dev's vercel CLI (never a shared org token) via execa. */
+async function vercelDelete(args) {
+    const { stdout } = await execa('vercel', args);
+    return { stdout };
+}
+/** Default type-to-confirm — a `prompts` text input (empty/Esc → '', i.e. a mismatch). */
+async function promptText(message) {
+    const { answer } = await prompts({ type: 'text', name: 'answer', message });
+    return typeof answer === 'string' ? answer : '';
+}
+/** Build the read-only list of what `--destroy` WOULD remove (the `--dry-run` plan). */
+function describeDestroyPlan(target) {
+    const lines = [];
+    if (target.neonProjectId) {
+        if (target.lifecycle === 'ephemeral') {
+            lines.push(`  － Neon project ${target.neonProjectId} (NUKE completo: branches + data) — DELETE /api/v2`);
+        }
+        else if (target.neonBranchDevId) {
+            lines.push(`  － Neon branch develop ${target.neonBranchDevId} (proyecto ${target.neonProjectId} se conserva) — DELETE /api/v2`);
+        }
+    }
+    for (const domain of target.domains) {
+        lines.push(`  － Dominio Vercel ${domain} — DELETE /v9/projects/.../domains`);
+        lines.push(`  － CNAME Cloudflare ${domain} — DELETE /zones/.../dns_records`);
+    }
+    if (target.vercelProjectId) {
+        lines.push(`  － Proyecto Vercel ${target.vercelProjectId} — \`vercel remove\` (sesión del dev)`);
+    }
+    if (target.githubRepo) {
+        lines.push(`  － Repo GitHub ${target.githubRepo} — \`gh repo delete\` (sesión del dev)`);
+    }
+    if (lines.length === 0) {
+        lines.push('  (No hay recursos registrados que destruir — el estado no tiene ids.)');
+    }
+    return lines;
+}
+/**
+ * Delete the Neon `develop` branch with the dev's NEON_API_KEY — the
+ * `deleteE2EBranch` pattern from `scripts/tools/neon-branch.ts` (DELETE
+ * /api/v2/projects/{id}/branches/{branchId}). A 404 (already gone) is "already
+ * clean" (§8). The shared org create-only key is NEVER used to delete.
+ */
+async function destroyNeonBranch(target, apiKey, fetchImpl) {
+    const resource = `Neon branch develop (${target.neonBranchDevId})`;
+    if (!target.neonProjectId || !target.neonBranchDevId) {
+        return { resource: 'Neon branch develop', status: 'skipped', detail: 'sin id en el estado' };
+    }
+    try {
+        const response = await fetchImpl(`${NEON_API_BASE}/projects/${encodeURIComponent(target.neonProjectId)}/branches/${encodeURIComponent(target.neonBranchDevId)}`, {
+            method: 'DELETE',
+            headers: { Authorization: `Bearer ${apiKey}`, Accept: 'application/json' },
+            signal: AbortSignal.timeout(30_000),
+        });
+        if (response.ok || response.status === 404) {
+            return {
+                resource,
+                status: 'removed',
+                detail: response.status === 404 ? 'ya estaba borrado (404)' : 'eliminado',
+            };
+        }
+        return { resource, status: 'failed', detail: `Neon respondió ${response.status}` };
+    }
+    catch (error) {
+        return { resource, status: 'failed', detail: error?.message ?? 'error de red' };
+    }
+}
+/**
+ * Nuke the ENTIRE Neon project (`deleteNeonProject` → DELETE /projects/{id}) — the
+ * `ephemeral` teardown blast radius (FIX 8). Unlike {@link destroyNeonBranch}
+ * (which removes only `develop` and preserves production `main` for a `live`
+ * stack), this removes the project + all its branches + data. It needs ONLY the
+ * project id, so it also tears down a PARTIAL stack whose develop branch never got
+ * created (FIX 9). A 404 → already gone (§8). The dev's key does this, never the
+ * shared org create-only key.
+ */
+async function destroyNeonProject(target, apiKey, fetchImpl) {
+    const resource = `Neon project (${target.neonProjectId})`;
+    if (!target.neonProjectId) {
+        return { resource: 'Neon project', status: 'skipped', detail: 'sin id en el estado' };
+    }
+    try {
+        await deleteNeonProject(apiKey, target.neonProjectId, { fetchImpl });
+        // Project gone — clean the project-scoped API key(s) it minted (`{slug}-e2e`)
+        // so the Neon org does not accumulate dead keys across provisions/tests.
+        // Best-effort (never throws): the project nuke already succeeded.
+        const keysDeleted = await deleteNeonApiKeysByName(apiKey, `${target.slug}-e2e`, { fetchImpl });
+        return {
+            resource,
+            status: 'removed',
+            detail: keysDeleted > 0
+                ? `proyecto + ${keysDeleted} API key(s) eliminados (nuke)`
+                : 'proyecto eliminado (nuke)',
+        };
+    }
+    catch (error) {
+        const detail = error instanceof NeonApiError
+            ? `Neon respondió ${error.status}`
+            : (error?.message ?? 'error de red');
+        return { resource, status: 'failed', detail };
+    }
+}
+/**
+ * Remove a domain from the Vercel project via the REST API (the dev's
+ * `VERCEL_TOKEN`). 404 → already gone (§8). A team scope is required; absent →
+ * skipped (the domain stays, reported). Mirrors {@link removeVercelDomain}'s 404
+ * tolerance.
+ */
+async function destroyVercelDomain(domain, projectId, teamId, token, fetchImpl) {
+    const resource = `Dominio Vercel ${domain}`;
+    try {
+        const outcome = await removeVercelDomain(projectId, domain, token, teamId, { fetchImpl });
+        return {
+            resource,
+            status: 'removed',
+            detail: outcome === 'absent' ? 'ya estaba removido (404)' : 'removido',
+        };
+    }
+    catch (error) {
+        return { resource, status: 'failed', detail: error?.message ?? 'error' };
+    }
+}
+/**
+ * Delete the Cloudflare CNAME for a domain with the dev's own `CLOUDFLARE_API_TOKEN`
+ * (the shared org token is DNS-EDIT but create-only by policy; the dev's token does the
+ * delete). A missing record (no CNAME) → "already clean", never a failure (§8 —
+ * a derivative with no domain configured simply has nothing to remove).
+ */
+async function destroyCloudflareRecord(domain, zoneId, token, fetchImpl) {
+    const resource = `CNAME Cloudflare ${domain}`;
+    try {
+        const record = await findCnameRecord(zoneId, domain, token, {
+            fetchImpl,
+        });
+        if (!record) {
+            return { resource, status: 'removed', detail: 'no había registro (ya limpio)' };
+        }
+        const response = await fetchImpl(`${CLOUDFLARE_API_BASE}/zones/${encodeURIComponent(zoneId)}/dns_records/${encodeURIComponent(record.id)}`, {
+            method: 'DELETE',
+            headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+            signal: AbortSignal.timeout(30_000),
+        });
+        if (response.ok || response.status === 404) {
+            return { resource, status: 'removed', detail: 'eliminado' };
+        }
+        return { resource, status: 'failed', detail: `Cloudflare respondió ${response.status}` };
+    }
+    catch (error) {
+        return { resource, status: 'failed', detail: error?.message ?? 'error' };
+    }
+}
+/**
+ * Remove the Vercel PROJECT via the dev's `vercel` CLI (`vercel remove <slug>
+ * --yes`) — issue §4: the project delete uses the DEV's session, never a shared org
+ * token (the shared org Vercel token is create/configure-only). A "not found" stderr
+ * is treated as already-removed (§8).
+ */
+async function destroyVercelProject(target, runVercel) {
+    const resource = `Proyecto Vercel ${target.slug}`;
+    // FIX 2: the slug came from the low-trust state file and is about to become a
+    // positional arg to `vercel remove`. A malformed slug (leading `-` = flag
+    // smuggling, or a non-subdomain shape) is NEVER passed to the command. It is a
+    // `failed` (not a silent skip) because a Vercel project IS recorded but cannot be
+    // torn down — so `hadFailures` keeps the state (no orphan), per FIX 3.
+    if (!isValidSubdomainSlug(target.slug)) {
+        return {
+            resource: 'Proyecto Vercel',
+            status: 'failed',
+            detail: `slug malformado en el estado (\`${target.slug}\`) — bórralo a mano en Vercel`,
+        };
+    }
+    try {
+        // `--` ends option parsing so the slug can never be read as a flag.
+        await runVercel(['remove', '--yes', '--', target.slug]);
+        return { resource, status: 'removed', detail: 'eliminado vía `vercel remove`' };
+    }
+    catch (error) {
+        const message = error?.message ?? '';
+        if (/not found|no such|does not exist|404/i.test(message)) {
+            return { resource, status: 'removed', detail: 'ya no existía (vercel)' };
+        }
+        return { resource, status: 'failed', detail: message || 'error en `vercel remove`' };
+    }
+}
+/**
+ * Delete the GitHub repo via the dev's `gh` session (`gh repo delete {org/slug}
+ * --yes`) — issue §4: NEVER a shared org token (shared org tokens are create-only). A
+ * "not found" is already-deleted (§8).
+ */
+async function destroyGithubRepo(target, runGh) {
+    const resource = `Repo GitHub ${target.githubRepo}`;
+    if (!target.githubRepo) {
+        return { resource: 'Repo GitHub', status: 'skipped', detail: 'sin repo en el estado' };
+    }
+    // FIX 2 defense-in-depth: `readDestroyTarget` already dropped a malformed repo
+    // to `null` (so `!target.githubRepo` caught it), but re-check the `owner/repo`
+    // shape here — a value starting with `-` could smuggle a flag into `gh`.
+    if (target.githubRepo.startsWith('-') ||
+        !/^[A-Za-z0-9_.][A-Za-z0-9_.-]*\/[A-Za-z0-9_.][A-Za-z0-9_.-]*$/.test(target.githubRepo)) {
+        return {
+            resource: 'Repo GitHub',
+            status: 'skipped',
+            detail: `repo malformado en el estado (\`${target.githubRepo}\`) — bórralo a mano`,
+        };
+    }
+    try {
+        // `--` ends option parsing so the repo can never be read as a flag.
+        await runGh(['repo', 'delete', '--yes', '--', target.githubRepo]);
+        return { resource, status: 'removed', detail: 'eliminado vía `gh repo delete`' };
+    }
+    catch (error) {
+        const message = error?.message ?? '';
+        if (/not found|could not resolve|404/i.test(message)) {
+            return { resource, status: 'removed', detail: 'ya no existía (gh)' };
+        }
+        return { resource, status: 'failed', detail: message || 'error en `gh repo delete`' };
+    }
+}
+/**
+ * Orchestrate the per-provider teardown (issue §4 + §8). Each provider failure is
+ * logged and the run CONTINUES with the others; the outcomes are collected so the
+ * caller can report what was NOT removed. Order: Neon branch → (per domain: Vercel
+ * domain + Cloudflare CNAME) → Vercel project → GitHub repo. Resource-delete tokens
+ * are the DEV's (Neon/Cloudflare from the rail, Vercel/GitHub from the dev's CLI
+ * session) — NEVER the shared org create-only tokens.
+ */
+async function teardownProviders(target, deps) {
+    const outcomes = [];
+    // 1. Neon — blast radius BY LIFECYCLE (FIX 8/9/10):
+    //    · ephemeral → nuke the WHOLE project (needs only neonProjectId, so it also
+    //      cleans a PARTIAL stack whose develop branch never got created).
+    //    · live      → remove ONLY the develop branch, preserving production `main`.
+    //    A missing Neon key is a `failed` outcome (keeps the state + flags the orphan),
+    //    NEVER a silent skip that drops the state with a project still alive.
+    const neonKey = readNeonApiKey(deps.envPath);
+    if (target.neonProjectId) {
+        if (!neonKey) {
+            outcomes.push({
+                resource: target.lifecycle === 'ephemeral'
+                    ? `Neon project (${target.neonProjectId})`
+                    : `Neon branch develop (${target.neonBranchDevId})`,
+                status: 'failed',
+                detail: 'sin `NEON_API_KEY` en el rail — bórralo a mano',
+            });
+        }
+        else if (target.lifecycle === 'ephemeral') {
+            outcomes.push(await destroyNeonProject(target, neonKey, deps.fetchImpl));
+        }
+        else if (target.neonBranchDevId) {
+            outcomes.push(await destroyNeonBranch(target, neonKey, deps.fetchImpl));
+        }
+        // live + no develop branch → nothing to remove (production `main` is preserved).
+    }
+    // 2. Per domain — remove from Vercel AND delete the Cloudflare CNAME (§8: no
+    //    domain configured → nothing to remove; a single provider failure continues).
+    const vercelToken = readVercelToken(deps.envPath);
+    const cfToken = readCloudflareApiKey(deps.envPath);
+    let zoneId = null;
+    for (const domain of target.domains) {
+        // The domain is registered in the state, so there IS a resource to remove. If
+        // a prerequisite is missing (FIX 3: e.g. `scope` null on an adopted stack, or
+        // no token), emit `failed` — NOT a silent skip — so `hadFailures` keeps the
+        // state and the dev knows a live domain was left behind, not orphaned silently.
+        if (!target.vercelProjectId) {
+            outcomes.push({
+                resource: `Dominio Vercel ${domain}`,
+                status: 'failed',
+                detail: 'sin `vercelProjectId` en el estado — retíralo a mano en Vercel',
+            });
+        }
+        else if (!target.scope) {
+            outcomes.push({
+                resource: `Dominio Vercel ${domain}`,
+                status: 'failed',
+                detail: 'sin `scope`/team en el estado (¿stack adoptado?) — retíralo a mano en Vercel',
+            });
+        }
+        else if (!vercelToken) {
+            outcomes.push({
+                resource: `Dominio Vercel ${domain}`,
+                status: 'failed',
+                detail: 'sin `VERCEL_TOKEN` en el rail — retíralo a mano en Vercel',
+            });
+        }
+        else {
+            outcomes.push(await destroyVercelDomain(domain, target.vercelProjectId, target.scope, vercelToken, deps.fetchImpl));
+        }
+        if (!cfToken) {
+            outcomes.push({
+                resource: `CNAME Cloudflare ${domain}`,
+                status: 'failed',
+                detail: 'sin `CLOUDFLARE_API_TOKEN` en el rail — borra el CNAME a mano',
+            });
+        }
+        else {
+            try {
+                if (zoneId === null) {
+                    zoneId = await resolveZoneIdForName(apexZoneOf(domain), cfToken, {
+                        fetchImpl: deps.fetchImpl,
+                    });
+                }
+                outcomes.push(await destroyCloudflareRecord(domain, zoneId, cfToken, deps.fetchImpl));
+            }
+            catch (error) {
+                outcomes.push({
+                    resource: `CNAME Cloudflare ${domain}`,
+                    status: 'failed',
+                    detail: error?.message ?? 'no se resolvió la zona',
+                });
+            }
+        }
+    }
+    // 3. Vercel PROJECT — the dev's `vercel remove` (NEVER a shared org token).
+    if (target.vercelProjectId) {
+        outcomes.push(await destroyVercelProject(target, deps.runVercel));
+    }
+    // 4. GitHub repo — the dev's `gh repo delete` (NEVER a shared org token).
+    if (target.githubRepo) {
+        outcomes.push(await destroyGithubRepo(target, deps.runGh));
+    }
+    return outcomes;
+}
+/** Print the per-provider teardown report (es-MX) and flag the not-removed ones. */
+function printDestroyReport(outcomes) {
+    for (const o of outcomes) {
+        const mark = o.status === 'removed' ? '✔' : o.status === 'skipped' ? '⏭' : '✖';
+        console.log(`  ${mark} ${o.resource}: ${o.detail}`);
+    }
+    const failed = outcomes.filter((o) => o.status === 'failed');
+    if (failed.length > 0) {
+        console.warn(`\n⚠ ${failed.length} recurso(s) NO se eliminaron — bórralos a mano:\n` +
+            failed.map((o) => `    · ${o.resource} (${o.detail})`).join('\n'));
+    }
+}
+/**
+ * `factory provision --destroy` (PROV-008). Tear down a derived stack, reading the
+ * state's `lifecycle` as the single authority:
+ *
+ *   - No state file        → `CLIError` ("ejecuta `--adopt` primero").
+ *   - Headless (no TTY / `--json`) → `CLIError` BEFORE any op (agente-only).
+ *   - `lifecycle: live` WITHOUT `--force`  → refuse, zero deletes.
+ *   - `lifecycle: live` WITH `--force`     → type-to-confirm the slug; mismatch → abort.
+ *   - `lifecycle: ephemeral`               → auto-nuke (no `--force` needed; `--force`
+ *                                            is a no-op — no type-to-confirm).
+ *   - `--dry-run`          → list the resources + tools, mutate NOTHING.
+ *
+ * Resource-delete tokens are the DEV's (Neon/Cloudflare from the rail; Vercel/GitHub
+ * from the dev's CLI session) — NEVER the shared org create-only tokens. A provider
+ * failure is logged and the teardown continues; the state file is cleared ONLY when
+ * every provider succeeded (issue §4 + §8).
+ *
+ * @throws {CLIError} on no-state, headless, a `live` refusal, or a confirm mismatch.
+ */
+export async function runDestroy(flags, deps = {}) {
+    // 1. 🔴 Guard no-headless — BEFORE any op (issue §4 + §6). `--json` OR no TTY is
+    //    headless; `--destroy` is agente-only (never the TUI/SaaS).
+    const isTty = deps.isTty ?? Boolean(process.stdin.isTTY);
+    if (!isTty || flags.json) {
+        throw new CLIError('--destroy requiere sesión interactiva (no headless)', 1);
+    }
+    const rootDir = deps.rootDir ?? process.cwd();
+    // 2. Read the state — the SINGLE authority. Absent → run `--adopt` first (§4).
+    const target = readDestroyTarget(rootDir);
+    if (!target) {
+        throw new CLIError('Sin provision state. Ejecuta --adopt primero.', 1);
+    }
+    // 3. Lifecycle guard (issue §4). `live` refuses unless `--force`; `live` + `--force`
+    //    requires type-to-confirm. `ephemeral` auto-nukes (`--force` has no extra effect).
+    if (target.lifecycle === 'live') {
+        if (!flags.force) {
+            throw new CLIError('Este derivado está marcado como live. Usa `--force` solo si estás seguro.', 1);
+        }
+        if (!flags.dryRun) {
+            const prompt = deps.prompt ?? promptText;
+            const answer = await prompt(`Escribe el slug del proyecto (\`${target.slug}\`) para confirmar la destrucción: `);
+            if (answer.trim() !== target.slug) {
+                throw new CLIError('Confirmación incorrecta. Operación cancelada.', 1);
+            }
+        }
+    }
+    // 4. `--dry-run` — list what WOULD be destroyed, mutate NOTHING (issue §4).
+    if (flags.dryRun) {
+        console.log(`Plan de \`--destroy\` para \`${target.slug}\` (lifecycle: ${target.lifecycle}):`);
+        for (const line of describeDestroyPlan(target))
+            console.log(line);
+        console.log('\n(`--dry-run`) No se ejecutó ninguna eliminación ni se borró el estado.');
+        return {
+            slug: target.slug,
+            lifecycle: target.lifecycle,
+            dryRun: true,
+            outcomes: [],
+            hadFailures: false,
+        };
+    }
+    // 5. Teardown — per provider, continuing past failures (issue §8).
+    console.log(`Destruyendo \`${target.slug}\` (lifecycle: ${target.lifecycle})…`);
+    const outcomes = await teardownProviders(target, {
+        fetchImpl: deps.fetchImpl ?? fetch,
+        envPath: deps.envPath ?? defaultEnvPath(),
+        runGh: deps.runGh ?? ghDelete,
+        runVercel: deps.runVercel ?? vercelDelete,
+    });
+    printDestroyReport(outcomes);
+    const hadFailures = outcomes.some((o) => o.status === 'failed');
+    // 6. Clear the state ONLY on a fully-successful teardown (issue §4). A partial
+    //    failure keeps the state so a `--resume`-style re-run can finish the job.
+    if (!hadFailures) {
+        clearState(rootDir);
+        console.log('\n✔ Destrucción completa. `.timekast/provision.json` eliminado.');
+    }
+    else {
+        console.warn('\n⚠ Quedaron recursos sin eliminar — conservo `.timekast/provision.json` ' +
+            'para que puedas reintentar tras borrarlos a mano.');
+    }
+    return { slug: target.slug, lifecycle: target.lifecycle, dryRun: false, outcomes, hadFailures };
+}
+/**
+ * `factory provision` entrypoint. Flag-driven, headless-safe scaffold:
+ *
+ *   1. Validate flags (at least one service; sane combos).
+ *   2. Resolve state: `--force` discards it; `--resume` reads it (tolerating
+ *      corruption with a `--force` hint); a fresh run refuses to clobber an
+ *      existing state without `--resume`/`--force`.
+ *   3. `--dry-run` prints the plan and returns — NO preflight network call, NO
+ *      state write.
+ *   4. Preflight (fail-closed: gh + rail tokens + Vercel team; neonctl optional).
+ *   5. Run each pending step (today: stubs) and persist state atomically after
+ *      each — so a mid-run failure leaves completed steps durable for `--resume`.
+ *
+ * @throws {CLIError | PreflightError} on any expected failure.
+ */
+export async function runProvision(flags) {
+    // Resolve the Vercel team-id from the rail (`VERCEL_TEAM_ID` in `~/.claude/.env`)
+    // when `--team` is omitted. The team-id is org-fixed config, NOT a per-run flag —
+    // it lives in the rail alongside the tokens, so devs never pass
+    // it. `--team` stays as an explicit override. Never hardcoded in source (CODING.md §5).
+    if (!flags.team) {
+        const railTeam = readGateValue('VERCEL_TEAM_ID', defaultEnvPath());
+        if (railTeam)
+            flags.team = railTeam;
+    }
+    // `--destroy` (PROV-008) tears a stack down. It is agente-only (refuses headless)
+    // and reads the state's `lifecycle` as the single authority. It wins over every
+    // other mode (a `--destroy --adopt` is destroy, not a re-adopt).
+    if (flags.destroy) {
+        return runDestroy(flags);
+    }
+    // `--adopt` (PROV-007) is a read-only backfill mode that bypasses the entire
+    // service-create path: it reconstructs the state from existing resources and
+    // never creates/deletes anything. It wins over `--services` (mutual-exclusive).
+    if (flags.adopt) {
+        return runAdopt(flags);
+    }
+    // `--domain` is a valid STANDALONE operation (PROV-006 patch mode): it may run
+    // with no `--services` (a deferred go-live over an existing provision) or
+    // alongside the initial run. It always runs AFTER the service steps.
+    const hasDomain = Boolean(flags.domain);
+    // 1. Flag validation.
+    if (flags.services.length === 0 && !hasDomain) {
+        throw new CLIError('No seleccionaste servicios. Usa `--services=neon,vercel,github,dns` ' +
+            `(válidos: ${KNOWN_SERVICES.join(', ')}), o \`--domain=<dominio>\` para el dominio del cliente.`);
+    }
+    // The Vercel env-sync (`vercel`), the project-create (`github`, PROV-004), the
+    // domain attach (`dns`, PROV-005) AND the client domain (`--domain`, PROV-006) all
+    // hit the team-scoped Vercel API — the project lives on the team, not the account.
+    if ((flags.services.includes('vercel') ||
+        flags.services.includes('github') ||
+        flags.services.includes('dns') ||
+        hasDomain) &&
+        !flags.team) {
+        throw new CLIError('El provision de Vercel/GitHub/DNS y `--domain` requieren el team del org. ' +
+            'Agrégalo al rail como `VERCEL_TEAM_ID=<teamId>` en `~/.claude/.env` (impórtalo con `factory secrets <archivo>`) ' +
+            'o pásalo con `--team=<teamId>`.');
+    }
+    const rootDir = process.cwd();
+    const lifecycle = flags.ephemeral ? 'ephemeral' : 'live';
+    // A STANDALONE `--domain` patch (no services) requires an existing state to
+    // patch — it cannot clobber, so it is treated like `--resume` for state-reading.
+    const standaloneDomain = hasDomain && flags.services.length === 0;
+    // 2. Resolve state. `--force` wins over `--resume` (issue §8): discard + restart.
+    if (flags.force) {
+        clearProvisionState(rootDir);
+    }
+    let state = null;
+    if ((flags.resume || standaloneDomain) && !flags.force) {
+        state = readProvisionState(rootDir); // throws CLIError on corrupt → hints --force
+        if (!state) {
+            throw new CLIError(standaloneDomain
+                ? '`--domain` en modo patch requiere un provision existente (`.timekast/provision.json`), ' +
+                    'pero no hay estado. Corre el provision inicial (`--services=...`) primero.'
+                : 'No hay estado de provision para retomar (`--resume`). Corre sin `--resume` para empezar.');
+        }
+    }
+    else if (!flags.force && flags.services.length > 0 && hasProvisionState(rootDir)) {
+        // A fresh (non-resume, non-force) service run must not clobber a prior state.
+        throw new CLIError('Ya existe un estado de provision (`.timekast/provision.json`). ' +
+            'Usa `--resume` para retomarlo o `--force` para descartarlo y empezar de cero.');
+    }
+    // In patch mode the projectName comes from the loaded state (the interim slug);
+    // a fresh run derives it from flags (the scaffold default).
+    const projectName = state?.projectName ?? deriveProjectName(flags, rootDir);
+    const steps = buildPlan(flags.services, state);
+    const result = {
+        projectName,
+        lifecycle: state?.lifecycle ?? lifecycle,
+        dryRun: flags.dryRun,
+        resumed: (flags.resume || standaloneDomain) && !flags.force,
+        steps,
+    };
+    if (hasDomain) {
+        result.clientDomain = { domain: flags.domain, route: flags.dns };
+    }
+    // 3. Dry-run: print the plan, touch nothing (no preflight network, no state).
+    if (flags.dryRun) {
+        if (flags.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            if (steps.length > 0)
+                printPlan(result);
+            if (hasDomain) {
+                const interim = provisionDomains(projectName).prod;
+                printClientDomainPlan(flags.domain, interim, flags.dns, flags.confirm);
+            }
+        }
+        return result;
+    }
+    // 4. Preflight — fail-closed BEFORE any mutation. A standalone `--domain` patch
+    //    preflights as `dns` (it needs the Vercel token + team + Cloudflare token).
+    const preflightServices = flags.services.length > 0 ? flags.services : hasDomain ? ['dns'] : [];
+    const preflight = await runProvisionPreflight({ services: preflightServices, teamId: flags.team, repoSlug: `${FACTORY_ORG}/${projectName}` }, {});
+    if (preflight.neonctl.status === 'warn') {
+        result.neonctlWarning = preflight.neonctl.message;
+    }
+    // 5. Initialize / carry the state, then run each pending step, persisting
+    //    atomically after each (resumability — issue §6 + Gherkin).
+    const runState = state ?? {
+        projectName,
+        lifecycle,
+        scope: flags.team ?? flags.orgId ?? '',
+        createdAt: new Date().toISOString(),
+    };
+    // Ensure the state dir exists + a baseline file before the first step, so a
+    // step failure on the very first service still leaves a resumable state.
+    writeProvisionState(rootDir, runState);
+    for (const step of steps) {
+        if (step.action === 'skip')
+            continue;
+        await runServiceStep(step.service, rootDir, runState, flags);
+        // Persist after each create. PROV-002 (neon) already writes its state
+        // atomically inside the step; the remaining stubs record nothing yet, and
+        // this write keeps the baseline durable for them too.
+        writeProvisionState(rootDir, runState);
+    }
+    // 5b. Client domain (PROV-006) — runs AFTER the services so the Vercel project
+    //     (and the interim domains) already exist. Standalone patch or post-services.
+    if (hasDomain) {
+        // Headless = no STDIN to answer the interim-retire prompt (not STDOUT, which a
+        // pipe redirects) — unify with `--destroy` / `--adopt` (FIX 3).
+        const headless = !process.stdin.isTTY;
+        await provisionClientDomain(rootDir, runState, flags.team, flags.domain, {
+            dnsRoute: flags.dns,
+            verifyTimeoutMin: flags.verifyTimeout,
+            preConfirmed: flags.confirm,
+            headless,
+        });
+    }
+    // 5c. Persist the provision state to the repo (resource IDs) so a `--resume` from
+    //     a fresh clone has them. Only when the git substrate exists; best-effort.
+    if (runState.github?.done) {
+        await commitProvisionState(rootDir);
+    }
+    // 6. Report.
+    if (flags.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        warnNeonctl(preflight.neonctl);
+        if (steps.length > 0)
+            printPlan(result);
+        if (hasDomain) {
+            console.log(`\n✔ Dominio del cliente listo: ${flags.domain} (ruta ${flags.dns}).`);
+        }
+        else {
+            console.log(`\n✔ Scaffold de provision listo (lifecycle: ${lifecycle}). ` +
+                'Estado en `.timekast/provision.json`.');
+        }
+    }
+    return result;
+}