diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 37f9c0a..50c695e 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "cys",
-  "version": "0.6.18",
+  "version": "0.6.19",
   "description": "Development methodology skills with parallel plan execution: design, plan, run, check, ship. Named after the author's twin daughters, Cielo y Sophia.",
   "author": { "name": "Christian Bacilio" },
   "repository": "https://github.com/bacsystem/parallel-plan-executor",
diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json
index 3fb56d5..d5b33a6 100644
--- a/.cursor-plugin/plugin.json
+++ b/.cursor-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "cys",
-  "version": "0.6.18",
+  "version": "0.6.19",
   "description": "Development methodology skills for design, plan, check, and ship — parallel plan execution (cys:run) is Claude Code only for now.",
   "author": { "name": "Christian Bacilio" },
   "repository": "https://github.com/bacsystem/parallel-plan-executor",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e4118b3..0d9abea 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.6.19 — 2026-07-19
+
+Changed:
+
+- Reorganized both `README.md` and `README.es.md` around a clear path
+  for a new user: What is cys → demo → Quick Start → plugin install (per
+  platform) → permissions setup → Using cys (step-by-step guide, manual
+  reference, `/run-plan`, Handoff, branch topology) → Building from
+  source → How it works → safety checks & known limitations → reporting
+  bugs & contributing. Added a table of contents to both. Surfaces a
+  distinction the old ordering buried: installing the cys plugin via the
+  marketplace already gives a ready-to-run, pre-built copy of this repo
+  — cloning and `npm run build` are only needed for contributors or
+  advanced engine use, not a typical first run.
+- Embedded `docs/diagram/flujo-cys-ecosystem.mmd`'s content directly as
+  a rendered Mermaid diagram in both READMEs instead of only linking the
+  file.
+
+Fixed:
+
+- `examples/README.md`'s `#usage` anchor link, stale after the
+  reorganization renamed that section to `#using-cys`.
+
 ## 0.6.18 — 2026-07-19
 
 Added:
diff --git a/README.es.md b/README.es.md
index 170136d..2b1e925 100644
--- a/README.es.md
+++ b/README.es.md
@@ -10,10 +10,110 @@ vez, como hacen los ejecutores secuenciales de planes.
 El **código que se genera** es agnóstico de tecnología: ya se validó con proyectos en
 Node y en Java/Spring Boot, y no hay nada en el diseño atado a un lenguaje en particular.
 
