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

package/README.md

@@ -35,12 +35,15 @@ platform does not tell you:
 ## The flow
 
 1. **Install your agent tooling** with agent-kitchen (config, hook and skill arrive in the repo).
-2. **Run `npx agent-cloud-kit prepare`** in a local terminal. It asks a few questions (secret
-   variable names, extra domains), creates a worktree on a dated branch, runs `init`, and opens
+2. **Run `npx agent-cloud-kit prepare`** in a local terminal. It asks nothing up front: it
+   creates a worktree on a dated branch, runs `init`, and opens
    Claude locally with the `cloud-ready` skill so it can write the cloud preparation with you. Then
    it writes the manual, commits, pushes and opens a draft PR.
 3. **Configure the environment in claude.ai** following `docs/agent-cloud.md`, which `prepare`
-   generated from your `.claude/cloud.json`.
+   generated from your `.claude/cloud.json`. The document keeps growing: when the skill, locally
+   or in the cloud, finds that a domain or an environment variable is missing, it adds it to
+   `.claude/cloud.json`, regenerates the document and tells you in the session what to add in
+   claude.ai.
 4. **Verification in the cloud:** `prepare` launches `claude --cloud` on that branch, so a real
    cloud session runs `cloud-ready verify`, fixes what fails and reports in the PR.
 
@@ -141,7 +144,7 @@ A Node version that is not exact (`22`, `22.1`, `lts/iron`, `lts/*` or `node`) i
 | `agent-cloud-kit docker`         | Starts `dockerd` detached and waits up to 60 seconds for it to answer. Exits 1 if it does not, at once when `dockerd` is not installed.                                                                                             |
 | `agent-cloud-kit doctor`         | Checks that the proxy lets the needed hosts through, that the pinned tools are installed, that Docker answers, and the recorded state (fingerprint and each step). Exits 1 if any check fails.                                       |
 | `agent-cloud-kit init`           | Creates `.claude/cloud.json` if missing, adds the `SessionStart` hook to `.claude/settings.json` (keeping the hooks already there), copies the `cloud-ready` skill to `.agents/skills/cloud-ready` when its version differs, and links it from `.claude/skills/cloud-ready`. Safe to run again.                                                                           |
-| `agent-cloud-kit manual`         | Writes `docs/agent-cloud.md` from `.claude/cloud.json`, deterministically: the exact setup script, domains, variable names, how to verify the environment. |
+| `agent-cloud-kit manual`         | Writes `docs/agent-cloud.md` from `.claude/cloud.json`, deterministically: the exact setup script (`agent-cloud-kit@<major>`, or the exact version for a release candidate), domains, variable names, how to verify the environment. |
 | `agent-cloud-kit prepare [--resume]` | Local only, needs an interactive terminal: sets the repo up for the cloud on a new branch in a worktree, opens the PR and verifies it in a real cloud session (see "The flow"). `--resume` continues in the existing worktree. |
 
 Environment variables: `AGENT_CLOUD_KIT_DIR` overrides `/opt/agent-cloud-kit` and `AGENT_CLOUD_KIT_HOME`
@@ -223,7 +226,7 @@ is configured on a package that already exists. Publish the first version by han
 2. On npmjs.com, open the package settings and add a trusted publisher: this GitHub repository and
    the `publish.yml` workflow.
 3. Remove the `NPM_TOKEN` secret if you created one. From then on, bump `version` in
-   `package.json`, update `CHANGELOG.md`, and publish a GitHub release tagged `v<version>`.
+   `package.json`, update `CHANGELOG.md`, and publish a GitHub release tagged `v<version>`. A version with a prerelease suffix (`1.0.0-rc.1`) is published under the `next` tag once a stable version is `latest`; before that it also becomes `latest`, so tools that read `latest` (agent-kitchen) see it. Mark its GitHub release as a pre-release.
 
 ## License
 

package/dist/cli.js

