agent-cloud-kit 1.0.0-rc.0 → 1.0.0-rc.2

package/dist/prepare/prompts.js

@@ -1,31 +1,16 @@
 /**
- * Formats a list for a prompt line.
- *
- * @param items Items.
- * @param none Text when there are no items.
- * @returns The items joined by commas, or `none`.
- * @example
- * list(["A", "B"], "ninguna"); // "A, B"
+ * @file Prompts `prepare` hands to Claude, in Spanish: they invoke the `cloud-ready` skill.
  */
-function list(items, none) {
-    return items.length > 0 ? items.join(", ") : none;
-}
 /**
- * Prompt for the local session: `configure` mode with the user's answers.
+ * Prompt for the local session: `configure` mode. `prepare` asks nothing first; the skill detects
+ * secrets and domains itself.
  *
- * @param answers What the user answered.
  * @returns The prompt.
  * @example
- * configurePrompt({ secrets: ["A"], domains: [] }).startsWith("/cloud-ready configure"); // true
+ * configurePrompt(); // "/cloud-ready configure"
  */
-export function configurePrompt(answers) {
-    return [
-        "/cloud-ready configure",
-        "",
-        "Respuestas del usuario (no las vuelvas a preguntar):",
-        `- Variables secretas: ${list(answers.secrets, "ninguna")}`,
-        `- Dominios extra: ${list(answers.domains, "ninguno")}`,
-    ].join("\n");
+export function configurePrompt() {
+    return "/cloud-ready configure";
 }
 /**
  * Prompt for the cloud session: `verify` mode with the prepare branch and, when known, the PR.

package/dist/prepare/questions.js

@@ -1,70 +1,5 @@
 /**
- * @file The questions `prepare` asks: only secret names and extra domains (tests are handled by
- * the skill with the user).
+ * @file How `prepare` asks the user a question. It asks nothing up front: secrets and domains are
+ * detected by the `cloud-ready` skill, locally or in the cloud, when they are needed.
  */
-import { isHostName } from "../config.js";
-import { OUTPUT_PREFIX } from "../constants.js";
-/** Answer that leaves a list empty. */
-const EMPTY_LIST_ANSWER = "-";
-/**
- * Turns a raw answer into a list.
- *
- * @param answer Raw answer: comma-separated, empty to accept, `-` for none.
- * @param suggestion Suggested items, used when the answer is empty.
- * @returns The items.
- * @example
- * parseList("a, b", []); // ["a", "b"]
- */
-function parseList(answer, suggestion) {
-    const text = answer.trim();
-    if (text === "")
-        return suggestion;
-    if (text === EMPTY_LIST_ANSWER)
-        return [];
-    return text.split(",").map((item) => item.trim()).filter((item) => item !== "");
-}
-/** Example host shown when a typed domain is not a host name. */
-const HOST_EXAMPLE = "api.example.com";
-/**
- * Keeps the typed domains that are host names (the rule of `domains` in the config). Each invalid
- * entry is asked again once; if it is still not a host name it is dropped with a printed note.
- *
- * @param ask Function that asks one question.
- * @param typed Domains as typed.
- * @param print Prints one line.
- * @returns The valid domains.
- * @example
- * await validDomains(ask, ["api.example.com"], console.log); // ["api.example.com"]
- */
-async function validDomains(ask, typed, print) {
-    const domains = [];
-    for (const entry of typed) {
-        if (isHostName(entry)) {
-            domains.push(entry);
-            continue;
-        }
-        const retry = (await ask(`${JSON.stringify(entry)} is not a host name (like ${HOST_EXAMPLE}); type it again, or ${EMPTY_LIST_ANSWER} to drop it`, "")).trim();
-        if (isHostName(retry)) {
-            domains.push(retry);
-            continue;
-        }
-        const dropped = retry === "" || retry === EMPTY_LIST_ANSWER ? entry : retry;
-        print(`${OUTPUT_PREFIX}dropped ${JSON.stringify(dropped)}: not a host name like ${HOST_EXAMPLE}`);
-    }
-    return domains;
-}
-/**
- * Asks every question.
- *
- * @param ask Function that asks one question.
- * @param suggestions Suggested items.
- * @param print Prints one line (notes about dropped domains).
- * @returns The answers.
- * @example
- * await askAll(ask, { secrets: ["API_TOKEN"] }, console.log); // { secrets: ["API_TOKEN"], domains: [] }
- */
-export async function askAll(ask, suggestions, print) {
-    const secrets = parseList(await ask("Secret environment variables needed in the cloud (comma-separated, - for none)", suggestions.secrets.join(", ")), suggestions.secrets);
-    const typed = parseList(await ask("Extra domains the setup or tests need (comma-separated, - for none)", ""), []);
-    return { secrets, domains: await validDomains(ask, typed, print) };
-}
+export {};

package/dist/run.js

@@ -16,7 +16,7 @@ export class RunTimeoutError extends Error {
      * @param ms - Time limit, in milliseconds.
      */
     constructor(cmd, ms) {
-        super(`${cmd} timed out after ${ms}ms`);
+        super(`${cmd} superó el límite de ${ms}ms`);
         this.name = "RunTimeoutError";
     }
 }
@@ -82,7 +82,7 @@ function spawnAndWait(cmd, args, opts, stdio, onStdout) {
             clearTimeout(timer);
             if (code === 0)
                 return resolve();
-            reject(new Error(`${cmd} exited with ${code === null ? `signal ${signal}` : `code ${code}`}`));
+            reject(new Error(`${cmd} terminó con ${code === null ? `la señal ${signal}` : `el código ${code}`}`));
         });
     });
 }

