@dforce2055/dai 0.9.0 → 0.11.0

package/docs/public/favicon.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+    <defs><radialGradient id="favc" cx="0.5" cy="0.5" r="0.5">
+      <stop offset="0.35" stop-color="#F4B41A"/><stop offset="1" stop-color="#D98E04"/>
+    </radialGradient></defs>
+    <g fill="url(#favc)"><path d="M50.00 4.00 L52.00 29.00 L48.00 29.00 Z"/><path d="M67.60 7.50 L59.88 31.36 L56.19 29.83 Z"/><path d="M82.53 17.47 L66.26 36.56 L63.44 33.74 Z"/><path d="M92.50 32.40 L70.17 43.81 L68.64 40.12 Z"/><path d="M96.00 50.00 L71.00 52.00 L71.00 48.00 Z"/><path d="M92.50 67.60 L68.64 59.88 L70.17 56.19 Z"/><path d="M82.53 82.53 L63.44 66.26 L66.26 63.44 Z"/><path d="M67.60 92.50 L56.19 70.17 L59.88 68.64 Z"/><path d="M50.00 96.00 L48.00 71.00 L52.00 71.00 Z"/><path d="M32.40 92.50 L40.12 68.64 L43.81 70.17 Z"/><path d="M17.47 82.53 L33.74 63.44 L36.56 66.26 Z"/><path d="M7.50 67.60 L29.83 56.19 L31.36 59.88 Z"/><path d="M4.00 50.00 L29.00 48.00 L29.00 52.00 Z"/><path d="M7.50 32.40 L31.36 40.12 L29.83 43.81 Z"/><path d="M17.47 17.47 L36.56 33.74 L33.74 36.56 Z"/><path d="M32.40 7.50 L43.81 29.83 L40.12 31.36 Z"/></g>
+    
+    <circle cx="50" cy="50" r="19" fill="none" stroke="#74ACDF" stroke-width="2.3"/>
+    <circle cx="50" cy="50" r="15" fill="#14305C"/><path d="M43.5 44.9 L39.5 50 L43.5 55.1
+      M56.5 44.9 L60.5 50 L56.5 55.1
+      M51.8 44.4 L48.2 55.6"
+      fill="none" stroke="#EAF4FB" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+  </svg>

package/docs/public/logo-link.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+    <defs><radialGradient id="sol-link" cx="0.5" cy="0.5" r="0.5">
+      <stop offset="0.35" stop-color="#F4B41A"/><stop offset="1" stop-color="#D98E04"/>
+    </radialGradient></defs>
+    <g fill="url(#sol-link)"><path d="M50.00 6.00 L51.12 32.00 L48.88 32.00 Z"/><path d="M57.61 11.75 L54.61 32.56 L52.41 32.13 Z"/><path d="M66.84 9.35 L57.92 33.80 L55.85 32.94 Z"/><path d="M71.67 17.57 L60.93 35.66 L59.07 34.41 Z"/><path d="M81.11 18.89 L63.52 38.06 L61.94 36.48 Z"/><path d="M82.43 28.33 L65.59 40.93 L64.34 39.07 Z"/><path d="M90.65 33.16 L67.06 44.15 L66.20 42.08 Z"/><path d="M88.25 42.39 L67.87 47.59 L67.44 45.39 Z"/><path d="M94.00 50.00 L68.00 51.12 L68.00 48.88 Z"/><path d="M88.25 57.61 L67.44 54.61 L67.87 52.41 Z"/><path d="M90.65 66.84 L66.20 57.92 L67.06 55.85 Z"/><path d="M82.43 71.67 L64.34 60.93 L65.59 59.07 Z"/><path d="M81.11 81.11 L61.94 63.52 L63.52 61.94 Z"/><path d="M71.67 82.43 L59.07 65.59 L60.93 64.34 Z"/><path d="M66.84 90.65 L55.85 67.06 L57.92 66.20 Z"/><path d="M57.61 88.25 L52.41 67.87 L54.61 67.44 Z"/><path d="M50.00 94.00 L48.88 68.00 L51.12 68.00 Z"/><path d="M42.39 88.25 L45.39 67.44 L47.59 67.87 Z"/><path d="M33.16 90.65 L42.08 66.20 L44.15 67.06 Z"/><path d="M28.33 82.43 L39.07 64.34 L40.93 65.59 Z"/><path d="M18.89 81.11 L36.48 61.94 L38.06 63.52 Z"/><path d="M17.57 71.67 L34.41 59.07 L35.66 60.93 Z"/><path d="M9.35 66.84 L32.94 55.85 L33.80 57.92 Z"/><path d="M11.75 57.61 L32.13 52.41 L32.56 54.61 Z"/><path d="M6.00 50.00 L32.00 48.88 L32.00 51.12 Z"/><path d="M11.75 42.39 L32.56 45.39 L32.13 47.59 Z"/><path d="M9.35 33.16 L33.80 42.08 L32.94 44.15 Z"/><path d="M17.57 28.33 L35.66 39.07 L34.41 40.93 Z"/><path d="M18.89 18.89 L38.06 36.48 L36.48 38.06 Z"/><path d="M28.33 17.57 L40.93 34.41 L39.07 35.66 Z"/><path d="M33.16 9.35 L44.15 32.94 L42.08 33.80 Z"/><path d="M42.39 11.75 L47.59 32.13 L45.39 32.56 Z"/></g>
+    
+    <circle cx="50" cy="50" r="15.5" fill="none" stroke="#74ACDF" stroke-width="2.3"/>
+    <circle cx="50" cy="50" r="12" fill="#14305C"/>
+    <line x1="45" y1="50" x2="55" y2="50" stroke="#EAF4FB" stroke-width="2.2" stroke-linecap="round"/>
+    <circle cx="45" cy="50" r="2.5" fill="#EAF4FB"/>
+    <circle cx="55" cy="50" r="2.5" fill="#EAF4FB"/>
+  </svg>