@@ -282,7 +282,7 @@ function manualCommand(deps) {
  * @returns The raw answer.
  * @throws InterruptedError on Ctrl+C.
  * @example
- * await askTerminal("Extra domains", ""); // "api.example.com"
+ * await askTerminal("Include these changes in the commit? [y/N]", ""); // "y"
  */
 const askTerminal = async (question, suggestion) => {
     const rl = createInterface({ input: process.stdin, output: process.stdout });

package/dist/constants.js

@@ -10,6 +10,21 @@ export const CONFIG_FILE = ".claude/cloud.json";
 export const RUNNING_PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
 /** Name of this package on npm. */
 export const PACKAGE = "agent-cloud-kit";
+/**
+ * The npm spec the setup script installs: the major (`agent-cloud-kit@1`) for a stable version,
+ * the exact version for a prerelease, which a major range does not match.
+ *
+ * @param packageVersion - Version of the running package.
+ * @returns The spec.
+ * @example
+ * packageSpec("1.2.0"); // "agent-cloud-kit@1"
+ * packageSpec("1.0.0-rc.1"); // "agent-cloud-kit@1.0.0-rc.1"
+ */
+export function packageSpec(packageVersion) {
+    if (packageVersion.includes("-"))
+        return `${PACKAGE}@${packageVersion}`;
+    return `${PACKAGE}@${packageVersion.split(".")[0]}`;
+}
 /** Default root directory that holds the installed tools and the state files. */
 export const TOOLS_DIR = "/opt/agent-cloud-kit";
 /** Environment variable that overrides `TOOLS_DIR` (used by tests). */

package/dist/manual.js

@@ -5,7 +5,7 @@
 import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { readConfig } from "./config.js";
-import { CONFIG_FILE, OUTPUT_PREFIX, PACKAGE } from "./constants.js";
+import { CONFIG_FILE, OUTPUT_PREFIX, PACKAGE, packageSpec } from "./constants.js";
 /** Path of the manual, relative to the repo. */
 export const MANUAL_FILE = "docs/agent-cloud.md";
 /** Marker that opens the generated block. */
@@ -16,17 +16,28 @@ export const END = "<!-- agent-cloud-kit:end -->";
 const FINDINGS = "## Hallazgos\n\n_Lo que el agente descubra de la nube va aquí._\n";
 /** Prefix of an https URL. */
 const HTTPS_PREFIX = "https://";
-/** Setup script the environment must run, in a `bash` block. */
-const SETUP_SCRIPT = `#!/bin/bash\nnpx -y ${PACKAGE}@1 setup`;
+/**
+ * Setup script the environment must run, for a `bash` block.
+ *
+ * @param packageVersion - Version of the running package.
+ * @returns The script.
+ * @example
+ * setupScript("1.2.0"); // "#!/bin/bash\nnpx -y agent-cloud-kit@1 setup"
+ */
+function setupScript(packageVersion) {
+    return `#!/bin/bash\nnpx -y ${packageSpec(packageVersion)} setup`;
+}
 /** The "how it works" section, five lines. */
 const HOW_IT_WORKS = [
     "## Cómo funciona",
     "",
     "1. agent-kitchen instala las herramientas y los ganchos en el repo.",
-    `2. \`${PACKAGE} prepare\` configura el repo con la skill y deja lista la lista de dominios y variables.`,
+    `2. \`${PACKAGE} prepare\` configura el repo con la skill y genera este documento.`,
     "3. Tú configuras el entorno en claude.ai con lo que indica la siguiente sección.",
     "4. Una sesión en la nube verifica que el entorno quedó bien.",
     "5. El PR guarda el resultado.",
+    "",
+    "Este documento se va actualizando. Cuando la skill `cloud-ready`, en local o en la nube, detecta que hace falta un dominio o una variable de entorno nueva, la agrega a `.claude/cloud.json`, regenera este archivo y te lo dice en la sesión. Cuando cambie la sección \"Configurar el entorno en claude.ai\", aplica lo nuevo en claude.ai y abre una sesión nueva.",
 ].join("\n");
 /**
  * Extracts the host of an apt repo URL.
@@ -62,11 +73,12 @@ function allowedHosts(config) {
  * Renders the "Configurar el entorno en claude.ai" section.
  *
  * @param config - Repo config.
+ * @param packageVersion - Version of the running package, for the setup script.
  * @returns The section, without a trailing newline.
  * @example
- * renderEnvironmentSection(config).startsWith("## Configurar el entorno en claude.ai"); // true
+ * renderEnvironmentSection(config, "1.0.0").startsWith("## Configurar el entorno en claude.ai"); // true
  */
-export function renderEnvironmentSection(config) {
+export function renderEnvironmentSection(config, packageVersion) {
     const hosts = allowedHosts(config);
     const lines = [
         "## Configurar el entorno en claude.ai",
@@ -82,7 +94,7 @@ export function renderEnvironmentSection(config) {
         "### Setup script",
         "",
         "```bash",
-        SETUP_SCRIPT,
+        setupScript(packageVersion),
         "```",
         "",
         "### Variables de entorno",
@@ -154,7 +166,7 @@ export function renderManual(input) {
         `<!-- Generado por ${PACKAGE} ${input.packageVersion}. No edites entre las marcas. -->`,
         "# Nube de Claude Code",
         HOW_IT_WORKS,
-        renderEnvironmentSection(input.config),
+        renderEnvironmentSection(input.config, input.packageVersion),
         VERIFY_SECTION,
         `## Qué corre en la nube\n\n${notes?.trim() ? notes.trim() : "Nada anotado."}`,
         END,

package/dist/prepare/detect.js

@@ -1,36 +1,8 @@
 /**
- * @file Pure parts of `prepare`: secret-name suggestions and preflight checks.
+ * @file Pure parts of `prepare`: preflight checks.
  */
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-/** File, in the repo root, whose keys are suggested as secret names. */
-const ENV_EXAMPLE_FILE = ".env.example";
-/** Matches a `KEY=value` line (optionally prefixed by `export`) and captures the key. */
-const ENV_LINE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
 /** Flag `claude` must advertise in its help to launch cloud sessions. */
 const CLOUD_FLAG = "--cloud";
-/**
- * Suggests secret names from the keys of `.env.example` in the repo root.
- *
- * @param repo Repo root.
- * @returns Keys in file order, without duplicates; empty when the file does not exist.
- * @example
- * suggestSecrets("/repo"); // ["API_TOKEN", "DB_URL"]
- */
-export function suggestSecrets(repo) {
-    const file = join(repo, ENV_EXAMPLE_FILE);
-    if (!existsSync(file))
-        return [];
-    const keys = [];
-    for (const line of readFileSync(file, "utf8").split(/\r?\n/)) {
-        if (line.trimStart().startsWith("#"))
-            continue;
-        const key = ENV_LINE.exec(line)?.[1];
-        if (key !== undefined && !keys.includes(key))
-            keys.push(key);
-    }
-    return keys;
-}
 /**
  * Checks that `prepare` can run.
  *

package/dist/prepare/index.js

@@ -10,9 +10,8 @@ import { CONFIG_FILE, OUTPUT_PREFIX, PACKAGE } from "../constants.js";
 import { defaultBranch } from "../detect.js";
 import { init } from "../init.js";
 import { renderEnvironmentSection, writeManual } from "../manual.js";
-import { preflight, suggestSecrets } from "./detect.js";
+import { preflight } from "./detect.js";
 import { configurePrompt, verifyPrompt } from "./prompts.js";
-import { askAll } from "./questions.js";
 /** Prefix of the branch `prepare` creates; the day follows it. */
 const BRANCH_PREFIX = "chore/cloud-ready-";
 /** Suffix added to the repo folder name to name the worktree folder, next to the repo. */
@@ -235,7 +234,7 @@ async function findResume(repo, deps) {
     return undefined;
 }
 /**
- * Steps 2–5: asks the questions, creates the worktree, installs the kit and runs the local agent.
+ * Steps 2–5: creates the worktree, installs the kit and runs the local agent.
  *
  * @param repo - Git root of the repo.
  * @param branch - Branch to create.
@@ -243,7 +242,6 @@ async function findResume(repo, deps) {
  * @param deps - Dependencies.
  * @param progress - Gets the worktree once it exists.
  * @returns True when the worktree is ready to commit.
- * @throws InterruptedError when the user presses Ctrl+C during the questions.
  * @example
  * await createAndConfigure("/home/u/app", "chore/cloud-ready-20261102", "/home/u/app-cloud-ready", deps, {});
  */
@@ -256,7 +254,6 @@ async function createAndConfigure(repo, branch, worktree, deps, progress) {
         deps.print(`${OUTPUT_PREFIX}branch ${branch} already exists; delete it (git branch -D ${branch}) or run prepare another day`);
         return false;
     }
-    const answers = await askAll(deps.ask, { secrets: suggestSecrets(repo) }, deps.print);
     const base = `origin/${defaultBranch(repo)}`;
     try {
         await deps.run("git", ["fetch", "-q", "origin"], { cwd: repo });
@@ -284,7 +281,7 @@ async function createAndConfigure(repo, branch, worktree, deps, progress) {
     }
     deps.print(EXIT_CLAUDE_HINT);
     try {
-        await runInteractive(deps, progress, [configurePrompt(answers)], worktree);
+        await runInteractive(deps, progress, [configurePrompt()], worktree);
     }
     catch {
         deps.print(stopped);
@@ -478,7 +475,7 @@ async function prepareSteps(gitRoot, deps, options, progress) {
         return EXIT_FAIL;
     const config = readConfig(worktree).config;
     if (config)
-        deps.print(renderEnvironmentSection(config));
+        deps.print(renderEnvironmentSection(config, deps.packageVersion));
     await deps.waitEnter(WAIT_TEXT);
     try {
         await runInteractive(deps, progress, ["--cloud", verifyPrompt({ branch, pr: pushed.pr })], worktree);

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/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";
@@ -91,12 +91,13 @@ 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`,
+            `the environment setup did not run for ${basename(repo)}. Set the setup script of the environment in claude.ai to: npx -y ${packageSpec(packageVersion)} setup`,
         ];
     }
     const out = [];
@@ -209,7 +210,7 @@ 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(", ")}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-cloud-kit",
-  "version": "1.0.0-rc.0",
+  "version": "1.0.0-rc.1",
   "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,7 +82,9 @@ 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,
@@ -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,24 @@ 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`), abre una sesión nueva y corre `/cloud-ready 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`,