@dforce2055/dai 0.9.0 → 0.10.0

package/docs/detalle/04-tdd.md

@@ -1,32 +1,38 @@
-# Paso 4 — TDD: test primero, en vertical slices
+# Paso 4 — Implementación: el agente construye con TDD (`/opsx:apply`)
 
 ← vuelve a [`SCRUM-CON-IA.md`](../SCRUM-CON-IA.md)
 
 ## En qué consiste en detalle
 
-El CÓMO se construye con **test primero**, un comportamiento a la vez:
+El CÓMO **lo implementa el agente** con `/opsx:apply`: aplica las tareas que salieron de
+`opsx:propose`, escribiendo **test primero**, un comportamiento a la vez:
 
 ```
-RED   → escribes UN test que falla (un criterio de aceptación)
+RED   → el agente escribe UN test que falla (un criterio de aceptación)
 GREEN → el código mínimo para que pase
-REFACTOR → limpias, con los tests en verde
+REFACTOR → limpia, con los tests en verde
 ```
 
 *Vertical slices* (un test → una implementación → repetir), **no** horizontal
-(todos los tests, después todo el código).
+(todos los tests, después todo el código). Se verifica por la **interfaz pública**.
 
 ## Herramientas
 
-- Skill [`tdd`](../../skills/tdd/SKILL.md) — el loop red-green-refactor y qué es un
-  buen test.
+- **`/opsx:apply`** — el paso donde el agente implementa las tareas del change.
+- Skill [`tdd`](../../skills/tdd/SKILL.md) — la disciplina que `/opsx:apply` sigue: el
+  loop red-green-refactor y qué es un buen test.
 
 ## Qué firma el humano
 