package/docs/public/logo.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+    <defs><radialGradient id="sol-code" cx="0.5" cy="0.5" r="0.5">
+      <stop offset="0.35" stop-color="#F4B41A"/><stop offset="1" stop-color="#D98E04"/>
+    </radialGradient></defs>
+    <g fill="url(#sol-code)"><path d="M50.00 6.00 L51.12 32.00 L48.88 32.00 Z"/><path d="M57.61 11.75 L54.61 32.56 L52.41 32.13 Z"/><path d="M66.84 9.35 L57.92 33.80 L55.85 32.94 Z"/><path d="M71.67 17.57 L60.93 35.66 L59.07 34.41 Z"/><path d="M81.11 18.89 L63.52 38.06 L61.94 36.48 Z"/><path d="M82.43 28.33 L65.59 40.93 L64.34 39.07 Z"/><path d="M90.65 33.16 L67.06 44.15 L66.20 42.08 Z"/><path d="M88.25 42.39 L67.87 47.59 L67.44 45.39 Z"/><path d="M94.00 50.00 L68.00 51.12 L68.00 48.88 Z"/><path d="M88.25 57.61 L67.44 54.61 L67.87 52.41 Z"/><path d="M90.65 66.84 L66.20 57.92 L67.06 55.85 Z"/><path d="M82.43 71.67 L64.34 60.93 L65.59 59.07 Z"/><path d="M81.11 81.11 L61.94 63.52 L63.52 61.94 Z"/><path d="M71.67 82.43 L59.07 65.59 L60.93 64.34 Z"/><path d="M66.84 90.65 L55.85 67.06 L57.92 66.20 Z"/><path d="M57.61 88.25 L52.41 67.87 L54.61 67.44 Z"/><path d="M50.00 94.00 L48.88 68.00 L51.12 68.00 Z"/><path d="M42.39 88.25 L45.39 67.44 L47.59 67.87 Z"/><path d="M33.16 90.65 L42.08 66.20 L44.15 67.06 Z"/><path d="M28.33 82.43 L39.07 64.34 L40.93 65.59 Z"/><path d="M18.89 81.11 L36.48 61.94 L38.06 63.52 Z"/><path d="M17.57 71.67 L34.41 59.07 L35.66 60.93 Z"/><path d="M9.35 66.84 L32.94 55.85 L33.80 57.92 Z"/><path d="M11.75 57.61 L32.13 52.41 L32.56 54.61 Z"/><path d="M6.00 50.00 L32.00 48.88 L32.00 51.12 Z"/><path d="M11.75 42.39 L32.56 45.39 L32.13 47.59 Z"/><path d="M9.35 33.16 L33.80 42.08 L32.94 44.15 Z"/><path d="M17.57 28.33 L35.66 39.07 L34.41 40.93 Z"/><path d="M18.89 18.89 L38.06 36.48 L36.48 38.06 Z"/><path d="M28.33 17.57 L40.93 34.41 L39.07 35.66 Z"/><path d="M33.16 9.35 L44.15 32.94 L42.08 33.80 Z"/><path d="M42.39 11.75 L47.59 32.13 L45.39 32.56 Z"/></g>
+    
+    <circle cx="50" cy="50" r="16" fill="none" stroke="#74ACDF" stroke-width="2.3"/>
+    <circle cx="50" cy="50" r="12.8" fill="#14305C"/><path d="M44.5 46.43 L40.5 50 L44.5 53.57
+      M55.5 46.43 L59.5 50 L55.5 53.57
+      M51.8 45.93 L48.2 54.07"
+      fill="none" stroke="#EAF4FB" stroke-width="2.1" stroke-linecap="round" stroke-linejoin="round"/>
+  </svg>