package/dist/select.js

@@ -0,0 +1,112 @@
+/**
+ * @file A small arrow-key menu for the terminal, with the look of agent-kitchen's (`@clack/prompts`)
+ * and no dependencies: ↑/↓ move, Enter picks, Esc or Ctrl+C cancels.
+ */
+import { emitKeypressEvents } from "node:readline";
+/** ANSI codes used by the menu. */
+const ANSI = {
+    dim: (text) => `\x1b[2m${text}\x1b[22m`,
+    cyan: (text) => `\x1b[36m${text}\x1b[39m`,
+    green: (text) => `\x1b[32m${text}\x1b[39m`,
+    hideCursor: "\x1b[?25l",
+    showCursor: "\x1b[?25h",
+    up: (lines) => (lines > 0 ? `\x1b[${lines}A` : ""),
+    clearDown: "\r\x1b[J",
+};
+/**
+ * Applies one key to the menu.
+ *
+ * @param state - Current state.
+ * @param key - Key pressed.
+ * @param count - Number of options.
+ * @returns The new state.
+ * @example
+ * menuKey({ active: 0 }, { name: "down" }, 2); // { active: 1 }
+ */
+export function menuKey(state, key, count) {
+    if (key.ctrl && key.name === "c")
+        return { ...state, done: "cancelled" };
+    if (key.name === "escape")
+        return { ...state, done: "cancelled" };
+    if (key.name === "return" || key.name === "enter")
+        return { ...state, done: "picked" };
+    if (key.name === "up" || key.name === "k")
+        return { active: (state.active - 1 + count) % count };
+    if (key.name === "down" || key.name === "j")
+        return { active: (state.active + 1) % count };
+    return state;
+}
+/**
+ * Draws the menu: the question, the options (hint only on the active one) and, once done, the
+ * picked option or "Cancelado".
+ *
+ * @param message - Question.
+ * @param choices - Options.
+ * @param state - Current state.
+ * @returns The lines to print.
+ * @example
+ * renderMenu("¿Dónde?", [{ value: "a", label: "A" }], { active: 0 })[0]; // "◆  ¿Dónde?" (with color)
+ */
+export function renderMenu(message, choices, state) {
+    const bar = ANSI.dim("│");
+    if (state.done === "picked")
+        return [`${ANSI.green("◇")}  ${message}`, `${bar}  ${ANSI.dim(choices[state.active]?.label ?? "")}`, bar];
+    if (state.done === "cancelled")
+        return [`${ANSI.dim("■")}  ${message}`, `${bar}  ${ANSI.dim("Cancelado")}`, bar];
+    const lines = [`${ANSI.cyan("◆")}  ${message}`];
+    choices.forEach((choice, index) => {
+        if (index === state.active) {
+            const hint = choice.hint ? ` ${ANSI.dim(`(${choice.hint})`)}` : "";
+            lines.push(`${ANSI.cyan("│")}  ${ANSI.green("●")} ${choice.label}${hint}`);
+        }
+        else {
+            lines.push(`${ANSI.cyan("│")}  ${ANSI.dim(`○ ${choice.label}`)}`);
+        }
+    });
+    lines.push(ANSI.cyan("└"));
+    return lines;
+}
+/**
+ * Shows the menu on the process terminal. Raw mode is on only while it is open, so a later
+ * `readline` question or a child process gets a normal terminal.
+ *
+ * @param message - Question.
+ * @param choices - Options.
+ * @param initial - Value active at the start.
+ * @returns The picked value, or null on Esc or Ctrl+C.
+ * @example
+ * await chooseTerminal("¿Dónde preparo el repo?", [{ value: "pr", label: "En un PR nuevo" }], "pr"); // "pr"
+ */
+export const chooseTerminal = async (message, choices, initial) => {
+    const { stdin, stdout } = process;
+    let state = { active: Math.max(0, choices.findIndex((c) => c.value === initial)) };
+    let drawn = 0;
+    const draw = () => {
+        const lines = renderMenu(message, choices, state);
+        stdout.write(`${ANSI.up(drawn)}${ANSI.clearDown}${lines.join("\n")}\n`);
+        drawn = lines.length;
+    };
+    emitKeypressEvents(stdin);
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdout.write(ANSI.hideCursor);
+    draw();
+    try {
+        return await new Promise((resolvePick) => {
+            const onKey = (_text, key = {}) => {
+                state = menuKey(state, key, choices.length);
+                draw();
+                if (state.done === undefined)
+                    return;
+                stdin.off("keypress", onKey);
+                resolvePick(state.done === "picked" ? (choices[state.active]?.value ?? null) : null);
+            };
+            stdin.on("keypress", onKey);
+        });
+    }
+    finally {
+        stdin.setRawMode(false);
+        stdin.pause();
+        stdout.write(ANSI.showCursor);
+    }
+};

