@dforce2055/dai 0.9.0 → 0.10.0

package/{.env.example → .env.dai.example}

@@ -1,6 +1,6 @@
-# dai · configuración del adaptador de PM (copiar a .env y completar).
-# El .env está gitignoreado para no filtrar secretos. Este .example SÍ se versiona.
-# Las variables ya exportadas en la shell/CI ganan sobre el .env.
+# dai · configuración del adaptador de PM (copiar a .env.dai y completar).
+# El .env.dai NO se versiona (evita filtrar secretos) y el .env del equipo no se toca
+# (ADR-0017). Este .example SÍ se versiona. Precedencia: shell/CI > .env.dai > .env.
 
 # ── Backend del tracker ──────────────────────────────────────────────────────
 # md | jira | clickup

package/CHANGELOG.md

@@ -3,6 +3,46 @@
 Formato basado en [Keep a Changelog](https://keepachangelog.com/). Versionado semver
 (ver `VERSION`).
 
+## [0.10.0] — 2026-07-18
+
+**La config de dai deja de vivir en el `.env` del equipo y pasa a un `.env.dai` propio (no
+versionado). Resuelve el caso de las empresas que versionan el `.env` como política: dai no
+toca ese archivo y guarda sus secretos donde git realmente los ignora. Y `dai init` estrena
+una bienvenida con el Sol de Mayo en bloques.**
+
+### Agregado
+- **Banner de bienvenida en `dai init`**: el Sol de Mayo de dai en bloques (cuerpo y rayos
+  rectos en oro, rayos ondulados en celeste) junto al título, más un preview de lo que se va
+  a configurar. Cero dependencias (solo ANSI); degrada a ASCII sin color en no-TTY o con
+  `NO_COLOR`.
+- **`dai skills install --from npm:@scope/pkg`** — nueva fuente para skills externas
+  ([ADR-0013](docs/adr/0013-skills-externas-install-from.md)): además de git URL y path
+  local, ahora un **paquete npm**. dai hace `npm install` a un temp (respetando el `.npmrc`
+  del repo, así resuelve **registries privados con scope**; `npm pack` no sirve con los
+  registries de grupo de GitLab). Es común distribuir skills como paquete npm; antes había
+  que materializarlo a mano.
+- **Descripciones en bloque YAML (`|` / `>`) en el frontmatter de las skills.** El parser
+  de frontmatter ahora lee bloques literales/plegados multilínea (antes tomaba solo la
+  primera línea `|` y el validador lo rechazaba). Es como se escriben las skills reales:
+  descripciones ricas con "USAR CUANDO / NO USAR CUANDO" que el agente usa para elegirlas.
+
+### Cambiado
+- **`dai init` escribe en `.env.dai` + `.env.dai.example`, no en `.env`/`.env.example`**
+  ([ADR-0017](docs/adr/0017-env-dai.md)). El `.env` del equipo queda intacto (dai solo lo
+  lee). `.env.dai` (secretos) se gitignorea; `.env.dai.example` (plantilla) se versiona.
+  En un repo sin `.env`, dai ya no crea uno: es del equipo, no de dai.
+- **El loader lee `.env.dai` y `.env`** con precedencia **shell/CI > `.env.dai` > `.env`**.
+  Seguir leyendo `.env` mantiene la compatibilidad: los repos que ya tenían los `DAI_*` ahí
+  no se rompen.
+- **`.gitignore`**: dai ignora `.env.dai` (su archivo), no `.env`. Ya no fuerza un ignore
+  sobre un archivo que muchas orgs versionan a propósito.
+- Se renombró el `.env.example` del paquete a `.env.dai.example`, y se actualizaron doctor,
+  mensajes de init/sync, tutoriales, constitución y README a la nueva convención.
+
+### Interno
+- **228 tests** (+4 desde 0.9.0): precedencia de `loadDaiEnv` (shell > `.env.dai` > `.env`),
+  compat con `.env`, y sin-archivos. Smokes de `dai init` con y sin `.env` preexistente.
+
 ## [0.9.0] — 2026-07-17
 
 **El review de dai deja de ser un comentario al final del hilo y pasa a ser un review
@@ -405,6 +445,7 @@ ClickUp y Jira Cloud.
 - Tests de las rutas de red (jira/clickup/forge) con `fetch` mockeado. Sin links rotos;
   `files` de npm sin tests ni secretos.
 
+[0.10.0]: https://github.com/dforce2055/dai/releases/tag/v0.10.0
 [0.9.0]: https://github.com/dforce2055/dai/releases/tag/v0.9.0
 [0.8.2]: https://github.com/dforce2055/dai/releases/tag/v0.8.2
 [0.8.1]: https://github.com/dforce2055/dai/releases/tag/v0.8.1

package/README.md

@@ -63,10 +63,10 @@ Y después, en el chat del asistente, según lo que tengas:
 
 > Las skills **te interrogan** hasta que la historia es testeable (nunca inventan
 > requerimientos: los sacan a preguntas), y la **publican en el tracker** que configuraste
-> (`DAI_PM` en el `.env`): por el **MCP** de Jira/ClickUp si está conectado, o con
+> (`DAI_PM` en el `.env.dai`): por el **MCP** de Jira/ClickUp si está conectado, o con
 > **`dai publish <us.md>`** si no (crea el issue vía token). Tú respondes y decides.
 
-¿Sin MCP, o querés publicar a mano? `dai publish` sube el `.md` al tracker y te devuelve el key:
+¿Sin MCP, o quieres publicar a mano? `dai publish` sube el `.md` al tracker y te devuelve el key:
 
 ```bash
 dai publish historia.md                                # crea la US → devuelve el key
@@ -87,7 +87,7 @@ Una vez, preparas el repo:
 ```bash
 npm i -g @dforce2055/dai
 cd mi-repo && dai init          # bootstrap: skills + tracker + OpenSpec + PR template
-# completa el token del tracker en .env  (o DAI_PM=md para probar sin credenciales)
+# completa el token del tracker en .env.dai  (o DAI_PM=md para probar sin credenciales)
 dai doctor                      # verifica que todo quedó en su lugar
 ```
 
@@ -112,12 +112,12 @@ dai pr --assignee <compañero>   # crea la PR precargada y se la asigna a un com
 dai stamp                       # al mergear: estampa la cobertura en el tracker
 ```
 
-> **Para que `dai pr` cree la PR/MR** necesitás el CLI del forge instalado y autenticado, una
+> **Para que `dai pr` cree la PR/MR** necesitas el CLI del forge instalado y autenticado, una
 > sola vez por máquina:
 > - **GitHub** → [`gh`](https://cli.github.com) · `gh auth login`
 > - **GitLab** → [`glab`](https://gitlab.com/gitlab-org/cli) · `glab auth login --hostname <tu-gitlab>`
 >   — en un GitLab self-hosted/corporativo el `--hostname` es **obligatorio**, y el token va con
->   scope `api`. (En Windows, tras instalar `glab` con `winget`, abrí una terminal nueva para que
+>   scope `api`. (En Windows, tras instalar `glab` con `winget`, abre una terminal nueva para que
 >   tome el PATH.)
 >
 > Sin el CLI del forge, `dai pr` **igual pushea tu branch** y te dice qué instalar — después
@@ -169,10 +169,10 @@ flowchart TD
 | 14 | **Cerrar la US** | `dai done` → vuelve a la base, actualiza y borra la branch local (si está mergeada) | dev |
 
 > **Paso 3b (publicar):** el MCP crea el issue interactivamente; `dai publish` necesita el
-> token del tracker en `.env` (Jira además `DAI_JIRA_PROJECT`, ClickUp `DAI_CLICKUP_LIST_ID`).
+> token del tracker en `.env.dai` (Jira además `DAI_JIRA_PROJECT`, ClickUp `DAI_CLICKUP_LIST_ID`).
 >
 > **Paso 7 (OpenSpec):** `dai init` te ofrece instalarlo **e inicializarlo** solo. Si los
-> comandos `/opsx:*` no aparecen en el asistente, reinicia el IDE (se cargan al arrancar).
+> comandos `/opsx:*` no aparecen en el asistente, reinicia el IDE (se cargan al iniciar).
 >
 > **Paso 11 (PR):** necesita un remoto git (`origin`) y `gh`/`glab` autenticado. Sin remoto,
 > dai no crea la PR (te deja el texto listo igual).
@@ -183,8 +183,8 @@ flowchart TD
 |---|---|
 | `dai init [<repo>]` | scaffolder interactivo del repo. Flags: `--for claude\|copilot\|both\|cursor\|all` (asistente, default `all`) · `--pm md\|jira\|clickup` (tracker) · `--openspec` |
 | `dai skills install [--global \| --local <repo>] [--force] [--dry-run] [--for claude\|copilot\|cursor\|all]` | instala/actualiza las skills de dai en Claude, Copilot y/o Cursor (`--for all` por defecto; Copilot global → `~/.copilot/skills`, local → `.github/skills/`). `--force` re-copia. Alias: **`dai install`**. Ej: `dai skills install --local . --for cursor --force` |
-| `dai skills install --from <git-url\|path>[#ref] [--for …]` | instala **skills externas** (por-stack: .NET, Java, …) desde un repo/dir, **convertidas para los 3 asistentes**. Self-service, one-off, sin registro; `dai sync` no las toca. Colisión con una skill de dai → salta ([ADR-0013](docs/adr/0013-skills-externas-install-from.md)). Ej: `dai skills install --from github.com/mi-org/net-skills` |
-| `dai sync [--dry-run] [--for <asistentes>]` | **refresca** skills, constitución, templates y PR template a la versión del CLI — **aditivo** (no pisa tu `CLAUDE.md`), no toca el `.env` ni OpenSpec. Detecta los asistentes del repo o pasás `--for`. `--dry-run` muestra qué cambiaría ([ADR-0010](docs/adr/0010-versionado-y-upgrade.md)) |
+| `dai skills install --from <git-url\|npm:pkg\|path>[#ref] [--for …]` | instala **skills externas** (por-stack: .NET, Java, …) desde un repo/dir/**paquete npm**, **convertidas para los 3 asistentes**. Self-service, one-off, sin registro; `dai sync` no las toca. Colisión con una skill de dai → salta ([ADR-0013](docs/adr/0013-skills-externas-install-from.md)). Ej: `dai skills install --from github.com/mi-org/net-skills` · `dai skills install --from npm:@mi-org/ui-skills` (usa el `.npmrc` del repo → registries privados OK) |
+| `dai sync [--dry-run] [--for <asistentes>]` | **refresca** skills, constitución, templates y PR template a la versión del CLI — **aditivo** (no pisa tu `CLAUDE.md`), no toca el `.env.dai` ni OpenSpec. Detecta los asistentes del repo o pasás `--for`. `--dry-run` muestra qué cambiaría ([ADR-0010](docs/adr/0010-versionado-y-upgrade.md)) |
 | `dai upgrade [--check] [--dry-run]` · alias `dai update` | **actualiza el CLI global** a la última publicada (`npm i -g …@latest`) — self-update. **No toca el repo**: reporta el drift del scaffold pero deja el `dai sync` al mantenedor. `--check` solo informa · `--dry-run` muestra el comando ([ADR-0012](docs/adr/0012-upgrade-self-update-del-cli.md)) |
 | `dai publish <us.md> [--parent KEY] [--issuetype T] [--field alias=valor]` | crea la US en el tracker (Jira/ClickUp/md) desde un `.md` y devuelve el key — el fallback del MCP para publicar sin el asistente. `--parent PROJ-42` la cuelga de su épica · `--issuetype Epic` publica una épica (fallback CLI de `grill-epic`) · `--field clasificacion=Mejora` (repetible) manda los campos propios que exige tu Jira, declarados en `.dai/jira-fields.json` ([ADR-0015](docs/adr/0015-jira-corporativo.md)) |
 | `dai link-us <ID> [--us <md>]` | crea branch + `implements.yaml`; sin `--us` trae la US del tracker |
@@ -203,20 +203,22 @@ flowchart TD
 > **🆕 Mantené tu repo al día — `dai sync`.** Las skills, la constitución y los templates son un
 > *caché derivable* del CLI. Cuando actualizás `dai` (`dai upgrade`), **`dai doctor` y
 > `dai version` te avisan solos** si tu scaffold quedó atrás — con color y un `⬆️` —, y **`dai sync`**
-> lo refresca: **aditivo** (conserva tu `CLAUDE.md` propio), sin tocar el `.env` ni OpenSpec. Probá sin
+> lo refresca: **aditivo** (conserva tu `CLAUDE.md` propio), sin tocar el `.env.dai` ni OpenSpec. Prueba sin
 > riesgo con `dai sync --dry-run`. El versionado es semver: patch/minor no rompen nada; solo un major
 > pediría migración. ([ADR-0010](docs/adr/0010-versionado-y-upgrade.md))
 
 > **🧩 Skills de cualquier stack — `dai skills install --from`.** Además de las skills de
-> dai, cada equipo suma las suyas (por-stack: .NET, Java, Rust…) desde su propio repo:
-> `dai skills install --from github.com/tu-org/net-skills`. dai las **convierte para los 3
-> asistentes** (Claude/Cursor/Copilot) e instala. **dai es el distribuidor de skills de
-> cualquier stack, sin opinar sobre su contenido** — self-service, sin registro; `dai sync`
-> sigue siendo solo de dai. ([ADR-0013](docs/adr/0013-skills-externas-install-from.md))
+> dai, cada equipo suma las suyas (por-stack: .NET, Java, Rust…) desde su propio repo o
+> **paquete npm**: `dai skills install --from github.com/tu-org/net-skills` · `dai skills
+> install --from npm:@tu-org/ui-skills` (el paquete npm usa el `.npmrc` del repo, así
+> resuelve registries privados con scope). dai las **convierte para los 3 asistentes**
+> (Claude/Cursor/Copilot) e instala. **dai es el distribuidor de skills de cualquier stack,
+> sin opinar sobre su contenido** — self-service, sin registro; `dai sync` sigue siendo solo
+> de dai. ([ADR-0013](docs/adr/0013-skills-externas-install-from.md))
 >
 > La fuente puede ser **pública, privada (por SSH) o un path local**: dai no hace auth
-> propia, delega en git — **si podés `git clone` el repo, dai instala desde ahí**. Para
-> privados usá la forma SSH (`git@github.com:tu-org/net-skills.git`), consistente con el
+> propia, delega en git — **si puedes `git clone` el repo, dai instala desde ahí**. Para
+> privados usa la forma SSH (`git@github.com:tu-org/net-skills.git`), consistente con el
 > modelo de auth de dai ([ADR-0007](docs/adr/0007-modelo-de-autenticacion.md)). Público =
 > cero fricción entre equipos/máquinas.
 >
@@ -229,8 +231,9 @@ flowchart TD
 > en [`skills/`](skills/).
 
 Skills (se invocan en el asistente): `/doc-to-backlog` · `/grill-intent` · `/grill-epic` · `/grill-user-story` · `/link-us` ·
-`/tdd` · `/dai-review`. Config del tracker (`md`\|`jira`\|`clickup`) y tokens: en `.env` —
-ver [`.env.example`](.env.example). Auth (SSH + tokens): [ADR-0007](docs/adr/0007-modelo-de-autenticacion.md).
+`/tdd` · `/dai-review`. Config del tracker (`md`\|`jira`\|`clickup`) y tokens: en `.env.dai`
+(no versionado; el `.env` del equipo no se toca — [ADR-0017](docs/adr/0017-env-dai.md)) —
+ver [`.env.dai.example`](.env.dai.example). Auth (SSH + tokens): [ADR-0007](docs/adr/0007-modelo-de-autenticacion.md).
 
 ## El flag `--for` — ¿para qué asistente preparo el repo?
 
@@ -262,7 +265,7 @@ Después de `dai init` (con `--for all`):
 ```
 mi-repo/
 ├── CLAUDE.md                       · Constitución del proyecto (auto-cargada por Claude)
-├── .env                            · configurado con tu tracker (gitignored, completa el token)
+├── .env.dai                        · tu tracker (NO versionado, completa el token) + .env.dai.example (plantilla, sí versionada)
 ├── .claude/skills/                 · Las skills, locales al repo (el equipo las hereda)
 │   └── doc-to-backlog · grill-intent · grill-epic · grill-user-story · link-us · tdd · dai-review
 ├── .github/
@@ -334,7 +337,7 @@ dai/
 ├── skills/         🤖  doc-to-backlog · grill-intent · grill-epic · grill-user-story · link-us · tdd · dai-review
 ├── governance/     🛡️  branch-naming · ci-rules · commit-convention
 ├── index.html      📊  landing autocontenido (la historia); publicable por GitHub Pages
-└── manifest.yaml · VERSION · install.sh (shim) · .env.example
+└── manifest.yaml · VERSION · install.sh (shim) · .env.dai.example
 ```
 
 ## Licencia
@@ -351,9 +354,17 @@ Detalle en [ADR-0006](docs/adr/0006-distribucion-y-licencia.md).
 
 ## Agradecimientos
 
-dai se apoya en ideas y aprendizajes de la comunidad. En particular, gracias a
-**[Matt Pocock](https://github.com/mattpocock)** por su aporte con las *skills* y por su
-[canal de YouTube](https://www.youtube.com/@mattpocockuk) explicándolas — su trabajo nos ayudó
-a construir esta herramienta.
+dai se apoya en ideas y herramientas de la comunidad.
+
+Un agradecimiento especial a **[OpenSpec](https://github.com/Fission-AI/OpenSpec)** (de
+[Fission AI](https://github.com/Fission-AI), `@fission-ai/openspec`): es la herramienta
+sobre la que se construye todo el **CÓMO** de dai — explorar la solución, proponer el diseño
+y las tareas, e implementar el change (`opsx:explore → propose → apply → archive`). dai no
+la bundlea ni la reemplaza; se apoya en ella para convertir el QUÉ en un plan técnico
+trazable. Sin OpenSpec, la mitad del método no existiría.
+
+Y gracias a **[Matt Pocock](https://github.com/mattpocock)** por su aporte con las *skills*
+y por su [canal de YouTube](https://www.youtube.com/@mattpocockuk) explicándolas — su
+trabajo nos ayudó a construir esta herramienta.
 
 Seguridad: [`SECURITY.md`](SECURITY.md) · Conducta: [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)

package/VERSION

@@ -1 +1 @@
-0.9.0
+0.10.0

package/cli/dai.mjs

@@ -21,7 +21,7 @@ import { createInterface } from "node:readline/promises";
 import { acHash } from "./lib/ac-hash.mjs";
 import { discoverImplements, isPlaceholderId } from "./lib/implements.mjs";
 import { isValidKey, slugify, branchName, extractTitle, renderImplementsYaml } from "./lib/link-us.mjs";
-import { loadEnv } from "./lib/env.mjs";
+import { loadDaiEnv } from "./lib/env.mjs";
 import { getAdapter, coverageStatus, statusLabel } from "./lib/pm-adapter.mjs";
 import { branchUrl, commitUrl, parseRemote, detectForge } from "./lib/forge-url.mjs";
 import { parsePrRef, getPR, postComment, postReview } from "./lib/forge-api.mjs";
@@ -48,8 +48,33 @@ const warn = (m) => process.stdout.write(`⚠ ${m}\n`);
 // Color ANSI mínimo — solo si es TTY y no está NO_COLOR (así no ensucia pipes/CI).
 const _color = process.stdout.isTTY && !process.env.NO_COLOR;
 const paint = (code, m) => (_color ? `\x1b[${code}m${m}\x1b[0m` : m);
-const C = { y: (m) => paint("33", m), r: (m) => paint("31", m), cy: (m) => paint("36", m), b: (m) => paint("1", m) };
+const C = { y: (m) => paint("33", m), r: (m) => paint("31", m), cy: (m) => paint("36", m), b: (m) => paint("1", m), dim: (m) => paint("2", m) };
 const ROOT = join(HERE, "..");            // raíz del paquete dai (cli/ está adentro)
+
+// Banner de bienvenida de `dai init`: el Sol de Mayo en bloques (cuerpo y rayos rectos en
+// oro; rayos ondulados en celeste) al lado del título, más el preview de lo que se configura.
+// Todo con caracteres — cero-dep. Degrada a ASCII sin color si no hay TTY o con NO_COLOR.
+const initBanner = () => {
+  const sun = [
+    "     █     ",
+    " ▒ ▄███▄ ▒ ",
+    "██ █████ ██",
+    " ▒ ▀███▀ ▒ ",
+    "     █     ",
+  ];
+  const paintSun = (line) => [...line].map((ch) => (ch === "▒" ? C.cy(ch) : ch === " " ? " " : C.y(ch))).join("");
+  const aside = ["", paint("1;33", "dai") + " · Desarrollo Asistido por IA", C.dim("La IA asiste; la persona firma."), "", ""];
+  let out = "\n";
+  for (let i = 0; i < sun.length; i++) out += "  " + paintSun(sun[i]) + (aside[i] ? "    " + aside[i] : "") + "\n";
+  out += "\n  " + C.b("Esto va a configurar el repo:") + "\n";
+  for (const b of [
+    "Skills del método (grill · link-us · tdd · dai-review) en tu asistente",
+    "La constitución del proyecto — las reglas del trabajo",
+    "OpenSpec para el CÓMO (design / tasks) — opcional",
+    "Plantilla de PR + .env.dai para el tracker",
+  ]) out += "    " + C.cy("▸") + " " + b + "\n";
+  return out;
+};
 const CLAUDE_SKILLS_DIR = process.env.CLAUDE_SKILLS_DIR || join(homedir(), ".claude", "skills");
 const CURSOR_SKILLS_DIR = process.env.CURSOR_SKILLS_DIR || join(homedir(), ".cursor", "skills");
 // Copilot lee las skills personales de ~/.copilot/skills (NO de ~/.claude/skills, que
@@ -119,10 +144,10 @@ async function cmdLinkUs(key, opts) {
     title = opts.title || extractTitle(md);
   } else {
     // Fuente tracker: traer la US del adaptador (mismo hash que usará `dai check`).
-    loadEnv();
+    loadDaiEnv();
     const adapter = getAdapter(process.env);
     const us = await adapter.fetchUS(key);
-    if (!us) fail(`no encontré la US ${key} en el backend ${adapter.kind}. Pasa --us <md> o revisa el .env.`, 2);
+    if (!us) fail(`no encontré la US ${key} en el backend ${adapter.kind}. Pasa --us <md> o revisa el .env.dai.`, 2);
     hash = us.ac_hash;
     if (hash == null) fail(`la US ${key} no tiene una sección 'Criterios de aceptación' con criterios testeables → sin ac_hash, no se puede linkear.\n  Agregá la sección en el tracker, o corré /grill-user-story ${key} para pulir la US (te interroga y la re-publica).`, 2);
     title = opts.title || us.title;
@@ -180,7 +205,7 @@ function gitCommit() { try { return git(["rev-parse", "HEAD"]); } catch { return
 
 // ── check ──────────────────────────────────────────────────────────────────
 async function cmdCheck() {
-  loadEnv();
+  loadDaiEnv();
   const adapter = getAdapter(process.env);
   const found = discoverImplements(process.cwd(), { includeArchived: false });
   let worst = 0, n = 0;
@@ -211,7 +236,7 @@ async function cmdCheck() {
 
 // ── stamp ──────────────────────────────────────────────────────────────────
 async function cmdStamp() {
-  loadEnv();
+  loadDaiEnv();
   const adapter = getAdapter(process.env);
   const remote = gitRemote(), branch = gitBranch(), commit = gitCommit();
   const found = discoverImplements(process.cwd());
@@ -233,7 +258,7 @@ async function cmdStamp() {
 
 // ── forge (review) ───────────────────────────────────────────────────────────
 async function cmdForge(sub, ref, opts) {
-  loadEnv();
+  loadDaiEnv();
   const pr = parsePrRef(ref, gitRemote());
   if (!pr) fail("no pude resolver la PR/MR. Pasa la URL completa o el número (con remoto git).", 1);
   if (sub === "pr") {
@@ -332,7 +357,7 @@ function loadJiraFieldsSpec() {
 
 async function cmdPublish(file, opts = {}) {
   if (!file) fail("uso: dai publish <archivo-us.md> [--parent KEY] [--issuetype T] [--field alias=valor]", 1);
-  loadEnv();
+  loadDaiEnv();
   const md = readFileSync(file, "utf8");
   const title = extractTitle(md);
   if (!title) fail("no pude extraer el título de la US (falta un '# Título').", 1);
@@ -409,7 +434,7 @@ function cmdDone(opts) {
 // ── pr: crea TU PROPIA PR/MR precargada desde el template + el link ────────────
 // (Distinto de dai-review, que revisa la PR de OTRO. Tu PR la creas y revisas tú.)
 async function cmdPr(opts) {
-  loadEnv();
+  loadDaiEnv();
   const remote = gitRemote(), branch = gitBranch(), commit = gitCommit();
   if (!remote) fail("no hay remoto git 'origin'. Configúralo para crear la PR.", 1);
   if (!branch || branch === "HEAD") fail("no estás en una branch.", 1);
@@ -447,7 +472,7 @@ async function cmdPr(opts) {
   for (const f of found) for (const im of f.implements || []) {
     if (!isPlaceholderId(im.id)) { entry = { f, im }; break; }
   }
-  if (!entry) fail("no encontré un implements.yaml con una US real. Ejecuta `dai link-us` primero.", 1);
+  if (!entry) fail("no hay una US linkeada (implements.yaml). Si este PR implementa una US, corré `dai link-us` primero. Si es un chore/tooling (sin US), creá la PR con tu forge: `glab mr create` / `gh pr create`.", 1);
   const { id, version, ac_hash } = entry.im;
 
   // 2. Estado de trazabilidad (dai check) contra la US viva.
@@ -470,7 +495,7 @@ async function cmdPr(opts) {
   const usUrl = usUrlFor(id, live?.url);
   if (!usUrl) {
     warn(`no sé la URL de ${id} en el tracker: la PR va a quedar sin link a la US.`);
-    warn(`configurá DAI_TRACKER_URL_TEMPLATE en el .env (p. ej. https://tu-tracker/browse/{id}).`);
+    warn(`configurá DAI_TRACKER_URL_TEMPLATE en el .env.dai (p. ej. https://tu-tracker/browse/{id}).`);
   }
   const body = composePrBody(readFileSync(tplPath, "utf8"), {
     id, version, ac_hash, status, usUrl, usTitle: live?.title, commits,
@@ -632,7 +657,7 @@ async function cmdInstall(opts) {
 // dai (colisión → warn + skip). `dai sync` NO las toca: es solo de dai.
 function cmdInstallFrom(opts) {
   if (typeof opts.from !== "string" || !opts.from.trim())
-    fail("--from necesita una fuente: un git URL (github.com/org/skills[#ref]) o un path local", 2);
+    fail("--from necesita una fuente: un git URL (github.com/org/skills[#ref]), un paquete npm (npm:@scope/pkg) o un path local", 2);
   let want;
   try { want = parseAssistants(typeof opts.for === "string" ? opts.for : "all"); }
   catch (e) { fail(`--for ${e.message}`); }
@@ -651,6 +676,33 @@ function cmdInstallFrom(opts) {
     try { git(args); }
     catch (e) { rmSync(tmp, { recursive: true, force: true }); fail(`no pude clonar la fuente: ${String(e.message).split("\n")[0]}`, 1); }
     root = tmp;
+  } else if (src.type === "npm") {
+    tmp = mkdtempSync(join(tmpdir(), "dai-skills-"));
+    info(`bajando el paquete npm ${src.location} …`);
+    try {
+      // `npm install` (no `npm pack`) en el temp. Dos decisiones a propósito:
+      // 1) install en vez de pack: los registries de GRUPO de GitLab devuelven una
+      //    `dist.tarball` malformada (el scope duplicado en el nombre) que `npm pack` sigue
+      //    literal y da 404; `npm install` —como `npx`— reconstruye la URL y resuelve.
+      // 2) copiamos el `.npmrc` del repo al temp y corremos con cwd=temp: así npm ve el
+      //    registry/scope privado (con `--prefix` npm NO lee el `.npmrc` del cwd y se va al
+      //    registry público). `--ignore-scripts`: no corremos scripts de un paquete de 3ros.
+      const repoNpmrc = join(process.cwd(), ".npmrc");
+      if (existsSync(repoNpmrc)) cpSync(repoNpmrc, join(tmp, ".npmrc"));
+      runNpmTool("npm", ["install", src.location,
+        "--no-save", "--no-package-lock", "--ignore-scripts", "--no-audit", "--no-fund"],
+        { cwd: tmp, stdio: ["ignore", "ignore", "pipe"] });
+      // El paquete queda en <tmp>/node_modules/<name>. name = spec sin la versión
+      // (@scope/pkg@1.2.3 → @scope/pkg; el `@` inicial del scope no cuenta).
+      let name = src.location; const at = name.lastIndexOf("@");
+      if (at > 0) name = name.slice(0, at);
+      root = join(tmp, "node_modules", name);
+      if (!existsSync(root)) throw new Error(`npm install no dejó '${name}' en node_modules`);
+    } catch (e) {
+      rmSync(tmp, { recursive: true, force: true });
+      const detail = String(e.stderr || e.stdout || e.message || "").split("\n").map((s) => s.trim()).filter(Boolean).slice(0, 3).join("\n         ");
+      fail(`no pude bajar el paquete npm '${src.location}':\n         ${detail || "npm install falló — revisá el spec, el registry y el .npmrc del repo"}`, 1);
+    }
   } else {
     root = src.location;
     if (!existsSync(root)) fail(`no existe la fuente: ${root}`, 2);
@@ -738,7 +790,7 @@ async function cmdInit(repo, opts) {
   }
   const rl = process.stdin.isTTY ? createInterface({ input: process.stdin, output: process.stdout }) : null;
 
-  process.stdout.write("\n  dai · configurar este repo para desarrollo asistido por IA\n");
+  process.stdout.write(initBanner());
 
   // Preguntas primero (después cerramos readline para liberar stdin a los instaladores).
   let forOpt = typeof opts.for === "string" ? opts.for.toLowerCase() : null;
@@ -789,28 +841,32 @@ async function cmdInit(repo, opts) {
   writeFileSync(join(dai, "VERSION"), readFileSync(join(ROOT, "VERSION"), "utf8"));
   ok(".dai/         moldes (templates) + reglas (governance) del método");
 
-  // .env.example — aditivo, reflejando el --pm elegido: mismas claves que el .env
-  // (con valores VACÍOS, sin secretos) para que el token del tracker esté presente.
-  const exSrc = envFor(pm);
-  const exPath = join(repo, ".env.example");
+  // Config de dai en SUS PROPIOS archivos, sin tocar el `.env`/`.env.example` del equipo:
+  // muchas orgs versionan el `.env` como política, así que dai lo deja en paz (solo lo lee,
+  // por compat) y pone lo suyo en `.env.dai` (ver ADR-0017). `.env.dai.example` se versiona
+  // como plantilla; `.env.dai` (gitignored) es donde cada dev completa token y datos propios.
+  const envBlock = envFor(pm);
+
+  // .env.dai.example — plantilla VERSIONADA, mismas claves con valores VACÍOS (sin secretos).
+  const exPath = join(repo, ".env.dai.example");
   if (existsSync(exPath)) {
-    const cur = readFileSync(exPath, "utf8"), merged = mergeEnv(cur, exSrc);
-    if (merged !== cur) { writeFileSync(exPath, merged); ok(".env.example  claves de dai agregadas (aditivo)"); }
-    else ok(".env.example  ya tenía la config de dai");
-  } else { writeFileSync(exPath, exSrc); ok(".env.example  creado"); }
+    const cur = readFileSync(exPath, "utf8"), merged = mergeEnv(cur, envBlock);
+    if (merged !== cur) { writeFileSync(exPath, merged); ok(".env.dai.example  claves de dai agregadas (aditivo)"); }
+    else ok(".env.dai.example  ya tenía la config de dai");
+  } else { writeFileSync(exPath, envBlock); ok(".env.dai.example  creado (plantilla versionada)"); }
 
-  // .env — aditivo: agrega las claves de dai que falten; si no existe, lo crea.
-  const envPath = join(repo, ".env"), envBlock = envFor(pm);
+  // .env.dai — el real de cada dev (gitignored): aditivo; si no existe, lo crea.
+  const envPath = join(repo, ".env.dai");
   if (existsSync(envPath)) {
     const cur = readFileSync(envPath, "utf8"), merged = mergeEnv(cur, envBlock);
-    if (merged !== cur) { writeFileSync(envPath, merged); ok(`.env          claves de dai agregadas (aditivo, DAI_PM=${pm}${pm === "md" ? "" : " — completa el token"})`); }
-    else ok(".env          ya tenía la config de dai");
-  } else { writeFileSync(envPath, envBlock); ok(`.env          listo, DAI_PM=${pm}${pm === "md" ? "" : " (completa el token)"}`); }
+    if (merged !== cur) { writeFileSync(envPath, merged); ok(`.env.dai      claves de dai agregadas (aditivo, DAI_PM=${pm}${pm === "md" ? "" : " — completa el token"})`); }
+    else ok(".env.dai      ya tenía la config de dai");
+  } else { writeFileSync(envPath, envBlock); ok(`.env.dai      creado (no versionado), DAI_PM=${pm}${pm === "md" ? "" : " (completa el token)"}`); }
 
   // .gitignore — versiona los artefactos de dai (según --for), deja fuera solo lo personal.
   const giPath = join(repo, ".gitignore");
   const gi = reconcileGitignore(existsSync(giPath) ? readFileSync(giPath, "utf8") : "", want);
-  if (gi.changed) { writeFileSync(giPath, gi.text.endsWith("\n") ? gi.text : gi.text + "\n"); ok(".gitignore    ajustado (skills/constitución versionadas; .env y settings.local.json fuera)"); }
+  if (gi.changed) { writeFileSync(giPath, gi.text.endsWith("\n") ? gi.text : gi.text + "\n"); ok(".gitignore    ajustado (skills/constitución versionadas; .env.dai y settings.local.json fuera)"); }
 
   mkdirSync(join(repo, ".github"), { recursive: true });
   cpSync(join(ROOT, "templates", "pull-request.md"), join(repo, ".github", "pull_request_template.md"));
@@ -894,12 +950,12 @@ async function cmdInit(repo, opts) {
   }
 
   // ── Próximos pasos ─────────────────────────────────────────────────────────
-  process.stdout.write("\n  ✔ Repo configurado. Próximos pasos:\n");
+  process.stdout.write("\n  " + C.y("✔") + " " + C.b("Repo configurado.") + " Próximos pasos:\n");
   process.stdout.write(pm === "md"
-    ? "    1. Crea tu primera US en .dai/us/<ID>.md (criterios bajo '## Criterios de aceptación')\n"
-    : `    1. Completa el token de ${pm} en .env, y verifica con: dai doctor\n`);
-  process.stdout.write("    2. dai link-us <ID>     → crea la branch + el link a la US\n");
-  process.stdout.write("    3. Implementa con test primero, después: dai check\n");
+    ? `    1. Crea tu primera US en ${C.cy(".dai/us/<ID>.md")} (criterios bajo '## Criterios de aceptación')\n`
+    : `    1. Copia ${C.cy(".env.dai.example")} → ${C.cy(".env.dai")} y completa el token de ${pm}; verifica con ${C.y("dai doctor")}\n`);
+  process.stdout.write(`    2. ${C.y("dai link-us <ID>")}     → crea la branch + el link a la US\n`);
+  process.stdout.write(`    3. Implementa con test primero, después: ${C.y("dai check")}\n`);
   process.stdout.write("    Guía paso a paso: https://github.com/dforce2055/dai/blob/main/docs/PROBAR.md\n\n");
 }
 
@@ -1031,7 +1087,7 @@ function cmdSync(repo, opts) {
     () => writeFileSync(giPath, gi.text.endsWith("\n") ? gi.text : gi.text + "\n"));
 
   if (dry) info("dry-run: nada escrito. Quitá --dry-run para aplicar.");
-  else { process.stdout.write("\n"); ok(`sync completo — .dai/ ahora en v${cliV}`); process.stdout.write("  (El .env y OpenSpec no se tocan: OpenSpec se actualiza aparte con `openspec`.)\n"); }
+  else { process.stdout.write("\n"); ok(`sync completo — .dai/ ahora en v${cliV}`); process.stdout.write("  (El .env.dai y OpenSpec no se tocan: OpenSpec se actualiza aparte con `openspec`.)\n"); }
 }
 
 // Imprime el estado de version-drift del scaffold (ADR-0010) con color + ícono.
@@ -1097,7 +1153,7 @@ function cmdUpgrade(opts) {
 
 // ── doctor: diagnóstico ───────────────────────────────────────────────────────
 function cmdDoctor() {
-  loadEnv();
+  loadDaiEnv();
   info(`dai doctor — versión v${readFileSync(join(ROOT, "VERSION"), "utf8").trim()}`);
 
   // Una skill sirve si está en el repo actual (la puso `dai init`) o global (la puso
@@ -1151,11 +1207,11 @@ function cmdDoctor() {
   const pm = process.env.DAI_PM || "md";
   ok(`DAI_PM=${pm}`);
   if (pm === "jira") {
-    if (!process.env.DAI_JIRA_BASE_URL) warn("falta DAI_JIRA_BASE_URL en el .env");
-    if (!process.env.DAI_JIRA_EMAIL) warn("falta DAI_JIRA_EMAIL en el .env");
+    if (!process.env.DAI_JIRA_BASE_URL) warn("falta DAI_JIRA_BASE_URL en .env.dai");
+    if (!process.env.DAI_JIRA_EMAIL) warn("falta DAI_JIRA_EMAIL en .env.dai");
     // Ojo: solo miramos que el token ESTÉ, no que sirva — uno vencido pasa este chequeo
     // y recién falla al publicar. Verificarlo de verdad es pegarle a la red.
-    if (!process.env.DAI_JIRA_TOKEN) warn("falta DAI_JIRA_TOKEN en el .env"); else ok("token de Jira presente (no verificado: eso lo dice `dai publish`)");
+    if (!process.env.DAI_JIRA_TOKEN) warn("falta DAI_JIRA_TOKEN en .env.dai"); else ok("token de Jira presente (no verificado: eso lo dice `dai publish`)");
     if (!process.env.DAI_JIRA_PROJECT) warn("DAI_JIRA_PROJECT vacío — solo hace falta para `dai publish` (crear issues)");
     else {
       try { ok(`proyecto=${assertProjectKey(process.env.DAI_JIRA_PROJECT)} (para dai publish)`); }
@@ -1173,7 +1229,7 @@ function cmdDoctor() {
     }
   }
   if (pm === "clickup") {
-    if (!process.env.DAI_CLICKUP_TOKEN) warn("falta DAI_CLICKUP_TOKEN en el .env"); else ok("token de ClickUp presente");
+    if (!process.env.DAI_CLICKUP_TOKEN) warn("falta DAI_CLICKUP_TOKEN en .env.dai"); else ok("token de ClickUp presente");
     process.env.DAI_CLICKUP_LIST_ID ? ok(`lista=${process.env.DAI_CLICKUP_LIST_ID} (para dai publish)`)
       : warn("DAI_CLICKUP_LIST_ID vacío — solo hace falta para `dai publish` (crear tareas)");
   }
@@ -1238,16 +1294,16 @@ switch (cmd) {
       "      Sin --yes no postea nada: muestra el preview y valida que cada hallazgo apunte al diff.\n\n" +
       "Instalación:\n" +
       "  skills install [--global | --local <repo>] [--force] [--dry-run] [--for <asistentes>]   instala las skills de dai (alias: `install`)\n" +
-      "  skills install --from <git-url|path>[#ref] [--for <asistentes>]   instala skills EXTERNAS (por-stack), convertidas para los 3 asistentes (ADR-0013)\n" +
+      "  skills install --from <git-url|npm:pkg|path>[#ref] [--for <asistentes>]   instala skills EXTERNAS (por-stack), convertidas para los 3 asistentes (ADR-0013)\n" +
       "  init [<repo>]                scaffolder interactivo del repo (asistente, gestor, OpenSpec)\n" +
       "       --for <asistentes>      claude|copilot|cursor (combinables con coma) · o both|all (default all)\n" +
       "                               ej: --for claude,cursor · --for copilot · --for all\n" +
       "       --pm md|jira|clickup · --openspec   (con flags salteas las preguntas)\n" +
-      "  sync [<repo>] [--dry-run] [--for <asistentes>]   refresca skills/constitución/templates a la versión del CLI (aditivo; no toca .env ni OpenSpec)\n" +
+      "  sync [<repo>] [--dry-run] [--for <asistentes>]   refresca skills/constitución/templates a la versión del CLI (aditivo; no toca .env.dai ni OpenSpec)\n" +
       "  upgrade [--check] [--dry-run]   (alias: update) actualiza el CLI global a la última (npm i -g …@latest) y avisa si el repo quedó atrasado (ADR-0012)\n" +
       "  docs <destino>               documentación conceptual → <destino>\n" +
       "  doctor                       diagnóstico del entorno\n\n" +
-      "  (config: .env — ver .env.example)\n"
+      "  (config: .env.dai — ver .env.dai.example)\n"
     );
     process.exit(cmd && cmd !== "help" ? 1 : 0);
 }

package/cli/lib/bootstrap.mjs

@@ -47,13 +47,38 @@ function unquoteScalar(s) {
 // Parsea el frontmatter YAML de un SKILL.md → { name, description, body }.
 // Devuelve los valores YA sin comillas, para que quien los reserialice (skillToCursor)
 // no los cite dos veces.
+// Lee un campo del frontmatter. Soporta escalar de una línea (con/sin comillas) y BLOQUE
+// YAML (`|` literal, `>` plegado, con chomp `-`/`+`): junta las líneas indentadas siguientes
+// hasta la próxima clave (columna 0). El parser de dai es regex, no un YAML completo — esto
+// cubre lo común: descripciones multilínea, que es como se escriben las skills reales.
+function readFmField(fm, key) {
+  const lines = fm.split(/\r?\n/);
+  const keyRe = new RegExp(`^${key}:\\s*(.*)$`);
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(keyRe);
+    if (!m) continue;
+    const inline = m[1].trim();
+    const blk = inline.match(/^([|>])[-+]?\s*$/);       // |, >, |-, |+, >-, >+
+    if (!blk) return unquoteScalar(inline) || null;     // escalar de una línea
+    const buf = [];
+    for (let j = i + 1; j < lines.length; j++) {
+      if (lines[j].trim() === "") { buf.push(""); continue; }
+      if (!/^\s/.test(lines[j])) break;                 // sin indentar → empezó otra clave
+      buf.push(lines[j]);
+    }
+    const indent = ((buf.find((l) => l.trim() !== "") || "").match(/^\s*/) || [""])[0].length;
+    const text = buf.map((l) => l.slice(indent)).join("\n").replace(/\s+$/, "");
+    // `>` plegado: un salto simple → espacio; los dobles (párrafo) se conservan.
+    return (blk[1] === ">" ? text.replace(/([^\n])\n(?!\n)/g, "$1 ") : text) || null;
+  }
+  return null;
+}
+
 export function parseFrontmatter(md) {
   const m = md.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
   if (!m) return { name: null, description: null, body: md.trim() };
   const fm = m[1];
-  const name = unquoteScalar((fm.match(/^name:\s*(.+)$/m) || [])[1]) || null;
-  const description = unquoteScalar((fm.match(/^description:\s*(.+)$/m) || [])[1]) || null;
-  return { name, description, body: m[2].trim() };
+  return { name: readFmField(fm, "name"), description: readFmField(fm, "description"), body: m[2].trim() };
 }
 
 // Valida el contrato MÍNIMO de un SKILL.md para que dai lo ingiera y los asistentes lo