package/docs/tutoriales/claves-ssh.md

@@ -0,0 +1,93 @@
+# Claves SSH para GitHub y GitLab
+
+Guía para generar tu **clave SSH** y registrarla en GitHub y/o GitLab. En dai, **git usa
+SSH** (clonar, `push`, `pull`); los tokens son solo para el forge y el tracker, y **nunca**
+se usa la contraseña ([ADR-0007](../adr/0007-modelo-de-autenticacion.md)). Con la clave
+configurada, `dai pr` puede pushear la rama sin pedirte credenciales.
+
+> **Una vez por máquina.** La misma clave sirve para GitHub y GitLab (y para todos tus
+> repos). No necesitas una por proyecto.
+
+---
+
+## Paso 1 — ¿Ya tienes una clave?
+
+```bash
+ls ~/.ssh/id_ed25519.pub
+```
+
+Si el archivo existe, ya tienes clave: salta al **Paso 4**. Si dice *"No such file"*, sigue
+con el paso 2.
+
+---
+
+## Paso 2 — Genera la clave
+
+```bash
+ssh-keygen -t ed25519 -C "tu-correo@ejemplo.com"
+```
+
+- Usa el correo de tu cuenta de GitHub/GitLab.
+- Cuando pregunte la ubicación, acepta la default (Enter).
+- La *passphrase* es opcional pero recomendada (una contraseña que protege la clave).
+
+> Si tu sistema es viejo y no soporta `ed25519`, usa `-t rsa -b 4096`.
+
+---
+
+## Paso 3 — Carga la clave en el agente SSH
+
+```bash
+eval "$(ssh-agent -s)"        # inicia el agente
+ssh-add ~/.ssh/id_ed25519     # carga tu clave (pide la passphrase si pusiste una)
+```
+
+> **Windows:** usa **Git Bash** para estos comandos, o habilita el servicio *OpenSSH
+> Authentication Agent* de Windows.
+
+---
+
+## Paso 4 — Copia la clave **pública**
+
+Nunca compartas la privada (`id_ed25519`). Copia solo la **pública** (`.pub`):
+
+```bash
+cat ~/.ssh/id_ed25519.pub        # muestra la clave; copiala entera (empieza con "ssh-ed25519")
+# atajos: macOS → | pbcopy   ·   Windows (Git Bash) → | clip   ·   Linux → | xclip -sel clip
+```
+
+---
+
+## Paso 5 — Pégala en GitHub y/o GitLab
+
+- **GitHub:** *Settings → SSH and GPG keys → New SSH key*. Pega la clave, ponle un título
+  (ej. `laptop-trabajo`) y guarda.
+  Acceso directo: **https://github.com/settings/ssh/new**
+- **GitLab:** *Preferences → SSH Keys → Add new key*. Pega la clave y guarda. En un GitLab
+  **self-hosted/corporativo** entra por la URL de tu instancia
+  (`https://gitlab.tu-empresa.com/-/user_settings/ssh_keys`).
+
+---
+
+## Paso 6 — Prueba la conexión
+
+```bash
+ssh -T git@github.com
+# → "Hi <usuario>! You've successfully authenticated..."
+
+ssh -T git@gitlab.com
+# (self-hosted: ssh -T git@gitlab.tu-empresa.com)
+```
+
+La primera vez te pregunta si confías en el host: escribí `yes`. Si ves el saludo con tu
+usuario, quedó lista.
+
+---
+
+## Reglas de seguridad
+
+- 🔒 **La clave privada nunca sale de tu máquina.** No la pegues en ningún lado, no la
+  commitees, no la mandes por chat. Solo se registra la **pública** (`.pub`).
+- 🧯 **Si se compromete tu máquina**, borra la clave pública de GitHub/GitLab (misma
+  pantalla del paso 5) y generá una nueva.
+- 👤 Es **por máquina y por persona**: cada dev tiene la suya.