package/dist/session.js

@@ -6,7 +6,7 @@ import { appendFileSync, existsSync } from "node:fs";
 import { basename, join } from "node:path";
 import { findProxyCa, shellQuote } from "./ca.js";
 import { readConfig } from "./config.js";
-import { CONFIG_FILE, GIT_FETCH_TIMEOUT_MS, OUTPUT_PREFIX, PACKAGE, SETUP_SLOW_MS } from "./constants.js";
+import { CONFIG_FILE, GIT_FETCH_TIMEOUT_MS, OUTPUT_PREFIX, packageSpec, SETUP_SLOW_MS } from "./constants.js";
 import { configImages, defaultBranch, readToolVersions } from "./detect.js";
 import { realDocker } from "./docker.js";
 import { pathLine, toolBinDirs } from "./installers.js";
@@ -15,7 +15,7 @@ import { resolveNotes } from "./manual.js";
 import { RunTimeoutError } from "./run.js";
 import { fingerprint, readState } from "./state.js";
 /** Generic note shown in every cloud session. */
-const GENERIC_NOTE = "you are in a Claude Code cloud session. There are no open ports or previews: test against localhost. gh pr and gh issue fail (the GitHub proxy blocks GraphQL): use gh api (REST).";
+const GENERIC_NOTE = "estás en una sesión cloud de Claude Code. No hay puertos abiertos ni previews: prueba contra localhost. gh pr y gh issue fallan (el proxy de GitHub bloquea GraphQL): usa gh api (REST).";
 /** Milliseconds in a second. */
 const MS_PER_SECOND = 1000;
 /** Seconds in a minute. */