+## Índice
+
+- [Qué es cys](#qué-es-cys)
+- [Viéndolo en acción (60 segundos)](#viéndolo-en-acción-60-segundos)
+- [Quick Start](#quick-start)
+- [Instalar el plugin cys](#instalar-el-plugin-cys)
+- [Configuración de permisos, una sola vez (merges)](#configuración-de-permisos-una-sola-vez-merges)
+- [Usar cys](#usar-cys)
+- [Construir desde el código fuente](#construir-desde-el-código-fuente)
+- [Cómo funciona](#cómo-funciona)
+- [Chequeos de seguridad y limitaciones conocidas](#chequeos-de-seguridad-y-limitaciones-conocidas)
+- [Reportar bugs y contribuir](#reportar-bugs-y-contribuir)
+
+## Qué es cys
+
+**cys** son dos cosas, en un solo repo:
+
+1. **Un plugin portable** — cinco skills que cubren el flujo completo
+   **design → plan → run → check → ship**, creado por Christian Bacilio y nombrado
+   en honor a sus hijas gemelas, **Cielo y Sophia**. Cuatro de las cinco skills son
+   markdown plano sin acoplamiento a nada específico de Claude Code, así que el mismo
+   directorio `skills/` funciona tal cual en Claude Code, Cursor y Gemini CLI — ver
+   [Instalar el plugin cys](#instalar-el-plugin-cys).
+2. **`cys:run`, el motor de ejecución paralela** (el script `Workflow` de este repo) —
+   el diferenciador real, y **exclusivo de Claude Code**. Es un script de `Workflow`,
+   un tercer tipo de extensión de Claude Code distinto de plugins y skills: se invoca
+   por ruta absoluta (`scriptPath: <clon>/workflows/parallel-plan-executor.js`), no
+   puede pausarse a mitad de la corrida para preguntarte nada, y todo lo que produce —
+   briefs de tarea, veredictos de revisión, `.cys/handoff.md` — se escribe a disco en
+   su lugar.
+
+| Skill | Qué hace |
+|---|---|
+| `cys:design` | idea → spec |
+| `cys:plan` | spec → plan de implementación |
+| `cys:run` | el `Workflow` de este repo — se lanza vía `/cys:run-plan` o `/cys:flow`. **Exclusivo de Claude Code.** |
+| `cys:check` | revisión adversarial / verificación |
+| `cys:ship` | commit / bump de SemVer / PR |
+| `cys:guide` | índice — qué skill usar en cada momento |
+
+`/cys:flow` (exclusivo de Claude Code) es el punto de entrada todo-en-uno: le das
+un repo destino y una idea, y recorre el flujo completo (diseño → plan → ejecución
+paralela) con tus puertas de aprobación en cada etapa. Usa `/cys:run-plan` cuando ya
+tengas un plan aprobado.
+
 Spec de diseño: `docs/cys/specs/2026-07-04-parallel-plan-executor-design.md`.
 
-Flujo del ecosistema (las 5 skills, sus artefactos, y los gates humanos
-de aprobación): `docs/diagram/flujo-cys-ecosystem.mmd`.
+```mermaid
+flowchart TD
+    subgraph DESIGN["1 · cys:design"]
+        D1["Idea del usuario"]
+        D2["Diálogo: contexto,<br/>preguntas de a una,<br/>2-3 enfoques"]
+        D3["docs/cys/specs/*.md"]
+        D1 --> D2 --> D3
+    end
+
+    GATE1{"Gate humano:<br/>¿usuario aprueba<br/>el spec?"}
+    D3 --> GATE1
+    GATE1 -- "no, cambios" --> D2
+    GATE1 -- "sí" --> PLAN
+
+    subgraph PLAN["2 · cys:plan"]
+        P1["Tareas numeradas<br/>Files + Consumes/Produces"]
+        P2["docs/cys/plans/*.md"]
+        P3["bin/parse-plan.js<br/>dry-run del grafo"]
+        P1 --> P2 --> P3
+    end
+
+    PLAN --> RUN
+
+    subgraph RUN["3 · cys:run (Claude Code únicamente)"]
+        R1["DAG inferido del plan"]
+        R2["worktree + implement + review<br/>adversarial + merge serializado,<br/>por tarea, en paralelo cuando<br/>el DAG lo permite"]
+        R3["ramas task-&lt;id&gt; mergeadas<br/>+ .cys/ (briefs, reportes, diffs)"]
+        R1 --> R2 --> R3
+    end
+
+    RUN --> CHECK
+
+    subgraph CHECK["4 · cys:check (opcional)"]
+        C1["Revisión adicional sobre<br/>una rama ya lista"]
+        C2["Verdicts + hallazgos<br/>a .cys/pending.md"]
+        C1 --> C2
+    end
+
+    CHECK --> SHIP
+    RUN -.-> SHIP
+
+    subgraph SHIP["5 · cys:ship"]
+        S1["Clasifica el cambio,<br/>calcula SemVer"]
+        S2["CHANGELOG + branch +<br/>commit + PR"]
+        S1 --> S2
+    end
+
+    GATE2{"Gate humano:<br/>¿usuario mergea<br/>el PR?"}
+    S2 --> GATE2
+    GATE2 -- "sí" --> DONE["Cambio integrado"]
+
+    style GATE1 fill:#8a6d1a,color:#fff
+    style GATE2 fill:#8a6d1a,color:#fff
+    style DONE fill:#1a6b2a,color:#fff
+```
+
+Fuente: `docs/diagram/flujo-cys-ecosystem.mmd`.
 
 ## Viéndolo en acción (60 segundos)
 
@@ -38,47 +138,37 @@ Las Tareas 2 y 3 no dependen entre sí — cys lo infirió de sus bloques
 detrás de la otra. Cada tarea pasó por su propio worktree de git
 aislado, una revisión adversarial de código, y un merge serializado —
 te queda un PR con un veredicto de revisión de toda la rama, no solo
-tests en verde. Mirá [Reportar un bug](#reportar-un-bug) más abajo si
+tests en verde. Mirá [Reportar un bug](#reportar-bugs-y-contribuir) más abajo si
 algo se ve raro — la revisión final ya escribe sus propios hallazgos en
 `.cys/pending.md` por vos.
 
-## ¿Qué tipo de cosa es esto? (¿plugin? ¿skill? ninguno)
-
-Ninguno de los dos. Este repo es un **script de `Workflow`** — un tercer tipo de
-extensión de Claude Code, distinto de plugins y skills:
+## Quick Start
 
-- **No es un plugin**: no se instala con `/plugin` ni desde un marketplace.
-- **No es una skill**: no vive bajo `.claude/skills/` ni se invoca con la tool Skill.
-- Es un **script para la tool `Workflow` de Claude Code**: clonas este repo en cualquier
-  lugar de tu máquina, y Claude Code corre el script por ruta absoluta
-  (`scriptPath: <clon>/workflows/parallel-plan-executor.js`) cuando se lo pides.
+El camino rápido, para Claude Code — sin clonar, sin buildear. Instalar
+el plugin ya materializa este repo entero (motor pre-compilado incluido)
+donde Claude Code puede correrlo:
 
-Lo único que sí se "instala" en el sentido de Claude Code es el comando opcional
-`/run-plan` (un solo archivo `.md` que copias — ver más abajo), o el **plugin cys**
-que se describe a continuación.
+```
+/plugin marketplace add bacsystem/parallel-plan-executor
+/plugin install cys@bacsystem
+```
 
-## El plugin cys
+Después, desde cualquier sesión de Claude Code:
 
-**cys** es el plugin de skills de este repo: cinco skills que cubren el flujo completo
-**design → plan → run → check → ship**, creado por Christian Bacilio y nombrado en
-honor a sus hijas gemelas, **Cielo y Sophia**.
+> `/cys:flow /ruta/absoluta/a/tu-proyecto "describí qué querés construir"`
 
-| Skill | Qué hace |
-|---|---|
-| `cys:design` | idea → spec |
-| `cys:plan` | spec → plan de implementación |
-| `cys:run` | el Workflow de este repo — se lanza vía `/cys:run-plan` o `commands/run-plan.md`. **Exclusivo de Claude Code** (ver "Soporte multi-IA" abajo). |
-| `cys:check` | revisión adversarial / verificación |
-| `cys:ship` | commit / bump de SemVer / PR |
-| `cys:guide` | índice — qué skill usar en cada momento |
+Ese es el flujo completo — diseño, plan, y (exclusivo de Claude Code) una
+ejecución paralela real — con tu aprobación en cada puerta. Ver
+[Instalar el plugin cys](#instalar-el-plugin-cys) para Cursor y Gemini CLI,
+y [Usar cys](#usar-cys) para la guía completa de primera corrida una vez
+que ya pasaste la versión rápida.
 
-El plugin también trae `/cys:flow` (exclusivo de Claude Code) — el punto
-de entrada todo-en-uno: le das un repo destino y una idea, y recorre el
-flujo completo (diseño → plan → ejecución paralela) con tus puertas de
-aprobación en cada etapa. Usa `/cys:run-plan` cuando ya tengas un plan
-aprobado.
+En otras plataformas (Cursor, Gemini CLI), el plugin te da `cys:design` y
+`cys:plan`; `cys:guide` te explica cómo ejecutar vos mismo las tareas del
+plan resultante, ya que el motor paralelo de `cys:run` es exclusivo de
+Claude Code.
 
-## Soporte multi-IA
+## Instalar el plugin cys
 
 Las cinco skills de cys que no son el motor (`design`, `plan`, `check`,
 `ship`, `guide`) son markdown plano sin acoplamiento a nada específico de
@@ -122,8 +212,8 @@ plugins de Cursor cambió después de escribir esta sección por primera
 vez, así que confiá en estos pasos antes que en cualquier captura vieja
 que encuentres en otro lado):
 
-1. Clona este repo (ver [Instalación](#instalación) abajo — para solo
-   usar las skills alcanza con clonar, no hace falta compilar el
+1. Clona este repo (ver [Construir desde el código fuente](#construir-desde-el-código-fuente)
+   abajo — para solo usar las skills alcanza con clonar, no hace falta compilar el
    artefacto del workflow ni correr su suite de tests).
 2. En Cursor: **Settings → Plugins** (o el panel **Customize**, si tu
    versión ya movió la gestión de plugins ahí) → **+ Add** → **From
@@ -211,60 +301,15 @@ comando. Como la instalación copia el repo en vez de seguirlo en vivo,
 corré `gemini extensions update cys` para traer futuras versiones.
 
 La ejecución paralela de `cys:run` sigue siendo exclusiva de Claude Code
-(ver Requisitos abajo): en Gemini CLI, `cys:guide` explica cómo ejecutar
-las tareas de un plan vos mismo en su lugar.
-
-## Requisitos
-
-- **[Claude Code](https://claude.com/claude-code)**, con acceso a la tool `Workflow`.
-  Esto **no es opcional ni intercambiable**: el script de `workflows/parallel-plan-executor.js`
-  está escrito contra las primitivas que provee esa tool (`agent()`, `pipeline()`,
-  `parallel()`, etc.). No es un estándar abierto que otro asistente de IA (ChatGPT,
-  Gemini, etc.) pueda interpretar — el workflow en sí depende de Claude Code. Lo que sí es
-  agnóstico es el **proyecto que termina automatizando**: puede ser Go, Node, Java, o
-  cualquier stack que el plan describa.
-- **El plugin cys** (ver arriba) para escribir planes con `cys:plan`. El motor es
-  totalmente autocontenido: el workflow trae sus propios scripts
-  `task-brief`/`review-package` en `bin/` y registra las corridas bajo `.cys/`.
-  Cualquier plan que siga el formato `### Task N:` + `Consumes`/`Produces` funciona,
-  sin importar qué herramienta lo escribió.
-- **Node.js >= 20** (para `bin/parse-plan.js` y la suite de tests — ninguna dependencia
-  de runtime, todo con el Node estándar).
-- Git, y un repo con working tree limpio para el proyecto que vas a automatizar.
-- `gh` (GitHub CLI) instalado y autenticado, **solo si** vas a usar `openPr: true` (para
-  que el workflow pueda crear el PR final).
-
-## Instalación
-
-```bash
-# 1. Clona este repositorio (donde vive el workflow) en tu máquina.
-#    DÓNDE: donde quieras — tu carpeta de usuario, un directorio de herramientas, etc.
-#    NO necesita estar dentro de .claude/, y NO necesita estar al lado de los proyectos
-#    que vas a automatizar; todas las rutas que le pases después son absolutas.
-git clone <url-de-este-repo> parallel-plan-executor
-cd parallel-plan-executor
-
-# 2. Verifica tu versión de Node (debe ser >= 20)
-node --version
-
-# 3. Instala (no hay dependencias de runtime; esto solo deja los scripts de npm listos)
-npm install
-
-# 4. Corre la suite de tests para confirmar que todo funciona en tu entorno
-npm test
-
-# 5. Genera el artefacto del workflow (regenera workflows/parallel-plan-executor.js
-#    a partir del template — hazlo también cada vez que cambies algo en src/)
-npm run build
-```
-
-Con esto el repo queda listo. El workflow se invoca **desde una sesión de Claude Code**
-(no hace falta publicarlo en npm ni instalarlo globalmente) — ver la sección de Uso.
-Antes de tu primera corrida real, haz también la **configuración de permisos** de abajo
-(una sola vez) para que los merges de tareas no se bloqueen a mitad de corrida.
+(ver [Construir desde el código fuente](#construir-desde-el-código-fuente)
+abajo): en Gemini CLI, `cys:guide` explica cómo ejecutar las tareas de un
+plan vos mismo en su lugar.
 
 ## Configuración de permisos, una sola vez (merges)
 
+Hacé esto una sola vez, antes de tu primera corrida real de `cys:run`,
+para que los merges de tareas no se bloqueen a mitad de la corrida.
+
 Los agentes de merge del workflow corren `git merge` dentro de tu repo destino. Claude
 Code trata a un agente mergeando código como una acción sensible, y lo que pasa depende
 de tu modo de permisos:
@@ -275,7 +320,8 @@ de tu modo de permisos:
   la corrida fluye sin volver a preguntar.
 - **Modo automático**: por defecto no hay diálogo — un clasificador automático decide
   solo, y puede bloquear los merges de agentes incluso habiendo autorizado tú mismo la
-  corrida de entrada (ver la nota de permisos más abajo para el porqué). Para tener el
+  corrida de entrada (ver la nota de permisos en
+  [topología de ramas](#topología-de-ramas-recomendada) para el porqué). Para tener el
   mismo diálogo yes/no del modo normal, agrega una **regla `ask`** al
   `.claude/settings.json` del **proyecto destino** (crea el archivo si no existe):
 
@@ -295,27 +341,19 @@ ti**, de forma determinística, sin importar el modo — solo haces clic, nunca
 Si prefieres que no te pregunte nunca, usa `"allow"` en vez de `"ask"` (la corrida queda
 100% sin manos; la puerta humana se muda a la revisión del PR final).
 
-## Cómo funciona
+## Usar cys
 
-1. `bin/parse-plan.js` lee un archivo de plan y calcula la lista de tareas + el grafo de
-   dependencias (Node puro, con tests unitarios completos — ver `tests/`).
-2. `workflows/parallel-plan-executor.js` (generado a partir de
-   `workflows-src/parallel-plan-executor.template.js` con `npm run build`) toma ese grafo y
-   corre cada tarea en su propio worktree de git vía `agent()`, arrancando una tarea en
-   cuanto sus dependencias específicas terminan, sin esperar a un lote completo.
-3. Cada tarea pasa por un agente de revisión adversarial en vez de un checkpoint humano
-   por tarea, porque un `Workflow` no puede pausarse a mitad de la corrida para
-   preguntarte algo.
-4. Los merges pasan de a uno, serializados, respetando el orden de dependencias.
-5. Al final se genera un reporte único y, si al menos una tarea se integró, un agente de
-   **Handoff** prepara el cierre estilo git-flow (ver más abajo).
+Esta sección recorre la experiencia completa de primera corrida, y
+después cubre las piezas de referencia (invocación manual, el comando
+`/run-plan`, la fase de Handoff, la topología de ramas) para cuando
+necesites más control del que te da `/cys:flow`.
 
-## Guía paso a paso (si es tu primera vez)
+### Guía paso a paso (si es tu primera vez)
 
-Esta sección es para quien nunca corrió el workflow y quiere ir sin perderse. Si ya lo
-conoces, la sección "Uso" de abajo es la referencia rápida.
+Esta subsección es para quien nunca corrió el workflow y quiere ir sin perderse. Si ya lo
+conoces, [Invocación manual](#invocación-manual-referencia) abajo es la referencia rápida.
 
-### Paso 0 — Lo que necesitas tener listo antes de empezar
+#### Paso 0 — Lo que necesitas tener listo antes de empezar
 
 - **Un plan de implementación aprobado**, con tareas numeradas y sus bloques
   `Consumes`/`Produces` (el formato que produce la skill `cys:plan`). Si todavía no
@@ -325,17 +363,17 @@ conoces, la sección "Uso" de abajo es la referencia rápida.
 - **El repo que vas a automatizar**, con el working tree limpio (`git status` sin
   cambios pendientes) y, si vas a pedir `openPr: true` al final, con un remoto de GitHub
   ya configurado y `gh auth status` en verde.
-- Este repo (`parallel-plan-executor`) clonado e instalado — ver "Instalación" más
-  arriba. No hace falta que esté en la misma carpeta que tu proyecto: las rutas que le
-  vas a pasar son siempre absolutas.
+- El plugin cys instalado (ver [Quick Start](#quick-start)) — no hace falta clonar nada
+  a mano para este camino. Si vas a manejar el motor directamente en vez de por los
+  comandos del plugin, ver [Construir desde el código fuente](#construir-desde-el-código-fuente).
 
-### Paso 1 — Abre una sesión de Claude Code
+#### Paso 1 — Abre una sesión de Claude Code
 
 Puede ser en la carpeta de tu proyecto, en la de este repo, o en cualquier otra: el
 workflow no depende de dónde esté corriendo tu sesión de Claude Code, siempre que le
 des rutas absolutas al plan y al repo destino.
 
-### Paso 2 — Pídeselo a Claude Code en español, con lenguaje natural
+#### Paso 2 — Pídeselo a Claude Code en español, con lenguaje natural
 
 **No hace falta escribir el JSON de `args` a mano.** Eso es trabajo de Claude Code: tú
 le cuentas qué quieres en una frase, con estos datos:
@@ -365,9 +403,9 @@ momento.
 > explícitamente los merges — y esa autorización necesita nombrar la acción concreta
 > ("mergear task-1 a task-6"), no un simple "sí" u "ok". Decirlo de entrada, con las
 > ramas nombradas, evita que el run se trabe a mitad de camino. Ver la nota de permisos
-> más abajo para el detalle técnico.
+> en [topología de ramas](#topología-de-ramas-recomendada) para el detalle técnico.
 
-### Paso 3 — Qué vas a ver mientras corre
+#### Paso 3 — Qué vas a ver mientras corre
 
 El workflow corre en segundo plano — no se queda esperando tu respuesta. Vas a ver:
 
@@ -382,7 +420,7 @@ algún problema. También puedes abrir el panel `/workflows` de Claude Code para
 detalle por fase (Implement, Review, Merge, Final review, Handoff), cuántos agentes y
 tokens llevó cada una, y el tiempo de cada agente.
 
-### Paso 4 — Si algo se traba
+#### Paso 4 — Si algo se traba
 
 Lo más común es que un merge quede marcado como bloqueado por precaución, **incluso
 habiendo autorizado de entrada** — es una medida de seguridad del entorno, no un error
@@ -395,19 +433,19 @@ de tu plan. Si eso pasa:
    (implementadas, revisadas, mergeadas) no se vuelven a correr — solo se reintenta lo
    que quedó pendiente.
 
-### Paso 5 — Cuando termina
+#### Paso 5 — Cuando termina
 
 - Si **al menos una tarea se integró**, vas a tener un archivo
   `.cys/handoff.md` en tu proyecto con: el título y cuerpo de PR sugeridos,
   la versión SemVer propuesta, y un checklist de limpieza (qué ramas `task-N` borrar y
-  cuándo).
+  cuándo) — ver [Fase de Handoff](#fase-de-handoff) para el detalle completo.
 - Si pediste `openPr: true`, el PR **ya va a estar creado** en GitHub contra la rama que
   indicaste — revísalo tú y haz el merge cuando estés conforme. El workflow nunca mergea
   el PR por su cuenta; esa decisión siempre queda en tus manos.
 - Si alguna tarea falló o quedó bloqueada, el reporte final te va a decir exactamente
   cuál y por qué — y cuáles otras tareas se saltearon en cascada por depender de ella.
 
-### Errores comunes
+#### Errores comunes
 
 | Lo que ves | Qué significa |
 |---|---|
@@ -416,7 +454,11 @@ de tu plan. Si eso pasa:
 | El run se corta a mitad de camino | Es recuperable: Claude Code puede retomarlo sin perder el trabajo ya hecho. |
 | El agente tarda varios minutos "sin hacer nada" al arrancar la primera tarea | Es normal — el primer `implement` incluye instalar/preparar el entorno del proyecto; vas a ver el aviso de progreso apenas termina. |
 
-## Uso
+### Invocación manual (referencia)
+
+Una vez que conocés el flujo, esta es la forma cruda de lo que
+`/cys:flow`/`/cys:run-plan` hacen por vos — útil si estás scripteando
+alrededor de cys o querés ver cada campo:
 
 ```bash
 # 1. Calcula el grafo de tareas para tu plan
@@ -440,7 +482,7 @@ node bin/parse-plan.js /ruta/a/tu-plan.md > /tmp/plan-graph.json
 #            mergeAuthorization: "Autorizo mergear las ramas task-1 a task-N contra <rama>",
 #               # opcional pero recomendado: tu autorización explícita, para que el agente
 #               # de merge no tenga que adivinar si ya diste consentimiento (ver nota de
-#               # permisos más abajo)
+#               # permisos en topología de ramas abajo)
 #            maxConcurrency: 3                      # opcional, default ilimitado — ver abajo
 #            }
 ```
@@ -451,13 +493,13 @@ propio tope de `min(16, cores-2)`, así que esto sirve sobre todo para ir *más
 ese default — por ejemplo, para evitar muchos worktrees locales simultáneos en tu propia
 máquina cuando un plan tiene una capa ancha de tareas independientes.
 
-## Opcional: el comando `/run-plan`
+### El comando `/run-plan`
 
 Si prefieres no escribir la solicitud en lenguaje natural de la guía paso a paso cada vez,
 este repo trae un comando personalizado de Claude Code que la envuelve:
 `commands/run-plan.md`.
 
-### Cómo instalarlo
+#### Cómo instalarlo
 
 1. Copia `commands/run-plan.md` de este repo a alguna de estas dos ubicaciones:
    - `~/.claude/commands/run-plan.md` — disponible en **todos** tus proyectos en esta
@@ -477,18 +519,18 @@ este repo trae un comando personalizado de Claude Code que la envuelve:
 3. Listo — no hace falta reiniciar nada. Claude Code toma los comandos bajo
    `.claude/commands/` la próxima vez que los uses.
 
-### Cómo usarlo
+#### Cómo usarlo
 
 ```
 /run-plan /ruta/a/tu-plan.md /ruta/a/tu/proyecto feature/mi-plan
 ```
 
 Los tres argumentos son opcionales de escribir de entrada — el comando te va a preguntar
-lo que falte, más lo que la sección "Uso" de arriba lista como opcional (`openPr`,
-campos de `pr`, tu autorización de merge). Nunca inventa tu texto de autorización por su
-cuenta; siempre te pide que nombres tú las ramas.
+lo que falte, más lo que [invocación manual](#invocación-manual-referencia) arriba lista
+como opcional (`openPr`, campos de `pr`, tu autorización de merge). Nunca inventa tu texto
+de autorización por su cuenta; siempre te pide que nombres tú las ramas.
 
-## Fase de Handoff (v0.5.0)
+### Fase de Handoff
 
 Cuando al menos una tarea se integró, un agente final de **handoff** prepara el cierre
 estilo git-flow — sin ejecutarlo. Escribe `.cys/handoff.md` en el repo
@@ -502,7 +544,7 @@ de integración y **crea** el pull request vía `gh` contra `pr.base` (por defec
 `develop`), aplicando los campos opcionales de `pr` — assignees, labels, milestone, y
 `Closes #<closes>` en el body. **Nunca mergea el PR**: esa puerta siempre es humana.
 
-## Topología de ramas recomendada (validada en el piloto 4)
+### Topología de ramas recomendada
 
 Apunta `integrationBranch` a una **rama feature efímera creada desde `develop`** — nunca
 directamente a `develop`/`main`:
@@ -529,13 +571,87 @@ merge* no se autobloquee por precaución (hallazgo F8 en
 `docs/pilots/2026-07-15-pilot-stats-bitacora.md`) — pero **no** obliga al clasificador:
 en una corrida real posterior, el clasificador rechazó explícitamente ese texto relayado
 como consentimiento "autoafirmado, no verificable" y bloqueó el merge igual. El fix
-determinístico es la **configuración de permisos de una sola vez** al comienzo de este
-README: una regla `ask` (o `allow`) para `git merge` en el `.claude/settings.json` del
-proyecto destino, agregada por ti. Las reglas tienen precedencia sobre el modo — con la
-regla puesta tienes un diálogo simple de yes/no (o allow silencioso) en vez del juicio
-del clasificador.
+determinístico es la [configuración de permisos de una sola vez](#configuración-de-permisos-una-sola-vez-merges)
+al comienzo de este README: una regla `ask` (o `allow`) para `git merge` en el
+`.claude/settings.json` del proyecto destino, agregada por ti. Las reglas tienen
+precedencia sobre el modo — con la regla puesta tienes un diálogo simple de yes/no (o
+allow silencioso) en vez del juicio del clasificador.
+
+## Construir desde el código fuente
+
+Solo hace falta si vas a **contribuir a este repo**, o querés correr el
+script `Workflow` crudo sin pasar por los comandos del plugin. Si solo
+querés *usar* cys, [Quick Start](#quick-start) alcanza — instalar el
+plugin ya te da una copia lista para correr, pre-compilada.
+
+### Requisitos
+
+- **[Claude Code](https://claude.com/claude-code)**, con acceso a la tool `Workflow`.
+  Esto **no es opcional ni intercambiable**: el script de `workflows/parallel-plan-executor.js`
+  está escrito contra las primitivas que provee esa tool (`agent()`, `pipeline()`,
+  `parallel()`, etc.). No es un estándar abierto que otro asistente de IA (ChatGPT,
+  Gemini, etc.) pueda interpretar — el workflow en sí depende de Claude Code. Lo que sí es
+  agnóstico es el **proyecto que termina automatizando**: puede ser Go, Node, Java, o
+  cualquier stack que el plan describa.
+- **El plugin cys** (ver [Instalar el plugin cys](#instalar-el-plugin-cys)) para escribir
+  planes con `cys:plan`. El motor es totalmente autocontenido: el workflow trae sus
+  propios scripts `task-brief`/`review-package` en `bin/` y registra las corridas bajo
+  `.cys/`. Cualquier plan que siga el formato `### Task N:` + `Consumes`/`Produces`
+  funciona, sin importar qué herramienta lo escribió.
+- **Node.js >= 20** (para `bin/parse-plan.js` y la suite de tests — ninguna dependencia
+  de runtime, todo con el Node estándar).
+- Git, y un repo con working tree limpio para el proyecto que vas a automatizar.
+- `gh` (GitHub CLI) instalado y autenticado, **solo si** vas a usar `openPr: true` (para
+  que el workflow pueda crear el PR final).
 
-## Chequeos de seguridad (v0.2)
+### Clonar y compilar
+
+```bash
+# 1. Clona este repositorio (donde vive el workflow) en tu máquina.
+#    DÓNDE: donde quieras — tu carpeta de usuario, un directorio de herramientas, etc.
+#    NO necesita estar dentro de .claude/, y NO necesita estar al lado de los proyectos
+#    que vas a automatizar; todas las rutas que le pases después son absolutas.
+git clone <url-de-este-repo> parallel-plan-executor
+cd parallel-plan-executor
+
+# 2. Verifica tu versión de Node (debe ser >= 20)
+node --version
+
+# 3. Instala (no hay dependencias de runtime; esto solo deja los scripts de npm listos)
+npm install
+
+# 4. Corre la suite de tests para confirmar que todo funciona en tu entorno
+npm test
+
+# 5. Genera el artefacto del workflow (regenera workflows/parallel-plan-executor.js
+#    a partir del template — hazlo también cada vez que cambies algo en src/)
+npm run build
+```
+
+Con esto el repo queda listo. El workflow se invoca **desde una sesión de Claude Code**
+(no hace falta publicarlo en npm ni instalarlo globalmente) — ver [Usar cys](#usar-cys)
+arriba. Antes de tu primera corrida real, haz también la
+[configuración de permisos de una sola vez](#configuración-de-permisos-una-sola-vez-merges)
+para que los merges de tareas no se bloqueen a mitad de corrida.
+
+## Cómo funciona
+
+1. `bin/parse-plan.js` lee un archivo de plan y calcula la lista de tareas + el grafo de
+   dependencias (Node puro, con tests unitarios completos — ver `tests/`).
+2. `workflows/parallel-plan-executor.js` (generado a partir de
+   `workflows-src/parallel-plan-executor.template.js` con `npm run build`) toma ese grafo y
+   corre cada tarea en su propio worktree de git vía `agent()`, arrancando una tarea en
+   cuanto sus dependencias específicas terminan, sin esperar a un lote completo.
+3. Cada tarea pasa por un agente de revisión adversarial en vez de un checkpoint humano
+   por tarea, porque un `Workflow` no puede pausarse a mitad de la corrida para
+   preguntarte algo.
+4. Los merges pasan de a uno, serializados, respetando el orden de dependencias.
+5. Al final se genera un reporte único y, si al menos una tarea se integró, un agente de
+   **Handoff** prepara el cierre estilo git-flow (ver [Fase de Handoff](#fase-de-handoff)).
+
+## Chequeos de seguridad y limitaciones conocidas
+
+### Chequeos de seguridad (v0.2)
 
 - **Validación de arranque**: el workflow valida `args` antes de lanzar cualquier agente
   — un grafo cíclico o un id presente en `graph` pero ausente en `tasks` falla rápido con
@@ -549,7 +665,7 @@ del clasificador.
 - **Las razones de skip apuntan a la causa raíz**: una tarea saltada por cascada reporta
   la tarea que originalmente falló, no el eslabón intermedio saltado.
 
-## Limitaciones conocidas (v1)
+### Limitaciones conocidas (v1)
 
 - Solo cuentan los símbolos entre comillas invertidas en `Consumes`/`Produces` (p. ej.
   `` - Produces: la factory `createWidget()` `` produce `createWidget`). La prosa suelta
@@ -569,7 +685,7 @@ del clasificador.
   preservan el estado parcial que exista para diagnóstico. Límpialas después con
   `git branch -D task-<id>` cuando ya no las necesites.
 
-## Reportar un bug
+## Reportar bugs y contribuir
 
 Abrí un issue en
 [github.com/bacsystem/parallel-plan-executor/issues](https://github.com/bacsystem/parallel-plan-executor/issues)
@@ -581,3 +697,7 @@ cys ya generó solo — no hace falta armar una repro desde cero:
 - `.cys/task-<id>-report.md`, de la tarea específica que falló.
 - `review-*.diff`, si una revisión marcó algo.
 - El stderr/stdout exacto de un comando que falló (ej. `node bin/parse-plan.js`).
+
+¿Querés contribuir código o docs? Ver `CONTRIBUTING.md` para la disciplina de este
+repo basada en evidencia (cada cambio de comportamiento necesita un test que rastree
+a un hallazgo real, más un comentario explicando el porqué) y el flujo de TDD/build.
diff --git a/README.md b/README.md
index b6a2eea..c5e9635 100644
--- a/README.md
+++ b/README.md
@@ -10,10 +10,109 @@ executors do.
 The **generated code** is technology-agnostic — validated against both Node and
 Java/Spring Boot projects, nothing in the design is tied to a specific language.
 
+## Table of contents
+
+- [What is cys?](#what-is-cys)
+- [See it in action (60 seconds)](#see-it-in-action-60-seconds)
+- [Quick Start](#quick-start)
+- [Installing the cys plugin](#installing-the-cys-plugin)
+- [One-time permissions setup (merges)](#one-time-permissions-setup-merges)
+- [Using cys](#using-cys)
+- [Building from source](#building-from-source)
+- [How it works](#how-it-works)
+- [Safety checks & known limitations](#safety-checks--known-limitations)
+- [Reporting bugs & contributing](#reporting-bugs--contributing)
+
+## What is cys?
+
+**cys** is two things, sharing one repo:
+
+1. **A portable plugin** — five skills covering the whole flow
+   **design → plan → run → check → ship**, created by Christian Bacilio and named
+   after his twin daughters, **Cielo y Sophia**. Four of the five skills are plain
+   Markdown with no Claude-Code-specific coupling, so the same `skills/` directory
+   works as-is on Claude Code, Cursor, and Gemini CLI — see
+   [Installing the cys plugin](#installing-the-cys-plugin).
+2. **`cys:run`, the parallel execution engine** (this repo's `Workflow` script) —
+   the actual differentiator, and **Claude Code only**. It's a `Workflow` script,
+   a third kind of Claude Code extension distinct from plugins and skills: you
+   invoke it by absolute path (`scriptPath: <clone>/workflows/parallel-plan-executor.js`),
+   it can't pause mid-run to ask you anything, and everything it produces —
+   task briefs, review verdicts, `.cys/handoff.md` — is written to disk instead.
+
+| Skill | What it does |
+|---|---|
+| `cys:design` | idea → spec |
+| `cys:plan` | spec → implementation plan |
+| `cys:run` | this repo's `Workflow` — launched via `/cys:run-plan` or `/cys:flow`. **Claude Code only.** |
+| `cys:check` | adversarial review / verification |
+| `cys:ship` | commit / SemVer bump / PR |
+| `cys:guide` | index — which skill to use when |
+
+`/cys:flow` (Claude Code only) is the all-in-one entry point: give it a target
+repo and an idea, and it walks the whole flow (design → plan → parallel run) with
+your approval gates at each stage. Use `/cys:run-plan` instead when an approved
+plan already exists.
+
 Design spec: `docs/cys/specs/2026-07-04-parallel-plan-executor-design.md`.
 
-Ecosystem flow (all 5 skills, their artifacts, and the human approval
-gates): `docs/diagram/flujo-cys-ecosystem.mmd`.
+```mermaid
+flowchart TD
+    subgraph DESIGN["1 · cys:design"]
+        D1["User's idea"]
+        D2["Dialogue: context,\none question at a time,\n2-3 approaches"]
+        D3["docs/cys/specs/*.md"]
+        D1 --> D2 --> D3
+    end
+
+    GATE1{"Human gate:\ndoes the user\napprove the spec?"}
+    D3 --> GATE1
+    GATE1 -- "no, revise" --> D2
+    GATE1 -- "yes" --> PLAN
+
+    subgraph PLAN["2 · cys:plan"]
+        P1["Numbered tasks\nFiles + Consumes/Produces"]
+        P2["docs/cys/plans/*.md"]
+        P3["bin/parse-plan.js\ngraph dry-run"]
+        P1 --> P2 --> P3
+    end
+
+    PLAN --> RUN
+
+    subgraph RUN["3 · cys:run (Claude Code only)"]
+        R1["DAG inferred from the plan"]
+        R2["worktree + implement + adversarial\nreview + serialized merge,\nper task, in parallel where\nthe DAG allows it"]
+        R3["merged task-&lt;id&gt; branches\n+ .cys/ (briefs, reports, diffs)"]
+        R1 --> R2 --> R3
+    end
+
+    RUN --> CHECK
+
+    subgraph CHECK["4 · cys:check (optional)"]
+        C1["Extra review on a\nbranch that's ready"]
+        C2["Verdicts + findings\nto .cys/pending.md"]
+        C1 --> C2
+    end
+
+    CHECK --> SHIP
+    RUN -.-> SHIP
+
+    subgraph SHIP["5 · cys:ship"]
+        S1["Classifies the change,\ncomputes SemVer"]
+        S2["CHANGELOG + branch +\ncommit + PR"]
+        S1 --> S2
+    end
+
+    GATE2{"Human gate:\ndoes the user\nmerge the PR?"}
+    S2 --> GATE2
+    GATE2 -- "yes" --> DONE["Change integrated"]
+
+    style GATE1 fill:#8a6d1a,color:#fff
+    style GATE2 fill:#8a6d1a,color:#fff
+    style DONE fill:#1a6b2a,color:#fff
+```
+
+Source: `docs/diagram/flujo-cys-ecosystem.mmd`.
 
 ## See it in action (60 seconds)
 
@@ -38,46 +137,35 @@ Tasks 2 and 3 don't depend on each other — cys inferred that from their
 after another. Every task went through its own isolated git worktree, an
 adversarial code review, and a serialized merge — you get a PR with a
 whole-branch review verdict, not just green tests. See
-[Reporting bugs](#reporting-bugs) below if anything looks off — the
+[Reporting bugs](#reporting-bugs--contributing) below if anything looks off — the
 final review already writes its own findings to `.cys/pending.md` for you.
 
-## What kind of thing is this? (plugin? skill? neither)
+## Quick Start
 
-Neither. This repo is a **`Workflow` script** — a third kind of Claude Code extension,
-different from plugins and skills:
+The fast path, for Claude Code — no cloning, no building. Installing the
+plugin already materializes this whole repo (pre-built engine included)
+where Claude Code can run it:
 
-- It is **not a plugin**: you don't install it through `/plugin` or a marketplace.
-- It is **not a skill**: it doesn't live under `.claude/skills/` and isn't invoked
-  through the Skill tool.
-- It is a **script for Claude Code's `Workflow` tool**: you clone this repo anywhere on
-  your machine, and Claude Code runs the script by absolute path
-  (`scriptPath: <clone>/workflows/parallel-plan-executor.js`) when you ask it to.
+```
+/plugin marketplace add bacsystem/parallel-plan-executor
+/plugin install cys@bacsystem
+```
 
-The only piece of it that gets "installed" in the Claude Code sense is the optional
-`/run-plan` slash command (a single `.md` file you copy — see below), or the **cys
-plugin** described next.
+Then, from any Claude Code session:
 
-## The cys plugin
+> `/cys:flow /absolute/path/to/your-project "describe what you want built"`
 
-**cys** is this repo's skill plugin: five skills covering the whole flow
-**design → plan → run → check → ship**, created by Christian Bacilio and named
-after his twin daughters, **Cielo y Sophia**.
+That's the whole flow — design, plan, and (Claude Code only) a real
+parallel run — with your approval at each gate. See
+[Installing the cys plugin](#installing-the-cys-plugin) for Cursor and
+Gemini CLI, and [Using cys](#using-cys) for the full first-run walkthrough
+once you're past the quick version.
 
-| Skill | What it does |
-|---|---|
-| `cys:design` | idea → spec |
-| `cys:plan` | spec → implementation plan |
-| `cys:run` | the Workflow in this repo — launched via `/cys:run-plan` or `commands/run-plan.md`. **Claude Code only** (see "Multi-AI support" below). |
-| `cys:check` | adversarial review / verification |
-| `cys:ship` | commit / SemVer bump / PR |
-| `cys:guide` | index — which skill to use when |
+On other platforms (Cursor, Gemini CLI), the plugin gives you `cys:design`
+and `cys:plan`; `cys:guide` tells you how to execute the resulting plan's
+tasks yourself, since `cys:run`'s parallel engine is Claude Code only.
 
-The plugin also ships `/cys:flow` (Claude Code only) — the all-in-one
-entry point: give it a target repo and an idea, and it walks the whole
-flow (design → plan → parallel run) with your approval gates at each
-stage. Use `/cys:run-plan` instead when an approved plan already exists.
-
-## Multi-AI support
+## Installing the cys plugin
 
 cys's five non-engine skills (`design`, `plan`, `check`, `ship`, `guide`)
 are plain Markdown with no Claude-Code-specific coupling, so they're
@@ -119,7 +207,7 @@ own Settings UI (confirmed working — Cursor's plugin UI changed after
 this section was first written, so trust these steps over any older
 screenshot you find elsewhere):
 
-1. Clone this repo (see [Installation](#installation) below — for just
+1. Clone this repo (see [Building from source](#building-from-source) below — for just
    the skills, cloning is enough, you don't need to build the workflow
    artifact or run its test suite).
 2. In Cursor: **Settings → Plugins** (or the **Customize** panel, if
@@ -182,72 +270,28 @@ skills available in every project — not just the one you ran the
 command from. Since install copies rather than tracks the repo live, run
 `gemini extensions update cys` to pick up future releases.
 
-`cys:run`'s parallel execution stays Claude-Code-only (see Requirements
-below): on Gemini CLI, `cys:guide` tells you how to execute a plan's
-tasks yourself instead.
-
-## Requirements
-
-- **[Claude Code](https://claude.com/claude-code)**, with access to the `Workflow` tool.
-  This is **not optional or swappable for another AI assistant**: the script in
-  `workflows/parallel-plan-executor.js` is written against that tool's primitives
-  (`agent()`, `pipeline()`, `parallel()`, etc.) — it isn't an open standard another
-  assistant (ChatGPT, Gemini, etc.) can interpret. What *is* agnostic is the **target
-  project** being automated: it can be Go, Node, Java, or whatever stack the plan
-  describes.
-- **The cys plugin** (see above) for authoring plans with `cys:plan`. The engine is
-  fully self-contained: the workflow ships its own `task-brief`/`review-package`
-  scripts in `bin/` and records runs under `.cys/`. Any plan following the
-  `### Task N:` + `Consumes`/`Produces` format works, whatever tool wrote it.
-- **Node.js >= 20** (for `bin/parse-plan.js` and the test suite — no runtime
-  dependencies, just standard Node).
-- Git, and a clean working tree in the project you're automating.
-- `gh` (GitHub CLI) installed and authenticated, **only if** you'll use `openPr: true`
-  (so the workflow can create the final PR).
-
-## Installation
-
-```bash
-# 1. Clone this repo (where the workflow lives) onto your machine.
-#    WHERE: anywhere you like — your home folder, a tools directory, etc.
-#    It does NOT need to be inside .claude/, and it does NOT need to live next to
-#    the projects you'll automate; every path you pass it later is absolute.
-git clone <this-repo-url> parallel-plan-executor
-cd parallel-plan-executor
-
-# 2. Check your Node version (must be >= 20)
-node --version
-
-# 3. Install (no runtime dependencies; this just wires up the npm scripts)
-npm install
-
-# 4. Run the test suite to confirm everything works in your environment
-npm test
-
-# 5. Build the workflow artifact (regenerates workflows/parallel-plan-executor.js
-#    from the template — also re-run this after any change under src/)
-npm run build
-```
-
-That's it — the workflow is invoked **from a Claude Code session**, no need to publish
-it to npm or install it globally. See Usage below. Before your first real run, also do
-the one-time **permissions setup** below so task merges don't get blocked mid-run.
+`cys:run`'s parallel execution stays Claude-Code-only (see
+[Building from source](#building-from-source) below): on Gemini CLI,
+`cys:guide` tells you how to execute a plan's tasks yourself instead.
 
 ## One-time permissions setup (merges)
 
-The workflow's merge agents run `git merge` inside your target repo. Claude Code treats
-an agent merging code as a sensitive action, and what happens depends on your
-permission mode:
+Do this once, before your first real `cys:run`, so task merges don't get
+blocked mid-run.
+
+The workflow's merge agents run `git merge` inside your target repo. Claude
+Code treats an agent merging code as a sensitive action, and what happens
+depends on your permission mode:
 
 - **Default (normal) mode**: nothing to configure. The first time a merge agent runs
   `git merge`, you get Claude Code's native permission dialog — **Allow once / Allow
   always / Deny**. Pick "Allow always" on the first one and the rest of the run flows
   without asking again.
-- **Auto mode**: there is no dialog by default — an automatic classifier decides alone,
-  and it may block agent merges even when you authorized the run up front (see the
-  permissions note further down for why). To get the same yes/no dialog as normal mode,
-  add an **`ask` rule** to the **target project's** `.claude/settings.json` (create the
-  file if needed):
+- **Auto mode**: there is no dialog by default — an automatic classifier decides
+  alone, and it may block agent merges even when you authorized the run up front (see
+  the permissions note in [branching topology](#recommended-branching-topology) for
+  why). To get the same yes/no dialog as normal mode, add an **`ask` rule** to the
+  **target project's** `.claude/settings.json` (create the file if needed):
 
 ```json
 {
@@ -265,27 +309,20 @@ deterministically, regardless of mode — you just click, never type. If you'd r
 never be asked, use `"allow"` instead of `"ask"` (the run becomes fully hands-off; the
 human gate moves to the final PR review).
 
-## How it works
+## Using cys
 
-1. `bin/parse-plan.js` reads a plan file and computes its task list + dependency graph
-   (pure Node, fully unit tested — see `tests/`).
-2. `workflows/parallel-plan-executor.js` (built from `workflows-src/parallel-plan-executor.template.js`
-   via `npm run build`) takes that graph and runs each task in its own git worktree via
-   `agent()`, starting a task the moment its specific dependencies finish rather than
-   waiting for a whole batch.
-3. Each task gets an adversarial review agent instead of a human checkpoint per task,
-   since a `Workflow` can't pause mid-run to ask you anything.
-4. Merges happen one at a time, serialized, respecting the dependency order.
-5. You get a single report at the end, and — if at least one task merged — a **Handoff**
-   agent prepares the git-flow closing for you (see below).
+This section walks the full first-run experience, then covers the
+reference pieces (manual invocation, the `/run-plan` command, the
+Handoff phase, branch topology) for when you need more control than
+`/cys:flow` gives you.
 
-## Step-by-step guide (first time using this)
+### Step-by-step guide (first time using this)
 
-This section is for anyone who hasn't run the workflow before and wants to go through
-it without getting lost. If you already know it, the "Usage" section below is the quick
-reference.
+This subsection is for anyone who hasn't run the workflow before and wants to go
+through it without getting lost. If you already know it, [Manual
+invocation](#manual-invocation-reference) below is the quick reference.
 
-### Step 0 — What you need ready before starting
+#### Step 0 — What you need ready before starting
 
 - **An approved implementation plan**, with numbered tasks and their
   `Consumes`/`Produces` blocks (the format produced by the `cys:plan` skill). If you
@@ -295,17 +332,17 @@ reference.
 - **The repo you're automating**, with a clean working tree (`git status` shows no
   pending changes) and, if you'll request `openPr: true` at the end, a GitHub remote
   already configured with `gh auth status` green.
-- This repo (`parallel-plan-executor`) cloned and installed — see Installation above.
-  It doesn't need to live in the same folder as your project: the paths you pass it are
-  always absolute.
+- The cys plugin installed (see [Quick Start](#quick-start)) — no manual cloning
+  needed for this path. If you're driving the engine directly instead of through the
+  plugin commands, see [Building from source](#building-from-source).
 
-### Step 1 — Open a Claude Code session
+#### Step 1 — Open a Claude Code session
 
 It can be in your project's folder, in this repo's folder, or anywhere else — the
 workflow doesn't depend on where your Claude Code session is running, as long as you
 give it absolute paths to the plan and the target repo.
 
-### Step 2 — Ask Claude Code in plain language
+#### Step 2 — Ask Claude Code in plain language
 
 **You don't need to hand-write the `args` JSON.** That's Claude Code's job: you just
 tell it what you want in a sentence, with these pieces of information:
@@ -334,10 +371,10 @@ and invoking the `Workflow` tool with this repo's script — you never touch JSO
 > permission classifier in auto mode, it may require a human to explicitly authorize
 > merges — and that authorization needs to name the concrete action ("merge task-1
 > through task-6"), not a plain "yes" or "go ahead". Saying it upfront, with branches
-> named, avoids the run getting stuck partway through. See the permissions note below
-> for the technical detail.
+> named, avoids the run getting stuck partway through. See the permissions note in
+> [branching topology](#recommended-branching-topology) for the technical detail.
 
-### Step 3 — What you'll see while it runs
+#### Step 3 — What you'll see while it runs
 
 The workflow runs in the background — it doesn't wait for your reply. You'll see:
 
@@ -352,7 +389,7 @@ anything went wrong. You can also open Claude Code's `/workflows` panel to see t
 per-phase detail (Implement, Review, Merge, Final review, Handoff), how many agents and
 tokens each phase used, and each agent's timing.
 
-### Step 4 — If something gets stuck
+#### Step 4 — If something gets stuck
 
 The most common snag is a merge getting marked as blocked out of caution, **even after
 you authorized upfront** — that's an environment safety measure, not a flaw in your
@@ -364,18 +401,19 @@ plan. If that happens:
 3. The run is recoverable: nothing already done is lost. Tasks that already finished
    (implemented, reviewed, merged) don't re-run — only what's still pending retries.
 
-### Step 5 — When it finishes
+#### Step 5 — When it finishes
 
 - If **at least one task merged**, you'll have a `.cys/handoff.md` file in
   your project with: the suggested PR title and body, the proposed SemVer bump, and a
-  cleanup checklist (which `task-N` branches to delete and when).
+  cleanup checklist (which `task-N` branches to delete and when) — see
+  [Handoff phase](#handoff-phase) for the full detail.
 - If you requested `openPr: true`, the PR is **already created** in GitHub against the
   branch you specified — review it yourself and merge it whenever you're satisfied. The
   workflow never merges the PR on its own; that decision always stays in your hands.
 - If any task failed or got blocked, the final report will tell you exactly which one
   and why — and which other tasks were skipped in cascade because they depended on it.
 
-### Common errors
+#### Common errors
 
 | What you see | What it means |
 |---|---|
@@ -384,7 +422,10 @@ plan. If that happens:
 | The run stops partway through | It's recoverable: Claude Code can resume it without losing the work already done. |
 | The agent takes several minutes "doing nothing" when the first task starts | Normal — the first `implement` includes setting up the project's environment; you'll see the progress notice as soon as it's done. |
 
-## Usage
+### Manual invocation (reference)
+
+Once you know the flow, this is the raw shape of what `/cys:flow`/`/cys:run-plan`
+do for you — useful if you're scripting around cys or want to see every field:
 
 ```bash
 # 1. Compute the task graph for your plan
@@ -407,7 +448,7 @@ node bin/parse-plan.js /path/to/your-plan.md > /tmp/plan-graph.json
 #            mergeAuthorization: "I authorize merging task-1 through task-N into <branch>",
 #               # optional but recommended: your explicit authorization, so the merge
 #               # agent doesn't have to guess whether consent was already given (see the
-#               # permissions note below)
+#               # permissions note in branching topology below)
 #            maxConcurrency: 3                      # optional, default unlimited — see below
 #            }
 ```
@@ -418,13 +459,13 @@ Claude Code `Workflow` tool already queues excess `agent()` calls beyond its own
 many simultaneous local git worktrees on your own machine for a plan with a wide layer of
 independent tasks.
 
-## Optional: the `/run-plan` slash command
+### The `/run-plan` slash command
 
 If you'd rather not type out the natural-language request from the step-by-step guide
 every time, this repo ships a Claude Code custom slash command that wraps it:
 `commands/run-plan.md`.
 
-### Installing it
+#### Installing it
 
 1. Copy `commands/run-plan.md` from this repo to either:
    - `~/.claude/commands/run-plan.md` — available in **every** project on your machine, or
@@ -441,18 +482,19 @@ every time, this repo ships a Claude Code custom slash command that wraps it:
 3. That's it — no restart needed. Claude Code picks up commands under `.claude/commands/`
    the next time you use them.
 
-### Using it
+#### Using it
 
 ```
 /run-plan /path/to/your-plan.md /path/to/your/project feature/my-plan
 ```
 
 All three arguments are optional to type up front — the command will ask you for
-anything you leave out, plus whatever `Usage` above lists as optional (`openPr`, `pr`
-fields, your merge authorization). It never invents your authorization text on your
-behalf; it always asks you to name the branches yourself.
+anything you leave out, plus whatever [manual invocation](#manual-invocation-reference)
+above lists as optional (`openPr`, `pr` fields, your merge authorization). It never
+invents your authorization text on your behalf; it always asks you to name the branches
+yourself.
 
-## Handoff phase (v0.5.0)
+### Handoff phase
 
 When at least one task merged, a final **handoff agent** prepares the git-flow closing
 for you — without executing it. It writes `.cys/handoff.md` in the target
@@ -466,7 +508,7 @@ integration branch and **creates** the pull request via `gh` against `pr.base` (
 `develop`), applying the optional `pr` fields — assignees, labels, milestone, and
 `Closes #<closes>` in the body. **It never merges the PR**: that gate is human, always.
 
-## Recommended branching topology (validated in pilot 4)
+### Recommended branching topology
 
 Point `integrationBranch` at an **ephemeral feature branch cut from `develop`** — never
 at `develop`/`main` directly:
@@ -491,12 +533,85 @@ mode, an automatic classifier judges each agent action on its own, and agent-per
 (finding F8 in `docs/pilots/2026-07-15-pilot-stats-bitacora.md`) — but it does **not**
 bind the classifier: in a later real run the classifier explicitly rejected that relayed
 text as "self-asserted, unverifiable" consent and blocked the merge anyway. The
-deterministic fix is the **one-time permissions setup** near the top of this README: an
-`ask` (or `allow`) rule for `git merge` in the target project's `.claude/settings.json`,
-added by you. Rules take precedence over the mode — with the rule in place you get a
-plain yes/no dialog (or silent allow) instead of a classifier judgment call.
+deterministic fix is the [one-time permissions setup](#one-time-permissions-setup-merges)
+above: an `ask` (or `allow`) rule for `git merge` in the target project's
+`.claude/settings.json`, added by you. Rules take precedence over the mode — with the
+rule in place you get a plain yes/no dialog (or silent allow) instead of a classifier
+judgment call.
+
+## Building from source
+
+Only needed if you're **contributing to this repo**, or want to run the raw
+`Workflow` script without going through the plugin commands. If you just want
+to *use* cys, [Quick Start](#quick-start) is enough — installing the plugin
+already gives you a ready-to-run, pre-built copy.
+
+### Requirements
+
+- **[Claude Code](https://claude.com/claude-code)**, with access to the `Workflow` tool.
+  This is **not optional or swappable for another AI assistant**: the script in
+  `workflows/parallel-plan-executor.js` is written against that tool's primitives
+  (`agent()`, `pipeline()`, `parallel()`, etc.) — it isn't an open standard another
+  assistant (ChatGPT, Gemini, etc.) can interpret. What *is* agnostic is the **target
+  project** being automated: it can be Go, Node, Java, or whatever stack the plan
+  describes.
+- **The cys plugin** (see [Installing the cys plugin](#installing-the-cys-plugin)) for
+  authoring plans with `cys:plan`. The engine is fully self-contained: the workflow ships
+  its own `task-brief`/`review-package` scripts in `bin/` and records runs under `.cys/`.
+  Any plan following the `### Task N:` + `Consumes`/`Produces` format works, whatever
+  tool wrote it.
+- **Node.js >= 20** (for `bin/parse-plan.js` and the test suite — no runtime
+  dependencies, just standard Node).
+- Git, and a clean working tree in the project you're automating.
+- `gh` (GitHub CLI) installed and authenticated, **only if** you'll use `openPr: true`
+  (so the workflow can create the final PR).
+
+### Cloning and building
+
+```bash
+# 1. Clone this repo (where the workflow lives) onto your machine.
+#    WHERE: anywhere you like — your home folder, a tools directory, etc.
+#    It does NOT need to be inside .claude/, and it does NOT need to live next to
+#    the projects you'll automate; every path you pass it later is absolute.
+git clone <this-repo-url> parallel-plan-executor
+cd parallel-plan-executor
+
+# 2. Check your Node version (must be >= 20)
+node --version
 
-## Safety checks (v0.2)
+# 3. Install (no runtime dependencies; this just wires up the npm scripts)
+npm install
+
+# 4. Run the test suite to confirm everything works in your environment
+npm test
+
+# 5. Build the workflow artifact (regenerates workflows/parallel-plan-executor.js
+#    from the template — also re-run this after any change under src/)
+npm run build
+```
+
+That's it — the workflow is invoked **from a Claude Code session**, no need to publish
+it to npm or install it globally. See [Using cys](#using-cys) above. Before your first
+real run, also do the [one-time permissions setup](#one-time-permissions-setup-merges)
+so task merges don't get blocked mid-run.
+
+## How it works
+
+1. `bin/parse-plan.js` reads a plan file and computes its task list + dependency graph
+   (pure Node, fully unit tested — see `tests/`).
+2. `workflows/parallel-plan-executor.js` (built from `workflows-src/parallel-plan-executor.template.js`
+   via `npm run build`) takes that graph and runs each task in its own git worktree via
+   `agent()`, starting a task the moment its specific dependencies finish rather than
+   waiting for a whole batch.
+3. Each task gets an adversarial review agent instead of a human checkpoint per task,
+   since a `Workflow` can't pause mid-run to ask you anything.
+4. Merges happen one at a time, serialized, respecting the dependency order.
+5. You get a single report at the end, and — if at least one task merged — a **Handoff**
+   agent prepares the git-flow closing for you (see [Handoff phase](#handoff-phase)).
+
+## Safety checks & known limitations
+
+### Safety checks (v0.2)
 
 - **Startup validation**: the workflow validates `args` before launching any agent —
   a cyclic graph or an id present in `graph` but missing from `tasks` fails fast with a
@@ -509,7 +624,7 @@ plain yes/no dialog (or silent allow) instead of a classifier judgment call.
 - **Skip reasons point at the root cause**: a task skipped through a cascade reports the
   task that originally failed, not the intermediate skipped link.
 
-## Known limitations (v1)
+### Known limitations (v1)
 
 - Only backtick-quoted symbols count in `Consumes`/`Produces` (e.g.
   `` - Produces: the `createWidget()` factory `` produces `createWidget`). Bare prose is
@@ -529,7 +644,7 @@ plain yes/no dialog (or silent allow) instead of a classifier judgment call.
   preserve whatever partial state exists for diagnosis. Clean them up afterwards with
   `git branch -D task-<id>` once you no longer need them.
 
-## Reporting bugs
+## Reporting bugs & contributing
 
 Open an issue at
 [github.com/bacsystem/parallel-plan-executor/issues](https://github.com/bacsystem/parallel-plan-executor/issues)
@@ -542,3 +657,7 @@ write a fresh repro from scratch:
 - `.cys/task-<id>-report.md`, for the specific task that misbehaved.
 - `review-*.diff`, if a review flagged something.
 - The exact stderr/stdout of a failing command (e.g. `node bin/parse-plan.js`).
+
+Want to contribute code or docs? See `CONTRIBUTING.md` for this repo's
+evidence-driven discipline (every behavior change needs a test tracing to a real
+finding, plus a comment explaining why) and the TDD/build workflow.
diff --git a/examples/README.md b/examples/README.md
index a002faa..aacb3cb 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -26,4 +26,4 @@ read yourself right now.
 4. To actually run this plan in parallel (not just read its graph), point
    `cys:run` / `/cys:run-plan` at `examples/hello-parallel/plan.md`
    against a throwaway git repo of your own — see the main
-   [README](../README.md#usage) for the full launch steps.
+   [README](../README.md#using-cys) for the full launch steps.
diff --git a/gemini-extension.json b/gemini-extension.json
index c80df4d..7be5f77 100644
--- a/gemini-extension.json
+++ b/gemini-extension.json
@@ -1,6 +1,6 @@
 {
   "name": "cys",
-  "version": "0.6.18",
+  "version": "0.6.19",
   "description": "Development methodology skills for design, plan, check, and ship — parallel plan execution (cys:run) is Claude Code only for now.",
   "repository": "https://github.com/bacsystem/parallel-plan-executor",
   "license": "MIT"
diff --git a/package.json b/package.json
index a05f83f..c20da52 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "parallel-plan-executor",
-  "version": "0.6.18",
+  "version": "0.6.19",
   "author": "Christian Bacilio",
   "private": true,
   "type": "module",