@dforce2055/dai 0.13.1 → 0.13.3

package/CHANGELOG.md

@@ -3,6 +3,126 @@
 Formato basado en [Keep a Changelog](https://keepachangelog.com/). Versionado semver
 (ver `VERSION`).
 
+## [0.13.3] — 2026-09-02
+
+**Una PR de dai se abría diciendo, en el mismo párrafo, dos cosas que no encajaban: que el
+spec estaba "verificado con dai check: ✅ al día", y a continuación una explicación general
+del método. Tirando de ese hilo aparecieron dos bugs distintos, y los dos eran dai afirmando
+cosas que no le constaban.**
+
+### Arreglado
+- **El relleno del estado reescribía la prosa del template.** `dai pr` hacía un replace
+  **global** de `verificado con `dai check` ✅`, y esa frase estaba dos veces en el molde: en
+  el dato (`## 🔗 Implementa`) y en la prosa que explica el método. Así que a una oración
+  general —igual en todas las PRs— dai le insertaba el estado de *esta* PR, y quedaba
+  publicado: *"verificado con `dai check`: ✅ al día. Sin esto, el código no sabe a qué QUÉ
+  responde…"*. Ni doctrina ni dato. Ahora el relleno se acota a la sección; sin la sección
+  (un template ajeno con otra forma) cae al body entero, porque rellenar de más es
+  recuperable y publicar `ABC-###` no.
+- **`dai pr` decía "❓ sin US" cuando el tracker no contestaba** — dos líneas debajo del id de
+  la US que sí existe. `coverageStatus` colapsaba en un mismo `sin-us` dos cosas que no
+  significan lo mismo: *el tracker contestó y la US no está* y *no hubo respuesta* (sin red,
+  sin token, 5xx, certificado corporativo). Los adaptadores ya distinguían los dos casos
+  (`404 → null`, cualquier otro error → `throw`), y el gate de CI también con su try/catch
+  propio; lo que rompía la distinción era un `.catch(() => null)` en `dai pr`. Hay un estado
+  nuevo, **`sin-respuesta`** (`⚠️ no verificado`), y la PR dice *"no verificado (el tracker no
+  respondió)"*, que es lo único cierto ([#43](https://github.com/dforce2055/dai/issues/43)).
+- **`dai: fetch failed` era todo lo que se llegaba a leer.** Es el mensaje pelado de undici
+  cuando no hay red, el host no resuelve o el certificado no valida: no dice qué se estaba
+  consultando, ni contra qué, ni qué mirar — indistinguible de un bug de dai, el mismo modo de
+  falla que el push por SSH de la 0.13.1. Ahora el error nombra la US, el backend y el host, y
+  distingue red / credencial / error del tracker, con el próximo paso en cada caso.
+- **`dai check` ya no se detenía en la primera US** que no pudiera consultar: lo reporta, sigue
+  con las demás y sale ≠ 0. **`dai stamp`** explicita que no estampa un estado que no pudo
+  verificar — escribir en el tracker de todo el equipo no se deshace.
+
+### Cambiado
+- **El molde de PR adelgaza: la doctrina pasa a comentario HTML.** El encabezado tenía cuatro
+  bloques y un solo dato — la doctrina de los dos activos, una línea que repetía la de arriba
+  (*"este PR está atado a la US vía implements.yaml"*) y la instrucción de borrar la sección si
+  no hay US, que `dai pr` resuelve solo desde la 0.13.2. Nada de eso decía algo sobre *esa* PR,
+  y repetirlo a la vista en cada una entrena a saltear el principio del cuerpo, que es
+  justamente donde va la descripción. Sigue estando para quien edite el molde, invisible al
+  renderizar; y la doctrina vive donde se lee una vez y no quinientas: `docs/glosario.md`,
+  `docs/guias/dev.md`, `governance/ci-rules.md`. Los repos ya inicializados lo reciben con
+  `dai sync`.
+
+### Interno
+- **367 tests** (+9): los dos caminos de la consulta (la US que no está y la que no se pudo
+  consultar), el mensaje de error por tipo de falla, y que el relleno del estado no toque la
+  prosa que lo rodea.
+
+## [0.13.2] — 2026-09-02
+
+**Una PR se publicaba con la descripción vacía y la lista de cambios diciendo "Cambio 1,
+Cambio 2". No siempre: a veces salía perfecta. Lo raro es que "Enlaces relacionados", que
+vive en el mismo template, nunca falló — y ahí estaba la pista. Y de yapa, el paquete de npm
+adelgaza de 3.7 MB a 703 kB: cargaba las capturas del sitio.**
+
+`dai pr` rellenaba cada sección **solo si tenía el dato** y, si no lo tenía, devolvía el
+molde del template intacto, en silencio. La "Descripción" quedaba en su comentario HTML, que
+no se renderiza: en GitHub y en GitLab la sección se ve **vacía**. El bloque de enlaces nunca
+falló porque su código siempre escribe — si no encuentra la sección, la agrega. Esa
+disciplina ahora vale para todo el cuerpo de la PR.
+
+Detrás del bug había algo más de fondo: **no existía forma de escribir la descripción**.
+`dai pr` no aceptaba ningún texto, así que el propósito de la PR solo podía salir del título
+de la US y de los subjects de los commits. Ni el dev ni su agente podían hacerlo bien aunque
+quisieran.
+
+### Arreglado
+- **La PR salía con el molde del template sin llenar.** Tres caminos llevaban al mismo
+  resultado, los tres silenciosos: (1) el tracker no contestaba —sin token, sin red, `DAI_PM`
+  mal seteado— y sin el título de la US no se llenaba "Descripción"; (2) la branch base no
+  existía **en local** —clones `--single-branch`, repos donde se trabaja sobre `develop` y la
+  base es `main`— y `git log base..HEAD` fallaba dentro de un `catch` vacío, dejando "Cambios
+  realizados" con `Cambio 1 / Cambio 2`; (3) una branch exenta (`chore/`, `docs/`) nunca
+  llenaba "Descripción", ni siquiera pudiendo. Ese mismo `catch` vacío también se comía el
+  chequeo de *"sin commits sobre la base no hay PR"*.
+- **La branch base ahora se resuelve** a `main` o, si no está en local, a `origin/main`.
+- **Las secciones se reconocen aunque el repo tenga su propio molde** (`## 📝 Descripción del
+  cambio`, `### CAMBIOS REALIZADOS`): antes el match era exacto, no encontraba la sección y
+  devolvía el body sin tocar — otra vez, sin decir nada. Ignora los `##` que estén dentro de
+  un bloque de código y, si la sección no existe, la agrega.
+
+### Agregado
+- **`dai pr --description "…"` y `--description-file <archivo.md>`** — el propósito de un
+  cambio no se deriva de git ni del tracker. dai llena la US, el estado del check, los commits
+  y los links; el porqué lo escribe quien crea la PR. **dai no lo inventa: lo pide.**
+- **`--changes` y `--changes-file`** — reemplazan el detalle de "Cambios realizados" cuando los
+  commits no cuentan bien la historia. Sin ellos, siguen saliendo de los commits de la branch.
+- **La constitución que escriben `dai init` y `dai sync` lo dice**, para que el agente que
+  corre `dai pr` sepa que la descripción es suya. Los repos ya inicializados la reciben con
+  `dai sync`.
+
+### Cambiado
+- ⚠️ **`dai pr` no publica una PR que saldría con el molde sin llenar.** Con `--yes` o sin TTY
+  —el camino de un agente o de CI— **aborta** y dice qué flag pasar; en terminal avisa y decide
+  la persona. **Si tenés automatización con `dai pr --yes` sin `--description`, se va a frenar**:
+  es justamente lo que publicaba las PRs vacías. El molde también se detecta en la cabecera
+  (`ABC-###`), la misma familia de los issues #31/#33.
+
+### Arreglado — el paquete de npm
+- **`npm i -g @dforce2055/dai` bajaba las capturas del sitio.** `files[]` lista `docs`
+  entero, y ahí adentro viven las de los tutoriales (`docs/public/tutoriales/*.png`): **2.9 MB
+  de los 3.7 MB del paquete**, que el CLI no abre nunca. El test de higiene que ya cubría el
+  sitio (`index.html`, `onboarding.html`) no las veía porque entraban por otra puerta.
+  **3.7 MB → 703 kB**, 130 → 117 archivos, cero PNG en el tarball ([#37](https://github.com/dforce2055/dai/issues/37)).
+- **`dai docs` copiaba imágenes que no se veían.** Los `.md` referencian las capturas con la
+  ruta absoluta del sitio (`![…](/tutoriales/x.png)`, que VitePress resuelve contra
+  `docs/public/`); fuera del sitio esa ruta apunta a la raíz del filesystem, así que en la
+  copia **ya estaban rotas**, con los 2.9 MB adentro y todo. Ahora `dai docs` no copia
+  `public/` —son assets del sitio, no documentación para leer desde un repo— y **absolutiza**
+  esos links contra el sitio publicado: la doc copiada por fin muestra las capturas.
+
+### Interno
+- **358 tests** (+19). Uno por cada camino que dejaba pasar el molde del template —tracker
+  caído, sin commits, branch sin US, template propio del repo, headings dentro de un fence, y
+  el caso peor (sin tracker y sin commits a la vez)— más los de la reescritura de links y dos
+  de higiene que fijan la regla del paquete: que `files[]` declare la exclusión, y que no
+  aparezcan imágenes versionadas bajo `docs/` fuera de esa carpeta. Si mañana una captura
+  aterriza en otro lado, el test obliga a decidir ahí, no midiendo el tarball.
+
 ## [0.13.1] — 2026-08-24
 
 **Un dev en Windows no podía pushear contra el GitLab de su empresa. `ssh -T` le autenticaba
@@ -737,6 +857,8 @@ 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.13.3]: https://github.com/dforce2055/dai/releases/tag/v0.13.3
+[0.13.2]: https://github.com/dforce2055/dai/releases/tag/v0.13.2
 [0.13.1]: https://github.com/dforce2055/dai/releases/tag/v0.13.1
 [0.13.0]: https://github.com/dforce2055/dai/releases/tag/v0.13.0
 [0.12.0]: https://github.com/dforce2055/dai/releases/tag/v0.12.0

package/README.md

@@ -103,7 +103,8 @@ dai link-us <ID>                # trae la US del tracker → branch + implements
 ```bash
 dai check                       # ¿tu código sigue al día con la US?  ✅ / ⚠️ atrasado
 # revisas tu propio código + smoke test local antes de la PR
-dai pr --assignee <compañero>   # crea la PR precargada y se la asigna a un compañero
+dai pr --assignee <compañero> \
+  --description "Qué resuelve y por qué"   # crea la PR precargada y se la asigna a un compañero
 ```
 ```text
 /dai-review <PR>                # tu compañero deja un review inline (comentario por línea); un humano aprueba
@@ -201,14 +202,14 @@ flowchart TD
 | `dai link-us <ID> --resync` | re-estampa el `ac_hash` contra la US viva (tras un ⚠️ de check) |
 | `dai check` | compara tu código vs la US viva → ✅ al día / ⚠️ atrasado (exit code = gate de PR) |
 | `dai ls [--json]` | lista las US que implementa el repo + su link al tracker |
-| `dai pr [--assignee u] [--base b] [--draft] [--yes] [--us ID] [--title t]` · alias **`dai mr`** | crea TU PR/MR precargada: pregunta la branch base (default `main`), muestra el texto y confirma antes de publicar. Detecta el forge (GitHub→PR con `gh` · GitLab→MR con `glab`); `mr` es el mismo comando, más natural en GitLab. **La US la resuelve la branch** (la nombra `dai link-us`): si hay varias vivas y ninguna coincide, **pregunta** en vez de elegir por vos (sin TTY falla pidiendo `--us <ID>`), y una branch `chore/`/`docs/` sale **sin US** en lugar de heredar la de otro |
+| `dai pr [--assignee u] [--base b] [--draft] [--yes] [--us ID] [--title t] [--description t\|--description-file f] [--changes t\|--changes-file f]` · alias **`dai mr`** | crea TU PR/MR precargada: pregunta la branch base (default `main`), muestra el texto y confirma antes de publicar. Detecta el forge (GitHub→PR con `gh` · GitLab→MR con `glab`); `mr` es el mismo comando, más natural en GitLab. **La US la resuelve la branch** (la nombra `dai link-us`): si hay varias vivas y ninguna coincide, **pregunta** en vez de elegir por vos (sin TTY falla pidiendo `--us <ID>`), y una branch `chore/`/`docs/` sale **sin US** en lugar de heredar la de otro. **La descripción la escribís vos (o tu agente) con `--description`**: dai llena la US, los commits y los links, pero no inventa el propósito de un cambio — si "Descripción" o "Cambios realizados" quedarían con el molde del template, con `--yes` o sin TTY **no publica** y te dice qué falta |
 | `dai stamp` | estampa la cobertura inversa en el tracker (branch + commit-ancla) |
 | `dai done [--base main] [--force]` | cierra la US: vuelve a la base, `fetch --prune` + `pull`, y borra la branch local **si está mergeada** (chequeo estricto; `--force` la borra igual). Redes: no estar en la base, sin cambios sueltos, sin commits sin pushear |
 | `dai archive [<change>] [--skip-specs]` | **funde los delta specs del change en las specs canónicas** (`openspec/specs/`) y lo archiva. Lo corre el **aprobador** de la PR (gate de aprobación, [ADR-0011](docs/adr/0011-archive-gate-de-aprobacion.md)); detecta el change activo o le pasás el nombre. Envuelve `openspec archive` |
 | `dai forge review <ref> --from <review.json>` `[--dry-run\|--yes]` | **review inline**: un resumen + un comentario anclado a cada `archivo:línea`, clasificado low/medium/high. **Valida cada posición contra el diff** (descarta lo que el modelo inventó) antes de postear; sin `--yes` muestra el preview y no postea nada. Modo desatendido: `--min-severity`/`--min-confidence`/`--max-comments`. El review sale con `event: COMMENT`, nunca `APPROVE` ([ADR-0016](docs/adr/0016-review-inline.md)) |
 | `dai forge comment <ref> --body-file <f>` · `dai forge pr <ref>` | comentar / leer una PR/MR (GitHub/GitLab) — el fallback simple, sin anclar |
 | `dai ac-hash <us.md>` | calcula el hash de los criterios de aceptación de una US |
-| `dai doctor` · `dai docs <dest>` · `dai version` | diagnóstico del entorno (incluye **version-drift** del scaffold) · copiar la doc · versión (`dai version` avisa si tu repo quedó atrás) |
+| `dai doctor` · `dai docs <dest>` · `dai version` | diagnóstico del entorno (incluye **version-drift** del scaffold) · copiar la doc (sin los assets del sitio; los links a las capturas apuntan al sitio publicado) · versión (`dai version` avisa si tu repo quedó atrás) |
 
 > **🆕 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

package/VERSION

@@ -1 +1 @@
-0.13.1
+0.13.3

package/cli/dai.mjs

@@ -22,12 +22,13 @@ 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 { loadDaiEnv } from "./lib/env.mjs";
-import { getAdapter, coverageStatus, statusLabel } from "./lib/pm-adapter.mjs";
+import { getAdapter, coverageStatus, statusLabel, fetchLiveUS } 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";
 import { trackerUrl } from "./lib/tracker-url.mjs";
 import { parseFindings, diffPositions, validateFindings, filterFindings, renderFindingBody, renderReviewSummary } from "./lib/review-findings.mjs";
-import { composePrBody, prTitle, forgeTool } from "./lib/pr.mjs";
+import { composePrBody, prTitle, forgeTool, bodyGaps } from "./lib/pr.mjs";
+import { absolutizeSiteLinks } from "./lib/docs-links.mjs";
 import { diagnoseGitSsh, pushFailureHint, WINDOWS_OPENSSH } from "./lib/git-ssh.mjs";
 import { dirsEqual } from "./lib/fsutil.mjs";
 import { parseFlags, parseAssistants, isAssistantToken, asList } from "./lib/args.mjs";
@@ -216,6 +217,27 @@ function gitUser() {
 function gitRemote() { try { return git(["remote", "get-url", "origin"]); } catch { return null; } }
 function gitBranch() { try { return git(["rev-parse", "--abbrev-ref", "HEAD"]); } catch { return null; } }
 function gitCommit() { try { return git(["rev-parse", "HEAD"]); } catch { return null; } }
+// ¿Existe esta ref como commit? Devuelve la ref si sí, null si no. Sirve para caer de
+// `main` a `origin/main` sin adivinar: en muchos repos la base solo existe en el remoto.
+function resolveRev(ref) {
+  try { git(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]); return ref; } catch { return null; }
+}
+// Un texto que se puede pasar inline (`--description "…"`) o por archivo
+// (`--description-file notas.md`). Un agente casi siempre quiere el archivo: markdown
+// multilínea no sobrevive entero a la línea de comandos.
+function textOpt(opts, name) {
+  const file = opts[`${name}File`];
+  if (file !== undefined) {
+    if (file === true) fail(`--${name}-file necesita la ruta de un archivo.`, 1);
+    const path = Array.isArray(file) ? file[file.length - 1] : file;
+    try { return readFileSync(path, "utf8"); }
+    catch { fail(`no pude leer --${name}-file '${path}'.`, 1); }
+  }
+  const v = opts[name];
+  if (v === true) fail(`--${name} necesita un texto (o usá --${name}-file <archivo>).`, 1);
+  if (Array.isArray(v)) return v.join("\n");
+  return typeof v === "string" ? v : null;
+}
 
 // ── check --ci: el gate de governance/ci-rules.md, ejecutable ────────────────
 //
@@ -310,13 +332,18 @@ async function cmdCheck() {
   for (const f of found) for (const im of f.implements || []) {
     if (isPlaceholderId(im.id)) continue;   // plantilla sin completar, no es una US real
     n++;
-    const live = await adapter.fetchUS(im.id);
-    const status = coverageStatus(im.ac_hash, live?.ac_hash);
+    const { us: live, unreachable, reason } = await fetchLiveUS(adapter, im.id);
+    const status = coverageStatus(im.ac_hash, live?.ac_hash, { unreachable });
     if (status === "al-dia") process.stdout.write(`✅ ${im.id} al día (${im.version})\n`);
     else if (status === "atrasado") {
       process.stdout.write(`⚠️  ${im.id} ATRASADO: implementaste ${im.ac_hash}, la US viva es ${live.ac_hash}${live.spec_version ? ` (${live.spec_version})` : ""}\n`);
       atrasadas.push(im.id);
       worst = Math.max(worst, 1);
+    } else if (status === "sin-respuesta") {
+      // No es "no hay US": es "no pude preguntar". Antes moría acá con `fetch failed` y sin
+      // chequear las demás; ahora lo dice, sigue, y sale ≠ 0 porque no pudo verificar nada.
+      process.stdout.write(`⚠️  ${reason}\n`);
+      worst = Math.max(worst, 2);
     } else {
       process.stdout.write(`❓ ${im.id}: no encontré la US (backend ${adapter.kind}). ¿Falta el .md o el token?\n`);
       worst = Math.max(worst, 2);
@@ -373,7 +400,11 @@ async function cmdStamp(ids = [], opts = {}) {
   }
 
   for (const r of targets) {
-    const live = await adapter.fetchUS(r.id);
+    // Estampar es ESCRIBIR en el tracker de todo el equipo, y no se deshace: si no se pudo
+    // verificar el estado, no se estampa. (Hoy ya frenaba, por la excepción sin atrapar; acá
+    // queda explícito, con el motivo, y cubierto por un test.)
+    const { us: live, unreachable, reason } = await fetchLiveUS(adapter, r.id);
+    if (unreachable) fail(`${reason}\n  No estampo un estado que no pude verificar.`, 2);
     const status = coverageStatus(r.ac_hash, live?.ac_hash);
     const record = {
       repo: r.repo, change: r.change, version: r.version, ac_hash: r.ac_hash, status,
@@ -879,9 +910,16 @@ async function cmdPr(opts) {
   let base = opts.base;
   if (!base) { const ans = await ask("  ¿Contra qué branch va la PR? (main) "); base = ans || "main"; }
 
+  // La base puede no existir LOCAL (clones con --single-branch, repos donde el dev
+  // trabaja sobre develop y la base es main, corporativos con la base solo en origin).
+  // Antes el catch vacío se comía el error y seguía de largo: ni se contaban los commits
+  // (→ "Cambios realizados" salía con el molde) ni frenaba el chequeo de abajo.
+  const baseRev = resolveRev(base) || resolveRev(`origin/${base}`);
+  if (!baseRev) warn(`no encuentro la branch base '${base}' (ni local ni en origin/${base}). Trae la base primero:  git fetch origin ${base}`);
+
   // Sin commits sobre la base no hay PR.
   let ahead = null;
-  try { ahead = Number(git(["rev-list", "--count", `${base}..HEAD`])); } catch { /* base no existe local */ }
+  try { ahead = Number(git(["rev-list", "--count", `${baseRev}..HEAD`])); } catch { /* base ausente */ }
   if (ahead === 0) {
     fail(`no hay commits en '${branch}' por encima de '${base}'. Una PR necesita cambios: haz commit primero (git commit).`, 1);
   }
@@ -931,8 +969,14 @@ async function cmdPr(opts) {
 
   // 2. Estado de trazabilidad (dai check) contra la US viva.
   const adapter = getAdapter(process.env);
-  const live = id ? await Promise.resolve(adapter.fetchUS(id)).catch(() => null) : null;
-  const status = id ? coverageStatus(ac_hash, live?.ac_hash) : null;
+  // El `.catch(() => null)` que había acá convertía "el tracker no contestó" en "no hay US",
+  // y esa afirmación se PUBLICABA en el cuerpo de la PR, al lado del id de la US que sí está.
+  const { us: live, unreachable, reason } = await fetchLiveUS(adapter, id);
+  if (unreachable) {
+    warn(reason);
+    warn("la PR va a decir que no se pudo verificar contra el tracker — no que no hay US.");
+  }
+  const status = id ? coverageStatus(ac_hash, live?.ac_hash, { unreachable }) : null;
   if (status === "atrasado") {
     warn(`la US ${id} está ATRASADA respecto de tu implementación (${ac_hash} ≠ ${live?.ac_hash}).`);
     warn(`resincroniza antes de abrir la PR:  dai link-us ${id} --resync`);
@@ -944,7 +988,13 @@ async function cmdPr(opts) {
     : join(ROOT, "templates", "pull-request.md");
   // Commits de la branch (para precargar "Cambios realizados").
   let commits = [];
-  try { commits = git(["log", `${base}..HEAD`, "--pretty=%s"]).split("\n").filter(Boolean); } catch { /* base local ausente */ }
+  if (baseRev) {
+    try { commits = git(["log", `${baseRev}..HEAD`, "--pretty=%s"]).split("\n").filter(Boolean); } catch { /* rango inválido */ }
+  }
+  // El texto que escribe quien crea la PR (el dev o su agente). Es la ÚNICA fuente de
+  // una descripción de verdad: dai lee git y el tracker, no el porqué del cambio.
+  const description = textOpt(opts, "description");
+  const changes = textOpt(opts, "changes");
   // La canónica del tracker (live.url) gana sobre la derivada; el template gana sobre todo.
   const usUrl = id ? usUrlFor(id, live?.url) : null;
   if (id && !usUrl) {
@@ -952,7 +1002,8 @@ async function cmdPr(opts) {
     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, noUsReason: id ? null : scope.reason,
+    id, version, ac_hash, status, usUrl, usTitle: live?.title, commits, description, changes,
+    noUsReason: id ? null : scope.reason,
     branch, branchUrl: branchUrl(remote, branch), commit, commitUrl: commitUrl(remote, commit),
   });
   // Sin US el título sale del último commit: describe lo que hay adentro, en vez de
@@ -969,6 +1020,27 @@ async function cmdPr(opts) {
   process.stdout.write(`  ─────────────────────────────────────────────────────\n\n${body}\n`);
   process.stdout.write(`  ─────────────────────────────────────────────────────\n`);
 
+  // 4b. Gate: una PR con el molde del template sin llenar no se puede revisar.
+  // Pasaba en repos reales — "Descripción" con el comentario HTML (que no se renderiza:
+  // la sección se ve VACÍA) y "Cambios realizados" con `Cambio 1/Cambio 2` — cada vez
+  // que el tracker no respondía o la base no estaba local. dai NO inventa la descripción:
+  // la pide. Sin TTY (el camino del agente) frena; en terminal avisa y decidís vos.
+  const gaps = bodyGaps(body);
+  if (gaps.length) {
+    const how =
+      `  Escribí el texto y pasáselo a dai:\n` +
+      `    dai pr --description "Qué resuelve este cambio y por qué (2–4 líneas)."\n` +
+      `    dai pr --description-file notas.md --changes-file cambios.md   (markdown multilínea)\n` +
+      `  El detalle de "Cambios realizados" sale de los commits si no pasás --changes.\n`;
+    if (opts.yes || !process.stdin.isTTY) {
+      closeRl();
+      fail(`la PR saldría con el molde del template sin llenar: ${gaps.join(", ")}.\n` +
+           `  Una PR sin descripción no se puede revisar, así que no la publico.\n${how}`, 1);
+    }
+    warn(`la PR va a salir con el molde sin llenar: ${gaps.join(", ")}.`);
+    process.stdout.write(how);
+  }
+
   // Archivo de paso para gh/glab: en el temp del sistema, NO en el repo (no lo ensucia).
   const bodyFile = join(mkdtempSync(join(tmpdir(), "dai-pr-")), "body.md");
   if (!opts.yes) {
@@ -1431,8 +1503,28 @@ async function cmdInit(repo, opts) {
 function cmdDocs(dest) {
   if (!dest) fail("uso: dai docs <destino>");
   mkdirSync(dest, { recursive: true });
-  cpSync(join(ROOT, "docs"), dest, { recursive: true });
+  // `public/` son los assets del sitio (VitePress), no documentación para leer desde el
+  // repo de nadie: las capturas de los tutoriales ni siquiera viajan en el paquete npm
+  // (issue #37). Se saltea, y los links que las nombran se absolutizan contra el sitio.
+  cpSync(join(ROOT, "docs"), dest, { recursive: true, filter: (src) => !/[/\\]public([/\\]|$)/.test(src) });
+  let reescritos = 0;
+  for (const f of walkMd(dest)) {
+    const md = readFileSync(f, "utf8");
+    const out = absolutizeSiteLinks(md);
+    if (out !== md) { writeFileSync(f, out); reescritos++; }
+  }
   ok(`documentación copiada a ${dest}`);
+  if (reescritos) info(`${reescritos} documento(s) con capturas: los links apuntan al sitio publicado.`);
+}
+
+// Los .md de un árbol, para la reescritura de links de cmdDocs.
+function walkMd(dir, out = []) {
+  for (const name of readdirSync(dir)) {
+    const p = join(dir, name);
+    if (statSync(p).isDirectory()) walkMd(p, out);
+    else if (name.endsWith(".md")) out.push(p);
+  }
+  return out;
 }
 
 // ── archive: funde los delta specs del change en los specs canónicos y lo archiva ─
@@ -1845,6 +1937,10 @@ switch (cmd) {
       "  archive [<change>] [--skip-specs]   funde los delta specs del change en las specs canónicas y lo archiva (lo corre el aprobador en la PR)\n" +
       "  pr (alias mr) [--assignee u] [--base b] [--draft] [--yes]   crea TU PR/MR precargada (muestra + confirma)\n" +
       "      [--us <ID>] [--title t]  la US la resuelve la branch; si hay varias, pregunta (sin TTY, falla)\n" +
+      "      --description <texto>    QUÉ resuelve la PR y por qué → sección 'Descripción' (o --description-file <f>)\n" +
+      "      --changes <texto>        detalle de 'Cambios realizados' (default: los commits) (o --changes-file <f>)\n" +
+      "                               sin descripción y sin commits, con --yes o sin TTY, dai NO publica: la PR\n" +
+      "                               saldría con el molde del template y no se podría revisar\n" +
       "  forge comment <ref> --body-file <f> · forge pr <ref>   comentar/leer una PR ajena (github/gitlab)\n" +
       "  forge review <ref> --from <review.json> [--dry-run|--yes]  review inline: resumen + comentario por línea\n" +
       "      --min-severity low|medium|high · --min-confidence 0..1 · --max-comments N · --base <branch>\n" +

package/cli/lib/bootstrap.mjs

@@ -277,6 +277,7 @@ export function constitution(kind) {
 - **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.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.
+- **La PR la escribe quien la crea:** \`dai pr\` precarga la US, el estado del check, los commits y los links, pero **la Descripción la escribes tú**: \`dai pr --description "qué resuelve y por qué"\` (o \`--description-file <archivo.md>\` para markdown multilínea, y \`--changes\` si los commits no cuentan bien la historia). dai **no inventa** el propósito de un cambio: si la Descripción o los Cambios realizados quedarían con el molde del template, no publica la PR. Una PR sin descripción no se puede revisar.
 - **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.
 - Separa el QUÉ (funcional) del CÓMO (técnico); no mezcles.
@@ -293,7 +294,7 @@ export function constitution(kind) {
 
 - **Skills (el QUÉ):** \`doc-to-backlog\` (un doc → backlog) · \`grill-intent\` (Gate 0) · \`grill-epic\` (épicas) · \`grill-user-story\` (la US)
 - **Skills (el CÓMO):** \`link-us\`, \`tdd\`, \`dai-review\`
-- **CLI:** \`dai link-us <ID>\` · \`dai check\` · \`dai stamp\` · \`dai pr\` · \`dai ls\`
+- **CLI:** \`dai link-us <ID>\` · \`dai check\` · \`dai stamp\` · \`dai pr --description "…"\` · \`dai ls\`
 - **Formatos:** \`.dai/templates/\` · **Governance:** \`.dai/governance/\`
 
 Detalle completo de la metodología: ${REPO_URL}

package/cli/lib/docs-links.mjs

@@ -0,0 +1,23 @@
+// dai · reescribir los links absolutos del sitio cuando la doc se copia afuera.
+//
+// Los .md de docs/ son la fuente del sitio (VitePress, `base: "/dai/docs/"`), así que las
+// capturas se referencian con la ruta absoluta del sitio: `![…](/tutoriales/x.png)`, que
+// VitePress resuelve contra docs/public/. Fuera del sitio esa ruta no resuelve a nada: en
+// una copia hecha con `dai docs`, `/tutoriales/x.png` apunta a la raíz del filesystem (o
+// del repo, si lo renderiza GitHub). O sea que la imagen ya estaba rota en la copia,
+// tuviera o no el paquete los 2.9 MB de PNG adentro (issue #37).
+//
+// Al copiar, esos links se vuelven absolutos contra el sitio publicado: la doc copiada
+// muestra las capturas, y el paquete de npm no las carga.
+
+export const SITE_DOCS = "https://dforce2055.github.io/dai/docs";
+
+// Rutas absolutas del sitio que aparecen en los .md. Se listan a propósito en vez de
+// reescribir toda `](/…)`: un link a `/etc/hosts` en un ejemplo no es un link del sitio.
+const SITE_PATHS = /\]\(\/(tutoriales\/[^)\s]+)\)/g;
+
+// Devuelve el markdown con los links del sitio apuntando al sitio publicado.
+// Idempotente: una URL ya absoluta no matchea (el patrón exige `](/`).
+export function absolutizeSiteLinks(md) {
+  return String(md).replace(SITE_PATHS, (_, path) => `](${SITE_DOCS}/${path})`);
+}

package/cli/lib/pm-adapter.mjs

@@ -21,19 +21,36 @@
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
-import { parseUS, renderCoverage } from "./us.mjs";
+import { parseUS, renderCoverage, explainFetchError } from "./us.mjs";
 import { slugify } from "./link-us.mjs";
 import { jiraAdapter } from "./pm-jira.mjs";
 import { clickupAdapter } from "./pm-clickup.mjs";
 
 // Re-export para compatibilidad (tests y CLI importan estos desde acá).
-export { parseUS, coverageStatus, statusLabel, renderCoverage } from "./us.mjs";
+export { parseUS, coverageStatus, statusLabel, renderCoverage, explainFetchError } from "./us.mjs";
+
+// Consulta la US preservando la diferencia entre "no existe" y "no pude preguntar". Los
+// adaptadores ya la hacen —404 → null, cualquier otro error → throw— pero se perdía en cada
+// caller: `dai pr` la borraba con un `.catch(() => null)` y publicaba "sin US" en la PR, y
+// los demás morían con el `fetch failed` pelado de undici. El gate de CI era el único que la
+// respetaba, con su try/catch propio; esto es ese criterio, compartido.
+//
+//   → { us, unreachable, reason }   ·  unreachable: no hubo respuesta, no sabemos nada
+export async function fetchLiveUS(adapter, id) {
+  if (!id) return { us: null, unreachable: false, reason: null };
+  try {
+    return { us: await adapter.fetchUS(id), unreachable: false, reason: null };
+  } catch (e) {
+    return { us: null, unreachable: true, reason: explainFetchError(e, { kind: adapter.kind, endpoint: adapter.endpoint, id }) };
+  }
+}
 
 // ── backend md (local, offline) ───────────────────────────────────────────────
 function mdAdapter(env) {
   const dir = env.DAI_MD_US_DIR || ".dai/us";
   return {
     kind: "md",
+    endpoint: dir,
     fetchUS(id) {
       const p = join(dir, `${id}.md`);
       if (!existsSync(p)) return null;

package/cli/lib/pm-clickup.mjs

@@ -25,6 +25,7 @@ export function clickupAdapter(env) {
   if (!env.DAI_CLICKUP_TOKEN) throw new Error("falta DAI_CLICKUP_TOKEN en el .env.dai (backend clickup).");
   return {
     kind: "clickup",
+    endpoint: "api.clickup.com",
     async fetchUS(id) {
       const res = await fetch(clickupTaskUrl(id), { headers: clickupAuthHeaders(env) });
       if (res.status === 404) return null;

package/cli/lib/pm-jira.mjs

@@ -139,6 +139,7 @@ export function jiraAdapter(env) {
   if (!base) throw new Error("falta DAI_JIRA_BASE_URL en el .env.dai (backend jira).");
   return {
     kind: "jira",
+    endpoint: trim(base),
     async fetchUS(id) {
       const res = await daiFetch(jiraIssueUrl(base, id), { headers: jiraAuthHeaders(env) });
       if (res.status === 404) return null;

package/cli/lib/pr.mjs

@@ -2,50 +2,150 @@
 // Parte pura y testeable: rellena el template con los datos del link + git + check.
 // Los efectos (git push, gh/glab create) viven en dai.mjs.
 
-const EMOJI = { "al-dia": "✅ al día", atrasado: "⚠️ atrasado", "sin-us": "❓ sin US" };
+// Más explícito que el label del CLI a propósito: esto queda PUBLICADO en la PR, donde
+// quien lee no tiene el contexto de la corrida que la creó.
+const EMOJI = {
+  "al-dia": "✅ al día", atrasado: "⚠️ atrasado", "sin-us": "❓ sin US",
+  "sin-respuesta": "⚠️ no verificado (el tracker no respondió)",
+};
 
-// Reemplaza el cuerpo de una sección (## Heading … hasta el próximo ## o el final)
-// por content. Tolerante: si no encuentra la sección, devuelve el body igual.
-// Sin flag `m`: `$` = fin de string (no fin de línea), así no corta antes de tiempo.
+// Las secciones que dai se compromete a entregar llenas. Si alguna sale con el molde
+// del template, la PR se publica vacía y el review no tiene qué mirar (era el bug:
+// "Descripción" con el comentario HTML y "Cambios realizados" con `Cambio 1/Cambio 2`).
+// `dai pr` las verifica con bodyGaps() antes de publicar.
+export const OWNED_SECTIONS = ["Descripción", "Cambios realizados"];
+
+// ── Secciones ────────────────────────────────────────────────────────────────
+// Normaliza un heading para compararlo: sin acentos, sin emoji ni puntuación, minúscula.
+// Un repo puede traer su propio template ("## 📝 Descripción del cambio") y dai igual
+// tiene que reconocer la sección: con el match exacto de antes no la encontraba y
+// devolvía el body intacto EN SILENCIO, que es la forma más cara de fallar.
+const norm = (s) => String(s).normalize("NFD").replace(/[\u0300-\u036f]/gu, "")
+  .replace(/[^\p{L}\p{N}]+/gu, " ").trim().toLowerCase();
+
+// Ubica una sección markdown (## Heading … hasta el próximo heading de igual o menor
+// nivel). Ignora lo que esté dentro de un bloque de código: un `## ` en un fence es
+// texto, no estructura. Devuelve null si no está.
+function findSection(lines, heading) {
+  const want = norm(heading);
+  let start = -1, level = 0, fence = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^\s*(```|~~~)/.test(lines[i])) { fence = !fence; continue; }
+    if (fence) continue;
+    const m = /^(#{2,6})[ \t]+(.+?)[ \t]*$/.exec(lines[i]);
+    if (!m) continue;
+    if (start === -1) { if (norm(m[2]).startsWith(want)) { start = i; level = m[1].length; } }
+    else if (m[1].length <= level) return { start, end: i, level };
+  }
+  return start === -1 ? null : { start, end: lines.length, level };
+}
+
+// El cuerpo crudo de una sección, o null si la sección no existe.
+export function sectionBody(body, heading) {
+  const lines = body.split("\n");
+  const at = findSection(lines, heading);
+  return at ? lines.slice(at.start + 1, at.end).join("\n") : null;
+}
+
+// Reemplaza el cuerpo de una sección por content. Tolerante: si no encuentra la
+// sección, devuelve el body igual (para eso está upsertSection).
 export function replaceSection(body, heading, content) {
-  const esc = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const re = new RegExp(`(^|\\n)(##[ \\t]*${esc}[ \\t]*\\n)([\\s\\S]*?)(\\n##\\s|$)`, "i");
-  if (!re.test(body)) return body;
-  return body.replace(re, (m, pre, h, _b, tail) => `${pre}${h}\n${content}\n${tail}`);
+  const lines = body.split("\n");
+  const at = findSection(lines, heading);
+  if (!at) return body;
+  return [...lines.slice(0, at.start + 1), "", content, "", ...lines.slice(at.end)].join("\n");
+}
+
+// Como replaceSection, pero si la sección no está la agrega al final con su heading.
+// Misma disciplina que el bloque de enlaces: dai siempre entrega el dato, nunca lo
+// pierde porque el template del repo no tenía dónde ponerlo. content null = no sé
+// nada → no toco (y bodyGaps lo va a reportar; dai no inventa contenido).
+export function upsertSection(body, heading, content) {
+  if (content == null || !String(content).trim()) return body;
+  if (findSection(body.split("\n"), heading)) return replaceSection(body, heading, content);
+  return `${body.replace(/\s*$/, "")}\n\n## ${heading}\n\n${content}\n`;
+}
+
+// ── Detección del molde sin llenar ───────────────────────────────────────────
+// Moldes conocidos del template: líneas que no dicen nada sobre ESTE cambio.
+const MOCK_LINES = [/^-?\s*\[[ x]\]\s*cambio\s*\d+\s*$/i, /^cambio\s*\d+\s*$/i, /^-?\s*\[[ x]\]\s*$/];
+
+// ¿El cuerpo de una sección es puro molde? Los comentarios HTML no cuentan como
+// contenido: no se renderizan, así que en la PR publicada la sección se ve VACÍA
+// (por eso el bug pasaba desapercibido hasta que alguien abría la PR).
+export function isPlaceholder(text) {
+  const lines = String(text ?? "").replace(/<!--[\s\S]*?-->/g, "").split("\n").map((l) => l.trim()).filter(Boolean);
+  if (!lines.length) return true;
+  return lines.every((l) => MOCK_LINES.some((re) => re.test(l)));
 }
 
-// Rellena el template del PR con los datos precargados. Tolerante: reemplaza los
-// placeholders que encuentra y deja el resto para que el humano lo edite.
+// Qué le falta al body para ser revisable. Vacío = la PR se puede publicar.
+// `dai pr` lo usa como gate: sin TTY (el camino del agente) falla en vez de publicar
+// una PR que nadie puede revisar.
+export function bodyGaps(body) {
+  const gaps = OWNED_SECTIONS.filter((h) => {
+    const s = sectionBody(body, h);
+    return s === null || isPlaceholder(s);
+  });
+  // Placeholders de la cabecera: la PR saldría diciendo `ABC-###` (issues #31/#33).
+  if (/ABC-###|`<hash>`|@ `vX`/.test(body)) gaps.push("🔗 Implementa");
+  return gaps;
+}
+
+// ── Composición ──────────────────────────────────────────────────────────────
+// Descripción: lo que escribió quien crea la PR (agente o dev) gana; si no, se deriva
+// de la US. Si dai no sabe nada, devuelve null: no inventa el propósito de un cambio.
+export function descriptionFor(d) {
+  const explicit = String(d.description ?? "").trim();
+  if (explicit) return explicit;
+  if (d.usTitle) return `Implementa la US **${d.usTitle}** (\`${d.id}\`). Ver los criterios de aceptación en el tracker.`;
+  return null;
+}
+
+// Cambios realizados: el detalle explícito gana; si no, los commits de la branch
+// (como `gh pr create --fill`). Sin ninguno de los dos, null.
+export function changesFor(d) {
+  const explicit = String(d.changes ?? "").trim();
+  if (explicit) return explicit;
+  if (d.commits && d.commits.length) return d.commits.map((c) => `- [x] ${c}`).join("\n");
+  return null;
+}
+
+// Rellena el template del PR con los datos precargados. Tolerante con el resto del
+// template (checklists, secciones propias del repo): dai suma, no borra.
 export function composePrBody(template, d) {
-  let b = template;
-  if (!d.id) return composePrBodyNoUs(b, d);
-  b = b.replace(/`ABC-###`/g, `\`${d.id}\``);
-  b = b.replace(/@ `vX`/g, `@ \`${d.version}\``);
-  b = b.replace(/`<hash>`/g, `\`${d.ac_hash}\``);
-  b = b.replace(/verificado con `dai check` ✅/g, `verificado con \`dai check\`: ${EMOJI[d.status] || d.status}`);
-
-  // Descripción: default desde la US (el humano lo pule).
-  if (d.usTitle) b = replaceSection(b, "Descripción", `Implementa la US **${d.usTitle}** (\`${d.id}\`). Ver los criterios de aceptación en el tracker.`);
-  // Cambios realizados: de los commits de la branch (como gh pr create --fill).
-  if (d.commits && d.commits.length) {
-    b = replaceSection(b, "Cambios realizados", d.commits.map((c) => `- [x] ${c}`).join("\n"));
-  }
+  let b = d.id ? fillUsHeader(template, d) : fillNoUsHeader(template, d);
+  b = upsertSection(b, "Descripción", descriptionFor(d));
+  b = upsertSection(b, "Cambios realizados", changesFor(d));
   return upsertLinksBlock(b, d);
 }
 
+// Los placeholders se rellenan DENTRO de la sección, no en todo el body: la misma frase
+// ("verificado con `dai check` ✅") aparecía en la prosa que explica el método, así que un
+// replace global le metía el estado de ESTA PR a una oración general y quedaba
+// "verificado con dai check: ✅ al día. Sin esto, el código no sabe…". dai reescribiendo
+// la prosa de otro es justo lo que el bloque de links ya evitaba con sus marcadores.
+// Sin la sección (un template ajeno con otra forma) se cae al body entero: rellenar de más
+// es recuperable, no rellenar deja la PR con `ABC-###` publicado.
+function fillUsHeader(template, d) {
+  const fill = (t) => t
+    .replace(/`ABC-###`/g, `\`${d.id}\``)
+    .replace(/@ `vX`/g, `@ \`${d.version}\``)
+    .replace(/`<hash>`/g, `\`${d.ac_hash}\``)
+    .replace(/verificado con `dai check` ✅/g, `verificado con \`dai check\`: ${EMOJI[d.status] || d.status}`);
+  const sec = sectionBody(template, "🔗 Implementa");
+  return sec == null ? fill(template) : replaceSection(template, "🔗 Implementa", fill(sec).trim());
+}
+
 // PR de una branch exenta (chore/, docs/, release/…): no implementa una US y no se le
 // exige link. Lo que NO puede pasar es que salga con la US de otro ni con el placeholder
 // `ABC-###` del template — las dos cosas pasaron en repos reales (issues #31, #33).
 // Se dice explícitamente que no hay US, y por qué.
-function composePrBodyNoUs(template, d) {
-  let b = replaceSection(template, "🔗 Implementa",
+function fillNoUsHeader(template, d) {
+  return replaceSection(template, "🔗 Implementa",
     `- **Sin US:** esta PR no implementa una User Story.\n` +
     (d.noUsReason ? `- **Motivo:** ${d.noUsReason}.\n` : "") +
     `- No se le exige link (\`governance/branch-naming.md\`).`);
-  if (d.commits && d.commits.length) {
-    b = replaceSection(b, "Cambios realizados", d.commits.map((c) => `- [x] ${c}`).join("\n"));
-  }
-  return upsertLinksBlock(b, d);
 }
 
 // ── Bloque de enlaces ────────────────────────────────────────────────────────

package/cli/lib/us.mjs

@@ -12,12 +12,22 @@ export function parseUS(raw) {
 }
 
 // Compara el hash estampado (implements.yaml) con el hash vivo de la US.
-export function coverageStatus(stampedHash, liveHash) {
+//
+// `sin-us` y `sin-respuesta` NO son lo mismo, y confundirlos es caro: el primero es una
+// RESPUESTA del tracker (preguntamos y la US no está), el segundo es la AUSENCIA de
+// respuesta (sin red, sin token, 5xx, certificado corporativo). Colapsados en un mismo
+// `null`, dai terminaba AFIRMANDO que no había US cuando lo único cierto era que no había
+// podido preguntar — y eso se publicaba en el cuerpo de una PR, al lado del id de la US.
+export function coverageStatus(stampedHash, liveHash, { unreachable = false } = {}) {
+  if (unreachable) return "sin-respuesta";
   if (liveHash == null) return "sin-us";
   return stampedHash === liveHash ? "al-dia" : "atrasado";
 }
 
-const STATUS_LABEL = { "al-dia": "✅ al día", atrasado: "⚠️ atrasado", "sin-us": "❓ sin US" };
+const STATUS_LABEL = {
+  "al-dia": "✅ al día", atrasado: "⚠️ atrasado",
+  "sin-us": "❓ sin US", "sin-respuesta": "⚠️ no verificado",
+};
 export const statusLabel = (s) => STATUS_LABEL[s] || s;
 
 // Render de la cobertura como markdown (lo que un backend "estampa").
@@ -34,3 +44,25 @@ export function renderCoverage(id, r) {
   if (r.commitUrl) lines.push(`- commit: ${r.commit} → ${r.commitUrl}  (ancla durable)`);
   return lines.join("\n") + "\n";
 }
+
+// `fetch failed` es TODO lo que dice undici cuando no hay red, el host no resuelve, el DNS
+// se cayó o el certificado no valida. Sin contexto es indistinguible de un bug de dai: el
+// dev lee "dai: fetch failed" y no sabe ni qué se estaba consultando. Es el mismo modo de
+// falla que el push por SSH de la 0.13.1 — el dato que resuelve el problema existe, y no
+// llega. Acá se le pone alrededor qué, contra qué, y qué mirar.
+export function explainFetchError(err, { kind, endpoint, id } = {}) {
+  const raw = String(err?.message ?? err ?? "").split("\n")[0] || "error desconocido";
+  const donde = [kind, endpoint].filter(Boolean).join(" · ");
+  const cabeza = `no pude consultar ${id ? `la US ${id}` : "el tracker"}${donde ? ` en ${donde}` : ""}: ${raw}`;
+  if (/fetch failed|ENOTFOUND|ECONNREFUSED|EAI_AGAIN|ETIMEDOUT|ECONNRESET|certificate|self.signed/i.test(raw)) {
+    return `${cabeza}\n  No llegó a haber respuesta. Revisá la red y el host del backend; si estás detrás de un\n` +
+           `  proxy corporativo, declará la CA con NODE_EXTRA_CA_CERTS (nunca NODE_TLS_REJECT_UNAUTHORIZED=0).\n` +
+           `  Diagnóstico:  dai doctor`;
+  }
+  if (/\b40[13]\b|unauthorized|forbidden/i.test(raw)) {
+    return `${cabeza}\n  El tracker rechazó las credenciales: revisá el token del .env.dai (¿venció?) y sus permisos.\n` +
+           `  Diagnóstico:  dai doctor`;
+  }
+  if (/\b5\d\d\b/.test(raw)) return `${cabeza}\n  El error es del tracker, no tuyo: probá de nuevo en un rato.`;
+  return cabeza;
+}

package/docs/EJEMPLO-END-TO-END.md

@@ -239,7 +239,9 @@ código + spec trazable) — y la asigna a un partner:
 ```
 $ dai check
 ✅ ABC-482 al día (v1)
-$ dai pr --assignee mgomez
+$ dai pr --assignee mgomez \
+    --description "Permite comprar sin crear cuenta: el checkout acepta un email de
+                   contacto y genera la orden como invitado. Baja el abandono del paso 2."
 ✓ PR #123 creada → …/pull/123   (base: main · US: ABC-482 @ v1 · dai check ✅)
 ```
 

package/docs/guias/dev.md

@@ -35,8 +35,11 @@
    (anti vibe-coding). Ajustas y **commiteas** lo que haga falta.
 6. **Creas la PR** → con el smoke verde y **todo commiteado** (lo que quede sin commitear
    **no entra** en la PR), corres `dai check` (gate: ¿al día con la US?) y en verde `dai pr`
-   arma la PR **precargada** (US + estado del check + links; los **dos activos**: código +
-   spec trazable) y la asignas a un partner.
+   arma la PR **precargada** (US + estado del check + commits + links; los **dos activos**:
+   código + spec trazable) y la asignas a un partner. **La descripción la escribes tú**
+   (`--description "…"`, o `--description-file notas.md`): dai llena lo que puede derivar,
+   pero no inventa el propósito de un cambio — y si esa sección quedaría con el molde del
+   template, **no publica la PR**. Una PR sin descripción no se puede revisar.
 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: un **review inline**
    (resumen + un comentario por línea), que le muestra el preview y espera su OK antes de postear.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforce2055/dai",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "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/",
@@ -27,6 +27,7 @@
     "cli/dai.mjs",
     "cli/lib",
     "docs",
+    "!docs/public/tutoriales",
     "templates",
     "governance",
     "skills",

package/templates/pull-request.md

@@ -5,26 +5,39 @@
   Lo puede pre-llenar `dai`/una skill a partir del implements.yaml y el diff.
 -->
 
-> **Un PR en dai entrega dos activos, y el review cubre los dos:**
-> 1. **La implementación** — el código que resuelve la US.
-> 2. **El spec trazable** — el `implements.yaml` con el link a la US y el `@version`
->    (`ac_hash`) verificado con `dai check` ✅. Sin esto, el código no sabe *a qué QUÉ*
->    responde, y el CI bloquea el PR (ver `governance/ci-rules.md`).
-
 ## 🔗 Implementa
 
 - **US:** `ABC-###` @ `vX`  ·  ac_hash: `<hash>`  ·  verificado con `dai check` ✅
-- **Link:** este PR está atado a la US vía `implements.yaml`.
 
-> Si este PR no implementa una US (chore/fix sin ticket), borra esta sección y
-> aclara el motivo — no se le exige link.
+<!--
+  Un PR en dai entrega DOS activos, y el review cubre los dos: la implementación (el código
+  que resuelve la US) y el spec trazable (el `implements.yaml` con el link a la US y el
+  `@version`/`ac_hash` verificado). Sin el link, el código no sabe a qué QUÉ responde y el
+  CI bloquea el PR — ver `governance/ci-rules.md`.
+
+  ¿Chore o fix sin ticket? No hay nada que borrar: `dai pr` lo detecta por el nombre de la
+  branch y escribe "Sin US" con el motivo. No se le exige link.
+
+  Esto es un comentario a propósito: es doctrina del método, igual en las 500 PRs del repo.
+  Repetirla a la vista en cada una entrena a saltear el principio del cuerpo, que es
+  justamente donde va la descripción.
+-->
 
 ## Descripción
 
-<!-- Breve propósito de este PR, en términos de negocio (2–4 líneas). -->
+<!--
+  Breve propósito de este PR, en términos de negocio (2–4 líneas).
+  Lo precarga `dai pr --description "…"` (o `--description-file <archivo.md>`).
+  dai NO lo inventa: si esta sección queda sin llenar, `dai pr` no publica la PR.
+-->
 
 ## Cambios realizados
 
+<!--
+  Lo precarga `dai pr` con los commits de la branch; `--changes` / `--changes-file`
+  lo reemplazan por el detalle que quieras contar.
+-->
+
 - [ ] Cambio 1
 - [ ] Cambio 2