package/docs/tutoriales/configurar-git.md

@@ -0,0 +1,53 @@
+# Configurar tu identidad de git
+
+Antes de tu primer commit, git necesita saber **quién sos**: cada commit lleva un nombre y
+un correo de autor. Sin configurarlo, los commits salen con un autor vacío o incorrecto, y
+en dai la **autoría siempre es de una persona** — nunca de un bot.
+
+> **Una vez por máquina.** Con `--global` queda para todos tus repos.
+
+---
+
+## Paso 1 — Nombre y correo
+
+```bash
+git config --global user.name "Nombre Completo"
+git config --global user.email "tu-correo@ejemplo.com"
+```
+
+> **Usa el mismo correo que tu cuenta de GitHub/GitLab.** Así el forge te **atribuye** los
+> commits (aparecen con tu avatar y cuentan en tu actividad). Si el correo no coincide, los
+> commits quedan "huérfanos", sin vincularse a tu cuenta.
+
+---
+
+## Paso 2 — Verifica
+
+```bash
+git config --global user.name       # → Nombre Completo
+git config --global user.email      # → tu-correo@ejemplo.com
+git config --global --list          # ve toda la config global
+```
+
+---
+
+## Un correo distinto para un repo puntual
+
+Si en un repo específico quieres usar otra identidad (ej. trabajo vs. personal), configúralo
+**sin** `--global`, dentro de ese repo:
+
+```bash
+cd mi-repo
+git config user.email "correo-de-este-repo@ejemplo.com"
+```
+
+La config del repo **gana** sobre la global, solo ahí.
+
+---
+
+## Por qué importa en dai
+
+- **Trazabilidad de autoría:** dai ata el QUÉ al CÓMO, y el CÓMO lo firma una persona. Un
+  commit con autor mal seteado rompe esa cadena.
+- **El review sale a tu nombre:** cuando `dai-review` postea con tu token, el forge lo
+  atribuye a **ti** — tener bien tu identidad es parte de responder por lo que firmas.

package/docs/tutoriales/index.md

@@ -0,0 +1,18 @@
+# Tutoriales
+
+Guías de **setup operativo** — lo que haces una vez por máquina para trabajar con dai.
+
+## Preparar el entorno
+
+- [**Configurar git**](./configurar-git) — tu identidad (nombre + correo) para que los
+  commits te atribuyan.
+- [**Claves SSH**](./claves-ssh) — generar y registrar tu clave en GitHub / GitLab. En dai,
+  git usa SSH ([ADR-0007](../adr/0007-modelo-de-autenticacion.md)).
+- [**Instalar gh / glab**](./instalar-glab) — el CLI del forge, para que `dai pr` cree la
+  PR/MR.
+
+## Conectar el tracker
+
+- [**Token de Jira**](./token-jira) — generar tu token de API de Atlassian (`DAI_PM=jira`).
+- [**Token de ClickUp**](./token-clickup) — generar tu token personal de ClickUp
+  (`DAI_PM=clickup`).

package/docs/tutoriales/instalar-glab.md

