@tacuchi/agent-workflow-cli 15.2.0 → 16.0.0

package/skills/w/commands/spec-refine.md

@@ -1,5 +1,5 @@
 ---
-description: Inicia o retoma el loop de refinamiento de una especificación (spec-refine-loop). Input: docs/specs/NNN-spec-<slug>.md (borrador — de spec-new, a mano, o materializado por la escalación de quick). Actualiza docs/specs/NNN-spec-<slug>.md in place.
+description: Starts or resumes the specification refinement loop (spec-refine-loop). Input: docs/specs/NNN-spec-<slug>.md (a draft — from spec-new, hand-written, or materialized by the quick escalation). Updates docs/specs/NNN-spec-<slug>.md in place.
 argument-hint: <docs/specs/NNN-spec-<slug>.md>
 allowed-tools:
   [
@@ -10,33 +10,33 @@ allowed-tools:
   ]
 ---
 
-# spec-refine — trampolín al loop de refinamiento
+# spec-refine — trampoline to the refinement loop
 
-Este comando no refina el spec él mismo: delega al loop `spec-refine-loop` (Layer 2), que es quien itera, cierra gaps y produce el spec refinado.
+This command does not refine the spec itself: it delegates to `spec-refine-loop` (Layer 2), which iterates, closes gaps and produces the refined spec.
 
-## Ejecutar el loop
+## Run the loop
 
-`spec-refine-loop` **no** es una skill invocable por nombre — es el manual de operación de este comando (un doc hermano del bundle). **Cargalo y ejecutalo de punta a punta**:
+`spec-refine-loop` is **not** a skill invocable by name — it is this command's operating manual (a sibling doc in the bundle). **Load it and execute it end to end**:
 
-1. **Leé** `../loops/spec-refine-loop/SKILL.md` (dentro de la skill `w` instalada — p. ej. `~/.claude/skills/w/loops/…`).
-2. **Seguí** sus instrucciones tomando `$ARGUMENTS` como input: detecta estado/resume, corre el motor gap-driven, crea y maneja sessions, converge y reporta.
+1. **Read** `../loops/spec-refine-loop/SKILL.md` (inside the installed `w` skill — e.g. `~/.claude/skills/w/loops/…`).
+2. **Follow** its instructions taking `$ARGUMENTS` as input: it detects state/resume, runs the gap-driven engine, creates and manages sessions, converges and reports.
 
-> No intentes `Skill: spec-refine-loop` — no está registrada como skill. El comando **es** la entrada; el loop es su cuerpo.
+> Do not try `Skill: spec-refine-loop` — it is not registered as a skill. The command **is** the entry; the loop is its body.
 
-## Resolución de estado (resumable)
+## State resolution (resumable)
 
-El skill detecta el estado previo antes de arrancar, **keyando off el `CHECKPOINT`** (no la existencia de un archivo "refined"):
+The skill detects prior state before starting, **keying off the `CHECKPOINT`** (never the existence of a "refined" file):
 
-1. Busca la sesión de refinamiento del spec en `.workflow/sessions/` y su `CHECKPOINT.md`.
-2. **En curso** (existe CHECKPOINT) → continúa desde el avance previo (gaps resueltos, Q&A).
-3. **Sin avance** (sin CHECKPOINT y el spec **no** tiene `## Refinement decisions`/`## Q&A traceability`) → arranca desde cero leyendo el spec (`NNN-spec*.md`).
-4. **Ya refinado / re-refine a demanda** (sin CHECKPOINT abierto pero el spec **ya tiene** `## Refinement decisions`/`## Q&A traceability`) → **soportado de primera clase**: mientras el flujo siga en SPEC podés re-correr este comando sobre el mismo spec **las veces que haga falta** (nuevos requerimientos, cambios de scope, re-lectura). El loop hace `create_or_resume` — localiza la refine session existente (aunque esté cerrada) y la **reabre** en vez de duplicarla — y re-refina leyendo el **spec mismo**; al `Guardar`, edita in place con confirmación.
+1. Find the spec's refinement session under `.workflow/sessions/` and its `CHECKPOINT.md`.
+2. **In progress** (a CHECKPOINT exists) → continue from the recorded progress (resolved gaps, Q&A).
+3. **No progress** (no CHECKPOINT and the spec does **not** have `## Refinement decisions`/`## Q&A traceability`) → start from zero reading the spec (`NNN-spec*.md`).
+4. **Already refined / re-refine on demand** (no open CHECKPOINT but the spec **already has** the 2 sections) → **first-class operation**: while the flow stays in SPEC you can re-run this command over the same spec **as many times as needed** (new requirements, scope changes, re-reads). The loop does `create_or_resume` — it locates the existing refine session (even closed) and **reopens** it instead of duplicating — and re-refines reading the **spec itself**; on `Guardar`, edits in place with confirmation.
 
