@timekast/factory 1.12.0 → 1.13.0

package/dist/commands/secrets.js

@@ -15,6 +15,10 @@
  *
  * The org gate is `runPreflight()` from `lib/preflight.ts` — the public API.
  * `preflight()` / `assertOrgMembership` are NOT public and are not called here.
+ *
+ * NOTE: the device-flow `secrets pull` + admin `secrets sync` (the org secrets
+ * gate, SECGATE-*) were REMOVED — that gate/droplet effort is parked. The interim
+ * model is this shared-file import; the future is Infisical (a fresh branch).
  */
 import { homedir } from 'node:os';
 import path from 'node:path';

package/dist/commands/status.js

@@ -26,6 +26,12 @@ import { isKitReleaseTag } from '../lib/unpack.js';
  * the tests assert on the exact rendered text (no magic string in the spec).
  */
 export const BETA_BANNER = '⚠️  cerebro BETA — corre `factory update --stable` para salir del canal';
+/** Parse `status`'s argv slice into flags. Unknown flags are ignored. */
+export function parseStatusFlags(argv) {
+    return {
+        json: argv.includes('--json'),
+    };
+}
 /**
  * Query the Factory repo for the latest published release, IGNORING prereleases
  * (`-rc`, `-test`, etc.) so a release candidate is never reported as latest.
@@ -48,8 +54,8 @@ async function fetchLatestRelease() {
             '30',
         ]);
         const releases = JSON.parse(stdout);
-        // Only consider the KIT release line (`v*`): the repo also hosts `launcher-v*`
-        // releases, which must never be mistaken for the latest kit version.
+        // Only consider the KIT release line (`v*`): the repo also hosts `gui-v*`
+        // launcher releases, which must never be mistaken for the latest kit version.
         const stable = releases.find((r) => !r.isPrerelease && isKitReleaseTag(r.tagName));
         if (!stable)
             return null;
@@ -151,8 +157,18 @@ function renderStatus(result) {
  * Run `factory status`. Always exits 0 — a missing lockfile and a network error
  * are advisory states, not failures (DIST-006 §8). Only an unexpected
  * programming bug would surface through the top-level handler.
+ *
+ * In `--json` mode (TGUI-003) the `StatusResult` is written as a single JSON
+ * object to stdout and NOTHING else: the human renderer (`console.log`) is
+ * suppressed so the GUI can `JSON.parse` stdout directly. Fail-open is unchanged
+ * — `computeStatus` already maps a missing lockfile / network error to flags
+ * instead of throwing, so the JSON path also exits 0 in those cases.
  */