@@ -0,0 +1,74 @@
+# Instalar el CLI del forge (`gh` / `glab`) para `dai pr`
+
+`dai pr` crea la Pull/Merge Request usando el **CLI del forge**: `gh` para GitHub, `glab`
+para GitLab. dai pushea la rama por **SSH** igual (necesitas las [claves SSH](claves-ssh)),
+pero para **crear la PR/MR** hace falta el CLI autenticado.
+
+> **Una vez por máquina.** Instalás el que use tu equipo (o los dos, si trabajás con ambos
+> forges). Sin el CLI, `dai pr` **igual pushea la rama** y te dice qué instalar — después
+> creás la PR a mano desde la web.
+
+---
+
+## GitHub → `gh`
+
+### Instalar
+
+```bash
+brew install gh                 # macOS
+winget install GitHub.cli       # Windows
+sudo apt install gh             # Debian/Ubuntu (o ver cli.github.com para tu distro)
+```
+
+### Autenticar
+
+```bash
+gh auth login
+```
+
+Elige **GitHub.com**, protocolo **SSH** (o HTTPS), y sigue los pasos. Verifica:
+
+```bash
+gh --version
+```
+
+---
+
+## GitLab → `glab`
+
+### Instalar
+
+```bash
+brew install glab               # macOS · o Linux con Homebrew
+winget install GitLab.GLab      # Windows  (alternativa: scoop install glab)
+sudo pacman -S glab             # Arch / Manjaro
+# Debian/Ubuntu y otras distros: el .deb o el binario de https://gitlab.com/gitlab-org/cli/-/releases
+```
+
+### Autenticar
+
+```bash
+# GitLab.com:
+glab auth login
+
+# GitLab self-hosted / corporativo (el --hostname es OBLIGATORIO):
+glab auth login --hostname gitlab.tu-empresa.com
+```
+
+Te va a pedir un **token con scope `api`** (lo generás en *GitLab → Preferences → Access
+Tokens*). Verifica:
+
+```bash
+glab --version
+```
+
+---
+
+## Notas
+
+- 🪟 **Windows:** después de instalar con `winget`/`scoop`, **abre una terminal nueva** para
+  que tome el PATH; si no, `glab`/`gh` "no se encuentra".
+- 🔑 **El CLI usa un token del forge** (no la contraseña, no la clave SSH). Git sigue usando
+  SSH; el CLI, token — cada uno lo suyo ([ADR-0007](../adr/0007-modelo-de-autenticacion.md)).
+- Con el CLI instalado y autenticado, `dai pr` (o `dai mr` en GitLab) crea la PR/MR
+  precargada con la US, el estado de `dai check` y los enlaces.

package/docs/tutoriales/token-clickup.md

@@ -0,0 +1,73 @@
+# Cómo obtener el token de API de ClickUp
+
+Guía paso a paso para generar tu **token de API personal de ClickUp**, necesario para que
+`dai` (o cualquier script) se autentique contra la REST API de **ClickUp** cuando el tracker
+del repo es ClickUp (`DAI_PM=clickup`).
+
+> **¿Por qué un token y no la contraseña?** ClickUp no permite autenticar la API con la
+> contraseña de la cuenta (menos aún con SSO / verificación en dos pasos). El **token
+> personal** cumple ese rol: es una credencial que representa a tu usuario y que tratas
+> **igual que una contraseña**. Empieza siempre con `pk_`.
+
+**Atajo:** si quieres saltar los pasos 1 y 2, entra directo a
+👉 **https://app.clickup.com/settings/apps** (te lleva al paso 3).
+
+---
+
+## Paso 1 — Abre la configuración de tu cuenta
+
+En ClickUp, haz clic en tu **avatar** (arriba a la derecha) y elige **Settings**
+(Configuración).
+
+![Menú del avatar → Settings](/tutoriales/clickup-1-settings.png)
+
+---
+
+## Paso 2 — Ve a "API de ClickUp"
+
+En la barra lateral de configuración, bajo tu cuenta, entra a la sección **API de ClickUp**.
+Ahí, arriba de todo, verás el bloque **API Token**.
+
+![Barra lateral de Settings → Apps](/tutoriales/clickup-2-api.png)
+
+---
+
+## Paso 3 — Genera o copia el token
+
+En **API Token**:
+
+- Si es la primera vez, haz clic en **Generate** para crearlo.
+- Si ya tenías uno, aparece oculto con un botón **Copy** (y un **Regenerate** al lado).
+
+El token empieza con `pk_` (ej. `pk_1234567_ABCDEFG…`). Haz clic en **Copy** para copiarlo.
+
+![Bloque API Token → Generate / Copy](/tutoriales/clickup-3-generate-copy.png)
+
+---
+
+## Paso 4 — Guárdalo en tu `.env.dai`
+
+Pega el token en el `.env.dai` del repo (que **no se versiona**; el `.env` del equipo no se
+toca — [ADR-0017](../adr/0017-env-dai.md)), en la variable que espera dai:
+
+```bash
+DAI_PM=clickup
+DAI_CLICKUP_TOKEN=pk_...        # ← tu token, solo el token (sin comillas ni comentarios al lado)
+# DAI_CLICKUP_LIST_ID=          # solo hace falta para `dai publish` (crear tareas)
+```
+
+Verifica con `dai doctor` → debería decir **"token de ClickUp presente"**.
+
+---
+
+## Reglas de seguridad (importante)
+
+- 🔒 **Trátalo como una contraseña.** Nunca lo pegues en el código, en un commit, en un chat
+  ni en el `implements.yaml`. Solo va en `.env.dai` (no versionado).
+- ♻️ **No vence por sí solo** (a diferencia de Jira): queda válido hasta que lo **regeneres**.
+  Regenerar crea uno nuevo e **invalida el anterior al instante** — así lo rotas y así cortas
+  el acceso de uno filtrado.
+- 👤 **Es personal:** representa a tu usuario, con tus permisos. Cada dev usa el suyo, nunca
+  uno compartido.
+- 🧯 **Si se filtra**, entra a la misma pantalla (paso 3) y haz **Regenerate** de inmediato;
+  el viejo deja de funcionar y actualizas el `.env.dai` con el nuevo.

