agent-cloud-kit 0.0.0-stage → 1.0.0-rc.0

package/dist/skill.js

@@ -0,0 +1,148 @@
+/**
+ * @file The `cloud-ready` skill that `init` copies into the repo, and the link Claude Code needs
+ * to discover it.
+ */
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** Repo-relative directory of the `cloud-ready` skill. */
+export const SKILL_DIR = ".agents/skills/cloud-ready";
+/** Directory of the skill inside this package. */
+const PACKAGE_SKILL_DIR = "skills/cloud-ready";
+/** Repo-relative folder of the skills that Claude Code discovers. */
+const CLAUDE_SKILLS_DIR = ".claude/skills";
+/** Repo-relative folder of the skills that skills-manager installs. */
+const AGENTS_SKILLS_DIR = ".agents/skills";
+/** Repo-relative path of the link to the skill that Claude Code discovers. */
+const SKILL_LINK = `${CLAUDE_SKILLS_DIR}/cloud-ready`;
+/** Target of `SKILL_LINK`, relative to the folder that holds it. */
+const SKILL_LINK_TARGET = `../../${SKILL_DIR}`;
+/** Matches the frontmatter at the start of a skill file; group 1 is its body. */
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---/;
+/** Matches the `metadata:` block of the frontmatter, up to the next top-level key or the end. */
+const METADATA_BLOCK = /^metadata:[ \t]*\n((?:[ \t]+.*(?:\n|$))*)/m;
+/** Matches an indented `version:` line inside the metadata block; the value may be quoted. */
+const VERSION_LINE = /^\s+version:\s*"?([^"\n]+)"?$/m;
+/**
+ * Reads `metadata.version` from the frontmatter of the installed skill.
+ *
+ * @param repo - Repo root.
+ * @returns The version, or undefined when the skill or its version is missing.
+ * @example
+ * skillVersion("/home/user/app"); // "1.0.0"
+ */
+export function skillVersion(repo) {
+    const file = join(repo, SKILL_DIR, "SKILL.md");
+    if (!existsSync(file))
+        return undefined;
+    const frontmatter = FRONTMATTER.exec(readFileSync(file, "utf8"))?.[1] ?? "";
+    const block = METADATA_BLOCK.exec(frontmatter)?.[1] ?? "";
+    return VERSION_LINE.exec(block)?.[1]?.trim();
+}
+/**
+ * Sets `metadata.version` in the frontmatter of a skill file, adding the block when it is missing.
+ *
+ * @param text - Content of SKILL.md.
+ * @param version - Version to write.
+ * @returns The new content; unchanged when the file has no frontmatter.
+ * @example
+ * withVersion('---\nname: x\nmetadata:\n  version: "0.0.0"\n---\n', "1.0.0"); // version "1.0.0"
+ */
+function withVersion(text, version) {
+    const match = FRONTMATTER.exec(text);
+    if (!match)
+        return text;
+    const frontmatter = match[1] ?? "";
+    const line = `  version: "${version}"`;
+    const block = METADATA_BLOCK.exec(frontmatter);
+    let updated;
+    if (!block) {
+        updated = `${frontmatter}\nmetadata:\n${line}`;
+    }
+    else {
+        const body = block[1] ?? "";
+        const newBody = VERSION_LINE.test(body) ? body.replace(VERSION_LINE, line) : `${line}\n${body}`;
+        const head = block[0].slice(0, block[0].length - body.length);
+        updated = frontmatter.slice(0, block.index) + head + newBody + frontmatter.slice(block.index + block[0].length);
+    }
+    return `---\n${updated}\n---${text.slice(match[0].length)}`;
+}
+/**
+ * Copies the `cloud-ready` skill of this package into the repo, with `metadata.version` set to the
+ * package version. Leaves it untouched when it is already at that version; otherwise replaces the
+ * whole folder atomically (copy to a temp folder, then rename).
+ *
+ * @param repo - Repo root.
+ * @param packageRoot - Root of this package, which holds `skills/cloud-ready`.
+ * @param packageVersion - Version of this package.
+ * @returns A line describing the outcome.
+ * @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"
+ */
+export function installSkill(repo, packageRoot, packageVersion) {
+    const current = skillVersion(repo);
+    if (current === packageVersion)
+        return `${SKILL_DIR} already at ${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}`);
+    const target = join(repo, SKILL_DIR);
+    const temp = `${target}.${process.pid}.tmp`;
+    const old = `${target}.${process.pid}.old`;
+    mkdirSync(dirname(target), { recursive: true });
+    try {
+        rmSync(temp, { recursive: true, force: true });
+        cpSync(source, temp, { recursive: true });
+        const skillFile = join(temp, "SKILL.md");
+        writeFileSync(skillFile, withVersion(readFileSync(skillFile, "utf8"), packageVersion));
+        if (existsSync(target))
+            renameSync(target, old);
+        renameSync(temp, target);
+    }
+    catch (err) {
+        rmSync(temp, { recursive: true, force: true });
+        if (existsSync(old) && !existsSync(target))
+            renameSync(old, target);
+        throw err;
+    }
+    rmSync(old, { recursive: true, force: true });
+    return current === undefined ? `installed ${SKILL_DIR} ${packageVersion}` : `updated ${SKILL_DIR} from ${current} to ${packageVersion}`;
+}
+/**
+ * Tells whether a path exists, counting a broken symlink as existing.
+ *
+ * @param path - Absolute path.
+ * @returns True when something is there.
+ */
+function present(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Links the skill where Claude Code discovers it: Claude Code does not read `.agents/skills/`, so
+ * this creates the relative symlink `.claude/skills/cloud-ready -> ../../.agents/skills/cloud-ready`.
+ * Does nothing when `.claude/skills` already resolves to `.agents/skills` or the entry exists.
+ *
+ * @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"
+ */
+export function linkSkill(repo) {
+    const claudeSkills = join(repo, CLAUDE_SKILLS_DIR);
+    const agentsSkills = join(repo, AGENTS_SKILLS_DIR);
+    if (existsSync(claudeSkills) && existsSync(agentsSkills) && realpathSync(claudeSkills) === realpathSync(agentsSkills))
+        return undefined;
+    const link = join(repo, SKILL_LINK);
+    if (present(link))
+        return undefined;
+    mkdirSync(claudeSkills, { recursive: true });
+    symlinkSync(SKILL_LINK_TARGET, link);
+    return `linked ${SKILL_LINK} to ${SKILL_DIR}`;
+}

package/dist/state.js

@@ -0,0 +1,147 @@
+/**
+ * @file Machine fingerprint and the per-repo state file that records what setup last did.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { TOOLS } from "./detect.js";
+/** Directory, inside the tools dir, that holds one state file per repo. */
+const STATE_DIR = "state";
+/** Prefix of every fingerprint. */
+const FINGERPRINT_PREFIX = "sha256-";
+/** Hash algorithm used for fingerprints. */
+const HASH_ALGORITHM = "sha256";
+/** Indentation of the state file. */
+const JSON_INDENT = 2;
+/**
+ * Serializes a value as JSON with object keys sorted recursively; arrays keep their order.
+ *
+ * @param value - Any JSON-compatible value.
+ * @returns A canonical JSON string.
+ */
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    if (typeof value === "object" && value !== null) {
+        const entries = Object.entries(value)
+            .filter(([, v]) => v !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([k, v]) => `${JSON.stringify(k)}:${stableJson(v)}`);
+        return `{${entries.join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+/**
+ * Hashes everything that decides how the machine is built, so a change asks for a rebuild.
+ * `session`, `requiredEnv` and `notes` are left out: changing them does not need a rebuild.
+ *
+ * @param config - Repo config.
+ * @param versions - Pinned tool versions.
+ * @param images - Docker images to pull.
+ * @param packageVersion - Version of this package.
+ * @returns `sha256-<hex>`.
+ * @example
+ * fingerprint(config, { node: "20.1.0" }, ["postgres:16"], "1.0.0"); // "sha256-ab12..."
+ */
+export function fingerprint(config, versions, images, packageVersion) {
+    const { version, aptRepos, apt, docker, setup } = config;
+    const json = stableJson({ version, aptRepos, apt, docker, setup, versions, images, packageVersion });
+    return FINGERPRINT_PREFIX + createHash(HASH_ALGORITHM).update(json).digest("hex");
+}
+/**
+ * Locates the state file of a repo.
+ *
+ * @param toolsDir - Tools directory.
+ * @param repo - Repo root path.
+ * @returns `<toolsDir>/state/<basename(repo)>.json`.
+ * @example
+ * statePath("/opt/agent-cloud-kit", "/home/user/app"); // "/opt/agent-cloud-kit/state/app.json"
+ */
+export function statePath(toolsDir, repo) {
+    return join(toolsDir, STATE_DIR, `${basename(repo)}.json`);
+}
+/**
+ * Writes the state file atomically (temp file in the same dir, then rename).
+ *
+ * @param toolsDir - Tools directory.
+ * @param repo - Repo root path.
+ * @param state - State to record.
+ * @example
+ * writeState("/opt/agent-cloud-kit", "/home/user/app", state);
+ */
+export function writeState(toolsDir, repo, state) {
+    const file = statePath(toolsDir, repo);
+    mkdirSync(join(toolsDir, STATE_DIR), { recursive: true });
+    const temp = `${file}.${process.pid}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(state, null, JSON_INDENT)}\n`);
+    renameSync(temp, file);
+}
+/**
+ * Tells whether a value is a plain JSON object.
+ *
+ * @param value - Any parsed JSON value.
+ * @returns True for non-null, non-array objects.
+ */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Tells whether a parsed value has the shape of a `StepResult`.
+ *
+ * @param value - Any parsed JSON value.
+ * @returns True for a string `name`, a boolean `ok`, a finite numeric `ms` and an optional string `error`.
+ */
+function isStepResult(value) {
+    if (!isRecord(value))
+        return false;
+    return (typeof value.name === "string" &&
+        typeof value.ok === "boolean" &&
+        typeof value.ms === "number" &&
+        Number.isFinite(value.ms) &&
+        (value.error === undefined || typeof value.error === "string"));
+}
+/**
+ * Tells whether a parsed value is a map of known tools to version strings.
+ *
+ * @param value - Any parsed JSON value.
+ * @returns True when every key is a tool and every value a string.
+ */
+function isVersionMap(value) {
+    if (!isRecord(value))
+        return false;
+    return Object.entries(value).every(([k, v]) => TOOLS.includes(k) && typeof v === "string");
+}
+/**
+ * Tells whether a parsed value has the shape of a `MachineState`; a missing `resolved` is accepted.
+ *
+ * @param value - Any parsed JSON value.
+ * @returns True when all required fields are present with the right types.
+ */
+function isMachineState(value) {
+    if (!isRecord(value))
+        return false;
+    return (typeof value.fingerprint === "string" &&
+        typeof value.packageVersion === "string" &&
+        typeof value.finishedAt === "string" &&
+        Array.isArray(value.steps) &&
+        value.steps.every(isStepResult) &&
+        (value.resolved === undefined || isVersionMap(value.resolved)));
+}
+/**
+ * Reads a repo's state file; never throws because it runs at session start.
+ *
+ * @param toolsDir - Tools directory.
+ * @param repo - Repo root path.
+ * @returns The state, or undefined when the file is missing, unreadable, invalid or incomplete.
+ * @example
+ * readState("/opt/agent-cloud-kit", "/home/user/app"); // undefined before the first setup
+ */
+export function readState(toolsDir, repo) {
+    try {
+        const parsed = JSON.parse(readFileSync(statePath(toolsDir, repo), "utf8"));
+        return isMachineState(parsed) ? { ...parsed, resolved: parsed.resolved ?? {} } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/steps.js

@@ -0,0 +1,46 @@
+/**
+ * @file Step results: runs one unit of work and reports its outcome without ever throwing.
+ */
+/**
+ * Runs a step, timing it and converting any failure into a result.
+ *
+ * @param name - Name reported in the result.
+ * @param fn - Work to run.
+ * @returns The outcome; this promise never rejects.
+ * @example
+ * await step("pull images", async () => pull()); // { name: "pull images", ok: true, ms: 1200 }
+ */
+export async function step(name, fn) {
+    const start = Date.now();
+    try {
+        await fn();
+        return { name, ok: true, ms: Date.now() - start };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        return { name, ok: false, ms: Date.now() - start, error };
+    }
+}
+/** Prefix of the name given to a lane whose function rejected. */
+const LANE_NAME_PREFIX = "lane ";
+/**
+ * Runs lanes of steps concurrently and joins their results in lane order.
+ *
+ * @param laneFns - Lane functions, each resolving to the results of its own steps.
+ * @returns Results ordered by lane, then by position within the lane; never rejects.
+ * @example
+ * await lanes(async () => [await step("a", fa)], async () => [await step("b", fb)]);
+ */
+export async function lanes(...laneFns) {
+    const groups = await Promise.all(laneFns.map(async (laneFn, index) => {
+        const start = Date.now();
+        try {
+            return await laneFn();
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            return [{ name: `${LANE_NAME_PREFIX}${index}`, ok: false, ms: Date.now() - start, error }];
+        }
+    }));
+    return groups.flat();
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "agent-cloud-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-rc.0",
+  "description": "Zero-dependency CLI that prepares Claude Code cloud sessions.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ramon-sg/agent-cloud-kit.git"
+  },
+  "homepage": "https://github.com/ramon-sg/agent-cloud-kit#readme",
+  "bugs": {
+    "url": "https://github.com/ramon-sg/agent-cloud-kit/issues"
+  },
+  "keywords": [
+    "cloud",
+    "sandbox",
+    "setup",
+    "session-start",
+    "cli"
+  ],
+  "bin": {
+    "agent-cloud-kit": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "schema.json",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "test": "node --test 'test/**/*.test.ts'"
+  },
+  "devDependencies": {
+    "@types/node": "20.19.43",
+    "typescript": "7.0.2"
+  }
+}

package/schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "agent-cloud-kit config",
+  "description": "Contents of .claude/cloud.json for agent-cloud-kit.",
+  "type": "object",
+  "required": ["version"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string", "description": "Path or URL of this schema." },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?(\\+[0-9A-Za-z.-]+)?$",
+      "description": "Exact agent-cloud-kit version to run (no ranges)."
+    },
+    "aptRepos": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": [],
+      "description": "HTTPS URLs of setup scripts that add APT repositories (piped to bash)."
+    },
+    "apt": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": [],
+      "description": "APT packages to install."
+    },
+    "docker": {
+      "type": "object",
+      "additionalProperties": false,
+      "default": { "pull": "auto" },
+      "properties": {
+        "pull": {
+          "description": "\"auto\" detects images, false disables pulling, or list images explicitly.",
+          "oneOf": [
+            { "const": "auto" },
+            { "const": false },
+            { "type": "array", "items": { "type": "string" } }
+          ],
+          "default": "auto"
+        }
+      }
+    },
+    "setup": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": [],
+      "description": "Shell commands run once when the environment is set up."
+    },
+    "session": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": [],
+      "description": "Shell commands run at the start of every session."
+    },
+    "requiredEnv": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": [],
+      "description": "Environment variables that must be set; a warning is shown when missing."
+    },
+    "domains": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)+$" },
+      "default": [],
+      "description": "Extra hosts the cloud environment must allow; doctor probes them and the manual lists them."
+    },
+    "notes": {
+      "type": "string",
+      "description": "What does and does not run in the cloud: free text, or a path, relative to the repo, of a text file inside it whose contents are used instead. The session prints it at start and the manual shows it."
+    }
+  }
+}

package/skills/cloud-ready/SKILL.md

@@ -0,0 +1,179 @@
+---
+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"
+metadata:
+  version: "1.0.0"
+---
+
+# cloud-ready
+
+Deja el repo listo para la nube de Claude Code y lo comprueba en la nube real. No impone una
+forma de testear: se respeta lo que el repo ya hace. Un repo sin tests solo necesita la máquina
+preparada.
+
+- **Modo:** el primer argumento. `configure` corre en local con el usuario; `verify`, en la nube.
+  Sin argumento: `verify` si `CLAUDE_CODE_REMOTE=true`, si no `configure`.
+- **Antes de empezar:** lee `reference/knowledge.md` (lo que se sabe de la nube) y, si el repo
+  tiene tests, `reference/compat.md` (cómo hacerlos compatibles).
+- **El archivo de `notes`:** el que diga `notes` en `.claude/cloud.json`; si no hay, usa
+  `.claude/cloud-notes.md` y pon `"notes": ".claude/cloud-notes.md"` en la config. Se muestra al
+  empezar cada sesión en la nube y se copia en `docs/agent-cloud.md`: que sea corto.
+- **La CLI:** `agent-cloud-kit <comando>`. Si no está en el `PATH`, usa `npx -y agent-cloud-kit <comando>`.
+
+## Archivos de la preparación
+
+Son los únicos que `verify` puede cambiar:
+
+- `.claude/cloud.json`
+- el archivo de `notes`
+- `docs/agent-cloud.md` (lo regenera `agent-cloud-kit manual`; a mano solo la sección "Hallazgos")
+- `.agents/skills/test-audit/project.md` (solo su sección "Nube", y solo si el archivo existe)
+
+## `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.
+
+1. **Lee qué usa el repo:** `package.json` (scripts, `packageManager`, `engines`), el lockfile,
+   `.tool-versions`, `mise.toml`, `.nvmrc`, archivos de Docker compose, `Dockerfile`,
+   `.env.example`, la CI (`.github/workflows/`) y el README. Lee `.claude/cloud.json` si existe.
+2. **Escribe la preparación en `.claude/cloud.json`** (no toques `version` ni `$schema`):
+   - `setup`: la instalación de dependencias con el gestor del repo y el lockfile congelado
+     (`npm ci`, `pnpm install --frozen-lockfile`, `bun install --frozen-lockfile`…), más lo que
+     haga falta una sola vez (p. ej. navegadores de Playwright). Node y los gestores fijados en
+     `.tool-versions`, `mise.toml`, `.nvmrc` o `packageManager` los instala el paquete solo: no
+     los agregues. Cada paso tiene 180 s y el setup entero debe quedar bajo ~5 min.
+   - `apt` y `aptRepos`: solo lo que el repo necesite y la imagen no traiga.
+   - `session`: comandos rápidos de cada sesión (2 min como máximo cada uno, sin depender de la red).
+   - `domains`: los hosts que el setup o los tests necesitan y que no están en la lista por
+     defecto de gestores de paquetes.
+   - `requiredEnv`: solo los nombres de las variables secretas que de verdad hacen falta en la nube.
+   - `notes`: la ruta del archivo de `notes`.
+3. **Busca los tests del repo:** scripts `test*` y `e2e*` de `package.json`, configuración de
+   runners (`vitest.config.*`, `jest.config.*`, `playwright.config.*`, `.mocharc*`),
+   Testcontainers en las dependencias, compose de tests y los jobs de la CI que corren tests.
+4. **Sin tests:** díselo al usuario y no hagas nada más con tests. Anota en `notes` que el repo
+   no tiene tests y que en la nube solo se prepara la máquina. Sigue en el paso 7.
+5. **Con tests:** agrúpalos (p. ej. unitarios, con base de datos, de navegador) y, para cada
+   grupo, di si correría en la nube tal cual. Si no, propón, en este orden
+   (`reference/compat.md`):
+   1. Adaptar la preparación: `setup`, `session`, `domains`, `requiredEnv`.
+   2. Solo si eso no basta, una variante para la nube: un script aparte (p. ej. `cloud:services`)
+      o una rama por `CLAUDE_CODE_REMOTE` en un script existente.
+   3. Si nada de eso alcanza, déjalo fuera de la nube y explica por qué.
+
+   Muestra cada propuesta con el cambio exacto (archivo y contenido).
+6. **Pregunta y aplica solo lo aprobado.** Un cambio fuera de la config (scripts, compose,
+   configuración de tests) necesita un sí explícito del usuario. Nunca cambies lo que un test
+   comprueba ni crees scripts de tests nuevos sin aprobación.
+7. **Escribe el archivo de `notes`:** qué correr en la nube (el comando tal como lo corre el
+   repo, lo que hay que levantar antes, cuánto tarda y si va en segundo plano), qué no y por qué.
+   Por ejemplo:
+
+   ```markdown
+   En la nube: `npm test` (~1 min). Antes de `npm run test:db`, `docker compose up -d db`
+   (~3 min, en segundo plano). No corre `npm run test:e2e:prod`: pega a una API externa que el
+   entorno no permite.
+   ```
+
+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).
+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
+    invocaron fuera de `prepare`, omite este paso.
+
+## `verify` (en la nube)
+
+Solo con `CLAUDE_CODE_REMOTE=true`; si no, detente y dilo. El prompt trae la rama de `prepare`
+(`chore/cloud-ready-…`) y puede traer el número del PR. La sesión trabaja en su propia rama
+`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).
+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
+   versiones fijadas (`node -v` y los demás gestores contra `.tool-versions`, `mise.toml`,
+   `.nvmrc` o `packageManager`), las variables de `requiredEnv` presentes (solo nombres; nunca
+   imprimas valores) y Docker, si el repo lo usa.
+4. **Tests, solo si las `notes` dicen qué correr en la nube.** Córrelos tal como el repo los
+   corre, con lo que haya que levantar antes. Las corridas largas van en segundo plano, con la
+   salida a un log que sigues hasta que terminen. Si las `notes` no dicen qué correr, no corras
+   tests y dilo en el reporte.
+5. **Si algo falla,** diagnostica con `reference/knowledge.md` y `reference/compat.md`, y
+   clasifica:
+   - **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.
+   - **Requiere cambiar código, tests o scripts:** no lo cambies; deja el cambio propuesto
+     (archivo y diff) para el comentario del PR.
+
+   Hasta **3 intentos** de arreglo en total. Tras el tercero, detente y reporta lo que queda.
+6. **Hallazgos:** ver "Hallazgos", abajo.
+7. **Corre `agent-cloud-kit manual`.**
+8. **Antes del commit,** revisa `git diff --name-only HEAD` y `git status --porcelain`. Todo lo
+   que no sea un archivo de la preparación se revierte con `git checkout -- <archivo>` (si está
+   versionado) o se borra (si es nuevo y lo creaste tú). Un cambio necesario al código, tests o
+   scripts queda como propuesta en el comentario del PR.
+9. **Commit y push:** agrega solo los archivos de la preparación que cambiaron, por nombre
+   (`git add -- .claude/cloud.json <archivo de notes> docs/agent-cloud.md`, más
+   `.agents/skills/test-audit/project.md` si lo tocaste); si hay algo en stage,
+   `git commit -m "chore(cloud): verify cloud-ready"`. Luego
+   `git push origin HEAD:<rama de prepare>`. Si el push se rechaza, `git fetch origin <rama de
+   prepare>`, `git rebase FETCH_HEAD` (el clon es parcial: `origin/<rama>` puede no existir) y
+   reintenta una vez.
+10. **Comentario en el PR,** por REST con `gh api` (`gh pr …` usa GraphQL y está bloqueado;
+    `gh auth status` dice que el token es inválido, pero `gh api` funciona):
+    - `owner` y `repo`: de `git remote get-url origin` (las dos últimas partes de la ruta, sin `.git`).
+    - Número del PR: el del prompt; si no viene,
+      `gh api "repos/{owner}/{repo}/pulls?head={owner}:{rama de prepare}&state=open" --jq '.[0].number'`.
+    - Comentario: escribe el cuerpo en un archivo temporal y
+      `gh api repos/{owner}/{repo}/issues/{n}/comments -f body="$(cat <archivo>)"`.
+    - Si no hay PR, el resultado queda solo en `docs/agent-cloud.md` y en tu resumen final.
+    - No saques el PR de draft: lo decide el usuario.
+11. **Resumen final** en la sesión, con lo mismo que el comentario.
+
+### El comentario del PR
+
+```markdown
+## cloud-ready verify
+
+**Comprobado:** `agent-cloud-kit doctor` (salida 0 / qué falló), dependencias, versiones, variables.
+**Corrió:** cada comando, su resultado y cuánto tardó.
+**No corrió:** qué y por qué.
+**Cambiar en claude.ai:** la instrucción exacta (dónde y qué), o "nada".
+**Cambios propuestos al código o los tests:** archivo y diff, o "ninguno".
+**Arreglado en la preparación:** archivos y por qué. Intentos: n de 3.
+**Hallazgos:** los nuevos, o "ninguno".
+```
+
+## Hallazgos
+
+En ambos modos: todo hecho nuevo sobre la nube (algo que no está en `reference/knowledge.md`,
+o que lo contradice) va a la sección `## Hallazgos` de `docs/agent-cloud.md`, fuera de las
+marcas de `agent-cloud-kit` (`manual` la conserva). Una línea por hallazgo, marcada
+"proponer al paquete":
+
+```markdown
+- (proponer al paquete) `docker compose` necesita `--wait` para que la base acepte conexiones.
+  Visto en `verify`, 2026-11-02, con `docker compose up -d db`.
+```
+
+No edites `reference/knowledge.md` del repo: se reemplaza al actualizar el paquete.
+
+## Límites
+
+- `verify` nunca cambia código, tests ni scripts; `configure`, solo con aprobación del usuario.
+- Nunca imprimas ni escribas el valor de una variable secreta; solo su nombre.
+- Nada de `gh pr` ni `gh issue` en la nube: usa `gh api` (REST).
+- No configures claude.ai: da la instrucción exacta y que la haga el usuario.