-El dev **decide qué comportamientos importa testear** (no se testea todo) y revisa
-cada slice. La IA escribe el test como spec ejecutable, el dev valida.
+El agente escribe el test y el código; el **dev decide qué comportamientos importa
+testear** (no se testea todo), valida cada slice, y **es responsable del resultado — no
+la IA** ([Art. 7](../MANIFIESTO.md#art-7)). Ese es el antídoto del vibe coding: la
+revisión minuciosa de lo que produjo el agente (paso 6, code review propio).
 
 ## Antipatrones
 
+- **Aceptar lo que sale sin revisarlo** → vibe coding con otra cara. El agente propone;
+  el dev responde por el código.
 - **Horizontal slicing** (todos los tests juntos) → tests de la *forma imaginada*, no
   del comportamiento real.
 - **Testear lo interno** (mocks de colaboradores, métodos privados) → el test se rompe

package/docs/detalle/06-code-review.md

@@ -8,16 +8,19 @@ Dos revisiones distintas:
 
 1. **El dev revisa su propia implementación** — la que produjo la IA, minucioso y con
    criterio (correctitud, casos borde, seguridad, calidad). Es responsable del código, no
-   la IA (anti vibe-coding). Recién con eso en orden, y todo **commiteado**, crea la PR.
+   la IA (anti vibe-coding). Solo con eso en orden, y todo **commiteado**, crea la PR.
 2. **Un partner revisa la PR** y **firma** aprobación/rechazo. Se apoya en la skill
    `dai-review` para un primer pase consciente de la metodología: corre `dai check` (¿la US
-   quedó atrasada?), valida el DoD, revisa el código (🔴 errores / 🟡 mejoras / ✅ bien) y
-   deja un **comentario estándar** en la PR/MR — le saca el ruido para que firme lo que importa.
+   quedó atrasada?), valida el DoD, revisa el código (severidad low/medium/high) y deja un
+   **review inline** — un resumen + **un comentario anclado a cada `archivo:línea`**. La
+   skill valida cada posición contra el diff (descarta lo que el modelo inventó), te muestra
+   el preview y **espera tu OK antes de postear** ([ADR-0016](../adr/0016-review-inline.md)).
 
 ## Herramientas
 
-- Skill [`dai-review`](../../skills/dai-review/SKILL.md) — GitHub y GitLab, postea por
-  MCP del forge o por `dai forge comment` (token).
+- Skill [`dai-review`](../../skills/dai-review/SKILL.md) — GitHub y GitLab. Postea el review
+  inline por el MCP del forge o por `dai forge review <ref> --from <review.json>` (token);
+  `dai forge comment` queda como fallback simple sin anclar.
 - `dai check` ([ADR-0003](../adr/0003-deteccion-y-estampado-son-comandos.md)).
 - Gate de cierre: [`definition-of-done.md`](../../templates/definition-of-done.md).
 

package/docs/detalle/08-daily.md

@@ -7,7 +7,7 @@
 15 minutos: qué hice, qué voy a hacer, qué me traba. Es **sincronización**, no
 reporte de estado. Se hace **a mano, sin IA, a propósito**.
 
-## Por qué no metemos IA acá
+## Por qué no metemos IA aquí
 
 La IA *podría* auto-generar el "qué se hizo" desde git + el tracker. **No lo hacemos**:
 el daily es donde el equipo se **apropia** del proceso, lo entiende y se coordina de

package/docs/detalle/README.md

@@ -9,7 +9,7 @@ los antipatrones a evitar.
 | [01](01-refinamiento.md) | Refinamiento (idea → US testeable) | ●●● |
 | [02](02-planning.md) | Planning (derivar el CÓMO) | ●● |
 | [03](03-ramas.md) | Rama ligada al QUÉ | ●●● |
-| [04](04-tdd.md) | TDD (test primero) | ●●● |
+| [04](04-tdd.md) | Implementación (`/opsx:apply`, con TDD) | ●●● |
 | [05](05-smoke.md) | Smoke end-to-end | ●● |
 | [06](06-code-review.md) | Code review (IA + partner) | ●● |
 | [07](07-merge-trazabilidad.md) | Merge + trazabilidad | ●●● |

package/docs/glosario.md

@@ -24,7 +24,7 @@
 | **`implements.yaml`** | El archivo, en el change del repo, que contiene ese link. Lo genera `link-us`. Ejemplo lleno + árbol de dónde vive entre los artefactos de OpenSpec: [ADR-0004](adr/0004-ubicacion-y-schema-implements.md). |
 | **Trazabilidad inversa / cobertura** | El mapa "quién implementó este QUÉ". **Se genera, nunca se escribe.** |
 | **Índice / router** | La tabla central que dice qué ID vive en qué repos. Es un router, **no un almacén**: no guarda el detalle. |
-| **Federación (dos niveles)** | Cómo se guarda la trazabilidad a escala: Nivel 1 = índice central chico; Nivel 2 = detalle en cada repo, resuelto on-demand. *(Es un eje distinto de los niveles de ceremonia N1/N2/N3: acá "nivel" es dónde vive el dato, no el tamaño del equipo.)* |
+| **Federación (dos niveles)** | Cómo se guarda la trazabilidad a escala: Nivel 1 = índice central chico; Nivel 2 = detalle en cada repo, resuelto on-demand. *(Es un eje distinto de los niveles de ceremonia N1/N2/N3: aquí "nivel" es dónde vive el dato, no el tamaño del equipo.)* |
 | **Matriz de trazabilidad** | La vista "repo × versión × estado (al día / atrasado)". Derivada, no mantenida a mano. |
 
 ## El versionado
@@ -46,7 +46,7 @@
 | **PR / MR (Pull / Merge Request)** | La unidad revisable del CÓMO. En dai lleva **dos activos**, y el review cubre ambos: (1) la **implementación** (el código) y (2) el **spec trazable** (el `implements.yaml` con el link a la US y el `@version` verificado). Sin el segundo, el CI bloquea el PR. Template en `../templates/pull-request.md`. |
 | **Change** | La unidad de trabajo de OpenSpec (proposal + design + tasks + specs). |
 | **ADR (Architecture Decision Record)** | El registro de una decisión estructural: contexto, decisión, consecuencias. Chico e **inmutable** — si algo cambia, se escribe uno nuevo que supersede al viejo. Template en `../templates/adr.md`; los de dai, en [`adr/`](adr/). |
-| **TDD (Test-Driven Development)** | Escribir el test **antes** que el código: RED (test que falla) → GREEN (código mínimo) → REFACTOR. En dai cada AC se vuelve un test (skill `tdd`); es el antídoto del vibe coding. |
+| **TDD (Test-Driven Development)** | Escribir el test **antes** que el código: RED (test que falla) → GREEN (código mínimo) → REFACTOR. En dai lo aplica el **agente** dentro de `/opsx:apply` (disciplina de la skill `tdd`): cada AC se vuelve un test. El dev valida y es responsable. Es el antídoto del vibe coding. |
 | **Vertical slice** | Un test → una implementación → repetir. Lo opuesto a "todos los tests, después todo el código". |
 | **Smoke** | Escenario end-to-end que verifica que el flujo grueso no se rompió. |
 

package/docs/guias/dev.md

@@ -18,12 +18,14 @@
 
 ## Tu día a día
 
-1. **Agarras una US** que cumple el [DoR](../../templates/definition-of-ready.md) → `/link-us ABC-###`. Crea la rama y el
+1. **Tomas una US** que cumple el [DoR](../../templates/definition-of-ready.md) → `/link-us ABC-###`. Crea la rama y el
    `implements.yaml` **desde el ID, sin que tipees el key a mano** (Art. 8, Art. 9).
 2. **Armas el CÓMO** → `opsx:explore` → `opsx:propose`. OpenSpec genera
    `design.md`/`tasks.md`; tú validas y ajustas. Las tareas nacen del cómo.
-3. **Implementas con TDD** → `/tdd`. Un test a la vez, vertical slices: RED → GREEN
-   → refactor. Verificas por la **interfaz pública**, no espías lo interno (Art. 7).
+3. **El agente implementa el CÓMO** → `/opsx:apply`. Aplica las tareas escribiendo
+   test-primero (TDD, vertical slices: RED → GREEN → refactor), por la **interfaz
+   pública** (Art. 7). Tú decides qué comportamientos importa testear; el agente los
+   construye.
 4. **Smoke** → ejecutas el escenario end-to-end del flujo.
 5. **Revisas la implementación de la IA** (code review propio) → minucioso y con criterio:
    correctitud, casos borde, seguridad, calidad. **Eres responsable del código, no la IA**
@@ -33,7 +35,8 @@
    arma la PR **precargada** (US + estado del check + links; los **dos activos**: código +
    spec trazable) y la asignas a un partner.
 7. **Review de un partner** → un compañero revisa tu PR y **firma** aprobación/rechazo
-   (Art. 5). Se apoya en la skill `/dai-review` para un primer pase con comentario estándar.
+   (Art. 5). Se apoya en la skill `/dai-review` para un primer pase: un **review inline**
+   (resumen + un comentario por línea), que le muestra el preview y espera su OK antes de postear.
    *(Tu PR la revisas tú en el paso 5; la de un compañero, lo ayudas con la skill.)*
 8. **Verificas el DoD** → [`definition-of-done.md`](../../templates/definition-of-done.md) antes de mergear.
 9. **Merge → se estampa la cobertura** con `dai stamp` (lo corres tú tras mergear, o el CI
@@ -45,7 +48,7 @@
 ## La trampa a evitar
 
 **Vibe coding.** Nada de codear sobre una idea vaga o "improvisar y después vemos".
-Si no hay US con criterios testeables, no arranques: falta el [DoR](../../templates/definition-of-ready.md). La disciplina
+Si no hay US con criterios testeables, no empieces: falta el [DoR](../../templates/definition-of-ready.md). La disciplina
 —US clara → design → test → código— es lo que separa esto de pedirle cosas a un chat.
 
 ## Cuando el QUÉ cambia
@@ -59,8 +62,8 @@ te avisa: el link versionado lo hace [Art. 11](../MANIFIESTO.md#art-11).
 - `/link-us`
 - `/opsx:explore`
 - `/opsx:propose`
-- `/opsx:apply`
-- `/tdd`
+- `/opsx:apply` — el agente implementa las tareas (con TDD)
+- `/tdd` — la disciplina TDD que aplica el paso anterior
 - `/dai-review`
 - `dai check` · `dai pr` · `dai stamp` · `dai done` (limpieza, opcional)
 - `definition-of-done.md`

package/docs/guias/index.md

@@ -0,0 +1,12 @@
+# Guías por rol
+
+Un camino corto según quién eres. Cada guía te dice de qué eres **dueño**, qué **no tocas**,
+y tu **día a día**.
+
+- [**Guía del PO / funcional**](./po) — dueño del **QUÉ**: defines las User Stories y el
+  porqué, nunca el CÓMO. Entrás por `grill-user-story`, `grill-epic` o `doc-to-backlog`.
+- [**Guía del dev / ingeniero**](./dev) — dueño del **CÓMO** y del **link**: el agente
+  implementa con `/opsx:apply`, tú revisas y autoras el `implements.yaml`.
+- [**Guía del lead / SM / arquitecto**](./lead) — custodio de las **invariantes** y del
+  **nivel de ceremonia** (N1 / N2 / N3): haces que el método se cumpla y se aligere donde
+  corresponde.

package/docs/guias/lead.md

@@ -23,7 +23,7 @@
 
 ## Tus decisiones clave
 
-### 1. ¿En qué nivel arranca el equipo?
+### 1. ¿En qué nivel empieza el equipo?
 - **1 dev / 1 repo →** N1 (OpenSpec solo, cero herramientas externas).
 - **Equipo compacto →** N2 (US en el gestor + `implements.yaml`).
 - **Muchos repos + equipos separados →** N3 (Jira hub, CI estampa, matriz de ambientes).

package/docs/guias/po.md

@@ -18,13 +18,17 @@
 
 ## Tu día a día
 
-1. **Nace una idea** → creas el ticket en el gestor (nace con ID, aunque sea vago).
-2. **Gate 0** → ejecutas `/grill-intent`. La IA te desafía el *problema*: ¿es el
-   correcto? ¿quién lo sufre? ¿qué pasa si no lo hacemos? Un veredicto válido es
-   *"no lo construyas"* — eso es el gate haciendo su trabajo (Art. 4).
-3. **Pulir el QUÉ** → ejecutas `/grill-user-story`. La IA te **interroga** hasta que
+1. **Nace una idea — o llega un documento** → creas el ticket en el gestor (nace con ID,
+   aunque sea vago). Si en cambio partes de un **documento de análisis** (PDF, Word),
+   `/doc-to-backlog` lo convierte en un **backlog candidato** de épicas + US para que
+   priorices y valides. Y si algo es **demasiado grande** para una sola US,
+   `/grill-epic` lo parte en varias.
+2. **Pulir el QUÉ** → ejecutas `/grill-user-story`. La IA te **interroga** hasta que
    la US es testeable (INVEST + Gherkin) y la publica en el gestor. La IA no
    inventa requerimientos: te los saca a preguntas. Tú respondes y decides.
+3. **Gate 0** → ejecutas `/grill-intent` sobre la US ya formada. La IA te desafía el
+   *problema*: ¿es el correcto? ¿quién lo sufre? ¿qué pasa si no lo hacemos? Un veredicto
+   válido es *"no lo construyas"* — eso es el gate haciendo su trabajo (Art. 4).
 4. **Verificas el [DoR](../../templates/definition-of-ready.md)** → antes de que entre al sprint, la US cumple el
    [`definition-of-ready.md`](../../templates/definition-of-ready.md).
 5. **Demo** → aceptas o rechazas contra los mismos criterios que ya eran tests.
@@ -44,7 +48,9 @@ el CI (Art. 10).
 
 ## Tus herramientas
 
-- `/grill-intent`
-- `/grill-user-story`
+- `/doc-to-backlog` — un documento (PDF/Word) → backlog candidato de épicas + US
+- `/grill-epic` — algo grande → una épica partida en varias US
+- `/grill-user-story` — una US funcional y testeable
+- `/grill-intent` — Gate 0: desafía el problema de la US antes del spec
 - el gestor de proyectos
 - [`definition-of-ready.md`](../../templates/definition-of-ready.md)

package/docs/index.md

@@ -0,0 +1,35 @@
+---
+layout: home
+
+hero:
+  name: dai
+  text: Desarrollo Asistido por IA
+  tagline: La documentación del método — el manifiesto, las decisiones (ADRs) y las guías por rol. Todo buscable con ⌘K.
+  actions:
+    - theme: brand
+      text: Empezar
+      link: /PROBAR
+    - theme: alt
+      text: El manifiesto
+      link: /MANIFIESTO
+    - theme: alt
+      text: ↩ Volver a la landing
+      link: https://dforce2055.github.io/dai/
+
+features:
+  - icon: 📐
+    title: El método
+    details: Manifiesto, metodología y el Scrum con IA en 10 pasos. El porqué antes que el cómo.
+    link: /MANIFIESTO
+    linkText: Leer el manifiesto
+  - icon: 🧭
+    title: Las decisiones (ADRs)
+    details: Cada decisión de diseño, registrada — del contrato del ac_hash al review inline. Por qué dai es como es.
+    link: /adr/
+    linkText: Ver los ADRs
+  - icon: 🧑‍💻
+    title: Guías por rol
+    details: Caminos cortos según quién sos — PO / analista, dev, o lead. Directo a lo que te toca.
+    link: /guias/dev
+    linkText: Ir a las guías
+---

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.