package/docs/tutoriales/token-jira.md

@@ -0,0 +1,74 @@
+# Cómo obtener el token de API de Jira (Atlassian)
+
+Guía paso a paso para generar un **token de API de Atlassian**, necesario para que `dai`
+(o cualquier script) se autentique contra la REST API de **Jira Cloud** cuando el tracker
+del repo es Jira (`DAI_PM=jira`).
+
+> **¿Por qué un token y no la contraseña?** Jira Cloud no permite autenticar la API con la
+> contraseña de la cuenta (menos aún con SSO / verificación en dos pasos). El token cumple
+> ese rol: es una credencial revocable, con vencimiento, que tratas **igual que una
+> contraseña**.
+
+**Atajo:** si quieres saltar los pasos 1 y 2, entra directo a
+👉 **https://id.atlassian.com/manage-profile/security/api-tokens** (te lleva al paso 3).
+
+---
+
+## Paso 1 — Abre la configuración de tu cuenta
+
+En Jira, haz clic en tu **avatar** (arriba a la derecha) y elige **Configuración de la cuenta**.
+
+![Menú del avatar → Configuración de la cuenta](/tutoriales/jira-1-avatar.png)
+
+---
+
+## Paso 2 — Ve a Seguridad → Tokens de API
+
+En la barra superior, entra a la pestaña **Seguridad**. Baja hasta la sección
+**Tokens de API** y haz clic en **Crear y gestionar tokens de API**.
+
+![Pestaña Seguridad → Crear y gestionar tokens de API](/tutoriales/jira-2-seguridad-tokens.png)
+
+---
+
+## Paso 3 — Crea el token
+
+Haz clic en **Crear token de API** (el botón simple, no el de "con alcances").
+Acceso directo => https://id.atlassian.com/manage-profile/security/api-tokens
+
+![Botón Crear token de API](/tutoriales/jira-3-crear-token.png)
+
+---
+
+## Paso 4 — Nombre y vencimiento
+
+- **Name:** un nombre que describa para qué es (ej. `dai-frontend`, `dai-backend`).
+- **Caduca el:** una fecha de vencimiento. Por seguridad, Atlassian **no permite más de un
+  año**. Pon la fecha máxima si no quieres renovarlo seguido, o una más corta para rotarlo
+  antes.
+
+Haz clic en **Crear**.
+
+![Formulario: Name + fecha de caducidad](/tutoriales/jira-4-nombre-vencimiento.png)
+
+---
+
+## Paso 5 — Cópialo AHORA (no se recupera después)
+
+Atlassian te muestra el token **una sola vez**. Haz clic en **Copiar** y guárdalo en un
+lugar seguro. **Si cierras esta ventana sin copiarlo, no hay forma de recuperarlo** —
+tendrías que crear uno nuevo.
+
+![Ventana Copia tu token de API](/tutoriales/jira-5-copiar.png)
+
+---
+
+## Reglas de seguridad (importante)
+
+- 🔒 **Trátalo como una contraseña.** Nunca lo pegues en el código, en un commit, en un chat
+  ni en el `implements.yaml`. Solo va en `.env.dai`, que **no se versiona** (el `.env` del
+  equipo no se toca; ver [ADR-0017](../adr/0017-env-dai.md)).
+- ♻️ **Rótalo** periódicamente y **revoca** los que no uses (misma pantalla del paso 3, columna
+  *Acción → Revocar*).
+- ⏱️ **Vencimiento:** el token deja de funcionar en la fecha que pusiste; anota cuándo renovarlo.
+- 🧯 **Si se filtra**, revócalo de inmediato y crea uno nuevo.