@@ -91,24 +91,25 @@ export function expectedFingerprint(repo, config, state) {
  * @param repo - Repo root.
  * @param config - Repo config.
  * @param state - Recorded state, if any.
+ * @param packageVersion - Version of the running package, for the setup command.
  * @returns Warning messages, without prefix.
  */
-function machineWarnings(repo, config, state) {
+function machineWarnings(repo, config, state, packageVersion) {
     if (!state) {
         return [
-            `the environment setup did not run for ${basename(repo)}. Set the setup script of the environment in claude.ai to: npx -y ${PACKAGE}@1 setup`,
+            `el setup del entorno no corrió para ${basename(repo)}. Pon como script de setup del entorno en claude.ai: npx -y ${packageSpec(packageVersion)} setup`,
         ];
     }
     const out = [];
     const failed = state.steps.filter((s) => !s.ok).map((s) => s.name);
     if (failed.length)
-        out.push(`setup failed: ${failed.join(", ")}. Run agent-cloud-kit doctor.`);
+        out.push(`falló el setup: ${failed.join(", ")}. Corre agent-cloud-kit doctor.`);
     if (expectedFingerprint(repo, config, state) !== state.fingerprint) {
-        out.push("the machine was prepared with another configuration. Edit the setup script field in claude.ai (any change) so it is rebuilt.");
+        out.push("la máquina se preparó con otra configuración. Edita el campo del script de setup en claude.ai (cualquier cambio) para que se reconstruya.");
     }
     const total = state.steps.reduce((sum, s) => sum + s.ms, 0);
     if (total > SETUP_SLOW_MS)
-        out.push(`setup took ${minutesSeconds(total)}, close to the ~5 minute limit.`);
+        out.push(`el setup tardó ${minutesSeconds(total)}, cerca del límite de ~5 minutos.`);
     return out;
 }
 /**
@@ -128,7 +129,7 @@ function writeEnvFile(env, lines) {
         return undefined;
     }
     catch (err) {
-        return `could not write ${ENV_FILE_VAR} (${file}): ${err instanceof Error ? err.message : String(err)}`;
+        return `no se pudo escribir ${ENV_FILE_VAR} (${file}): ${err instanceof Error ? err.message : String(err)}`;
     }
 }
 /**
@@ -169,7 +170,7 @@ async function runSessionSteps(repo, commands, run, env) {
             await run("bash", ["-c", command], { cwd: repo, env, stdio: "stderr", timeoutMs: SESSION_STEP_TIMEOUT_MS });
         }
         catch (err) {
-            problems.push(`${err instanceof RunTimeoutError ? "session step timed out" : "session step failed"}: ${command}`);
+            problems.push(`${err instanceof RunTimeoutError ? "el paso de sesión superó el tiempo límite" : "falló el paso de sesión"}: ${command}`);
         }
     }
     return problems;
@@ -209,16 +210,16 @@ async function sessionBody(repo, ctx, out) {
     if (envFileProblem)
         out.push(envFileProblem);
     if (config)
-        out.push(...machineWarnings(repo, config, state));
+        out.push(...machineWarnings(repo, config, state, ctx.packageVersion));
     const missing = (config?.requiredEnv ?? []).filter((name) => !ctx.env[name]);
     if (missing.length)
-        out.push(`missing environment variables: ${missing.join(", ")}`);
+        out.push(`faltan variables de entorno: ${missing.join(", ")}`);
     const notes = resolveNotes(repo, config?.notes)?.trim();
     if (notes)
         out.push(notes);
     const dockerProblem = startDocker(ctx.docker ?? realDocker);
     if (dockerProblem)
-        out.push(`could not start dockerd: ${dockerProblem}`);
+        out.push(`no se pudo iniciar dockerd: ${dockerProblem}`);
     const env = toolsEnv(dirs, ctx.env, ca);
     await syncGit(repo, ctx.run, env);
     out.push(...(await runSessionSteps(repo, config?.session ?? [], ctx.run, env)));
@@ -239,7 +240,7 @@ export async function session(repo, ctx) {
         await sessionBody(repo, ctx, out);
     }
     catch (err) {
-        out.push(`session error: ${err instanceof Error ? err.message : String(err)}`);
+        out.push(`error en session: ${err instanceof Error ? err.message : String(err)}`);
     }
     return out.map((line) => OUTPUT_PREFIX + line);
 }

package/dist/setup.js

@@ -66,14 +66,14 @@ async function aptLane(config, deps) {
     for (const url of config.aptRepos) {
         const name = `apt repo ${url}`;
         if (!url.startsWith(HTTPS_PREFIX)) {
-            results.push(await refused(name, `apt repo must be an ${HTTPS_PREFIX} URL`));
+            results.push(await refused(name, `el repo de apt debe ser una URL ${HTTPS_PREFIX}`));
             continue;
         }
         results.push(await step(name, () => deps.run("bash", ["-c", APT_REPO_SCRIPT, SCRIPT_NAME, url], { env, timeoutMs: APT_STEP_TIMEOUT_MS })));
     }
     const valid = config.apt.filter((pkg) => DEBIAN_PACKAGE_NAME.test(pkg));
     for (const pkg of config.apt.filter((p) => !valid.includes(p))) {
-        results.push(await refused(`apt package ${pkg}`, "invalid Debian package name"));
+        results.push(await refused(`apt package ${pkg}`, "nombre de paquete Debian inválido"));
     }
     if (!valid.length && !config.aptRepos.length)
         return results;
@@ -119,11 +119,11 @@ async function dockerLane(config, images, docker, deps) {
     const results = [];
     const valid = images.filter((image) => !WHITESPACE.test(image) && !image.startsWith("-") && image !== "");
     for (const image of images.filter((i) => !valid.includes(i))) {
-        results.push(await refused(`docker pull ${image}`, "invalid image reference"));
+        results.push(await refused(`docker pull ${image}`, "referencia de imagen inválida"));
     }
     const up = await docker.ensure().catch(() => false);
     if (!up)
-        return [...results, await refused("docker", `dockerd did not start; see ${DOCKERD_LOG}`)];
+        return [...results, await refused("docker", `dockerd no arrancó; revisa ${DOCKERD_LOG}`)];
     return [...results, ...(await pullAll(valid, deps))];
 }
 /**
@@ -181,7 +181,7 @@ function manifestVersion(root) {
 function copyPackage(source, target, version) {
     const found = manifestVersion(source);
     if (found !== version)
-        throw new Error(`the package at ${source} is ${found ?? "unknown"}, not ${version}`);
+        throw new Error(`el paquete en ${source} es ${found ?? "desconocido"}, no ${version}`);
     const temp = `${target}.${process.pid}.tmp`;
     rmSync(temp, { recursive: true, force: true });
     mkdirSync(temp, { recursive: true });
@@ -267,7 +267,7 @@ export async function setupRepo(repo, ctx) {
     });
     const { config, errors } = readConfig(repo);
     if (!config)
-        return failed("config", errors.join("; ") || "no config");
+        return failed("config", errors.join("; ") || "sin configuración");
     try {
         return await runPhases(repo, config, ctx);
     }

package/dist/skill.js

@@ -78,15 +78,15 @@ function withVersion(text, version) {
  * @throws When the package has no skill or the copy fails (the installed skill is kept).
  * @example
  * installSkill("/home/user/app", "/usr/lib/node_modules/agent-cloud-kit", "1.0.0");
- * // "installed .agents/skills/cloud-ready 1.0.0"
+ * // "se instaló .agents/skills/cloud-ready 1.0.0"
  */
 export function installSkill(repo, packageRoot, packageVersion) {
     const current = skillVersion(repo);
     if (current === packageVersion)
-        return `${SKILL_DIR} already at ${packageVersion}`;
+        return `${SKILL_DIR} ya está en ${packageVersion}`;
     const source = join(packageRoot, PACKAGE_SKILL_DIR);
     if (!existsSync(join(source, "SKILL.md")))
-        throw new Error(`${PACKAGE_SKILL_DIR}/SKILL.md not found in ${packageRoot}`);
+        throw new Error(`no se encontró ${PACKAGE_SKILL_DIR}/SKILL.md en ${packageRoot}`);
     const target = join(repo, SKILL_DIR);
     const temp = `${target}.${process.pid}.tmp`;
     const old = `${target}.${process.pid}.old`;
@@ -107,7 +107,7 @@ export function installSkill(repo, packageRoot, packageVersion) {
         throw err;
     }
     rmSync(old, { recursive: true, force: true });
-    return current === undefined ? `installed ${SKILL_DIR} ${packageVersion}` : `updated ${SKILL_DIR} from ${current} to ${packageVersion}`;
+    return current === undefined ? `se instaló ${SKILL_DIR} ${packageVersion}` : `se actualizó ${SKILL_DIR} de ${current} a ${packageVersion}`;
 }
 /**
  * Tells whether a path exists, counting a broken symlink as existing.
@@ -132,7 +132,7 @@ function present(path) {
  * @param repo - Repo root.
  * @returns A line describing what was done, or undefined when nothing was needed.
  * @example
- * linkSkill("/home/user/app"); // "linked .claude/skills/cloud-ready to .agents/skills/cloud-ready"
+ * linkSkill("/home/user/app"); // "se enlazó .claude/skills/cloud-ready a .agents/skills/cloud-ready"
  */
 export function linkSkill(repo) {
     const claudeSkills = join(repo, CLAUDE_SKILLS_DIR);
@@ -144,5 +144,5 @@ export function linkSkill(repo) {
         return undefined;
     mkdirSync(claudeSkills, { recursive: true });
     symlinkSync(SKILL_LINK_TARGET, link);
-    return `linked ${SKILL_LINK} to ${SKILL_DIR}`;
+    return `se enlazó ${SKILL_LINK} a ${SKILL_DIR}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-cloud-kit",
-  "version": "1.0.0-rc.0",
+  "version": "1.0.0-rc.2",
   "description": "Zero-dependency CLI that prepares Claude Code cloud sessions.",
   "type": "module",
   "license": "MIT",

package/skills/cloud-ready/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: cloud-ready
 description: Prepara o verifica un repo Node/TypeScript para las sesiones en la nube de Claude Code (claude.ai/code). Usa `configure` en local, con el usuario, para escribir `.claude/cloud.json` y decidir qué corre en la nube; usa `verify` dentro de una sesión en la nube para comprobar la preparación, arreglarla y reportar en el PR.
-argument-hint: "configure [respuestas] | verify"
+argument-hint: "configure | verify"
 metadata:
   version: "1.0.0"
 ---
@@ -33,8 +33,9 @@ Son los únicos que `verify` puede cambiar:
 ## `configure` (local, con el usuario)
 
 Si `CLAUDE_CODE_REMOTE=true`, detente: este modo necesita al usuario en una terminal local.
-Las respuestas que traiga el argumento (variables secretas, dominios extra) son el punto de
-partida: no las vuelvas a preguntar.
+No le pidas al usuario una lista de variables secretas ni de dominios: anota en `requiredEnv` y
+`domains` solo lo que veas que el repo necesita en la nube; lo que falte lo detecta `verify` (ver
+"Dominios y variables nuevos").
 
 1. **Lee qué usa el repo:** `package.json` (scripts, `packageManager`, `engines`), el lockfile,
    `.tool-versions`, `mise.toml`, `.nvmrc`, archivos de Docker compose, `Dockerfile`,
@@ -81,11 +82,13 @@ partida: no las vuelvas a preguntar.
 8. **Si existe `.agents/skills/test-audit/project.md`:** escribe o actualiza su sección "Nube"
    con el mismo resumen; no toques el resto del archivo.
 9. **Corre `agent-cloud-kit manual`** y muéstrale al usuario la sección "Configurar el entorno en
-   claude.ai" de `docs/agent-cloud.md` (setup script, dominios, variables).
+   claude.ai" de `docs/agent-cloud.md` (setup script, dominios, variables). Dile que ese
+   documento se irá actualizando: si la skill, en local o en la nube, detecta que hace falta un
+   dominio o una variable nueva, lo agrega ahí y se lo dice.
 10. **No hagas commit:** `agent-cloud-kit prepare` lo hace al salir. Si te invocaron fuera de
     `prepare`, pregunta al usuario.
 11. **Termina diciéndole al usuario que salga:** dile al usuario, con estas palabras o parecidas,
-    "configure terminó: sal de claude con `/exit` y `prepare` sigue (commit, push y PR)". Si te
+    "configure terminó: sal de claude con `/exit` y `prepare` sigue". Si te
     invocaron fuera de `prepare`, omite este paso.
 
 ## `verify` (en la nube)
@@ -95,8 +98,8 @@ Solo con `CLAUDE_CODE_REMOTE=true`; si no, detente y dilo. El prompt trae la ram
 `claude/…`: no la cambies; al final empujas a la rama de `prepare`.
 
 1. **Contexto:** lee `.claude/cloud.json`, el archivo de `notes` y `docs/agent-cloud.md`. Anota
-   las líneas `agent-cloud-kit:` de falla que mostró el inicio de la sesión ("did not run",
-   pasos fallidos, "another configuration", variables faltantes).
+   las líneas `agent-cloud-kit:` de falla que mostró el inicio de la sesión ("el setup del entorno no corrió",
+   "falló el setup: …", "la máquina se preparó con otra configuración", "faltan variables de entorno").
 2. **Corre `agent-cloud-kit doctor`** y guarda la salida. Si `agent-cloud-kit` no está en el
    `PATH`, el setup no corrió: usa `npx -y agent-cloud-kit doctor` y repórtalo.
 3. **Comprueba la preparación:** dependencias instaladas (p. ej. `node_modules` existe), las
@@ -112,9 +115,11 @@ Solo con `CLAUDE_CODE_REMOTE=true`; si no, detente y dilo. El prompt trae la ram
    - **Se arregla en la preparación:** cambia solo los archivos de la preparación y vuelve a
      comprobar. Un cambio de `setup` no se re-ejecuta en esta sesión (el setup ya corrió): corre
      el comando a mano para probarlo y anota que la máquina guardada se rehará en una sesión nueva.
-   - **Solo se cambia en claude.ai** (dominios de la red, variables, entorno por defecto con
-     `/remote-env`, rehacer la máquina editando el setup script, el Claude GitHub App): no lo
-     intentes; deja la instrucción exacta para el reporte y deja de intentar arreglos.
+   - **Falta un dominio o una variable:** sigue "Dominios y variables nuevos" y deja de intentar
+     arreglos que dependan de eso.
+   - **Solo se cambia en claude.ai** (entorno por defecto con `/remote-env`, rehacer la máquina
+     editando el setup script, el Claude GitHub App): no lo intentes; deja la instrucción exacta
+     para el reporte y deja de intentar arreglos.
    - **Requiere cambiar código, tests o scripts:** no lo cambies; deja el cambio propuesto
      (archivo y diff) para el comentario del PR.
 
@@ -157,6 +162,25 @@ Solo con `CLAUDE_CODE_REMOTE=true`; si no, detente y dilo. El prompt trae la ram
 **Hallazgos:** los nuevos, o "ninguno".
 ```
 
+## Dominios y variables nuevos
+
+En ambos modos, cuando algo falla porque falta un dominio en la red del entorno (el proxy
+rechaza la conexión, `403` o `CONNECT` fallido hacia un host) o una variable de entorno (el
+inicio de la sesión la marca como faltante, o el error nombra una variable vacía):
+
+1. Agrega el host a `domains` o el nombre a `requiredEnv` en `.claude/cloud.json` (solo el
+   nombre; nunca un valor).
+2. Corre `agent-cloud-kit manual`: `docs/agent-cloud.md` queda con lo nuevo.
+3. **Díselo al usuario en la sesión, en ese momento**, sin esperar al final: qué falta, por qué
+   (el comando y el error) y qué hacer, con estas palabras o parecidas: "Falta `<X>` en el entorno
+   de claude.ai. Agrégalo en <Network access / Variables de entorno> (está en
+   `docs/agent-cloud.md`) y vuelve a verificar: en tu terminal, en la rama `<rama>` actualizada
+   (`git pull`), corre `npx agent-cloud-kit verify`".
+4. En `verify`, ponlo también en "Cambiar en claude.ai" del comentario del PR.
+
+Un dominio que ya está en `domains`, o una variable que ya está en `requiredEnv`, no se agrega
+de nuevo: si sigue faltando, el usuario aún no actualizó el entorno; recuérdaselo.
+
 ## Hallazgos
 
 En ambos modos: todo hecho nuevo sobre la nube (algo que no está en `reference/knowledge.md`,