kcreate-scaffolding-gcp-script 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kronops
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,371 @@
-# Temporary Holding Version
+# KCreateScaffoldingGCPScripts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Skill de Claude Code (`kcreate-scaffolding-gcp-script`) que genera el
+scaffolding de Terragrunt para un entorno GCP nuevo, copiando y adaptando
+uno ya existente del mismo repo (`live/<entorno-nuevo>/` a partir de
+`live/<entorno-existente>/`). Pensado para repos con la convención de
+[`club-tijuana/infra-cloud`](https://github.com/club-tijuana/infra-cloud):
+`live/<entorno>/<componente>/terragrunt.hcl` + `Makefile` + `.gitignore`
+por componente.
+
+Este repo es el **instalador** del skill: contiene el skill, sus scripts y su
+dependencia vendorizada, y los copia a `<repo-destino>/.claude/skills/`. No
+contiene `live/` ni se instala a sí mismo.
+
+**Este skill no despliega nada en GCP.** Solo crea/edita archivos locales.
+El despliegue es un proceso aparte, posterior y manual.
+
+> El directorio local y el nombre viejo del repo eran
+> `KTerragruntScaffoldingScripts`; el repo en GitHub es
+> [`kronops/KCreateScaffoldingGCPScripts`](https://github.com/kronops/KCreateScaffoldingGCPScripts).
+
+| Documento | Para qué |
+|---|---|
+| `README.md` (este) | Manual de usuario: qué hace, cómo se instala y cómo se usa. |
+| [`AGENT.md`](AGENT.md) | Guía operativa para agentes de IA: ciclo completo, contrato de exit codes, fallas comunes, receta de validación. |
+| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Flujo de contribución, convenciones e invariantes del código. |
+| [`DeployNPM.md`](DeployNPM.md) | Manual operativo para publicar el paquete npm (comandos exactos, autenticación con OTP, verificación y errores comunes). |
+| [`CHANGELOG.md`](CHANGELOG.md) | Historia de versiones (Keep a Changelog). |
+| [`IDEA.md`](IDEA.md) | Especificación de origen del skill. |
+| [`kcreate-scaffolding-gcp-script/SKILL.md`](kcreate-scaffolding-gcp-script/SKILL.md) | Instrucciones del agente, etapa por etapa (lo que ejecuta el skill instalado). |
+| [`kcreate-scaffolding-gcp-script/references/lessons-learned.md`](kcreate-scaffolding-gcp-script/references/lessons-learned.md) | El "por qué" de cada script y validación, con los errores reales que los motivaron. |
+
+## Qué resuelve
+
+Generar estos scripts a mano es mecánico pero con muchas oportunidades de
+error que **no se detectan hasta el momento real de desplegar en GCP**
+(un rango CIDR que colisiona, una IP mal transcrita, una API faltante, un
+nombre de red que se quedó con el del entorno viejo). Este skill
+automatiza esa generación con scripts de shell determinísticos — no con
+juicio de un agente de IA en cada paso — para eliminar esa clase de
+errores por diseño. El detalle completo de cada error real que este
+diseño evita está en
+[`kcreate-scaffolding-gcp-script/references/lessons-learned.md`](kcreate-scaffolding-gcp-script/references/lessons-learned.md).
+
+## Instalación
+
+Hay dos instaladores **intercambiables**: dejan exactamente el mismo
+resultado en el repo destino (mismos archivos, mismos permisos, mismos exit
+codes). Elige el que te acomode.
+
+En ambos casos se instala el skill (+ su dependencia
+[`github-proyect-tracking`](https://github.com/kronops/KGithubTracking),
+vendorizada en `vendor/`) en el repo donde se va a usar, como skill de
+proyecto de Claude Code.
+
+### Opción A — `npx` (sin instalar el skill a mano)
+
+Si el paquete está en el registro de npm (o tienes el tarball):
+
+```bash
+npx --yes kcreate-scaffolding-gcp-script --target-repo /ruta/a/tu/repo-de-infra
+npx --yes ./kcreate-scaffolding-gcp-script-0.2.0.tgz --target-repo /ruta/a/tu/repo-de-infra
+```
+
+Generar el tarball desde una copia del repo:
+
+```bash
+git clone git@github-work:kronops/KCreateScaffoldingGCPScripts.git
+cd KCreateScaffoldingGCPScripts/npm
+npm pack          # prepack empaqueta skill/ + vendor/ + README + LICENSE
+npx --yes ./kcreate-scaffolding-gcp-script-0.2.0.tgz --target-repo /ruta/a/tu/repo
+```
+
+Requisitos del instalador npx: **Node ≥ 18** (cero dependencias npm). El skill
+en sí no usa Node: es bash + Python 3.8+ stdlib.
+
+> `npx ... github:kronops/KCreateScaffoldingGCPScripts` **no** sirve: npm
+exige el `package.json` en la raíz del repo y aquí vive en `npm/` (npm no
+soporta subdirectorios en dependencias git). Por eso la opción `npx`
+requiere el paquete publicado o un tarball local.
+
+### Opción B — clonando el repo
+
+```bash
+git clone git@github-work:kronops/KCreateScaffoldingGCPScripts.git
+cd KCreateScaffoldingGCPScripts
+./install.sh --target-repo /ruta/a/tu/repo-de-infra
+```
+
+### Resultado (idéntico en ambas opciones)
+
+```
+<tu-repo>/.claude/skills/
+├── kcreate-scaffolding-gcp-script/   # este skill
+└── github-proyect-tracking/          # dependencia, para poder reanudar
+```
+
+Si el repo destino no tiene `live/`, el instalador avisa con `[WARN]` (el
+skill asume la convención `live/<entorno>/<componente>/terragrunt.hcl`) pero
+igual instala: la herramienta sirve para cualquier repo, aunque falle al
+usarse.
+
+### Flags
+
+Los mismos nombres y semántica en `install.sh` y en el instalador npx:
+
+| Flag | Para qué |
+|---|---|
+| `--target-repo RUTA` | Raíz del repo destino (obligatorio; debe ser un repo git). |
+| `--skip-tracking` | No instala/actualiza `github-proyect-tracking`, por si el repo destino ya lo gestiona por su cuenta. |
+| `--force` | Sobreescribe si el skill ya existe en el destino. Sin esta bandera, una instalación existente nunca se toca: se reporta con `[ERROR]` y **exit 1** (no se instala nada). |
+
+Para desinstalar:
+
+```bash
+# npx
+npx --yes kcreate-scaffolding-gcp-script uninstall --target-repo /ruta/a/tu/repo
+
+# clonado
+./uninstall.sh --target-repo /ruta/a/tu/repo
+```
+
+| Flag de uninstall | Para qué |
+|---|---|
+| `--with-tracking` | También elimina `github-proyect-tracking`. Por defecto **no** se toca, porque otro skill del mismo repo podría seguir usándolo. |
+| `--clean-gitignore` | También quita la línea `.kcreate-scaffolding/` del `.gitignore` del destino y borra la carpeta `.kcreate-scaffolding/` (configs y warnings de ejecuciones anteriores). Es destructivo a propósito: úsalo solo si ya no necesitas revisar esos archivos. |
+
+### Diagnóstico previo (`npx … doctor`)
+
+Solo en el instalador npx. No modifica nada: dice qué hay instalado en el
+repo destino y si están las dependencias que usan los scripts.
+
+```bash
+npx --yes kcreate-scaffolding-gcp-script doctor --target-repo /ruta/a/tu/repo
+```
+
+Revisa `bash`, `git`, `python3` (con `ipaddress`), `curl` y `terragrunt`
+(**opcional**: si falta, el build omite `hcl fmt`/`hcl validate` y avisa).
+Termina con `[OK] Entorno listo para usar el skill.` (exit 0) o con exit 1
+listando los requisitos faltantes.
+
+### Publicar el paquete npm (mantenedores)
+
+El procedimiento completo — y los comandos exactos, uno por uno — está en
+[`DeployNPM.md`](DeployNPM.md). Resumen:
+
+```bash
+cd npm
+npm whoami                     # ¿hay sesión? (hoy: E401, hay que loguearse)
+npm login --auth-type=legacy   # usuario, password, email y, si la cuenta tiene 2FA, OTP
+npm publish --dry-run          # ensayo obligatorio: construye el tarball sin subir nada
+npm publish                    # publicar (con 2FA: npm publish --otp=123456)
+```
+
+Ojo: si la cuenta tiene 2FA, el login por navegador **no** sirve sin GUI; hay
+que usar `--auth-type=legacy` y pasar el OTP. El `.npmrc` que deja el login
+contiene `_authToken` y ya está en `.gitignore`.
+
+`npm/bin/build.js` reconstruye `npm/skill/`, `npm/vendor/`,
+`npm/README.md` y `npm/LICENSE` desde la raíz del repo en cada
+`npm pack`/`npm publish` — son artefactos generados y están en `.gitignore`,
+nunca se comitean. Prueba local sin publicar:
+
+```bash
+cd npm && npm pack
+npx --yes ./kcreate-scaffolding-gcp-script-0.2.0.tgz --target-repo /ruta/al/repo
+```
+
+Para subir una versión nueva: `node -p "require('./package.json').version"`,
+luego `npm version patch --no-git-tag-version` (o `minor`/`major` según el
+cambio) y refleja la versión en `CHANGELOG.md` y en las rutas de este README.
+El `--no-git-tag-version` es obligatorio aquí: el `package.json` no está en la
+raíz git y sin ese flag `npm version` crea commits y tags inesperados. Subir la
+versión no es opcional cuando ya se publicó: una versión del registro no se
+puede reutilizar (`E409`).
+
+## Uso
+
+Desde una sesión de Claude Code abierta en el repo destino (con el skill
+ya instalado ahí), con el cwd en la raíz de ese repo:
+
+```
+/kcreate-scaffolding-gcp-script <SOURCE_ENV> <NEW_ENV>
+```
+
+- `SOURCE_ENV`: el entorno ya existente a copiar (ej. `boletera-qa`).
+  Cualquiera que ya exista en `live/` sirve — no hay uno "oficial".
+- `NEW_ENV`: el id del entorno nuevo, patrón `<app>-qa` o `<app>-prod` en
+  minúsculas (ej. `xoloshop-prod`).
+
+El agente sigue entonces las 3 etapas descritas en
+[`kcreate-scaffolding-gcp-script/SKILL.md`](kcreate-scaffolding-gcp-script/SKILL.md):
+
+1. **Pre requisitos** — genera (o reanuda) un archivo de configuración en
+   `.kcreate-scaffolding/<NEW_ENV>.config`, autodetectando del propio
+   `SOURCE_ENV` todo lo que se pueda (org id, billing account,
+   región/zona, owner, IPs fijas, versiones actuales). Solo pide al
+   humano lo que de verdad no se puede inferir: el repo de GitHub de la
+   app nueva y la URL del proyecto de GitHub usado para llevar el
+   seguimiento de esta ejecución. Antes de construir nada, muestra el
+   archivo completo y pide confirmación explícita.
+2. **Construcción** — un solo comando genera `live/<NEW_ENV>/` completo,
+   componente por componente, con sustituciones de texto determinísticas
+   (nunca ediciones "a mano" de HCL). Avisa con `[WARN]` en los pocos
+   casos que de verdad requieren revisión humana (ver la lista completa en
+   `lessons-learned.md`).
+3. **Validación** — dos scripts confirman que el resultado está completo
+   (mismos archivos que `SOURCE_ENV`, ni más ni menos) y que cada
+   componente apunta siempre al proyecto GCP correcto, sin importar qué
+   proyecto tenga `gcloud` como default en ese momento.
+
+Si el proceso se interrumpe a la mitad (sesión caída, error de red), basta
+con pedirle al agente que vuelva a correr el mismo comando. El progreso
+se registra en `github-proyect-tracking` (un Issue del repo de GitHub que
+pusiste en `TRACKING_GITHUB_PROJECT_URL`) cuando está disponible — si
+falla (sin red, token, URL inválida), la construcción sigue igual sin
+tracking, solo con un aviso. La construcción en sí es idempotente: cada
+componente se reconstruye siempre desde `SOURCE_ENV`, así que reintentar
+después de un fallo a medias no requiere borrar nada ni produce un
+resultado distinto (el rango CIDR elegido también se reusa, no se vuelve
+a calcular).
+
+### El archivo de configuración
+
+Se genera una sola vez por ejecución, en
+`.kcreate-scaffolding/<NEW_ENV>.config` (gitignorado automáticamente —
+nunca se comitea). Plantilla de referencia:
+[`kcreate-scaffolding-gcp-script/templates/scaffolding.config.template`](kcreate-scaffolding-gcp-script/templates/scaffolding.config.template).
+
+Campos que **siempre** hay que llenar a mano (no se pueden inferir de
+`SOURCE_ENV`):
+
+| Campo | Qué es |
+|---|---|
+| `APP_GITHUB_REPO` | Repo(s) de GitHub (`owner/repo`) que hacen `push` de imágenes Docker al Artifact Registry del proyecto nuevo. Uno solo en el caso común; si la app tiene varios repos, sepáralos con `;` — se genera un binding de `github_workload_identity` por cada uno. Se asume que ya existen — no se valida contra GitHub. |
+| `TRACKING_GITHUB_PROJECT_URL` | URL (`https://github.com/{owner}/{repo}`) donde `github-proyect-tracking` va a crear el Issue de seguimiento de esta ejecución. |
+
+Campos opcionales, con default vacío (no bloquean `CONFIG_READY`):
+
+| Campo | Qué es |
+|---|---|
+| `EXTRA_COMPONENTS` | Componentes a incluir además de los base (ver "Componentes base vs. opcionales" abajo), separados por `;`. Vacío por defecto. |
+| `DNS_DOMAIN` | Si `sql_postgres` usa `dns_domain_name`, el dominio real que `NEW_ENV` usa. Vacío por defecto — el skill genera un valor por patrón marcado con `[WARN]` para confirmar. |
+
+Todo lo demás se autodetecta y queda ahí para revisión, no para
+llenarlo desde cero. El `02_print_config.sh` también corre un chequeo de
+salud ("doctor") sobre `SOURCE_ENV` antes de mostrar el config — avisa si
+le falta algo que el resto de `live/` ya tiene (ver
+`lessons-learned.md`, sección C).
+
+### Componentes base vs. opcionales
+
+El build solo incluye, por defecto, los componentes que existen en
+**todos** los entornos reales de `live/` (la intersección real, calculada
+en el momento — no una lista hardcodeada). Un componente que `SOURCE_ENV`
+tenga pero que no sea base (`cloud_armor`, `secrets`, etc.) queda
+excluido, siguiendo la guía de experiencia (§1.2: "no incluir salvo
+pedido explícito"). Para incluirlo de todas formas, agrégalo a
+`EXTRA_COMPONENTS` en el config y vuelve a correr la construcción.
+
+## Ejecutar los scripts manualmente (sin el agente)
+
+Cada script es independiente y se puede correr a mano, desde la raíz del
+repo destino:
+
+```bash
+S=.claude/skills/kcreate-scaffolding-gcp-script/scripts
+
+$S/01_init_config.sh   boletera-qa xoloshop-prod   # pre requisitos
+# ... editar los campos __PENDIENTE__ del .config ...
+$S/01_init_config.sh   boletera-qa xoloshop-prod   # confirma CONFIG_READY
+$S/02_print_config.sh  xoloshop-prod                # revisar antes de construir
+
+$S/10_build_components.sh xoloshop-prod             # construcción
+
+$S/20_validate_file_parity.sh      boletera-qa xoloshop-prod
+$S/21_validate_project_pinning.sh  xoloshop-prod
+```
+
+Cada script termina con un mensaje de una sola línea y un código de salida
+acorde — pensado para scripting, no solo para lectura humana:
+
+| Script | `0` | `2` | `1` | `3` |
+|---|---|---|---|---|
+| `install.sh` | skill instalado/actualizado | — | no se instaló nada (ya existía, sin `--force`) o argumento inválido | — |
+| `npm/bin/cli.js install` | skill instalado/actualizado | argumento/flag inválido o paquete corrupto | no se instaló nada (ya existía, sin `--force`) o destino no es repo git | — |
+| `uninstall.sh` | desinstalado (o no estaba) | — | argumento inválido / destino no es repo git | — |
+| `npm/bin/cli.js uninstall` | desinstalado (o no estaba) | argumento/flag inválido | destino no es repo git | — |
+| `npm/bin/cli.js doctor` | entorno listo | argumento/flag inválido | falta algún requisito (bash/git/python3/curl) | — |
+| `01_init_config.sh` | `CONFIG_READY` | `CONFIG_PENDING` (faltan campos) | error de validación | — |
+| `02_print_config.sh` | config impreso | — | falta config / `NEW_ENV` | — |
+| `10_build_components.sh` | `BUILD_OK: <ruta>` | — | `BUILD_FAILED: <paso> - <detalle>` | — |
+| `20_validate_file_parity.sh` | `FILE_PARITY_OK: <n>` | — | `FILE_PARITY_MISMATCH` | — |
+| `21_validate_project_pinning.sh` | `PROJECT_PINNING_OK: <n>` | — | `PROJECT_PINNING_FAILED` | — |
+| `run_tracking.sh` | comando OK | — | error de tracking | tracking no instalado |
+
+`2` no es un error: es la señal de "faltan datos, llénalos y vuelve a correr
+el mismo comando".
+
+## Estructura de este repo
+
+```
+KCreateScaffoldingGCPScripts/
+├── README.md / AGENT.md / CONTRIBUTING.md / CHANGELOG.md
+├── DeployNPM.md                   # manual para publicar el paquete en npm
+├── IDEA.md                        # especificación de origen del skill
+├── CreateScriptsNewGCPProjectInstructions.md  # guía manual de referencia (base de experiencia)
+├── LICENSE                        # MIT
+├── .gitignore
+├── install.sh / uninstall.sh      # instalan/quitan el skill de un repo destino
+├── lib/common.sh                  # helpers de install.sh/uninstall.sh
+├── npm/                           # instalador npx (mismo contrato que install.sh)
+│   ├── package.json               # bin: kcreate-scaffolding-gcp-script
+│   └── bin/{cli.js,build.js}      # cli = instalador; build = prepack (empaqueta skill/ y vendor/)
+├── vendor/github-proyect-tracking/  # dependencia vendorizada (ver vendor/VENDORED_FROM.md)
+└── kcreate-scaffolding-gcp-script/
+    ├── SKILL.md                   # instrucciones para el agente, por etapa
+    ├── references/
+    │   └── lessons-learned.md     # el "por qué" de cada script/validación
+    ├── templates/
+    │   └── scaffolding.config.template
+    └── scripts/
+        ├── lib/common.sh          # helpers del skill (CIDR, extracción HCL, etc.)
+        ├── 01_init_config.sh      # Pre requisitos, paso 1
+        ├── 02_print_config.sh     # Pre requisitos, paso 2
+        ├── 10_build_components.sh # Construcción
+        ├── 20_validate_file_parity.sh      # Validación 1
+        ├── 21_validate_project_pinning.sh  # Validación 2
+        └── run_tracking.sh        # envoltura sobre github-proyect-tracking
+```
+
+## Limitaciones conocidas
+
+- Asume que `NEW_ENV` usa la misma región/zona que `SOURCE_ENV` — no hay
+  forma de pedir una región distinta todavía.
+- Sin suite de pruebas automatizada. La verificación es por ejecución real;
+  la receta reproducible (install/uninstall de humo y ciclo completo contra
+  una copia descartable de un entorno real) está en
+  [`CONTRIBUTING.md`](CONTRIBUTING.md#validación-reproducible) y
+  [`AGENT.md`](AGENT.md#desarrollo-y-pruebas).
+- El instalador npx **no** puede consumirse como
+  `npx github:kronops/KCreateScaffoldingGCPScripts`: npm exige el
+  `package.json` en la raíz del repo y aquí vive en `npm/` (no soporta
+  subdirectorios en dependencias git). Requiere publicación en el registro
+  de npm o un tarball local (`npm pack`).
+- `npm publish` está preparado pero el paquete aún no está publicado en el
+  registro; hoy la vía sin clonar el repo es el tarball.
+- El nombre del proyecto (`PROJECT_NAME`, ej. `Xoloshop-Prod`) se infiere de
+  `NEW_ENV` con la convención `<App>-<QA|Prod>`; si la app tiene siglas o una
+  capitalización no obvia, corrígelo a mano en el config antes de construir.
+- Los componentes incluidos vía `EXTRA_COMPONENTS` (sin manejo dedicado)
+  se copian con una sustitución genérica y quedan marcados `[WARN]` para
+  revisión manual — no tienen el mismo nivel de automatización que los
+  componentes base.
+- `project_iam` requiere siempre una revisión humana (bindings
+  específicos del equipo/app de `SOURCE_ENV`) — no es mecanizable sin
+  conocer el negocio de la app nueva. Ver `lessons-learned.md` (A10).
+  `artifact_registry`, en cambio, ya se resuelve solo incluso cuando
+  `SOURCE_ENV` tiene valores genéricos: aprende el patrón de otro
+  entorno de `live/` que sí tenga el suyo específico (ver
+  `lessons-learned.md`, D7) — solo queda en `[WARN]` manual si **ningún**
+  entorno de `live/` tiene uno específico del que aprender.
+- `service_accounts`/`project_iam` pueden copiar (renombradas) entradas
+  que son específicas de `SOURCE_ENV` y no corresponden a la app nueva
+  (ej. SAs o namespaces de un componente que `SOURCE_ENV` tiene pero
+  `NEW_ENV` no construye) — hoy solo se advierte si hay más de 5 service
+  accounts, no se filtra cuál sobra.
+- El "doctor" de `02_print_config.sh` compara contra el resto de `live/`
+  por mayoría/recencia, no contra una lista de requisitos conocida — no
+  detecta un requisito nuevo si NINGÚN entorno de `live/` lo tiene todavía
+  (ver `lessons-learned.md`, sección C, nota en el ítem del doctor).

package/bin/build.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Empaqueta el contenido del skill dentro de npm/ para su distribución
+ * (prepack). Se ejecuta automáticamente con `npm pack` / `npm publish`.
+ *
+ *   kcreate-scaffolding-gcp-script/  → npm/skill/
+ *   vendor/github-proyect-tracking/   → npm/vendor/github-proyect-tracking/
+ *   README.md, LICENSE                → npm/README.md, npm/LICENSE
+ *
+ * Ninguno de estos artefactos se comitea (ver .gitignore): se recrean en cada
+ * prepack, para que el paquete nunca quede desincronizado del repo.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const here = path.join(__dirname, '..');
+const root = path.join(here, '..');
+const srcSkill = path.join(root, 'kcreate-scaffolding-gcp-script');
+const srcTracking = path.join(root, 'vendor', 'github-proyect-tracking');
+const dstSkill = path.join(here, 'skill');
+const dstTracking = path.join(here, 'vendor', 'github-proyect-tracking');
+
+function fail(msg) {
+  console.error(`ERROR: ${msg}`);
+  process.exit(1);
+}
+
+if (!fs.existsSync(path.join(srcSkill, 'SKILL.md'))) {
+  fail(`no se encontró ${srcSkill}/SKILL.md`);
+}
+if (!fs.existsSync(path.join(srcTracking, 'SKILL.md'))) {
+  fail(`no se encontró ${srcTracking}/SKILL.md (dependencia vendorizada)`);
+}
+
+function clean(dir) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (e.name === '__pycache__') fs.rmSync(p, { recursive: true, force: true });
+      else clean(p);
+    } else if (/\.py[co]$/.test(e.name)) {
+      fs.rmSync(p, { force: true });
+    }
+  }
+}
+
+function stage(src, dst) {
+  fs.rmSync(dst, { recursive: true, force: true });
+  fs.cpSync(src, dst, { recursive: true });
+  clean(dst);
+}
+
+stage(srcSkill, dstSkill);
+stage(srcTracking, dstTracking);
+
+// Los modos se preservan tal cual desde el origen (fs.cpSync los copia), igual
+// que `cp -R` en install.sh: el resultado instalado desde el repo debe ser
+// idéntico con los dos instaladores. Ojo: `npm pack`/`npm publish` normaliza
+// los modos del tarball; por eso npm/bin/cli.js vuelve a poner los bits de
+// ejecución al instalar (chmodScripts/addExecBits) — la red de seguridad para
+// el caso del paquete publicado.
+
+fs.copyFileSync(path.join(root, 'README.md'), path.join(here, 'README.md'));
+fs.copyFileSync(path.join(root, 'LICENSE'), path.join(here, 'LICENSE'));
+
+console.log(`skill    → ${dstSkill}`);
+console.log(`tracking → ${dstTracking}`);
+console.log('README.md + LICENSE → npm/');