package/governance/ci-rules.md

@@ -12,15 +12,45 @@
 
 ## Qué valida el CI en cada PR/MR
 
-| Check | Regla | Si falla |
-|---|---|---|
-| **Link presente** | Toda rama de producto (`feature/ABC-###-*`) tiene `implements.yaml`. | ❌ bloquea el PR |
-| **ID válido** | El `id` matchea el formato del gestor (`ABC-\d+`) y el ID existe. | ❌ bloquea |
-| **`ac_hash` calculado** | El CI (re)calcula el hash de los criterios de la US y lo compara. | ⚠️ marca atrasado si no coincide |
-| **Tests verdes** | La suite de la US pasa. | ❌ bloquea |
-| **Estándares** | Lint + tipos + convenciones del repo. | ❌ bloquea |
+Las dos primeras filas **las ejecuta un comando**, no la buena voluntad:
 
-> Ramas `chore/`/`fix/` sin US no requieren `implements.yaml` (ver `branch-naming.md`).
+```bash
+dai check --ci        # salidas: 0 pasa · 1 falta el link · 2 el QUÉ cambió
+```
+
+Hay un workflow listo para copiar en [`templates/ci-dai-gate.yml`](../templates/ci-dai-gate.yml).
+Si tu CI no es GitHub Actions, el contrato es el mismo: un comando y su código de salida.
+
+| Check | Regla | Quién lo hace | Si falla |
+|---|---|---|---|
+| **Link presente** | Toda rama de producto (`feature/`) tiene `implements.yaml`. | `dai check --ci` | ❌ bloquea (exit 1) |
+| **`ac_hash` al día** | Recalcula el hash de los criterios de la US viva y lo compara. | `dai check --ci` | ❌ bloquea (exit 2) |
+| **ID resoluble** | El `id` del link existe en el gestor. | `dai check --ci` | ❌ bloquea (exit 2) |
+| **Tests verdes** | La suite de la US pasa. | el CI del repo | ❌ bloquea |
+| **Estándares** | Lint + tipos + convenciones del repo. | el CI del repo | ❌ bloquea |
+
+### Qué ramas quedan exentas
+
+Un gate que le exige US a todo se desactiva a la semana, y entonces no protege nada.
+Por eso `dai check --ci` decide **leyendo el nombre de la rama** (`branch-naming.md`):
+
+| Prefijo | ¿Exige `implements.yaml`? |
+|---|---|
+| `feature/`, `feat/` | **Sí, siempre** — es trabajo de producto |
+| `chore/`, `docs/`, `ci/`, `build/`, `test/`, `refactor/`, `style/`, `release/`, `hotfix/`, `revert/` | **No** — trabajo sin US |
+| `fix/` y cualquier otro prefijo | **Solo si el nombre trae un ID** (`fix/ABC-482-…`). Sin ID, no |
+| `main`, `develop` (sin prefijo) | No — no es una rama de trabajo |
+
+> Si tu PR es una corrección o un chore y el gate te lo bloquea, la respuesta **no** es
+> inventarle una US: es renombrar la rama con el prefijo que corresponde. El nombre de la
+> rama es la declaración de qué tipo de trabajo es.
+
+### Sin credenciales del tracker
+
+`dai check --ci --no-network` valida el link y **no** compara contra la US viva. Es el
+default del template: un gate que falla porque un token venció o porque el CI no tiene
+salida a internet enseña al equipo a ignorarlo. Con los secrets cargados, sacá el flag y
+el gate detecta además las US atrasadas.
 
 ## Qué hace el CI al mergear
 