-> **Compat (legacy):** el glob `NNN-spec*.md` también captura specs viejos `NNN-spec.md` / `NNN-spec-refined.md`. Re-correr spec-refine los edita in place de ahí en adelante.
+> **Compat (legacy):** the `NNN-spec*.md` glob also catches old `NNN-spec.md` / `NNN-spec-refined.md` specs. Re-running spec-refine edits them in place from then on.
 
 ## Plan mode
 
-El skill resuelve el estado y describe las acciones que ejecutaría el loop (gaps que cerraría, preguntas que haría), sin arrancar la iteración.
+The skill resolves the state and describes the actions the loop would run (gaps it would close, questions it would ask), without starting the iteration.
 
 ## Resources
 

package/skills/w/commands/status.md

@@ -1,6 +1,6 @@
 ---
-description: Dashboard read-only del workspace — qué se hizo / qué falta / qué se descartó, con fechas en español (hace 2 días, ayer en la mañana). Se apoya en `aw status`. Comando transversal (no es un flow); no escribe nada.
-argument-hint: (sin argumentos)
+description: Read-only workspace dashboard — what got done / what is missing / what was discarded, with dates humanized in the user's language. Backed by `aw status`. Transversal command (not a flow); writes nothing.
+argument-hint: (no arguments)
 allowed-tools:
   [
     "Bash",
@@ -8,22 +8,22 @@ allowed-tools:
   ]
 ---
 
-# status — estado del workspace (read-only)
+# status — workspace state (read-only)
 
-Muestra, simple y directo, el estado del workspace agrupado en **Hecho / Falta / Descartó**. Single-pass, read-only: no abre loop, no crea sesiones, no escribe en `docs/` ni en `.workflow/`. Comando **transversal** (no pertenece a ningún flow).
+Shows, simple and direct, the workspace state grouped as **Done / Missing / Discarded**. Single-pass, read-only: no loop, no sessions, writes nothing in `docs/` or `.workflow/`. **Transversal** command (belongs to no flow).
 
-## Ejecutar
+## Run
 