-export async function runStatus(deps = {}) {
+export async function runStatus(deps = {}, flags = { json: false }) {
     const result = await computeStatus(deps);
+    if (flags.json) {
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+        return;
+    }
     renderStatus(result);
 }

package/dist/commands/update.js

@@ -47,6 +47,8 @@ import { extractManagedBlock, syncManagedBlock } from '../lib/gitattributes.js';
 import { diffLockfiles, hasLockfile, normalizeThenHash, planAutoRegister, readLockfile, writeLockfile, } from '../lib/lockfile.js';
 import { detectProfile, insertFactoryUpdateScript, setAgentKitVersion, } from '../lib/package-json.js';
 import { runPreflight } from '../lib/preflight.js';
+import { printProvisionPointer } from '../lib/provision-pointer.js';
+import { hasProvisionState } from '../lib/provision-state.js';
 import { detectRepo } from '../lib/repo-detection.js';
 import { downloadBetaProfileTarball, downloadProfileTarball, stageProfileTarball, } from '../lib/unpack.js';
 /** Parse `update`'s argv slice into flags. Unknown flags are ignored here. */
@@ -263,6 +265,10 @@ async function runResume(rootDir, flags) {
     await maybeCommitBrain(rootDir, newLock.version, [...state.plan.writes, ...state.plan.deletes], flags);
     rmSync(state.stagedDir, { recursive: true, force: true });
     console.log('✔ `update` retomado y completado.');
+    // A resumed update that succeeds completed the setup → show the end-pointer
+    // (PVSKILL-002 §8 edge: `--resume` SÍ lo muestra). Suppressed only in headless
+    // `--yes` (CI/launcher noise).
+    printProvisionPointer({ assumeYes: flags.yes });
 }
 /**
  * Stamp the birth seal onto the new manifest before it becomes the lockfile.
@@ -407,6 +413,41 @@ function reportSummary(diff, manifest) {
         `${diff.overwriteSilent.length} actualizados${unchanged}, ` +
         `${diff.deleteSilent.length} retirados${kept}, ${diff.conflicts.length} conflictos.`);
 }
+/**
+ * After a successful update, OFFER to run `factory provision --adopt` when the
+ * derived project has no `.timekast/provision.json` (PROV-007 AC). A pre-CLI
+ * derivative (provisioned before the adopt path existed) needs the backfill so
+ * `--destroy`/`--resume`/the TUI can operate on it.
+ *
+ * Interactive-only (issue §8 edge): it ONLY prompts on a TTY and NEVER when
+ * `--yes` was passed (the GUI/headless launcher). It does NOT run the adopt
+ * itself — it just points the dev at the command (the adopt needs `--team` + the
+ * gate tokens the update flow does not carry). Headless / `--yes` → no-op.
+ *
+ * `isTTY`/`hasState` are injectable so the unit test drives every branch without
+ * a real terminal or a real `.timekast/` dir.
+ */
+export async function maybeOfferAdopt(rootDir, flags, opts = {}) {
+    const isTTY = opts.isTTY ?? Boolean(process.stdout.isTTY);
+    const hasState = opts.hasState ?? hasProvisionState(rootDir);
+    // Only offer interactively (a TTY) and never under `--yes` (GUI/headless): the
+    // adopt is opt-in and needs flags the update flow does not have.
+    if (hasState || flags.yes || !isTTY)
+        return;
+    const ask = opts.prompt ?? prompts;
+    // A cancelled prompt (Esc) returns an empty object → null-safe read (no-op).
+    const answer = (await ask({
+        type: 'confirm',
+        name: 'adopt',
+        message: 'Este proyecto no tiene `.timekast/provision.json` (registro de infra). ' +
+            '¿Reconstruirlo ahora con `factory provision --adopt`? (read-only — no toca ningún recurso)',
+        initial: false,
+    }));
+    if (answer?.adopt === true) {
+        console.log('\nCorre:  `factory provision --adopt --team=<teamId>`\n' +
+            '  (asegúrate de tener los tokens en `~/.claude/.env`; impórtalos con `factory secrets <archivo>` primero).');
+    }
+}
 /**
  * Run `factory update`. Orchestrates the full flow; `deps.acquire` is the only
  * network seam (tests inject a local fixture).
@@ -489,6 +530,8 @@ export async function runUpdate(flags, deps = {}) {
         }
         if (legacy) {
             await applyLegacy(rootDir, stagedDir, manifest);
+            // Legacy auto-register succeeded → end-pointer (PVSKILL-002).
+            printProvisionPointer({ assumeYes: flags.yes });
             return;
         }
         // Hash only the union of tracked paths (old lock ∪ new manifest). Files
@@ -531,6 +574,10 @@ export async function runUpdate(flags, deps = {}) {
         maintainDerivedDotfiles(rootDir, stagedDir, manifest.version);
         await maybeCommitBrain(rootDir, manifest.version, [...plan.writes, ...plan.deletes], flags);
         reportSummary(diff, manifest);
+        // End-pointer to the next step (PVSKILL-002). Reached only after a clean apply;
+        // `--verify`/`--resume` short-circuit above (verify NEVER prints), an error path
+        // throws earlier, and headless `--yes` is suppressed (CI noise).
+        printProvisionPointer({ assumeYes: flags.yes });
     }
     finally {
         // Keep the staged tarball if an update-state survives (a post-apply failure —

package/dist/index.js

@@ -11,15 +11,16 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { CLIError } from './lib/cli-error.js';
 import { parseAddFlags, runAdd } from './commands/add.js';
-import { runBootstrapVersion } from './commands/bootstrap-version.js';
-import { runDoctor } from './commands/doctor.js';
-import { runLauncherPath } from './commands/launcher-path.js';
+import { parseDoctorFlags, runDoctor, runLauncherDoctor } from './commands/doctor.js';
 import { parseNewFlags, runNew } from './commands/new.js';
+import { parseProvisionFlags, runProvision } from './commands/provision.js';
 import { parsePublishArgs, runPublish } from './commands/publish.js';
 import { secretsCommand } from './commands/secrets.js';
-import { runStatus } from './commands/status.js';
+import { parseStatusFlags, runStatus } from './commands/status.js';
 import { parseUnpublishTargets, runUnpublish } from './commands/unpublish.js';
-import { parseUpdateFlags, runUpdate } from './commands/update.js';
+import { maybeOfferAdopt, parseUpdateFlags, runUpdate } from './commands/update.js';
+import { detectRepo } from './lib/repo-detection.js';
+import { runTuiMenu } from './tui/index.js';
 const HELP = `
 @timekast/factory — bootstrap y mantenimiento de proyectos derivados del Factory.
 
@@ -33,11 +34,11 @@ Comandos:
   beta             Atajo de \`update --beta\`: instala el cerebro del canal beta
   status           Reporta la versión instalada vs. la última disponible
   doctor           Detecta huérfanos, conflictos y rules sin importar + aviso de seguridad
+                   (--launcher: verifica el entorno — Node ≥ 22, gh, gh auth, membresía org)
   publish <qué>    Publica el entregable (proposal|mockup|both) a proposals.timekast.mx
   unpublish [qué]  Baja del hub un entregable publicado (proposal|mockup|both; default both)
+  provision        Aprovisiona la infra de un derivado (Neon/Vercel/GitHub/DNS) — flag-driven, --json
   secrets <file>   Mergea un archivo KEY=value de secretos de metodología a ~/.claude/.env (chmod 600)
-  launcher-path    (interno) Imprime el path del launcher.applescript empacado (lo usa el bootstrap)
-  bootstrap-version (interno) Imprime/compara la versión del bootstrap (\`--have <ver>\` → ok|outdated)
 
 Sobre \`new\`:
   Pregunta el perfil de forma interactiva. Los flags \`--full\` / \`--core\` lo
@@ -70,17 +71,45 @@ Sobre \`update\`:
   Un \`update\` sin \`--beta\` sobre un lockfile beta pide confirmación (y en headless
   rechaza, sin degradar en silencio).
 
+Sobre \`provision\`:
+  Aprovisiona la infra de un proyecto derivado. Flag-driven (sin prompts) y
+  headless-safe; la interacción la pone la skill \`tk-provision\`. Preflight
+  fail-closed (gh + tokens del gate + \`VERCEL_TOKEN\` con acceso al team);
+  \`neonctl\` es opcional (ausente → warning). Flags:
+    --services=a,b   Servicios a crear (neon,vercel,github,dns)
+    --slug=<slug>    Identificador del stack (nombre del proyecto + dominios interinos)
+    --team=<id>      Team de Vercel (override; default = \`VERCEL_TEAM_ID\` del rail ~/.claude/.env)
+    --org-id=<id>    Org de GitHub (override; default = org del Factory)
+    --domain=<dom>   Dominio definitivo del cliente (diferible; standalone o inicial)
+    --dns=<ruta>     Ruta DNS para --domain: org (default) | cliente-cf | registrar
+    --verify-timeout=<min>  Timeout del sondeo de verificación de Vercel (default 10)
+    --confirm        Pre-aprueba retirar el dominio interino tras verificar (headless-safe)
+    --ephemeral      Marca el stack \`ephemeral\` (vs \`live\`) para \`--destroy\`
+    --dry-run        Imprime el plan sin tocar ninguna API ni escribir estado
+    --resume         Retoma desde \`.timekast/provision.json\`, salta pasos hechos
+    --adopt          Reconstruye \`.timekast/provision.json\` de un derivado existente
+                     consultando los providers EN SOLO-LECTURA (nunca crea/borra)
+    --destroy        Destruye los recursos del derivado por lifecycle (solo sesión
+                     interactiva — nunca headless). ephemeral → nuke; live → rehúsa
+                     salvo --force con type-to-confirm. --dry-run lista sin borrar
+    --force          Descarta el estado existente y empieza de cero (o sobreescribe en
+                     --adopt; o autoriza el --destroy de un stack live con type-to-confirm)
+    --json           Salida machine-readable en stdout
+
 Sobre \`status\` y \`doctor\`:
   Solo diagnostican — nunca modifican archivos. \`status\` lee el lockfile y
   consulta la última versión publicada (ignorando prereleases); sin lockfile o
   sin conexión, avisa y termina con éxito. \`doctor\` lista huérfanos y conflictos
   pendientes y siempre imprime el aviso de seguridad de \`src/\`.
+  \`doctor --launcher\` verifica en su lugar el entorno (Node ≥ 22, gh instalado,
+  gh auth, membresía del org) — termina con código 1 si falla algún check, para
+  que un lanzador GUI / CI / el TUI puedan ramificar sobre el resultado.
 
 Opciones:
   -h, --help       Muestra esta ayuda
   -v, --version    Muestra la versión del CLI
 `.trim();
-/** Read this package's version from its own package.json. */
+/** Read this CLI's version from its own package.json. */
 function readVersion() {
     try {
         const here = dirname(fileURLToPath(import.meta.url));
@@ -95,10 +124,17 @@ function readVersion() {
 }
 async function main(argv) {
     const [command, ...rest] = argv;
-    if (command === undefined || command === '-h' || command === '--help' || command === 'help') {
+    // Explicit help flags always print the static HELP — never the TUI.
+    if (command === '-h' || command === '--help' || command === 'help') {
         console.log(HELP);
         return;
     }
+    // No command at all → interactive TUI menu (LTUI-001). The menu degrades to
+    // HELP itself when there's no TTY (CI / pipe), so it never hangs.
+    if (command === undefined) {
+        await runTuiMenu({ printHelp: () => console.log(HELP) });
+        return;
+    }
     if (command === '-v' || command === '--version' || command === 'version') {
         console.log(readVersion());
         return;
@@ -117,7 +153,14 @@ async function main(argv) {
             return;
         }
         case 'update': {
-            await runUpdate(parseUpdateFlags(rest));
+            const updateFlags = parseUpdateFlags(rest);
+            await runUpdate(updateFlags);
+            // PROV-007: after a successful update, OFFER the read-only `--adopt` backfill
+            // when this derivative has no provision state (interactive-only; `--yes` /
+            // headless → no-op). Lives at the dispatch layer so `runUpdate`'s prompt
+            // contract stays untouched.
+            const updateRoot = detectRepo(process.cwd()).repoRoot ?? process.cwd();
+            await maybeOfferAdopt(updateRoot, updateFlags);
             return;
         }
         case 'beta': {
@@ -127,11 +170,25 @@ async function main(argv) {
             return;
         }
         case 'status': {
-            await runStatus();
+            // `--json` (TGUI-003): emit the StatusResult as JSON to stdout for the GUI.
+            // Without it, behavior is identical to before.
+            await runStatus({}, parseStatusFlags(rest));
             return;
         }
         case 'doctor': {
-            runDoctor();
+            const flags = parseDoctorFlags(rest);
+            if (flags.launcher) {
+                // `--json` (TGUI-003): emit the LauncherCheck[] to stdout and force exit
+                // 0 so the GUI can read it. The exit-1 contract is kept without `--json`.
+                await runLauncherDoctor({}, flags.json);
+            }
+            else {
+                runDoctor();
+            }
+            return;
+        }
+        case 'provision': {
+            await runProvision(parseProvisionFlags(rest));
             return;
         }
         case 'publish': {
@@ -143,22 +200,17 @@ async function main(argv) {
             return;
         }
         case 'secrets': {
-            const file = rest.find((arg) => !arg.startsWith('-'));
+            // Single shape: `factory secrets <file>` — merge a KEY=value file into the
+            // rail (~/.claude/.env). The org gate (`secrets pull`/`sync`) was removed;
+            // the future shared-secrets system is Infisical (a fresh branch).
+            const file = rest.filter((a) => !a.startsWith('-'))[0];
             if (!file) {
                 throw new CLIError('Falta el archivo de secretos. Uso: `factory secrets <file>` ' +
-                    '(un archivo `KEY=value`, p.ej. el master `secrets.env`).');
+                    '(un archivo `KEY=value`, p.ej. el master `secrets.env`) que se mergea a `~/.claude/.env`.');
             }
             await secretsCommand(file);
             return;
         }
-        case 'launcher-path': {
-            runLauncherPath();
-            return;
-        }
-        case 'bootstrap-version': {
-            runBootstrapVersion(rest);
-            return;
-        }
         default:
             throw new CLIError(`Comando desconocido: \`${command}\`.\nEjecuta \`factory --help\` para ver los comandos disponibles.`);
     }
@@ -167,7 +219,11 @@ main(process.argv.slice(2)).then(() => {
     process.exit(0);
 }, (error) => {
     if (error instanceof CLIError) {
-        console.error(`\n✖ ${error.message}`);
+        // An empty message is intentional (the command already rendered its own
+        // actionable output, e.g. `doctor --launcher`'s per-check ❌ lines) — only
+        // the exit code matters; don't print a stray "✖ " line.
+        if (error.message)
+            console.error(`\n✖ ${error.message}`);
         process.exit(error.exitCode);
     }
     // Unexpected error — surface it (this path is a bug, not a user error).

package/dist/lib/cloudflare-api.js

@@ -0,0 +1,243 @@
+/**
+ * Cloudflare DNS REST helper for `factory provision` (PROV-005).
+ *
+ * A THIN, reusable Cloudflare client that mirrors the proven fetch shape of
+ * `vercel-env.ts` (`Authorization: Bearer ${token}` + a single central URL
+ * builder + an injectable `fetchImpl` seam). Its scope is DNS-ONLY: it resolves
+ * the `timekast.mx` zone id, looks up an existing CNAME, creates one
+ * (`proxied: false` so Vercel's own TLS terminates the domain), and PATCHes an
+ * existing record that was manually left `proxied: true` back to `false`.
+ *
+ * 🔴 Scope contract (issue §4 + the frozen plan): the token handed in here is the
+ * shared org Cloudflare token from the rail, minted SCOPED to the `timekast.mx` zone
+ * with DNS-edit only — never an account-wide token (a DNS-write leak over `timekast.mx` could
+ * repoint records, intercept MX, or mint certs). A 403 from any call therefore
+ * means "the token is out of scope for this zone" and the caller maps it to an
+ * actionable `CLIError` (issue §8 Gherkin) — it NEVER deletes a record to recover.
+ *
+ * What this module does NOT do:
+ *   - Delete a DNS record. The idempotent path is create-or-PATCH; an existing
+ *     record is never removed without explicit human confirmation (issue §8).
+ *   - Read or log a token value. The token arrives as an argument and is handed
+ *     straight to the `Authorization` header; it never reaches stdout.
+ *
+ * The live REST flow is exercised e2e by PROV-010; here every branch is driven by
+ * the unit test through the `fetchImpl` mock (issue §7).
+ */
+import { CLIError } from './cli-error.js';
+/** Base URL of the Cloudflare REST API v4 (named constant — never an inline literal). */
+export const CLOUDFLARE_API_BASE = 'https://api.cloudflare.com/client/v4';
+/** The org DNS zone every provisioned interim domain lives under (issue §4). */
+export const TIMEKAST_ZONE_NAME = 'timekast.mx';
+/** CNAME target for a Vercel-hosted domain — Vercel's edge resolves it (issue §6). */
+export const CNAME_VERCEL_TARGET = 'cname.vercel-dns.com';
+/**
+ * Build the two interim domains for a slug (issue §4):
+ *   - dev:  `{slug}-dev.timekast.mx`  → tracks the `develop` branch (preview)
+ *   - prod: `{slug}.timekast.mx`      → production
+ *
+ * Lives HERE (next to {@link TIMEKAST_ZONE_NAME}) so BOTH `provision.ts` (which
+ * creates these) and `provision-state.ts` (whose `--destroy` target re-derives the
+ * dev domain from the slug, since the committed state only records the prod one)
+ * share ONE definition — no circular import, no drift in the `-dev` convention.
+ */
+export function provisionDomains(slug) {
+    return {
+        dev: `${slug}-dev.${TIMEKAST_ZONE_NAME}`,
+        prod: `${slug}.${TIMEKAST_ZONE_NAME}`,
+    };
+}
+/** Timeout (ms) for every Cloudflare REST call — a dead network must not hang provision. */
+const CLOUDFLARE_API_TIMEOUT_MS = 30_000;
+/** A non-2xx (or `success: false`) response from the Cloudflare REST API. */
+export class CloudflareApiError extends Error {
+    status;
+    /** The raw response body (best-effort) — useful context, never a secret. */
+    body;
+    constructor(status, body, context) {
+        super(`Cloudflare API ${status} en ${context}: ${body || '(sin cuerpo)'}`);
+        this.name = 'CloudflareApiError';
+        this.status = status;
+        this.body = body;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** Build the shared headers for every Cloudflare REST call (Bearer auth + JSON). */
+function cloudflareHeaders(token) {
+    return {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json',
+    };
+}
+/** Read a response body as text (best-effort) for error context — never throws. */
+async function safeBody(response) {
+    try {
+        return (await response.text()).slice(0, 500);
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Build a Cloudflare API URL. This is the ONE place a Cloudflare URL is assembled,
+ * so query params (e.g. the zone `name` filter) are merged in one consistent way.
+ */
+export function cloudflareUrl(pathname, query = {}) {
+    const qs = new URLSearchParams(query).toString();
+    return `${CLOUDFLARE_API_BASE}${pathname}${qs ? `?${qs}` : ''}`;
+}
+/**
+ * Make an authenticated Cloudflare API call. Surfaces a typed
+ * {@link CloudflareApiError} on a non-2xx HTTP status OR on a 2xx body whose
+ * `success` is `false` (Cloudflare returns 200 with `success: false` for some
+ * permission/validation failures, so the HTTP status alone is not enough).
+ */
+async function cloudflareApi(method, pathname, token, deps, body, query) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const url = cloudflareUrl(pathname, query);
+    const init = {
+        method,
+        headers: cloudflareHeaders(token),
+        signal: AbortSignal.timeout(CLOUDFLARE_API_TIMEOUT_MS),
+    };
+    if (body !== undefined)
+        init.body = JSON.stringify(body);
+    const response = await fetchImpl(url, init);
+    if (!response.ok) {
+        throw new CloudflareApiError(response.status, await safeBody(response), `${method} ${pathname}`);
+    }
+    let parsed;
+    try {
+        parsed = (await response.json());
+    }
+    catch {
+        parsed = {};
+    }
+    // Cloudflare may answer 200 with `{ success: false, errors: [...] }`.
+    if (parsed.success === false) {
+        throw new CloudflareApiError(response.status, JSON.stringify(parsed).slice(0, 500), `${method} ${pathname}`);
+    }
+    return parsed;
+}
+/**
+ * Resolve the zone id for {@link TIMEKAST_ZONE_NAME} via `GET /zones?name=`.
+ *
+ * The scoped shared org token can only see the `timekast.mx` zone, so the lookup
+ * returns exactly that zone (or nothing). An empty result means the zone is not
+ * visible to this token — either the token is out of scope or the zone id rotated
+ * (issue §8). Either way it is a clear, actionable failure, never a silent skip.
+ *
+ * @throws {CloudflareApiError} on any non-2xx / `success: false`.
+ * @throws {CLIError} when the zone is not found with this token (issue §8).
+ */
+export async function resolveZoneId(token, deps = {}) {
+    return resolveZoneIdForName(TIMEKAST_ZONE_NAME, token, deps);
+}
+/**
+ * Resolve the Cloudflare zone id for an ARBITRARY zone name via `GET /zones?name=`
+ * (PROV-006). The interim flow targets `timekast.mx` ({@link resolveZoneId} is the
+ * fixed-name shortcut); the client-domain flow targets the client's own apex zone,
+ * which may sit under the org token (`--dns=org`) or the client's own token
+ * (`--dns=cliente-cf`). The zone name passed here is the registrable apex derived
+ * from the client domain (`app.miapp.com` → `miapp.com`); a subdomain CNAME is
+ * created INSIDE that zone.
+ *
+ * @throws {CloudflareApiError} on any non-2xx / `success: false`.
+ * @throws {CLIError} when the zone is not visible to this token (issue §8).
+ */
+export async function resolveZoneIdForName(zoneName, token, deps = {}) {
+    const data = (await cloudflareApi('GET', '/zones', token, deps, undefined, {
+        name: zoneName,
+    }));
+    const zone = (data.result ?? []).find((z) => z.name === zoneName);
+    if (!zone?.id) {
+        throw new CLIError(`No se encontró la zona \`${zoneName}\` en Cloudflare con el token usado.\n` +
+            'Verifica que el token esté scopeado a esa zona (DNS-edit) y reintenta con `--resume`; ' +
+            'si usas `--dns=cliente-cf`, confirma que la API key del cliente cubre esa zona.');
+    }
+    return zone.id;
+}
+/**
+ * Derive the registrable apex zone from a fully-qualified domain (PROV-006). A
+ * Cloudflare zone is the apex (`miapp.com`); a CNAME for a subdomain
+ * (`app.miapp.com`) lives INSIDE that zone, so the zone lookup must use the apex,
+ * not the full host. This takes the LAST TWO labels (`a.b.miapp.com` → `miapp.com`).
+ * Multi-part public suffixes (`co.uk`) are out of scope for the interim flow; the
+ * `--dns=registrar` path sidesteps zone resolution entirely (manual records).
+ */
+export function apexZoneOf(domain) {
+    const labels = domain.split('.').filter(Boolean);
+    if (labels.length <= 2)
+        return labels.join('.');
+    return labels.slice(-2).join('.');
+}
+/**
+ * Find an existing CNAME record for `name` in the zone (issue §8 idempotency).
+ * Returns the record when present (so the caller can detect a `proxied: true`
+ * record left by a manual edit and PATCH it) or `null` when absent.
+ *
+ * @throws {CloudflareApiError} on any non-2xx / `success: false`.
+ */
+export async function findCnameRecord(zoneId, name, token, deps = {}) {
+    const data = (await cloudflareApi('GET', `/zones/${encodeURIComponent(zoneId)}/dns_records`, token, deps, undefined, {
+        type: 'CNAME',
+        name,
+    }));
+    return (data.result ?? []).find((r) => r.name === name && r.type === 'CNAME') ?? null;
+}
+/**
+ * Create a CNAME record pointing `name` → {@link CNAME_VERCEL_TARGET} with
+ * `proxied: false` and `ttl: 1` (auto) — `POST /zones/{id}/dns_records` (issue §4).
+ * `proxied: false` is non-negotiable: a proxied record would terminate TLS at
+ * Cloudflare instead of letting Vercel issue+serve the cert for the domain.
+ *
+ * @throws {CloudflareApiError} on any non-2xx / `success: false`.
+ */
+export async function createCnameRecord(zoneId, name, token, deps = {}) {
+    await cloudflareApi('POST', `/zones/${encodeURIComponent(zoneId)}/dns_records`, token, deps, {
+        type: 'CNAME',
+        name,
+        content: CNAME_VERCEL_TARGET,
+        proxied: false,
+        ttl: 1,
+    });
+}
+/**
+ * PATCH an existing CNAME record to `proxied: false` — `PATCH
+ * /zones/{id}/dns_records/{recordId}` (issue §8). Used when a record was left
+ * `proxied: true` by a manual edit: we flip the proxy flag in place. We NEVER
+ * delete the record to "fix" it (a destructive change requires confirmation).
+ *
+ * @throws {CloudflareApiError} on any non-2xx / `success: false`.
+ */
+export async function unproxyCnameRecord(zoneId, recordId, name, token, deps = {}) {
+    await cloudflareApi('PATCH', `/zones/${encodeURIComponent(zoneId)}/dns_records/${encodeURIComponent(recordId)}`, token, deps, {
+        type: 'CNAME',
+        name,
+        content: CNAME_VERCEL_TARGET,
+        proxied: false,
+    });
+}
+/**
+ * Idempotently ensure a `proxied: false` CNAME for `name` exists in the zone
+ * (issue §4 + §8). Returns the outcome so the caller can narrate it (no-echo —
+ * a domain name is not a secret, but the token never crosses this boundary):
+ *   - `created`   — no record existed → POSTed a fresh `proxied: false` CNAME
+ *   - `unproxied` — a `proxied: true` record existed → PATCHed it to `false`
+ *   - `unchanged` — a `proxied: false` record already existed → nothing to do
+ *
+ * @throws {CloudflareApiError} on any non-2xx / `success: false` (caller maps it).
+ */
+export async function ensureCnameRecord(zoneId, name, token, deps = {}) {
+    const existing = await findCnameRecord(zoneId, name, token, deps);
+    if (!existing) {
+        await createCnameRecord(zoneId, name, token, deps);
+        return 'created';
+    }
+    if (existing.proxied) {
+        // A manually-edited record left proxied:true → flip it (never delete — §8).
+        await unproxyCnameRecord(zoneId, existing.id, name, token, deps);
+        return 'unproxied';
+    }
+    return 'unchanged';
+}

package/dist/lib/constants.js

@@ -7,10 +7,21 @@
 export const FACTORY_ORG = 'TimeKast';
 /** The Factory monorepo, source of the distribution releases. */
 export const FACTORY_REPO = 'TimeKast/TimeKast-Factory';
+// NOTE: the org secrets gate constants (SECRETS_GATE_URL, GITHUB_DEVICE_CLIENT_ID,
+// GITHUB_DEVICE_SCOPE, SECRETS_STATE_FILE) were REMOVED with the `secrets pull`/`sync`
+// device-flow gate — that droplet effort is parked; the future is Infisical.
 /** The static hub repo that hosts published proposals/mockups (`factory publish`). */
 export const PROPOSALS_HUB_REPO = `${FACTORY_ORG}/proposals`;
 /** HTTPS git URL of the hub (token is injected by the publish command). */
 export const PROPOSALS_HUB_GIT = `https://github.com/${FACTORY_ORG}/proposals.git`;
+/**
+ * End-pointer printed at the tail of a SUCCESSFUL `new` / `update` flow (PVSKILL-002):
+ * the next step a dev takes to finish setting up the environment. Shared by both
+ * commands so the copy is a single named constant, never an inline literal (CODING.md §5).
+ * Printed only on success (exit 0, after the last step) and gated against CI noise —
+ * see `printProvisionPointer` in each command.
+ */
+export const PROVISION_POINTER = 'Para terminar el setup, pide al agente /provision.';
 /** Distribution profiles selectable in `new`. */
 export const PROFILES = {
     full: 'full',

package/dist/lib/env-merge.js

@@ -1,8 +1,16 @@
 /**
  * Non-naive `.env` parser + merger for the `factory secrets` rail (SEC-001).
  *
- * Merges a SOURCE `.env`-style file into a TARGET (`~/.claude/.env` in
- * production), idempotently and additively:
+ * Two entry points, one engine:
+ *   - `mergeEnvFile(sourcePath, target)` — merge a `.env` FILE on disk (the local
+ *     master of `factory secrets <file>`).
+ *   - `mergeEnvText(text, target)`       — merge an in-memory `KEY=value` BLOB (a
+ *     caller that already holds the text can merge without writing a temp file).
+ * `mergeEnvFile` reads its file and delegates to `mergeEnvText`; the merge logic
+ * below is written once.
+ *
+ * Merges a SOURCE `.env` blob into a TARGET (`~/.claude/.env` in production),
+ * idempotently and additively:
  *   - keys in source that are absent in target → ADDED
  *   - keys in source that already exist with a different value → UPDATED
  *   - keys in source whose value already matches target → SKIPPED (no churn)
@@ -131,6 +139,11 @@ function parseSource(text) {
  * couple of small reads/writes, and sync keeps the chmod-before-write ordering
  * race-free.
  *
+ * Thin wrapper over {@link mergeEnvText}: reads + validates the SOURCE FILE, then
+ * delegates the merge to the text-level engine. `factory secrets <file>` (a local
+ * master on disk) uses this; a caller that already holds the text in memory uses
+ * `mergeEnvText` directly.
+ *
  * @throws when the source is missing/unreadable, or either file is not UTF-8.
  */
 export async function mergeEnvFile(sourcePath, targetPath) {
@@ -139,7 +152,31 @@ export async function mergeEnvFile(sourcePath, targetPath) {
     if (!existsSync(sourcePath)) {
         throw new Error(`No encontré el archivo fuente \`${sourcePath}\`.`);
     }
-    const { pairs: sourcePairs, invalid } = parseSource(readEnvText(sourcePath));
+    // The only difference from a `pull` is WHERE the source text comes from (a file
+    // here, an HTTP body there). Once read, the merge is identical — so read here
+    // and hand the text to the shared engine. No reimplementation of the merge.
+    return mergeEnvText(readEnvText(sourcePath), targetPath);
+}
+/**
+ * Merge SOURCE TEXT (a `KEY=value` blob already in memory) into `targetPath`.
+ *
+ * This is the engine `mergeEnvFile` delegates to, kept as a separate text-level
+ * entry point so a caller that already holds the blob in memory can merge it
+ * straight in, so a secret value NEVER lands in a temp file or any intermediate
+ * path on the way to `~/.claude/.env`.
+ *
+ * Same contract as `mergeEnvFile` for everything downstream of the source read:
+ * additive/idempotent merge, first-`=` split, quoted values preserved, comments +
+ * untouched target keys preserved, trailing newline preserved, target created
+ * `0600` if absent and re-asserted `0600` if it already existed (Edge case §8 —
+ * a `0644` file edited by hand is corrected before any secret is written).
+ *
+ * @throws when the target is a symlink or not UTF-8. (The source is in-memory
+ *   text, so there is no "source missing" failure mode here — the caller owns
+ *   validating that the HTTP body is well-formed before calling.)
+ */
+export async function mergeEnvText(text, targetPath) {
+    const { pairs: sourcePairs, invalid } = parseSource(text);
     // Reject a symlink target explicitly (SEC-001 §8): writing through a symlink
     // could redirect secrets outside `~/.claude/`. We refuse rather than follow.
     if (existsSync(targetPath) && lstatSync(targetPath).isSymbolicLink()) {