@@ -28,6 +58,15 @@
 2. **Estampa la cobertura inversa** en el gestor: en el ticket `ABC-###`, deja
    "implementado por `<repo>` @ `<version>` (`ac_hash`) ✅". **Nadie lo escribe a
    mano** ([Art. 10](../docs/MANIFIESTO.md#art-10)).
+
+   ```bash
+   dai stamp ABC-482       # explícito: lo que corresponde en CI
+   dai stamp               # local: deduce la US de la rama; si hay varias, pregunta
+   ```
+
+   > En CI **pasá el ID**. `dai stamp` sin argumentos es para el dev en su máquina:
+   > deduce la US del nombre de la rama y, si no puede, pregunta en vez de estampar de
+   > más. Un comentario en el tracker no se deshace.
 3. **Actualiza el índice/router central** de la federación: la fila `ABC-### → { repos }`.
 
 ## Qué hace el CD al desplegar (solo N3 · organización grande)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforce2055/dai",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Metodología de desarrollo asistido por IA — CLI de acciones deterministas (trazabilidad QUÉ↔CÓMO).",
   "repository": { "type": "git", "url": "git+https://github.com/dforce2055/dai.git" },
   "homepage": "https://dforce2055.github.io/dai/",
@@ -32,7 +32,7 @@
     "skills",
     "manifest.yaml",
     "install.sh",
-    ".env.example",
+    ".env.dai.example",
     "VERSION",
     "LICENSE",
     "README.md",
@@ -43,7 +43,13 @@
   ],
   "scripts": {
     "test": "node --test cli/test/*.test.mjs",
-    "prepublishOnly": "npm test"
+    "prepublishOnly": "npm test",
+    "docs:dev": "vitepress dev",
+    "docs:build": "vitepress build",
+    "docs:preview": "vitepress preview"
+  },
+  "devDependencies": {
+    "vitepress": "^1.6.3"
   },
   "engines": {
     "node": ">=18"

package/skills/dai-review/SKILL.md

@@ -30,7 +30,7 @@ falló. El CLI lo caza antes.
 ### Cómo postear (elige la primera disponible)
 
 1. **`dai forge review <ref> --from <archivo> --yes`** — la forma. Review inline:
-   resumen + un comentario por línea. Usa `GITHUB_TOKEN`/`GITLAB_TOKEN` del `.env`.
+   resumen + un comentario por línea. Usa `GITHUB_TOKEN`/`GITLAB_TOKEN` de `.env.dai` o `.env`.
 2. **MCP del forge / `dai forge comment`** — fallback si no hay token, o si necesitas
    dejar un comentario suelto sin anclar. Pierdes el inline y la validación.
 

package/skills/grill-epic/SKILL.md

@@ -60,11 +60,11 @@ la forma. Nunca reescribas el formato inline.
 1. **Armar la épica** con el formato de `templates/epica.md`: metadata (`ID`, autor,
    estado, US que la componen) + objetivo + alcance (in/out) + lista de US + métricas +
    dependencias.
-2. **Publicar en el tracker.** **No asumas el tracker: lee `DAI_PM` del `.env` primero.**
+2. **Publicar en el tracker.** **No asumas el tracker: lee `DAI_PM` primero**, de `.env.dai` o `.env` (dai lee los dos; `.env.dai` gana clave por clave).
    Tres caminos, mismo contenido:
    - **Con MCP** (`jira` → MCP de Atlassian · `clickup` → MCP de ClickUp): crea el ticket
      de épica; las US hijas se crean como tickets vinculados (o quedan listadas).
-   - **Sin MCP, con token** (`DAI_PM=jira` + token en `.env`): escribe la épica como `.md`
+   - **Sin MCP, con token** (`DAI_PM=jira` + token en `.env.dai` o `.env`): escribe la épica como `.md`
      y publícala con **`dai publish <epica.md> --issuetype Epic`**. Devuelve el key. Si el
      proyecto exige campos propios, van con `--field alias=valor` (los declarados en
      `.dai/jira-fields.json`; `dai doctor` te los lista). Después, cada US hija se cuelga

package/skills/grill-intent/SKILL.md

@@ -36,7 +36,7 @@ Pull *up* from the story's "I want Y" to the problem underneath, and pressure-te
 1. **Read** the user story and the constitution.
 2. **Challenge, one axis at a time.** grill-me discipline: ask, listen, push, move on. Don't dump the five questions at once.
 3. **Reach a verdict** — `a-spec` (problem survived, go to propose), `reframe` (the real problem is different, back to `grill-user-story`), or `descartar` (not worth solving now, stop and record why).
-4. **Emit** the filled `intent.md` (default location `openspec/intents/<YYYYMMDD-slug>/intent.md`; adjust to where the manifesto puts intents). Embed the tracker ID (the issue/task key — Jira or ClickUp, per `DAI_PM` in the repo's `.env`) and the source story.
+4. **Emit** the filled `intent.md` (default location `openspec/intents/<YYYYMMDD-slug>/intent.md`; adjust to where the manifesto puts intents). Embed the tracker ID (the issue/task key — Jira or ClickUp, per `DAI_PM` in the repo's `.env.dai` or `.env` — dai reads both, `.env.dai` wins) and the source story.
 
 ## Hand-off