@@ -66,7 +91,11 @@ export function validateSkill(md) {
   if (!name) return "falta 'name' en el frontmatter";
   if (!description) return "falta 'description' en el frontmatter";
   for (const key of ["name", "description"]) {
-    const issue = yamlScalarIssue(rawFrontmatterValue(md, key));
+    const raw = rawFrontmatterValue(md, key);
+    // Un bloque YAML (`|`, `>`, con chomp) es literal → siempre válido; su contenido va en las
+    // líneas indentadas, no en el valor de la clave. No lo pasamos por el scalar-check.
+    if (/^[|>][-+]?\s*$/.test(String(raw ?? "").trim())) continue;
+    const issue = yamlScalarIssue(raw);
     if (issue) return `'${key}' no es YAML válido: ${issue} — citá el valor con comillas dobles`;
   }
   return null;
@@ -98,7 +127,7 @@ export function skillToCursor(md) {
 // la URL canónica que devuelve el tracker, así que el `/t/{id}` que escribíamos acá
 // tapaba la de ClickUp con team_id. Queda como override manual para trackers raros.
 export function envFor(pm) {
-  const head = "# Config de dai — completá lo que falte. NUNCA commitees tokens (.env está gitignored).\n";
+  const head = "# Config de dai — va en .env.dai (NO versionado), no en el .env del equipo.\n# Completá lo que falte. NUNCA commitees tokens.\n";
   if (pm === "clickup") {
     return head + "DAI_PM=clickup\nDAI_CLICKUP_TOKEN=\nDAI_CLICKUP_LIST_ID=\n";
   }
@@ -156,7 +185,10 @@ export function reconcileGitignore(text, want) {
   // `.dai/` NO va acá: ahí vive config que SÍ se versiona (jira-fields.json). Solo se
   // ignora `.dai/reviews/`, que son borradores de `dai forge review` — efímeros, con
   // hallazgos a medio editar, y no tienen por qué viajar en un commit.
-  const ensure = [".env", ".dai/reviews/"];
+  // `.env.dai` (config y secretos de dai) SÍ se ignora; el `.env` del equipo NO lo tocamos:
+  // es suyo y muchas orgs lo versionan como política (ADR-0017). La plantilla
+  // `.env.dai.example` sí se versiona (no matchea `.env.dai` exacto, así que no se ignora).
+  const ensure = [".env.dai", ".dai/reviews/"];
   if (want.claude) { broad.add("CLAUDE.md"); broad.add(".claude"); ensure.push(".claude/settings.local.json"); }
   if (want.cursor) { broad.add(".cursor"); }
   let changed = false;
@@ -199,7 +231,7 @@ export function constitution(kind) {
 - **El link se autora una vez** (\`implements.yaml\`); la cobertura se **deriva** (nunca a mano).
 - **Verifica el comportamiento, no solo que compile:** que pase el chequeo estático o el build no prueba que funcione; ejercita el flujo real antes de darlo por hecho.
 - **La IA confirma antes de construir:** el asistente declara que entendió esta constitución y la va a obedecer antes de generar código.
-- **Secretos:** en \`.env\` (nunca commiteados). git por **SSH**, APIs por **token scopeado**.
+- **Secretos:** en \`.env.dai\` (NO versionado; el \`.env\` del equipo no se toca). git por **SSH**, APIs por **token scopeado**.
 - **No bajes la seguridad para avanzar:** si una llamada falla por el certificado, declara la CA (\`NODE_EXTRA_CA_CERTS\`). **Nunca** \`NODE_TLS_REJECT_UNAUTHORIZED=0\`, \`verify=False\`, \`-k\` ni equivalentes: apagan la verificación de toda la conexión, y por ahí viajan los tokens.
 - **Si el CLI no llega, para y dilo:** cuando \`dai\` no cubre un caso, repórtalo — no improvises una llamada a la API por fuera. El atajo publica igual, pero rompe el link QUÉ↔CÓMO en silencio y nadie se entera hasta que la trazabilidad ya está mal.
 - **Docs vivas:** una constitución o arquitectura desactualizada es un defecto, no documentación.

package/cli/lib/env.mjs

@@ -4,6 +4,18 @@
 
 import { readFileSync } from "node:fs";
 
+// Config de dai: `.env.dai` (propio, nunca versionado) tiene prioridad sobre `.env`.
+// Pensado para equipos que versionan el `.env` (política de empresa): dai deja ese
+// archivo en paz y pone sus claves y secretos en `.env.dai` (gitignored). Se carga
+// `.env.dai` PRIMERO porque el loader es "primero-gana" (ver más abajo), así la
+// precedencia queda: entorno (shell/CI) > .env.dai > .env. Leer también `.env`
+// mantiene compatibilidad con repos previos que tienen los DAI_* ahí.
+export function loadDaiEnv(env = process.env) {
+  loadEnv(".env.dai", env);
+  loadEnv(".env", env);
+  return env;
+}
+
 export function loadEnv(path = ".env", env = process.env) {
   let text;
   try { text = readFileSync(path, "utf8"); } catch { return env; } // sin .env: no pasa nada