-1. Corré `aw status` (devuelve JSON; se apoya en `status-service`).
-2. Renderizá un resumen legible a partir del JSON — **no** muestres el JSON crudo. Usá el campo `relative` tal cual (ya viene humanizado en español). Encabezá con `workspace.name`.
-3. Agrupá en tres bloques:
-   - **▸ HECHO** — specs con `refined: true`; plans con su progreso (`tasks_done`/`tasks_total`, `progress_pct`); sesiones `closed`.
-   - **▸ FALTA** — sesiones `active`; plans con tareas pendientes (`tasks_total − tasks_done`); specs con `open_questions > 0`.
-   - **▸ DESCARTÓ** — cada item de `discarded[]` (`kind: deferred` = diferido en BACKLOG; `kind: excluded` = excluido en CHECKPOINT), con su `text`.
-4. Cada línea termina con su fecha relativa tras ` · ` (ej. `· ayer en la mañana`). Si una sección queda vacía, mostrá `— (nada)`. No inventes datos que no estén en el JSON.
-5. Si `workspace.initialized` es `false` y todo está vacío → decí "No es un workspace de agent-workflow (no hay `.workflow/`)" y sugerí `/w:workspace-init`.
+1. Run `aw status` (returns JSON; backed by `status-service`).
+2. Render a readable summary from the JSON — do **not** show the raw JSON. Use the `relative` field verbatim (it comes pre-humanized in the user's language — Spanish). Head it with `workspace.name`.
+3. Group into three blocks (the dashboard is user-facing → render it in the user's language; the canonical Spanish labels below):
+   - `▸ HECHO` — specs with `refined: true`; plans with their progress (`tasks_done`/`tasks_total`, `progress_pct`); `closed` sessions.
+   - `▸ FALTA` — `active` sessions; plans with pending tasks (`tasks_total − tasks_done`); specs with `open_questions > 0`.
+   - `▸ DESCARTÓ` — every item in `discarded[]` (`kind: deferred` = deferred in BACKLOG; `kind: excluded` = excluded in CHECKPOINT), with its `text`.
+4. Every line ends with its relative date after ` · ` (e.g. `· ayer en la mañana`). An empty section shows `— (nada)`. Never invent data not present in the JSON.
+5. If `workspace.initialized` is `false` and everything is empty → say the folder is not an agent-workflow workspace (no `.workflow/`) and suggest `/w:workspace-init`.
 
-Formato sugerido (texto plano):
+Suggested format (plain text; user-facing labels in Spanish):
 
 ```
 Workspace: <name>
@@ -43,8 +43,10 @@ Workspace: <name>
 ```
 
 ## Plan mode
-Igual que en ejecución: corré `aw status` (read-only) y mostrá el resumen. No hay cambios que aplicar.
+
+Same as execution: run `aw status` (read-only) and show the summary. There are no changes to apply.
 
 ## Resources
-- CLI: `aw status` (servicio `status-service`; fechas vía `humanize-es`)
+
+- CLI: `aw status` (service `status-service`; dates via `humanize-es`)
 - Design reference: `docs/referencias/workflow-skills/status.md`

package/skills/w/commands/workspace-init.md

@@ -1,6 +1,6 @@
 ---
-description: Convierte la carpeta actual en un workspace de agent-workflow (scaffolding .workflow/ + docs/ + WORKSPACE block + skills.toml). Reemplaza hub-init + project-init — sin distinción project/hub. Correr una vez antes de cualquier flujo; idempotente.
-argument-hint: --source alias:path[:rama] [--proyecto <nombre>] [--main-branch <rama>] [--dry-run]
+description: Turns the current folder into an agent-workflow workspace (scaffolding .workflow/ + docs/ + WORKSPACE block + skills.toml). Replaces hub-init + project-init — no project/hub distinction. Run once before any flow; idempotent.
+argument-hint: --source alias:path[:branch] [--proyecto <name>] [--main-branch <branch>] [--dry-run]
 allowed-tools:
   [
     "Bash",
@@ -10,30 +10,30 @@ allowed-tools:
   ]
 ---
 
-# workspace-init — bootstrap del workspace
+# workspace-init — workspace bootstrap
 
-Corre `aw workspace-init` para convertir la carpeta actual en un workspace de agent-workflow. Un workspace tiene **1+ fuentes** (repos); "standalone" = una sola fuente. No hay modos project/hub — el modelo es unificado.
+Runs `aw workspace-init` to turn the current folder into an agent-workflow workspace. A workspace has **1+ sources** (repos); "standalone" = a single source. There are no project/hub modes — the model is unified.
 
 ```bash
-aw workspace-init --source alias:path[:rama] [--proyecto <nombre>] [--main-branch <rama>] [--dry-run]
+aw workspace-init --source alias:path[:branch] [--proyecto <name>] [--main-branch <branch>] [--dry-run]
 ```
 
-## Pasos interactivos
+## Interactive steps
 
-1. **Detectar/confirmar fuentes** — el CLI detecta la/s ruta/s de repo; el usuario confirma aliases, paths y ramas. Se acepta `--source` múltiple.
-2. **Elegir skills por defecto** — se presenta el catálogo de capacidades (roles) disponibles. Para cada rol: `built-in default`, override a skill de tercero (`skills.sh`), o `off`. Resultado escrito en `.workflow/skills.toml`. La cascada de config es: `built-in → ~/.workflow/skills.toml (global) → .workflow/skills.toml (workspace)`.
-3. **Escribir scaffolding** — crea `.workflow/sessions/`, `docs/` con su taxonomía (`specs/`, `plans/`, `scripts/`, `manuals/`, `diagrams/`, `reports/`), el bloque `WORKSPACE` en `CLAUDE.md`/`AGENTS.md` (fuentes + metadatos), y `.workflow/skills.toml`.
-4. **Multi-fuente** — si hay ≥2 fuentes, configura visibilidad multi-root (settings.local.json + config, gitignored) y reconcilia fuentes.
+1. **Detect/confirm sources** — the CLI detects the repo path(s); the user confirms aliases, paths and branches. Multiple `--source` accepted.
+2. **Pick default skills** — the catalog of available capabilities (roles) is presented. Per role: `built-in default`, override to a third-party skill (`skills.sh`), or `off`. The result is written to `.workflow/skills.toml`. Config cascade: `built-in → ~/.workflow/skills.toml (global) → .workflow/skills.toml (workspace)`.
+3. **Write the scaffolding** — creates `.workflow/sessions/`, `docs/` with its taxonomy (`specs/`, `plans/`, `scripts/`, `manuals/`, `diagrams/`, `reports/`), the `WORKSPACE` block in CLAUDE.md/AGENTS.md (sources + metadata), and `.workflow/skills.toml`.
+4. **Multi-source** — with ≥2 sources, configures multi-root visibility (settings.local.json + config, gitignored) and reconciles sources.
 
-Al terminar, el usuario puede correr `/w:spec-new`, `/w:plan-new` o `/w:quick` directamente.
+When done, the user can run `/w:spec-new`, `/w:plan-new` or `/w:quick` directly.
 
-**Idempotente**: re-ejecutar reconcilia (no duplica entradas ni sobrescribe configuración manual).
+**Idempotent**: re-running reconciles (no duplicate entries, no overwriting manual configuration).
 
 ## Plan mode
 
-Resuelve las fuentes y describe el scaffolding que crearía, sin escribir archivos. Muestra qué crearía en `.workflow/` y `docs/`, y qué escribiría en `CLAUDE.md`.
+Resolves the sources and describes the scaffolding it would create, without writing files. Shows what it would create under `.workflow/` and `docs/`, and what it would write into CLAUDE.md.
 
 ## Resources
 
 - Design reference: `docs/referencias/workflow-commands/workspace-init.md`
-- Skills config: `docs/referencias/workflow-roles/` (capacidades/roles disponibles y cascada de binding)
+- Skills config: `docs/referencias/workflow-roles/` (available capabilities/roles and the binding cascade)

package/skills/w/exports/README.md

@@ -25,9 +25,9 @@
 | Export | Composes | Reads (artifacts / sessions + corpus) | Writes (its ONLY category) |
 |---|---|---|---|
 | [`export-scripts`](export-scripts/SKILL.md) | `sql` | type-B `SCRIPTS.sql` (DDL/DML migrations) across N sessions + standalone `docs/scripts/*.sql` | `docs/scripts/NNN-export-scripts-<date>/` (numbered forwards + `00-ROLLBACK.sql`) |
-| [`export-manuals`](export-manuals/SKILL.md) | — (prosa: convenciones ambientes) | sessions + `DECISION` + plan-doc (`Solution`, `Final behavior`, `Validations`) + touched code | `docs/manuals/` |
+| [`export-manuals`](export-manuals/SKILL.md) | — (prose: ambient conventions) | sessions + `DECISION` + plan-doc (`Solution`, `Final behavior`, `Validations`) + touched code | `docs/manuals/` |
 | [`export-diagrams`](export-diagrams/SKILL.md) | `diagrams` | source code of the sources + plan-doc (`AS-IS` / `TO-BE`, `Impacted`) | `docs/diagrams/` (C4 / mermaid) |
-| [`export-reports`](export-reports/SKILL.md) | — (prosa: convenciones ambientes) | corpus of sessions (spec, `CONCLUSIONS`, `DECISION`) + plan-doc state + `docs/` | `docs/reports/` (executive / functional report) |
+| [`export-reports`](export-reports/SKILL.md) | — (prose: ambient conventions) | corpus of sessions (spec, `CONCLUSIONS`, `DECISION`) + plan-doc state + `docs/` | `docs/reports/` (executive / functional report) |
 
 > **Composition over ownership:** an export that owns a derived artifact does **not** own its authoring logic — it **composes a capability role** from [`../roles/`](../roles/) (resolved through `.workflow/skills.toml`): `export-scripts` composes `sql`; `export-diagrams` composes `diagrams`. Swapping the implementation is a one-line config change; it never touches the export. `export-manuals` and `export-reports` produce **prose**, which follows **ambient writing conventions** (the host auto-applies an installed writing skill if present) — they do **not** compose or bind a `writing` role.
 
@@ -36,7 +36,7 @@
 1. **Layer 1, explicit** — the **user** invokes them (`/w:export-<cat>`). **Never** automatic (no loop fires them).
 2. **Single-pass, read-only over sessions** — they read artifacts/sessions and `docs/`, **synthesize**, and write **only** their own `docs/<category>/` folder. They do **not** mutate sessions and do **not** open/close loops.
 3. **Cross-session** — they consolidate **N** sessions + the `docs/` corpus (dedup, roadmap, continuous numbering).
-4. **No loop, no internal sessions** — options come from **args** (no *structured-choice* de ciclo de vida — capacidad del arnés; ver [`../harness/SKILL.md`](../harness/SKILL.md)).
+4. **No loop, no internal sessions** — options come from **args** (no lifecycle *structured-choice*; harness capability — see [`../harness/SKILL.md`](../harness/SKILL.md)).
 5. **Git-safe** — they **never** commit, merge, push, `--amend`, or `--no-verify`. The output is a written document the user reviews and commits when ready.
 6. **DB scripts-only** — `export-scripts` ships migration SCRIPTS as a bundle; it **never executes** DDL/DML (a human/DBA applies them).
 
@@ -83,6 +83,6 @@ Exports read the corpus through the CLI — **never hard-coded paths**:
 | Export | File | Category | Composes |
 |---|---|---|---|
 | `export-scripts` | [`export-scripts/SKILL.md`](export-scripts/SKILL.md) | `docs/scripts` | `sql` |
-| `export-manuals` | [`export-manuals/SKILL.md`](export-manuals/SKILL.md) | `docs/manuals` | — (prosa: convenciones ambientes) |
+| `export-manuals` | [`export-manuals/SKILL.md`](export-manuals/SKILL.md) | `docs/manuals` | — (prose: ambient conventions) |
 | `export-diagrams` | [`export-diagrams/SKILL.md`](export-diagrams/SKILL.md) | `docs/diagrams` | `diagrams` |
-| `export-reports` | [`export-reports/SKILL.md`](export-reports/SKILL.md) | `docs/reports` | — (prosa: convenciones ambientes) |
+| `export-reports` | [`export-reports/SKILL.md`](export-reports/SKILL.md) | `docs/reports` | — (prose: ambient conventions) |

package/skills/w/exports/export-diagrams/SKILL.md

@@ -1,125 +1,125 @@
 ---
 name: export-diagrams
-description: "Genera diagramas de arquitectura y flujos del workspace en `docs/diagrams/` consolidando el código de las fuentes + el plan-doc (`Current state (AS-IS)` / `Target state (TO-BE)`, `Impacted`) de N sesiones. Produce contexto, contenedores, componentes, integraciones y modelo de datos (si MCP read-only disponible). Default `mermaid` (renderiza en GitHub, link `mermaid.ink` para preview); `c4`/structurizr opt-in vía `--engine`. Output en `docs/diagrams/NNN-export-diagrams-YYYY-MM-DD/` (o `.md`). Read-only/reporte: emite solo el source del diagrama (el render visual lo hace el lector); no commitea ni muta nada; MCP solo lecturas. Compone la capacidad `diagrams`. Úsalo para 'diagrama del sistema', 'C4 del workspace', 'mapa de arquitectura/flujos'. Invocado por el usuario vía `/w:export-diagrams`."
+description: "Generates the workspace's architecture and flow diagrams in `docs/diagrams/` consolidating the sources' code + the plan-doc (`Current state (AS-IS)` / `Target state (TO-BE)`, `Impacted`) of N sessions. Produces context, containers, components, integrations and data model (when read-only MCP is available). Default `mermaid` (renders on GitHub, `mermaid.ink` link for preview); `c4`/structurizr opt-in via `--engine`. Output in `docs/diagrams/NNN-export-diagrams-YYYY-MM-DD/` (or `.md`). Read-only/report: emits only the diagram source (the reader renders it); never commits nor mutates anything; MCP reads only. Composes the `diagrams` capability. Use for 'system diagram', 'workspace C4', 'architecture/flow map'. User-invoked via `/w:export-diagrams`."
 ---
 
-# export-diagrams — Diagramas de arquitectura y flujos desde código + plan-doc
+# export-diagrams — architecture and flow diagrams from code + plan-doc
 
-Genera un dossier de diagramas (**arquitectura y flujos**) del workspace, agregando la estructura de las fuentes y el delta de las sesiones. **Read-only / reporte** — emite solo el **source** del diagrama (Mermaid / DSL); el render visual lo hace el lector. No commitea, no muta nada; MCP solo lecturas.
+Generates a diagram dossier (**architecture and flows**) of the workspace, aggregating the sources' structure and the sessions' delta. **Read-only / report** — it emits only the diagram **source** (Mermaid / DSL); the reader renders it. It never commits, never mutates anything; MCP reads only.
 
-> Familia `export-*` (la única vía artefacto→`docs/`). Recicla el espíritu del viejo `export-arq` (C4, niveles contexto/contenedores/componentes, integraciones, modelo de datos), reubicado a `docs/diagrams` y modernizado: default `mermaid` (en vez de structurizr), sin modos project/hub, y la generación la aporta la capacidad `diagrams` (no una skill propia). Diseño: `docs/referencias/workflow-exports/export-diagrams.md`.
+> `export-*` family (the only artifact→`docs/` path). Design: `docs/referencias/workflow-exports/export-diagrams.md`.
 
 ## Category
 
-`docs/diagrams` — **única** carpeta `docs/` que este export escribe.
+`docs/diagrams` — the **only** `docs/` folder this export writes.
 
 ## Composes
 
-Capacidad **`diagrams`** (built-in default `diagrams`), resuelta vía `.workflow/skills.toml`. Aporta el motor de render (Mermaid C4 nativo / Structurizr DSL), los niveles C1–C4 y la convención del link de preview. Este export **no** posee esa lógica: la compone. Rebindeable u `off` por config.
+The **`diagrams`** capability (built-in default `diagrams`), resolved via `.workflow/skills.toml`. It contributes the render engine (native Mermaid C4 / Structurizr DSL), the C1–C4 levels and the preview-link convention. This export does **not** own that logic: it composes it. Rebindable or `off` by config.
 
 ## When to use
 
-- "Diagrama del sistema", "C4 del workspace", "mapa de arquitectura".
-- "Diagrama de flujo" entre componentes / integraciones tocadas.
-- Onboarding técnico; antes de cambios estructurales (validar arquitectura vigente); auditoría técnica.
+- "System diagram", "workspace C4", "architecture map".
+- "Flow diagram" across touched components / integrations.
+- Technical onboarding; before structural changes (validate the current architecture); technical audit.
 
 ## What it does
 
-1. Inspecciona el código de las fuentes del workspace (estructura, wiring, integraciones, tecnologías).
-2. Lee de las sesiones el plan-doc: `Current state (AS-IS)` / `Target state (TO-BE)` y `Impacted` (qué cambió y dónde).
-3. (Opcional) Si MCP read-only está disponible y se pide modelo de datos: consulta esquemas BD (solo lectura).
-4. Resuelve el motor (`--engine`) y consolida la arquitectura/flujos tocados por las N sesiones.
-5. Renderiza los diagramas (compone `diagrams`): contexto, contenedores, componentes, integraciones, modelo de datos (si aplica).
-6. Escribe el dossier en `docs/diagrams/NNN-export-diagrams-YYYY-MM-DD/` con un `README.md` (índice + cómo leer).
+1. Inspects the workspace sources' code (structure, wiring, integrations, technologies).
+2. Reads the plan-doc from the sessions: `Current state (AS-IS)` / `Target state (TO-BE)` and `Impacted` (what changed and where).
+3. (Optional) With read-only MCP available and a data-model request: queries DB schemas (reads only).
+4. Resolves the engine (`--engine`) and consolidates the architecture/flows touched by the N sessions.
+5. Renders the diagrams (composes `diagrams`): context, containers, components, integrations, data model (when it applies).
+6. Writes the dossier to `docs/diagrams/NNN-export-diagrams-YYYY-MM-DD/` with a `README.md` (index + how to read).
 
 ## What it does NOT do
 
-- Ejecutar commits, merges, push, ni SQL.
-- Mutar sesiones, el plan-doc ni el código (solo lectura). MCP **solo** lecturas read-only (nunca DML/DDL).
-- Escribir cualquier carpeta `docs/` que no sea `docs/diagrams/` (invariante: una categoría).
-- **Renderizar visualmente** el diagrama: emite solo el source (Mermaid / DSL); el render lo hace el lector con sus herramientas (o el link `mermaid.ink`).
-- Validar que las integraciones funcionen (eso es del doctor) ni inventar componentes ausentes.
-- Sobrescribir dossiers previos (siempre next-number).
+- Run commits, merges, push, or SQL.
+- Mutate sessions, the plan-doc or the code (read-only). MCP **reads only** (never DML/DDL).
+- Write any `docs/` folder other than `docs/diagrams/` (invariant: one category).
+- **Visually render** the diagram: it emits only the source (Mermaid / DSL); the reader renders with their tools (or the `mermaid.ink` link).
+- Validate that the integrations work (that is doctor work) or invent absent components.
+- Overwrite previous dossiers (always next-number).
 
 ## Read-only sandbox
 
-En plan mode **describe**, no escribe: el motor resuelto, los niveles/secciones que aparecerían (resueltos por args), las fuentes a inspeccionar + integraciones detectadas, y — si se pide modelo de datos — las queries MCP propuestas con su costo estimado. **No** ejecuta `Write`, ni mutaciones MCP, ni `aw next-number` con efecto.
+In plan mode it **describes**, never writes: the resolved engine, the levels/sections that would appear (resolved by args), the sources to inspect + detected integrations, and — with a data-model request — the proposed MCP queries with their estimated cost. It does **not** run `Write`, MCP mutations, or effectful `aw next-number`.
 
 ## Inputs
 
-**CLI `agent-workflow` (alias `aw`)** — no leer paths hardcodeados:
+**`agent-workflow` CLI (alias `aw`)** — never read hardcoded paths:
 
-- `aw sessions` / `aw release-data [--since sessionNNN] [--source <alias>]` — enumera el corpus (insumo del delta AS-IS/TO-BE).
-- `aw session-artifacts --code <NNN> --dump objetivo` — ubica la sesión y su referencia al plan-doc; `AS-IS`/`TO-BE`/`Impacted` se leen del plan-doc por su path.
-- `aw next-number docs/diagrams` — numeración determinística (la resolución de la carpeta destino la maneja el CLI).
+- `aw sessions` / `aw release-data [--since sessionNNN] [--source <alias>]` — enumerates the corpus (input for the AS-IS/TO-BE delta).
+- `aw session-artifacts --code <NNN> --dump objetivo` — locates the session and its plan-doc reference; `AS-IS`/`TO-BE`/`Impacted` are read from the plan-doc by its path.
+- `aw next-number docs/diagrams` — deterministic numbering (the CLI handles destination-folder resolution).
 
-**Filesystem / código**:
+**Filesystem / code**:
 
-- Código de las fuentes declaradas (estructura, wiring, manifests de tecnología).
-- `docs/diagrams/` existentes (para complementar / no colisionar).
+- The declared sources' code (structure, wiring, technology manifests).
+- Existing `docs/diagrams/` (to complement / avoid collisions).
 
-**MCP read-only** (opcional, solo si se pide modelo de datos y está configurado): `\d <tabla>`, `SELECT count(*)`, relaciones FK para el `erDiagram`. Con cost guard.
+**Read-only MCP** (optional, only with a data-model request and configuration): `\d <table>`, `SELECT count(*)`, FK relations for the `erDiagram`. With the cost guard.
 
-**Args** (sin *structured-choice* de ciclo de vida — capacidad del arnés; ver [`../../harness/SKILL.md`](../../harness/SKILL.md)):
+**Args** (no lifecycle *structured-choice*; harness capability — see [`../../harness/SKILL.md`](../../harness/SKILL.md)):
 
 ```
 /w:export-diagrams [--sessions NNN[,NNN]] [--since sessionNNN] [--source <alias>]
                    [--engine mermaid|c4] [--scope c4|integrations|data|todo] [--dry-run]
 ```
 
-| Flag | Comportamiento |
+| Flag | Behavior |
 |---|---|
-| `--sessions NNN[,NNN]` | Filtro discreto por código (precede a `--since`); afecta el delta AS-IS/TO-BE |
-| `--since sessionNNN` | Solo sesiones posteriores a NNN (exclusivo: la propia NNN no entra; usá `--sessions` para incluirla) |
-| `--source <alias>` | Limita a una fuente (workspace multi-fuente) |
-| `--engine mermaid\|c4` | Default `mermaid` (render en GitHub); `c4` = Structurizr DSL opt-in |
-| `--scope` | Qué secciones aparecen: `c4` (contexto/contenedores/componentes), `integrations`, `data` (solo si MCP), `todo` (default) |
-| `--dry-run` | Reporte propositivo sin escribir archivos |
+| `--sessions NNN[,NNN]` | Discrete filter by code (takes precedence over `--since`); affects the AS-IS/TO-BE delta |
+| `--since sessionNNN` | Only sessions after NNN (exclusive: NNN itself is out; use `--sessions` to include it) |
+| `--source <alias>` | Limits to one source (multi-source workspace) |
+| `--engine mermaid\|c4` | Default `mermaid` (renders on GitHub); `c4` = opt-in Structurizr DSL |
+| `--scope` | Which sections appear: `c4` (context/containers/components), `integrations`, `data` (only with MCP), `todo` (default: all) |
+| `--dry-run` | Propositional report, no files written |
 
-Sin args: `--engine mermaid --scope todo`. El **snapshot** del sistema es siempre el último estado conocido; `--since`/`--sessions` modulan el énfasis del delta (qué se tocó), no el snapshot base. *(Si algún flag exacto difiere en el CLI runtime, ajustar al contrato real de `aw`.)*
+No args: `--engine mermaid --scope todo`. The system **snapshot** is always the last known state; `--since`/`--sessions` modulate the delta emphasis (what was touched), not the base snapshot.
 
 ## Flow
 
-### Paso 1 — Resolver contexto y corpus
+### Step 1 — Resolve context and corpus
 
-`aw sessions` / `release-data` aplicando `--sessions`/`--since`/`--source`. La resolución de la carpeta destino la maneja el CLI.
+`aw sessions` / `release-data` applying `--sessions`/`--since`/`--source`. The CLI handles destination-folder resolution.
 
-### Paso 2 — Inspeccionar las fuentes
+### Step 2 — Inspect the sources
 
-Por cada fuente: estructura básica, componentes internos (módulos, servicios, comandos, hooks, MCP configurado), tecnologías por manifest (`package.json`, `pom.xml`, …), integraciones externas.
+Per source: basic structure, internal components (modules, services, commands, hooks, configured MCP), technologies per manifest (`package.json`, `pom.xml`, …), external integrations.
 
-### Paso 3 — Leer el delta del corpus
+### Step 3 — Read the corpus delta
 
-Por sesión filtrada (`aw session-artifacts --code <NNN> --dump objetivo`): seguir la referencia al plan-doc y leer `Current state (AS-IS)` / `Target state (TO-BE)` e `Impacted`. Sirve para resaltar lo que cambió sobre el snapshot vigente.
+Per filtered session (`aw session-artifacts --code <NNN> --dump objetivo`): follow the plan-doc reference and read `Current state (AS-IS)` / `Target state (TO-BE)` and `Impacted`. Used to highlight what changed over the current snapshot.
 
-### Paso 4 — Inspeccionar MCP (opcional)
+### Step 4 — Inspect MCP (optional)
 
-Si `--scope` incluye `data` y hay MCP read-only: `\d <tabla>`, `count(*)`, relaciones FK (con cost guard). Si no disponible → omitir la sección "Modelo de datos" con nota inline.
+If `--scope` includes `data` and read-only MCP exists: `\d <table>`, `count(*)`, FK relations (with the cost guard). Not available → omit the "Data model" section with an inline note.
 
-### Paso 5 — Renderizar (compone `diagrams`)
+### Step 5 — Render (composes `diagrams`)
 
-Según `--engine`: `mermaid` → bloques Mermaid C4 nativos (`C4Context`/`C4Container`/`C4Component`) y `flowchart` para flujos; `c4` → `workspace.dsl` Structurizr aparte + Mermaid auxiliar embebido para lectura offline. Por cada bloque ```` ```mermaid ````, agregar inmediatamente después del fence de cierre un blockquote con el link de preview: `> Ver diagrama renderizado: <https://mermaid.ink/img/BASE64>` (base64 URL-safe del código plano). No aplica a `workspace.dsl`.
+Per `--engine`: `mermaid` → native Mermaid C4 blocks (`C4Context`/`C4Container`/`C4Component`) and `flowchart` for flows; `c4` → a separate Structurizr `workspace.dsl` + auxiliary embedded Mermaid for offline reading. For every ```` ```mermaid ```` block, add immediately after the closing fence a blockquote with the preview link: `> Ver diagrama renderizado: <https://mermaid.ink/img/BASE64>` (URL-safe base64 of the plain code). Not applicable to `workspace.dsl`.
 
-### Paso 6 — Escribir o reportar
+### Step 6 — Write or report
 
-Si `--dry-run`: imprimir el reporte; no escribir. Si no: `aw next-number docs/diagrams` + escribir el dossier. **NUNCA commitear**. Resumen al usuario: motor, secciones presentes/omitidas (p.ej. Datos omitido si no MCP) y ruta.
+With `--dry-run`: print the report; write nothing. Otherwise: `aw next-number docs/diagrams` + write the dossier. **NEVER commit**. Summary to the user: engine, present/omitted sections (e.g. Data omitted without MCP) and the path.
 
 ## Output location
 
 ```
 docs/diagrams/NNN-export-diagrams-YYYY-MM-DD/
-├── README.md          # índice + cómo leer + counts
-├── diagrams.md        # documento principal con Mermaid embebido (+ links mermaid.ink)
-└── workspace.dsl      # solo con --engine c4 (Structurizr)
+├── README.md          # index + how to read + counts
+├── diagrams.md        # main document with embedded Mermaid (+ mermaid.ink links)
+└── workspace.dsl      # only with --engine c4 (Structurizr)
 ```
 
 ## Re-run
 
-Idempotente funcional: cada invocación toma el siguiente `NNN`; no sobrescribe dossiers previos. Para regenerar: borrar el directorio y re-invocar.
+Functionally idempotent: each invocation takes the next `NNN`; it never overwrites previous dossiers. To regenerate: delete the directory and re-invoke.
 
 ## Resources
 
-- Design: `docs/referencias/workflow-exports/export-diagrams.md` · familia: [`../README.md`](../README.md).
-- Capacidad compuesta: `diagrams` (built-in default; ver `docs/referencias/workflow-roles/`).
-- Insumo: plan-doc `AS-IS`/`TO-BE`/`Impacted` (ver `docs/plans`).
+- Design: `docs/referencias/workflow-exports/export-diagrams.md` · family: [`../README.md`](../README.md).
+- Composed capability: `diagrams` (built-in default; see `docs/referencias/workflow-roles/`).
+- Input: plan-doc `AS-IS`/`TO-BE`/`Impacted` (see `docs/plans`).
 - Siblings: [`../export-scripts/SKILL.md`](../export-scripts/SKILL.md) · [`../export-manuals/SKILL.md`](../export-manuals/SKILL.md) · [`../export-reports/SKILL.md`](../export-reports/SKILL.md).