diff --git a/AGENTS.md b/AGENTS.md
index 0b46dda..2347522 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,144 +1,157 @@
-# AGENTS.md — Guía para desarrolladores y agentes de IA
-
-Este fichero es la referencia operativa para cualquier persona o agente de IA que trabaje
-en el repositorio `docsai`. Léelo completo antes de tocar código.
-
-## 1. Qué es este proyecto
-
-`docsai` es un binario Rust multiplataforma (Windows/Linux/macOS) que convierte documentos
-Office (`.doc`, `.docx`, `.xls`, `.xlsx`) y LibreOffice (`.odt`, `.ods`) a un Markdown
-extendido llamado **DocMark**, y de vuelta, con pérdida mínima de formato. Se invoca como
-CLI o como servidor **MCP por stdio**.
-
-**Estado actual**: **Fases 0 y 1 cerradas**. Existe el workspace con los siete crates, el IR
-(`docsai-model`), el lector `.docx` (`docsai-office`), el serializador DocMark
-(`docsai-docmark`), la orquestación (`docsai-convert`) y la CLI con `convert` y `formats`.
-`docsai-odf` y `docsai-mcp` son esqueletos que sólo fijan las reglas de dependencia.
-
-Lo siguiente es la **Fase 2**: parser DocMark, writer `.docx` y el comando `roundtrip`.
-
-## 2. Documentos que debes leer antes de implementar
-
-Orden de lectura obligatorio:
-
-1. `docs/plan-desarrollo.md` — el plan por fases. **Identifica en qué fase está el proyecto
-   antes de escribir nada.** No implementes elementos de fases futuras.
-2. `docs/arquitectura.md` — estructura del workspace, modelo IR, contratos entre crates.
-3. `docs/especificacion-docmark.md` — el formato Markdown extendido. Es un contrato:
-   cualquier cambio requiere subir la versión del campo `docmark` del front matter y
-   documentar la migración.
-4. `docs/analisis-tecnico.md` — por qué se eligió cada librería. No sustituyas una
-   dependencia clave (calamine, docx-rs, rmcp, comrak…) sin dejar constancia escrita del
-   motivo en ese documento.
-5. `kb/` — base de conocimiento de lo **ya construido**: resumen de las fases cerradas,
-   estructura real del código, decisiones técnicas con su motivo, y las consideraciones para
-   la fase que vayas a abordar. Empieza por `kb/README.md`. Si tu cambio altera la estructura
-   o toma una decisión técnica no obvia, actualízala en el mismo PR.
-
-## 3. Estructura del repositorio (objetivo)
+# AGENTS.md — Guide for developers and AI agents
+
+This file is the operational reference for anyone or any AI agent working
+on the `docsai` repository. Read it fully before touching code.
+
+## 1. What this project is
+
+`docsai` is a cross-platform Rust binary (Windows/Linux/macOS) that converts
+Office documents (`.doc`, `.docx`, `.xls`, `.xlsx`) and LibreOffice documents
+(`.odt`, `.ods`) to an extended Markdown called **DocMark**, and back, with
+minimal format loss. It is invoked as a CLI or as an **MCP server over stdio**.
+
+**Current status**: **Phases 0–2 are closed** for the core path. The workspace
+has the seven crates, the IR (`docsai-model`), the `.docx` reader **and writer**
+(`docsai-office`), DocMark serialize **and parse** (`docsai-docmark`),
+orchestration (`docsai-convert`), and the CLI with `convert`, `formats` and
+`roundtrip`. `docsai-odf` and `docsai-mcp` remain skeletons that only fix the
+dependency rules.
+
+Next up is **Phase 3**: spreadsheets (`.xlsx` / `.xls` ⇄ DocMark).
+
+## 2. Documents you must read before implementing
+
+Mandatory reading order:
+
+1. `docs/development-plan.md` — the phased plan. **Identify which phase the
+   project is in before writing anything.** Do not implement items from future
+   phases.
+2. `docs/architecture.md` — workspace structure, IR model, contracts between
+   crates.
+3. `docs/docmark-specification.md` — the extended Markdown format. It is a
+   contract: any change requires bumping the `docmark` field version in the
+   front matter and documenting the migration.
+4. `docs/technical-analysis.md` — why each library was chosen. Do not replace a
+   key dependency (calamine, docx-rs, rmcp, comrak…) without leaving a written
+   record of the reason in that document.
+5. `kb/` — knowledge base of what is **already built**: summary of closed
+   phases, real code structure, technical decisions with their rationale, and
+   considerations for the phase you are about to tackle. Start with
+   `kb/README.md`. If your change alters the structure or takes a non-obvious
+   technical decision, update it in the same PR.
+
+## 3. Repository structure (target)
 
 ```
 docsai/
-├── Cargo.toml                # workspace raíz
+├── Cargo.toml                # root workspace
 ├── crates/
-│   ├── docsai-model/         # IR: modelo de documento intermedio (sin I/O, sin deps pesadas)
-│   ├── docsai-docmark/       # serializador + parser de DocMark (IR ⇄ Markdown extendido)
-│   ├── docsai-office/        # lectores/escritores OOXML: docx, xlsx (+ xls, doc lectura)
-│   ├── docsai-odf/           # lectores/escritores ODF: odt, ods
-│   ├── docsai-convert/       # orquestación: pipelines, detección de formato, assets, informes de fidelidad
-│   ├── docsai-cli/           # binario CLI (clap)
-│   └── docsai-mcp/           # servidor MCP stdio (rmcp)
-├── docs/                     # documentación de diseño (este conjunto)
-├── corpus/                   # documentos de prueba versionados (ver §6)
-└── tests/                    # tests de integración y round-trip
+│   ├── docsai-model/         # IR: intermediate document model (no I/O, no heavy deps)
+│   ├── docsai-docmark/       # DocMark serializer + parser (IR ⇄ extended Markdown)
+│   ├── docsai-office/        # OOXML readers/writers: docx, xlsx (+ xls, doc read)
+│   ├── docsai-odf/           # ODF readers/writers: odt, ods
+│   ├── docsai-convert/       # orchestration: pipelines, format detection, assets, fidelity reports
+│   ├── docsai-cli/           # CLI binary (clap)
+│   └── docsai-mcp/           # MCP stdio server (rmcp)
+├── docs/                     # design documentation (this set)
+├── corpus/                   # versioned test documents (see §6)
+└── tests/                    # integration and round-trip tests
 ```
 
-Reglas de dependencia entre crates (violarlas es un error de arquitectura):
+Dependency rules between crates (violating them is an architecture error):
 
-- `docsai-model` no depende de ningún otro crate del workspace.
-- `docsai-docmark`, `docsai-office`, `docsai-odf` dependen **solo** de `docsai-model`.
-- `docsai-convert` depende de los cuatro anteriores. `docsai-cli` y `docsai-mcp`
-  dependen solo de `docsai-convert` (y `docsai-model` para tipos).
-- Ningún crate de formato importa a otro crate de formato.
+- `docsai-model` depends on no other crate in the workspace.
+- `docsai-docmark`, `docsai-office`, `docsai-odf` depend **only** on `docsai-model`.
+- `docsai-convert` depends on the four above. `docsai-cli` and `docsai-mcp`
+  depend only on `docsai-convert` (and `docsai-model` for types).
+- No format crate imports another format crate.
 
-## 4. Comandos de trabajo
+## 4. Working commands
 
-Cuando exista el workspace, estos son los comandos canónicos (deben mantenerse verdes):
+When the workspace exists, these are the canonical commands (they must stay green):
 
 ```bash
 cargo build --workspace
-cargo test --workspace                 # unit + integración + round-trip
+cargo test --workspace                 # unit + integration + round-trip
 cargo clippy --workspace --all-targets -- -D warnings
 cargo fmt --all -- --check
 cargo run -p docsai-cli -- convert corpus/docx/basic-styles.docx -o /tmp/out.dmk.md
-python3 corpus/generate.py --check     # el corpus es generado; CI comprueba que está al día
+python3 corpus/generate.py --check     # the corpus is generated; CI checks it is up to date
 ```
 
-Actualizar un golden es un acto deliberado, y su diff se revisa a mano:
+Updating a golden is a deliberate act, and its diff is reviewed by hand:
 
 ```bash
 DOCSAI_UPDATE_GOLDENS=1 cargo test -p docsai-convert --test goldens
 ```
 
-CI (GitHub Actions) ejecuta la matriz `{ubuntu-latest, windows-latest, macos-latest}` ×
-`{stable}`. Un PR no se fusiona con CI en rojo.
-
-## 5. Convenciones de código
-
-- **Edición Rust 2021+ / toolchain stable**. Nada de `nightly` en el árbol principal.
-- `rustfmt` por defecto y `clippy -D warnings`. Sin excepciones sin comentario `#[allow]` justificado.
-- Errores: `thiserror` en las bibliotecas, `anyhow` solo en los binarios (`docsai-cli`, `docsai-mcp`).
-- Logging: `tracing`. En el servidor MCP **jamás escribir en stdout** salvo el protocolo
-  (stdout es el canal JSON-RPC); logs siempre a stderr.
-- Nombres de código, mensajes de commit y comentarios de código en **inglés**;
-  la documentación de `docs/` se mantiene en español.
-- Commits: Conventional Commits (`feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:`),
-  con ámbito de crate cuando aplique: `feat(office): read numbering.xml`.
-- `unsafe` prohibido salvo justificación documentada en el PR (no debería ser necesario).
-- Toda función pública de los crates de biblioteca lleva doc-comment con ejemplo cuando sea razonable.
-
-## 6. Estrategia de pruebas (resumen; detalle en el plan §Fase 0 y §Fase 8)
-
-- **Corpus versionado** en `corpus/`: documentos pequeños creados a propósito, un rasgo
-  por fichero (`basic-styles.docx`, `nested-lists.docx`, `formulas-basic.xlsx`…). Nunca
-  añadir documentos con datos reales o privados.
-- **Golden files**: cada documento del corpus tiene su DocMark esperado al lado
-  (`.expected.dmk.md`). Los tests comparan la salida con el golden; actualizar un golden
-  requiere revisar el diff a mano.
-- **Round-trip tests**: `Office → DocMark → Office → DocMark` debe producir DocMark
-  idéntico en la segunda pasada (idempotencia). La comparación primera-vs-segunda pasada
-  del fichero Office se hace a nivel de IR normalizado, no de bytes.
-- **Fuzzing** (`cargo-fuzz`) sobre los parsers de entrada a partir de la Fase 8; los
-  parsers nunca deben entrar en pánico con entrada corrupta: siempre `Err`, nunca `panic!`.
-
-## 7. Reglas específicas para agentes de IA
-
-1. **No amplíes el alcance.** Si la tarea pide la Fase N, no adelantes trabajo de la fase
-   N+1 "ya que estás". El plan define el orden por dependencias reales.
-2. **No cambies la especificación DocMark para hacer pasar un test.** Si el formato no
-   puede representar algo, documenta la limitación y usa el mecanismo `raw-block` descrito
-   en la especificación.
-3. **Nunca degrades la fidelidad en silencio.** Toda pérdida de información en una
-   conversión debe emitir una advertencia estructurada (ver `ConversionReport` en
-   `docs/arquitectura.md`).
-4. **No añadas dependencias pesadas sin justificación.** El objetivo es un binario único y
-   razonablemente pequeño. Antes de añadir un crate: ¿está mantenido?, ¿es pure-Rust?,
-   ¿qué añade al tamaño del binario? Deja la justificación en el PR.
-5. **Documenta al terminar.** Si tu cambio altera comportamiento visible (CLI, formato,
-   tools MCP), actualiza README.md y el documento de `docs/` correspondiente en el mismo PR.
-6. **Verifica en las tres plataformas mentales.** Rutas con `std::path` (nunca concatenar
-   con `/`), finales de línea (el serializador DocMark emite siempre `\n`; el parser acepta
-   `\r\n`), y nada de dependencias de herramientas POSIX en el código de producción.
-7. Trabaja en ramas y push a la rama que se te indique; no hagas push a `main`.
-
-## 8. Definición de "hecho" (Definition of Done)
-
-Una tarea/fase se considera terminada cuando:
-
-- [ ] Compila y pasa `cargo test --workspace` en las tres plataformas de CI.
-- [ ] `clippy` y `fmt` limpios.
-- [ ] Tests nuevos cubren el comportamiento añadido (incluidos casos de error).
-- [ ] Golden files y corpus actualizados si aplica.
-- [ ] Documentación actualizada (README, docs/, `--help` de la CLI).
-- [ ] Los criterios de aceptación de la fase correspondiente en `docs/plan-desarrollo.md`
-      están marcados y verificados.
+CI (GitHub Actions) runs the matrix `{ubuntu-latest, windows-latest, macos-latest}` ×
+`{stable}`. A PR is not merged with red CI.
+
+## 5. Code conventions
+
+- **Rust edition 2021+ / stable toolchain**. No `nightly` in the main tree.
+- Default `rustfmt` and `clippy -D warnings`. No exceptions without a justified
+  `#[allow]` comment.
+- Errors: `thiserror` in libraries, `anyhow` only in binaries (`docsai-cli`,
+  `docsai-mcp`).
+- Logging: `tracing`. In the MCP server **never write to stdout** except for the
+  protocol (stdout is the JSON-RPC channel); logs always go to stderr.
+- **Hard language rule: everything is English.** All documentation (`docs/`,
+  `kb/`, `README.md`, `AGENTS.md`), code identifiers, commit messages, and code
+  comments **must** be in English. Do not write Spanish (or any other language)
+  in those places.
+- Commits: Conventional Commits (`feat:`, `fix:`, `docs:`, `test:`, `refactor:`,
+  `chore:`), with crate scope when applicable: `feat(office): read numbering.xml`.
+- `unsafe` is forbidden unless justified in the PR documentation (it should not
+  be necessary).
+- Every public function in library crates has a doc-comment with an example when
+  reasonable.
+
+## 6. Testing strategy (summary; detail in the plan §Phase 0 and §Phase 8)
+
+- **Versioned corpus** in `corpus/`: small documents created on purpose, one
+  trait per file (`basic-styles.docx`, `nested-lists.docx`,
+  `formulas-basic.xlsx`…). Never add documents with real or private data.
+- **Golden files**: each corpus document has its expected DocMark beside it
+  (`.expected.dmk.md`). Tests compare output against the golden; updating a
+  golden requires reviewing the diff by hand.
+- **Round-trip tests**: `Office → DocMark → Office → DocMark` must produce
+  identical DocMark on the second pass (idempotence). First-vs-second pass
+  comparison of the Office file is done at the normalized IR level, not bytes.
+- **Fuzzing** (`cargo-fuzz`) on input parsers from Phase 8 onward; parsers must
+  never panic on corrupt input: always `Err`, never `panic!`.
+
+## 7. Specific rules for AI agents
+
+1. **Do not expand scope.** If the task asks for Phase N, do not advance Phase
+   N+1 work "while you are at it". The plan defines order by real dependencies.
+2. **Do not change the DocMark specification to make a test pass.** If the
+   format cannot represent something, document the limitation and use the
+   `raw-block` mechanism described in the specification.
+3. **Never degrade fidelity silently.** Every information loss in a conversion
+   must emit a structured warning (see `ConversionReport` in
+   `docs/architecture.md`).
+4. **Do not add heavy dependencies without justification.** The goal is a single,
+   reasonably small binary. Before adding a crate: is it maintained? is it
+   pure-Rust? what does it add to binary size? Leave the justification in the PR.
+5. **Document when you finish.** If your change alters visible behavior (CLI,
+   format, MCP tools), update README.md and the corresponding document under
+   `docs/` in the same PR.
+6. **Verify against the three mental platforms.** Paths with `std::path` (never
+   concatenate with `/`), line endings (the DocMark serializer always emits
+   `\n`; the parser accepts `\r\n`), and no POSIX tool dependencies in production
+   code.
+7. Work on branches and push to the branch you are told; do not push to `main`.
+
+## 8. Definition of Done
+
+A task/phase is considered finished when:
+
+- [ ] It compiles and passes `cargo test --workspace` on all three CI platforms.
+- [ ] `clippy` and `fmt` are clean.
+- [ ] New tests cover the added behavior (including error cases).
+- [ ] Golden files and corpus are updated if applicable.
+- [ ] Documentation is updated (README, docs/, CLI `--help`).
+- [ ] The acceptance criteria for the corresponding phase in
+      `docs/development-plan.md` are marked and verified.
diff --git a/README.md b/README.md
index 72ab3cc..908d4ae 100644
--- a/README.md
+++ b/README.md
@@ -1,103 +1,104 @@
 # docsai
 
-**Conversor bidireccional de documentos Office / LibreOffice ⇄ Markdown extendido, escrito en Rust.**
+**Bidirectional converter between Office / LibreOffice documents and extended Markdown, written in Rust.**
 
-`docsai` es un binario único y multiplataforma (Windows, Linux, macOS) que convierte documentos ofimáticos a un perfil de Markdown extendido — **DocMark** — diseñado para conservar la máxima información posible (estilos, imágenes, propiedades, fórmulas) y permitir la **conversión inversa con pérdida mínima de formato**. Puede usarse como herramienta CLI o como **servidor MCP (Model Context Protocol) por stdio**, para integrarse con asistentes de IA como Claude.
+`docsai` is a single cross-platform binary (Windows, Linux, macOS) that converts office documents to an extended Markdown profile — **DocMark** — designed to keep as much information as possible (styles, images, properties, formulas) and to allow the **reverse conversion with minimal format loss**. It can be used as a CLI tool or as an **MCP (Model Context Protocol) server over stdio**, for integration with AI assistants such as Claude.
 
-> **Estado del proyecto: Fases 0 y 1 completadas.**
-> Ya se convierte `.docx` → DocMark con estilos, listas, tablas, imágenes (con toda su
-> geometría), cabeceras, pies, notas al pie, campos y propiedades. La conversión inversa
-> (DocMark → `.docx`) es la Fase 2 y todavía no existe; las hojas de cálculo llegan en la
-> Fase 3. Ver [`docs/plan-desarrollo.md`](docs/plan-desarrollo.md).
+> **Project status: Phases 0–2 completed.**
+> `.docx` ⇄ DocMark works with styles, lists, tables, images, headers/footers,
+> footnotes, fields and properties. `docsai roundtrip` checks DocMark idempotence
+> after a write/read cycle. Spreadsheets arrive in Phase 3. See
+> [`docs/development-plan.md`](docs/development-plan.md).
 
 ```bash
-cargo run -p docsai-cli -- convert informe.docx -o informe.dmk.md
+cargo run -p docsai-cli -- convert report.docx -o report.dmk.md
 cargo run -p docsai-cli -- formats
 ```
 
 ---
 
-## Formatos soportados (objetivo)
+## Supported formats (target)
 
-✅ = funciona hoy · 🕓 = planificado, con la fase que lo trae · ➖ = fuera de alcance
+✅ = works today · 🕓 = planned, with the phase that lands it · ➖ = out of scope
 
-| Formato | Extensión | Lectura | Escritura | Notas |
+| Format | Extension | Read | Write | Notes |
 |---|---|---|---|---|
-| Word OOXML | `.docx` | ✅ | 🕓 Fase 2 | Estilos, imágenes, tablas, listas, cabeceras/pies, notas al pie, campos, propiedades |
-| Word binario | `.doc` | 🕓 Fase 5 | ➖ | Solo lectura (vía parser nativo o fallback LibreOffice headless) |
-| Excel OOXML | `.xlsx` | 🕓 Fase 3 | 🕓 Fase 3 | Valores **y fórmulas**, formatos de número, celdas combinadas, imágenes ancladas |
-| Excel binario | `.xls` | 🕓 Fase 3 | ➖ | Solo lectura (calamine) |
-| OpenDocument Text | `.odt` | 🕓 Fase 4 | 🕓 Fase 4 | Equivalente libre de `.docx` |
-| OpenDocument Spreadsheet | `.ods` | 🕓 Fase 4 | 🕓 Fase 4 | Equivalente libre de `.xlsx` |
-| Markdown extendido | `.dmk.md` | 🕓 Fase 2 | ✅ | Formato pivote **DocMark** (superconjunto de CommonMark + GFM) |
+| Word OOXML | `.docx` | ✅ | ✅ | Styles, images, tables, lists, headers/footers, footnotes, fields, properties |
+| Word binary | `.doc` | 🕓 Phase 5 | ➖ | Read only (native parser or LibreOffice headless fallback) |
+| Excel OOXML | `.xlsx` | 🕓 Phase 3 | 🕓 Phase 3 | Values **and formulas**, number formats, merged cells, anchored images |
+| Excel binary | `.xls` | 🕓 Phase 3 | ➖ | Read only (calamine) |
+| OpenDocument Text | `.odt` | 🕓 Phase 4 | 🕓 Phase 4 | Free equivalent of `.docx` |
+| OpenDocument Spreadsheet | `.ods` | 🕓 Phase 4 | 🕓 Phase 4 | Free equivalent of `.xlsx` |
+| Extended Markdown | `.dmk.md` | ✅ | ✅ | Pivot format **DocMark** (superset of CommonMark + GFM) |
 
-`docsai formats` imprime esta misma matriz según lo que el binario realmente sabe hacer.
+`docsai formats` prints this same matrix for what the binary can actually do.
 
-La escritura de `.doc` y `.xls` (formatos binarios legados) queda fuera de alcance de forma deliberada: la ruta de salida recomendada hacia el ecosistema Microsoft es siempre OOXML (`.docx` / `.xlsx`).
+Writing `.doc` and `.xls` (legacy binary formats) is deliberately out of scope: the recommended output path into the Microsoft ecosystem is always OOXML (`.docx` / `.xlsx`).
 
-## ¿Qué es DocMark?
+## What is DocMark?
 
-DocMark es un perfil de Markdown extendido definido en este proyecto (ver [`docs/especificacion-docmark.md`](docs/especificacion-docmark.md)). Es **Markdown legible y editable a mano**, que se renderiza de forma razonable en GitHub o cualquier visor CommonMark, pero que añade capas de metadatos para no perder información:
+DocMark is an extended Markdown profile defined in this project (see [`docs/docmark-specification.md`](docs/docmark-specification.md)). It is **human-readable and hand-editable Markdown** that renders reasonably on GitHub or any CommonMark viewer, but adds metadata layers so information is not lost:
 
-- **Front matter YAML** con las propiedades del documento (título, autor, idioma…) y el **catálogo de estilos** original.
-- **Atributos inline y de bloque** `{#id .clase clave="valor"}` (sintaxis compatible con Pandoc) para anclar estilos, dimensiones de imagen, propiedades de celda, etc.
-- **Contenedores fenced** `::: {...}` para secciones, cuadros de texto, cabeceras y pies.
-- **Tablas extendidas** con metadatos por celda (fórmulas, tipos, formatos de número, combinaciones) para hojas de cálculo.
-- **Activos externos**: las imágenes se extraen a un directorio `assets/` (deduplicadas por hash de contenido) y se referencian con un modelo completo de atributos de geometría: tamaño mostrado y nativo, posición y anclaje (en línea, flotante con wrap y z-order, o anclada a celdas en hojas de cálculo), rotación, recorte, volteo, texto alternativo e hipervínculo.
-- **Escotilla de fidelidad** (`raw-block`) para fragmentos sin representación Markdown posible, que se conservan de forma opaca y se restauran en la conversión inversa.
+- **YAML front matter** with document properties (title, author, language…) and the original **style catalogue**.
+- **Inline and block attributes** `{#id .class key="value"}` (Pandoc-compatible syntax) to attach styles, image dimensions, cell properties, and more.
+- **Fenced containers** `::: {...}` for sections, text boxes, headers and footers.
+- **Extended tables** with per-cell metadata (formulas, types, number formats, merges) for spreadsheets.
+- **External assets**: images are extracted to an `assets/` directory (deduplicated by content hash) and referenced with a full geometry attribute model: display and native size, position and anchoring (inline, floating with wrap and z-order, or cell-anchored in spreadsheets), rotation, crop, flip, alternative text and hyperlink.
+- **Fidelity hatch** (`raw-block`) for fragments with no Markdown representation, kept opaque and restored on the reverse conversion.
 
-Ejemplo mínimo:
+Minimal example:
 
 ```markdown
 ---
 docmark: "1.0"
 source-format: docx
-title: "Informe Anual"
+title: "Annual Report"
 styles:
   Heading1: { font: "Calibri Light", size: 16pt, color: "#2E74B5" }
 ---
 
-# Informe Anual {.Heading1}
+# Annual Report {.Heading1}
 
-Texto con **negrita** y [color]{color="#FF0000"} personalizado.
+Text with **bold** and [color]{color="#FF0000"} custom colour.
 
-![Diagrama de ventas](assets/img-001.png){width=450px height=300px anchor=inline}
+![Sales chart](assets/img-001.png){width=450px height=300px anchor=inline}
 ```
 
-## Uso (CLI)
+## Usage (CLI)
 
-Lo que funciona hoy:
+What works today:
 
 ```bash
-docsai convert informe.docx -o informe.dmk.md      # extrae assets/ junto al .md
-docsai convert informe.docx                         # a stdout, sin escribir medios al lado
-docsai convert informe.docx --fidelity plain        # CommonMark limpio, para LLM/RAG
-docsai convert informe.docx -o out.md --json        # informe de conversión en JSON
-docsai formats                                      # matriz de soporte de este binario
+docsai convert report.docx -o report.dmk.md      # extracts assets/ next to the .md
+docsai convert report.docx                         # to stdout, without writing media beside it
+docsai convert report.docx --fidelity plain        # clean CommonMark, for LLM/RAG
+docsai convert report.docx -o out.md --json        # conversion report as JSON
+docsai formats                                      # support matrix for this binary
 ```
 
-Grados de fidelidad (`--fidelity`, spec §6): `full` (defecto, apto para ida y vuelta),
-`standard` (Markdown rico sin catálogos ni raw-blocks) y `plain` (CommonMark+GFM puro).
+Fidelity levels (`--fidelity`, spec §6): `full` (default, round-trip grade),
+`standard` (rich Markdown without catalogues or raw-blocks) and `plain` (pure
+CommonMark+GFM).
 
-Códigos de salida: `0` correcto, `1` conversión con pérdidas (`--strict` incluye las advertencias
-menores), `2` error de entrada, `3` formato no soportado.
+Exit codes: `0` success, `1` conversion with losses (`--strict` also treats minor
+warnings as failures), `2` input error, `3` unsupported format.
 
-Planificado:
+Planned:
 
 ```bash
-docsai convert informe.dmk.md -o informe.docx   # Fase 2
-docsai convert ventas.xlsx -o ventas.dmk.md      # Fase 3
-docsai inspect informe.docx                      # Fase 6
-docsai roundtrip informe.docx                    # Fase 2
+docsai convert report.dmk.md -o report.docx
+docsai convert sales.xlsx -o sales.dmk.md      # Phase 3
+docsai inspect report.docx                      # Phase 6
+docsai roundtrip report.docx
 ```
 
-## Uso previsto (servidor MCP, Fase 7)
+## Intended usage (MCP server, Phase 7)
 
 ```bash
-docsai mcp        # arranca el servidor MCP por stdio
+docsai mcp        # starts the MCP server over stdio
 ```
 
-Registro en un cliente MCP (p. ej. Claude Desktop / Claude Code):
+Registration in an MCP client (e.g. Claude Desktop / Claude Code):
 
 ```json
 {
@@ -107,41 +108,41 @@ Registro en un cliente MCP (p. ej. Claude Desktop / Claude Code):
 }
 ```
 
-Tools MCP previstas: `convert_to_markdown`, `convert_from_markdown`, `inspect_document`, `list_supported_formats`. Ver detalle en [`docs/arquitectura.md`](docs/arquitectura.md).
+Planned MCP tools: `convert_to_markdown`, `convert_from_markdown`, `inspect_document`, `list_supported_formats`. Details in [`docs/architecture.md`](docs/architecture.md).
 
-## Documentación del proyecto
+## Project documentation
 
-| Documento | Contenido |
+| Document | Contents |
 |---|---|
-| [`docs/analisis-tecnico.md`](docs/analisis-tecnico.md) | Análisis de formatos, librerías Rust evaluadas, proyectos open source previos (Pandoc, MarkItDown, Docling, mammoth…), decisiones y riesgos |
-| [`docs/especificacion-docmark.md`](docs/especificacion-docmark.md) | Especificación del formato DocMark (Markdown extendido) v1.0-draft |
-| [`docs/arquitectura.md`](docs/arquitectura.md) | Arquitectura del software: workspace de crates, modelo de documento intermedio (IR), CLI, servidor MCP |
-| [`docs/plan-desarrollo.md`](docs/plan-desarrollo.md) | Plan de desarrollo detallado en 9 fases, con entregables, criterios de aceptación, estimaciones y estrategia de pruebas |
-| [`AGENTS.md`](AGENTS.md) | Guía operativa para desarrolladores y agentes de IA que trabajen en este repositorio |
-| [`corpus/README.md`](corpus/README.md) | El corpus de pruebas: qué aísla cada documento y cómo se regenera |
-| [`docs/spikes/`](docs/spikes/) | Informes de los spikes de riesgo, con la decisión que cerró cada uno |
-| [`kb/`](kb/) | Base de conocimiento: qué hay construido, cómo está estructurado, las decisiones técnicas y lo que espera a las fases siguientes |
+| [`docs/technical-analysis.md`](docs/technical-analysis.md) | Format analysis, evaluated Rust libraries, prior open-source projects (Pandoc, MarkItDown, Docling, mammoth…), decisions and risks |
+| [`docs/docmark-specification.md`](docs/docmark-specification.md) | DocMark format specification (extended Markdown) v1.0-draft |
+| [`docs/architecture.md`](docs/architecture.md) | Software architecture: crate workspace, intermediate document model (IR), CLI, MCP server |
+| [`docs/development-plan.md`](docs/development-plan.md) | Detailed development plan in 9 phases, with deliverables, acceptance criteria, estimates and testing strategy |
+| [`AGENTS.md`](AGENTS.md) | Operational guide for developers and AI agents working in this repository |
+| [`corpus/README.md`](corpus/README.md) | The test corpus: what each document isolates and how it is regenerated |
+| [`docs/spikes/`](docs/spikes/) | Risk-spike reports, with the decision that closed each one |
+| [`kb/`](kb/) | Knowledge base: what is built, how it is structured, technical decisions and what later phases will face |
 
-## Desarrollo
+## Development
 
 ```bash
 cargo test --workspace
 cargo clippy --workspace --all-targets -- -D warnings
 cargo fmt --all -- --check
-python3 corpus/generate.py --check     # el corpus es generado, no dibujado a mano
+python3 corpus/generate.py --check     # the corpus is generated, not hand-drawn
 ```
 
-Los golden files viven junto al corpus (`corpus/docx/*.expected.dmk.md`). Para actualizarlos:
-`DOCSAI_UPDATE_GOLDENS=1 cargo test -p docsai-convert --test goldens`, y **se revisa el diff**.
+Golden files live next to the corpus (`corpus/docx/*.expected.dmk.md`). To update them:
+`DOCSAI_UPDATE_GOLDENS=1 cargo test -p docsai-convert --test goldens`, and **review the diff**.
 
-## Principios de diseño
+## Design principles
 
-1. **Binario único, sin runtime externo**: pura biblioteca Rust siempre que sea posible; los fallbacks externos (LibreOffice headless para `.doc`) son opcionales y detectados en tiempo de ejecución, nunca requeridos.
-2. **IR pivote**: todos los formatos convergen en un modelo de documento intermedio (inspirado en el AST de Pandoc y en DoclingDocument); los conversores nunca se hablan entre sí directamente.
-3. **Fidelidad medible**: la pérdida de formato no se estima, se mide — el comando `roundtrip` y la suite de tests de ida y vuelta forman parte del producto.
-4. **Markdown primero legible, después completo**: los metadatos extendidos degradan con elegancia; un visor Markdown normal muestra un documento útil aunque ignore los atributos.
-5. **Los datos del usuario nunca se pierden en silencio**: lo que no se pueda representar se conserva en bloques raw o se reporta como advertencia explícita.
+1. **Single binary, no external runtime**: pure Rust libraries whenever possible; external fallbacks (LibreOffice headless for `.doc`) are optional and detected at runtime, never required.
+2. **Pivot IR**: every format converges on an intermediate document model (inspired by Pandoc's AST and DoclingDocument); converters never talk to each other directly.
+3. **Measurable fidelity**: format loss is not estimated, it is measured — the `roundtrip` command and the round-trip test suite are part of the product.
+4. **Markdown readable first, complete second**: extended metadata degrades gracefully; a normal Markdown viewer shows a useful document even if it ignores the attributes.
+5. **User data is never lost silently**: what cannot be represented is kept in raw blocks or reported as an explicit warning.
 
-## Licencia
+## License
 
-Ver [LICENSE](LICENSE).
+See [LICENSE](LICENSE).
diff --git a/corpus/README.md b/corpus/README.md
index 7bd3bdb..a558e16 100644
--- a/corpus/README.md
+++ b/corpus/README.md
@@ -1,83 +1,87 @@
-# Corpus de pruebas
+# Test corpus
 
-Documentos de prueba versionados. **Un rasgo por fichero**: cuando un golden falla, el fichero
-que falla señala el área del lector que se ha roto.
+Versioned test documents. **One trait per file**: when a golden fails, the failing
+file points at the reader area that broke.
 
-Ningún documento contiene datos reales ni privados (`AGENTS.md` §6).
+No document contains real or private data (`AGENTS.md` §6).
 
-## Cómo se generan
+## How they are generated
 
-Todos los ficheros los produce `corpus/generate.py`, sin dependencias más allá de la biblioteca
-estándar de Python 3:
+Every file is produced by `corpus/generate.py`, with no dependencies beyond the
+Python 3 standard library:
 
 ```bash
-python3 corpus/generate.py          # regenera todo
-python3 corpus/generate.py --check  # falla si el árbol está desfasado (lo ejecuta CI)
+python3 corpus/generate.py          # regenerate everything
+python3 corpus/generate.py --check  # fails if the tree is out of date (run by CI)
 ```
 
-Que el corpus sea **generado y no dibujado a mano** es deliberado:
+That the corpus is **generated rather than hand-drawn** is deliberate:
 
-- El XML de cada documento vive en el generador, donde se revisa en un `git diff` normal; un
-  `.docx` hecho con Word es una caja opaca en la revisión.
-- Los paquetes se escriben con marca de tiempo y orden de miembros fijos, así que regenerar
-  produce archivos byte a byte idénticos y el repositorio no acumula ruido binario.
-- Los medios (PNG, GIF, EMF) se sintetizan en Python puro, sin Pillow, para que el generador
-  funcione igual en las tres plataformas de CI.
+- The XML of each document lives in the generator, where it is reviewed in a
+  normal `git diff`; a `.docx` made with Word is an opaque box in review.
+- Packages are written with a fixed timestamp and member order, so regenerating
+  produces byte-identical files and the repository does not accumulate binary
+  noise.
+- Media (PNG, GIF, EMF) are synthesised in pure Python, without Pillow, so the
+  generator works the same on the three CI platforms.
 
-La contrapartida: son documentos *mínimos*, no documentos de Word reales. Los documentos reales
-anonimizados que pide la Fase 1 (tarea 10) y los corpus de rendimiento y adversarios de la Fase 8
-se añadirán aparte; el test de rendimiento de 50 páginas sintetiza su propio documento en tiempo
-de ejecución (`crates/docsai-convert/tests/goldens.rs`).
+The trade-off: these are *minimal* documents, not real Word documents. The
+anonymised real-world documents required by Phase 1 (task 10) and the
+performance and adversarial corpora of Phase 8 will be added separately; the
+50-page performance test synthesises its own document at runtime
+(`crates/docsai-convert/tests/goldens.rs`).
 
 ## Golden files
 
-Cada `docx/<nombre>.docx` tiene al lado su DocMark esperado, `docx/<nombre>.expected.dmk.md`.
-Los comparan los tests de `crates/docsai-convert/tests/goldens.rs`. Para actualizarlos:
+Each `docx/<name>.docx` has its expected DocMark beside it,
+`docx/<name>.expected.dmk.md`. They are compared by the tests in
+`crates/docsai-convert/tests/goldens.rs`. To update them:
 
 ```bash
 DOCSAI_UPDATE_GOLDENS=1 cargo test -p docsai-convert --test goldens
 ```
 
-El diff resultante **se revisa a mano** antes de confirmarlo: un golden actualizado sin mirar es
-un test que ha dejado de comprobar nada.
+The resulting diff **is reviewed by hand** before confirming: a golden updated
+without looking is a test that has stopped checking anything.
 
-## Documentos de texto (`docx/`)
+## Text documents (`docx/`)
 
-| Fichero | Rasgo que aísla |
+| File | Trait it isolates |
 |---|---|
-| `basic-text.docx` | Párrafos, salto de línea manual, párrafo vacío y los caracteres que Markdown escapa |
-| `basic-styles.docx` | Negrita, cursiva, tachado, subrayado, color, resaltado, fuente y tamaño, sub/superíndice, hipervínculo, alineación y sangrías |
-| `nested-lists.docx` | `numbering.xml` con tres niveles numerados y dos de viñetas; reconstrucción del árbol desde pares `(numId, ilvl)` |
-| `table-simple.docx` | Tabla regular con estilo de tabla y rejilla |
-| `table-merged.docx` | `gridSpan` y `vMerge` → `colspan`/`rowspan` y celdas absorbidas |
-| `images-inline.docx` | Imágenes `wp:inline`: PNG con alt/título/nombre, GIF entre texto, EMF vectorial |
-| `images-floating.docx` | `wp:anchor`: offsets relativos al margen con `wrapSquare`, alineación simbólica relativa a la página con `wrapTopAndBottom`, y marca de agua con `behindDoc` |
-| `images-transformed.docx` | Rotación 45°, recorte `a:srcRect` con borde `a:ln`, volteo H+V y escala ≠ 100 % |
-| `images-duplicated.docx` | El mismo mapa de bits en tres partes distintas del paquete con geometrías distintas: prueba la deduplicación del `AssetStore` |
-| `images-vml.docx` | `w:pict` con VML heredado (documentos convertidos desde `.doc`) |
-| `headers-footers.docx` | `sectPr` con cabecera por defecto y de primera página, pie con campos `PAGE`/`NUMPAGES`, dos columnas y `titlePg` |
-| `footnotes.docx` | `footnotes.xml` con dos notas, una con formato dentro |
-| `custom-styles.docx` | Estilo personalizado, estilo heredado con delta directo, estilo de carácter y propiedades personalizadas del documento |
-| `fields-raw.docx` | Control de contenido `w:sdt`, campo complejo `TOC` y campo simple `DATE` |
-
-## Hojas de cálculo (`xlsx/`)
-
-Generadas en la Fase 0 para que el corpus esté completo; las consume la **Fase 3**, que es cuando
-existirá el lector de `xlsx`.
-
-| Fichero | Rasgo que aísla |
+| `basic-text.docx` | Paragraphs, manual line break, empty paragraph and characters that Markdown escapes |
+| `basic-styles.docx` | Bold, italic, strike, underline, colour, highlight, font and size, sub/superscript, hyperlink, alignment and indents |
+| `nested-lists.docx` | `numbering.xml` with three numbered levels and two bullet levels; tree rebuild from `(numId, ilvl)` pairs |
+| `table-simple.docx` | Regular table with table style and grid |
+| `table-merged.docx` | `gridSpan` and `vMerge` → `colspan`/`rowspan` and absorbed cells |
+| `images-inline.docx` | `wp:inline` images: PNG with alt/title/name, GIF between text, EMF vector |
+| `images-floating.docx` | `wp:anchor`: margin-relative offsets with `wrapSquare`, symbolic page-relative alignment with `wrapTopAndBottom`, and watermark with `behindDoc` |
+| `images-transformed.docx` | 45° rotation, `a:srcRect` crop with `a:ln` border, H+V flip and scale ≠ 100 % |
+| `images-duplicated.docx` | The same bitmap in three distinct package parts with different geometries: tests `AssetStore` deduplication |
+| `images-vml.docx` | `w:pict` with legacy VML (documents converted from `.doc`) |
+| `headers-footers.docx` | `sectPr` with default and first-page header, footer with `PAGE`/`NUMPAGES` fields, two columns and `titlePg` |
+| `footnotes.docx` | `footnotes.xml` with two notes, one with inner formatting |
+| `custom-styles.docx` | Custom style, inherited style with direct delta, character style and custom document properties |
+| `fields-raw.docx` | `w:sdt` content control, complex `TOC` field and simple `DATE` field |
+
+## Spreadsheets (`xlsx/`)
+
+Generated in Phase 0 so the corpus is complete; consumed by **Phase 3**, when
+the `xlsx` reader exists.
+
+| File | Trait it isolates |
 |---|---|
-| `values-types.xlsx` | Los seis tipos de celda: entero, decimal, booleano, error, fecha (serial + `numFmt`) y cadena en línea |
-| `formulas-basic.xlsx` | Fórmulas con valor cacheado, referencia entre celdas y un nombre definido |
-| `formulas-shared.xlsx` | Fórmulas compartidas (`t="shared"`) y de matriz (`t="array"`) |
-| `number-formats.xlsx` | Moneda, fecha, porcentaje y millares por `numFmtId` |
-| `merged-cells.xlsx` | `mergeCells` horizontal y vertical, y ancho de columna personalizado |
-| `images-anchored.xlsx` | Los tres anclajes de hoja: `twoCellAnchor`, `oneCellAnchor` y `absoluteAnchor` |
-
-## Añadir un documento
-
-1. Escribe una función `docx_<rasgo>()` en `generate.py` y añádela a `GENERATORS`.
-2. Regenera (`python3 corpus/generate.py`) y añade la fila a la tabla de arriba.
-3. Genera su golden y **revisa el diff**.
-4. Si el rasgo aún no está implementado, el golden documentará la degradación actual (un
-   raw-block, por ejemplo). Eso es correcto: hace visible lo que falta.
+| `values-types.xlsx` | The six cell types: integer, decimal, boolean, error, date (serial + `numFmt`) and inline string |
+| `formulas-basic.xlsx` | Formulas with cached value, cell reference and a defined name |
+| `formulas-shared.xlsx` | Shared formulas (`t="shared"`) and array formulas (`t="array"`) |
+| `number-formats.xlsx` | Currency, date, percentage and thousands via `numFmtId` |
+| `merged-cells.xlsx` | Horizontal and vertical `mergeCells`, and custom column width |
+| `images-anchored.xlsx` | The three sheet anchors: `twoCellAnchor`, `oneCellAnchor` and `absoluteAnchor` |
+
+## Adding a document
+
+1. Write a `docx_<trait>()` function in `generate.py` and add it to `GENERATORS`.
+2. Regenerate (`python3 corpus/generate.py`) and add the row to the table above.
+3. Generate its golden and **review the diff**.
+4. If the trait is not implemented yet, the golden will document the current
+   degradation (a raw-block, for example). That is correct: it makes the gap
+   visible.
diff --git a/crates/docsai-cli/src/main.rs b/crates/docsai-cli/src/main.rs
index 9fb8677..3c6faa5 100644
--- a/crates/docsai-cli/src/main.rs
+++ b/crates/docsai-cli/src/main.rs
@@ -8,7 +8,7 @@ use clap::{Parser, Subcommand};
 use docsai_convert::{ConvertOptions, Fidelity, SUPPORT};
 use docsai_model::Format;
 
-/// Exit codes (arquitectura §5).
+/// Exit codes (architecture §5).
 const EXIT_OK: u8 = 0;
 const EXIT_WARNINGS: u8 = 1;
 const EXIT_INPUT: u8 = 2;
@@ -61,6 +61,20 @@ enum Command {
         #[arg(long)]
         json: bool,
     },
+    /// Round-trip a document (Office → DocMark → Office → DocMark) and compare.
+    Roundtrip {
+        /// Input Office document.
+        input: PathBuf,
+        /// Optional path for the regenerated .docx.
+        #[arg(short, long)]
+        output: Option<PathBuf>,
+        /// How much of the source survives: full, standard or plain.
+        #[arg(long, default_value = "full")]
+        fidelity: String,
+        /// Print the fidelity report as JSON on stdout.
+        #[arg(long)]
+        json: bool,
+    },
 }
 
 fn main() -> ExitCode {
@@ -89,6 +103,60 @@ fn run(cli: &Cli) -> anyhow::Result<u8> {
             print_formats(*json);
             Ok(EXIT_OK)
         }
+        Command::Roundtrip {
+            input,
+            output,
+            fidelity,
+            json,
+        } => {
+            let fidelity = docsai_convert::Fidelity::parse(fidelity).ok_or_else(|| {
+                anyhow::anyhow!("unknown --fidelity `{fidelity}`; use full, standard or plain")
+            })?;
+            let options = docsai_convert::ConvertOptions {
+                fidelity,
+                ..Default::default()
+            };
+            let outcome = docsai_convert::roundtrip_file(input, output.as_deref(), &options)?;
+            if *json {
+                let payload = serde_json::json!({
+                    "source_format": outcome.source_format.as_str(),
+                    "identical": outcome.identical,
+                    "report": outcome.report,
+                });
+                println!("{}", serde_json::to_string_pretty(&payload)?);
+            } else {
+                eprintln!(
+                    "docsai: roundtrip {} — second DocMark {} first",
+                    outcome.source_format.as_str(),
+                    if outcome.identical {
+                        "matches"
+                    } else {
+                        "differs from"
+                    }
+                );
+                if !outcome.identical {
+                    eprintln!(
+                        "  first: {} bytes, second: {} bytes",
+                        outcome.first_markdown.len(),
+                        outcome.second_markdown.len()
+                    );
+                }
+                if !outcome.report.warnings.is_empty() {
+                    eprintln!(
+                        "  {} warning(s), {} raw-block(s)",
+                        outcome.report.warnings.len(),
+                        outcome.report.raw_blocks_emitted
+                    );
+                    if cli.verbose {
+                        for warning in &outcome.report.warnings {
+                            eprintln!("  [{:?}] {}", warning.severity(), warning.message());
+                        }
+                    }
+                }
+            }
+            let lost = outcome.report.has_severe() || !outcome.identical;
+            Ok(if lost { EXIT_WARNINGS } else { EXIT_OK })
+        }
         Command::Convert {
             input,
             output,
diff --git a/crates/docsai-convert/src/assets.rs b/crates/docsai-convert/src/assets.rs
index f4361b2..0ca4e45 100644
--- a/crates/docsai-convert/src/assets.rs
+++ b/crates/docsai-convert/src/assets.rs
@@ -1,4 +1,4 @@
-//! [`AssetStore`] implementations (arquitectura §3.2).
+//! [`AssetStore`] implementations (architecture §3.2).
 
 use std::collections::BTreeMap;
 use std::path::{Path, PathBuf};
diff --git a/crates/docsai-convert/src/lib.rs b/crates/docsai-convert/src/lib.rs
index d61fc38..b64f445 100644
--- a/crates/docsai-convert/src/lib.rs
+++ b/crates/docsai-convert/src/lib.rs
@@ -1,7 +1,7 @@
 //! Conversion orchestration: format detection, pipelines and asset management.
 //!
 //! This is the only crate that knows about more than one format; the readers
-//! and writers never talk to each other (arquitectura §1).
+//! and writers never talk to each other (architecture §1).
 
 #![forbid(unsafe_code)]
 
@@ -10,7 +10,10 @@ mod pipeline;
 
 pub use assets::DirAssetStore;
 pub use docsai_docmark::{Fidelity, Options as DocMarkOptions};
-pub use pipeline::{convert_file, read_document, ConvertOptions, Outcome};
+pub use pipeline::{
+    convert_file, read_document, read_path, roundtrip_file, ConvertOptions, Outcome,
+    RoundtripOutcome,
+};
 
 use docsai_model::Format;
 
@@ -20,6 +23,12 @@ pub enum ConvertError {
     #[error("{0}")]
     Read(#[from] docsai_office::ReadError),
 
+    #[error("{0}")]
+    Write(#[from] docsai_office::WriteError),
+
+    #[error("{0}")]
+    Parse(#[from] docsai_docmark::ParseError),
+
     #[error("i/o error on `{path}`: {source}")]
     Io {
         path: String,
@@ -43,7 +52,7 @@ pub struct FormatSupport {
     pub format: Format,
     pub read: bool,
     pub write: bool,
-    /// Phase of `docs/plan-desarrollo.md` that lands the missing direction.
+    /// Phase of `docs/development-plan.md` that lands the missing direction.
     pub note: &'static str,
 }
 
@@ -52,44 +61,44 @@ pub const SUPPORT: &[FormatSupport] = &[
     FormatSupport {
         format: Format::Docx,
         read: true,
-        write: false,
-        note: "writing arrives in Fase 2",
+        write: true,
+        note: "Phase 2",
     },
     FormatSupport {
         format: Format::Doc,
         read: false,
         write: false,
-        note: "reading arrives in Fase 5; writing is out of scope",
+        note: "reading arrives in Phase 5; writing is out of scope",
     },
     FormatSupport {
         format: Format::Xlsx,
         read: false,
         write: false,
-        note: "arrives in Fase 3",
+        note: "arrives in Phase 3",
     },
     FormatSupport {
         format: Format::Xls,
         read: false,
         write: false,
-        note: "reading arrives in Fase 3; writing is out of scope",
+        note: "reading arrives in Phase 3; writing is out of scope",
     },
     FormatSupport {
         format: Format::Odt,
         read: false,
         write: false,
-        note: "arrives in Fase 4",
+        note: "arrives in Phase 4",
     },
     FormatSupport {
         format: Format::Ods,
         read: false,
         write: false,
-        note: "arrives in Fase 4",
+        note: "arrives in Phase 4",
     },
     FormatSupport {
         format: Format::DocMark,
-        read: false,
+        read: true,
         write: true,
-        note: "reading arrives in Fase 2",
+        note: "Phase 2",
     },
 ];
 
@@ -120,8 +129,13 @@ mod tests {
             );
         }
         assert!(can_read(Format::Docx));
-        assert!(!can_write(Format::Docx), "docx writing is Fase 2");
+        assert!(can_write(Format::Docx));
+        assert!(can_read(Format::DocMark));
         assert!(can_write(Format::DocMark));
+        assert_eq!(
+            can_write(Format::Docx),
+            docsai_office::WRITABLE.contains(&Format::Docx)
+        );
     }
 
     #[test]
diff --git a/crates/docsai-convert/src/pipeline.rs b/crates/docsai-convert/src/pipeline.rs
index b3f4ee2..a810256 100644
--- a/crates/docsai-convert/src/pipeline.rs
+++ b/crates/docsai-convert/src/pipeline.rs
@@ -1,11 +1,12 @@
 //! The conversion pipelines.
 
-use std::io::{Read, Seek};
+use std::fs::File;
+use std::io::{Cursor, Read, Seek};
 use std::path::{Path, PathBuf};
 
 use docsai_docmark::{Fidelity, Options as DocMarkOptions};
 use docsai_model::assets::AssetStore;
-use docsai_model::{ConversionReport, Document, Format};
+use docsai_model::{ConversionReport, Document, Format, MemoryAssetStore};
 
 use crate::assets::DirAssetStore;
 use crate::ConvertError;
@@ -35,13 +36,24 @@ impl Default for ConvertOptions {
 pub struct Outcome {
     pub source_format: Format,
     pub target_format: Format,
-    /// The DocMark text, also written to `output_path` when one was given.
+    /// The DocMark text when the target (or intermediate) is DocMark.
     pub markdown: String,
     pub output_path: Option<PathBuf>,
     pub assets_written: Vec<PathBuf>,
     pub report: ConversionReport,
 }
 
+/// Result of a round-trip fidelity check.
+#[derive(Debug)]
+pub struct RoundtripOutcome {
+    pub source_format: Format,
+    pub first_markdown: String,
+    pub second_markdown: String,
+    pub identical: bool,
+    pub report: ConversionReport,
+    pub output_path: Option<PathBuf>,
+}
+
 /// Reads any supported document into the IR, detecting its format by content.
 pub fn read_document<R: Read + Seek>(
     reader: R,
@@ -59,7 +71,88 @@ pub fn read_document<R: Read + Seek>(
             _ => ConvertError::UnknownFormat(hint.unwrap_or("<input>").to_string()),
         });
     }
-    let (document, report) = docsai_office::read(format, reader, assets)?;
+    let (document, report) = match format {
+        Format::DocMark => {
+            let mut bytes = Vec::new();
+            reader
+                .read_to_end(&mut bytes)
+                .map_err(|source| ConvertError::Io {
+                    path: hint.unwrap_or("<input>").to_string(),
+                    source,
+                })?;
+            let text = String::from_utf8_lossy(&bytes);
+            let base = hint.and_then(|h| {
+                let p = Path::new(h);
+                if p.is_absolute() || p.components().count() > 1 {
+                    p.parent()
+                } else {
+                    None
+                }
+            });
+            let (document, report) = docsai_docmark::parse_with_base(&text, base, assets)
+                .map_err(ConvertError::Parse)?;
+            (document, report)
+        }
+        other => docsai_office::read(other, reader, assets)?,
+    };
+    docsai_model::validate::validate(&document).map_err(|errors| {
+        ConvertError::Invalid(
+            errors
+                .iter()
+                .map(|e| e.to_string())
+                .collect::<Vec<_>>()
+                .join("; "),
+        )
+    })?;
+    Ok((document, format, report))
+}
+
+/// Reads a document from a path on disk.
+pub fn read_path(
+    input: &Path,
+    assets: &mut dyn AssetStore,
+) -> Result<(Document, Format, ConversionReport), ConvertError> {
+    let hint = input.file_name().and_then(|n| n.to_str());
+    let (format, score) = {
+        let mut probe = File::open(input).map_err(|source| ConvertError::Io {
+            path: input.display().to_string(),
+            source,
+        })?;
+        docsai_office::detect(&mut probe, hint)
+    };
+    if score == docsai_office::DetectScore::No || !crate::can_read(format) {
+        return Err(match crate::SUPPORT.iter().find(|s| s.format == format) {
+            Some(support) if score != docsai_office::DetectScore::No => ConvertError::Unsupported {
+                from: support.format,
+                to: Format::DocMark,
+            },
+            _ => ConvertError::UnknownFormat(input.display().to_string()),
+        });
+    }
+    if format == Format::DocMark {
+        let text = std::fs::read_to_string(input).map_err(|source| ConvertError::Io {
+            path: input.display().to_string(),
+            source,
+        })?;
+        let base = input.parent();
+        let (document, report) =
+            docsai_docmark::parse_with_base(&text, base, assets).map_err(ConvertError::Parse)?;
+        docsai_model::validate::validate(&document).map_err(|errors| {
+            ConvertError::Invalid(
+                errors
+                    .iter()
+                    .map(|e| e.to_string())
+                    .collect::<Vec<_>>()
+                    .join("; "),
+            )
+        })?;
+        return Ok((document, format, report));
+    }
+    let file = File::open(input).map_err(|source| ConvertError::Io {
+        path: input.display().to_string(),
+        source,
+    })?;
+    let (document, report) = docsai_office::read(format, file, assets)?;
     docsai_model::validate::validate(&document).map_err(|errors| {
         ConvertError::Invalid(
             errors
@@ -74,8 +167,7 @@ pub fn read_document<R: Read + Seek>(
 
 /// Converts a file on disk.
 ///
-/// With `output` set, the DocMark is written there and media go to the assets
-/// directory; without it the text is returned for the caller to print.
+/// Supports Office → DocMark, DocMark → Office, and DocMark → DocMark.
 pub fn convert_file(
     input: &Path,
     output: Option<&Path>,
@@ -89,61 +181,208 @@ pub fn convert_file(
         });
     }
 
-    let file = std::fs::File::open(input).map_err(|source| ConvertError::Io {
-        path: input.display().to_string(),
-        source,
-    })?;
-    let hint = input.file_name().and_then(|n| n.to_str());
-
     let assets_dir = options
         .assets_dir
         .clone()
         .unwrap_or_else(|| default_assets_dir(input, output));
     let mut store = DirAssetStore::new(assets_dir.clone());
 
-    let (document, source_format, mut report) = read_document(file, hint, &mut store)?;
+    let (document, source_format, mut report) = read_path(input, &mut store)?;
+    if !crate::can_read(source_format) {
+        return Err(ConvertError::Unsupported {
+            from: source_format,
+            to: target,
+        });
+    }
 
-    let docmark_options = DocMarkOptions {
-        fidelity: options.fidelity,
-        assets_dir: relative_assets_dir(&assets_dir, output),
-        source_format,
-    };
-    let (markdown, write_report) = docsai_docmark::serialize(&document, &store, &docmark_options);
-    report.merge(write_report);
+    match target {
+        Format::DocMark => {
+            let docmark_options = DocMarkOptions {
+                fidelity: options.fidelity,
+                assets_dir: relative_assets_dir(&assets_dir, output),
+                source_format,
+            };
+            let (markdown, write_report) =
+                docsai_docmark::serialize(&document, &store, &docmark_options);
+            report.merge(write_report);
 
-    if let Some(output) = output {
-        if let Some(parent) = output.parent().filter(|p| !p.as_os_str().is_empty()) {
-            std::fs::create_dir_all(parent).map_err(|source| ConvertError::Io {
-                path: parent.display().to_string(),
+            if let Some(output) = output {
+                ensure_parent(output)?;
+                std::fs::write(output, markdown.as_bytes()).map_err(|source| ConvertError::Io {
+                    path: output.display().to_string(),
+                    source,
+                })?;
+            }
+
+            Ok(Outcome {
+                source_format,
+                target_format: target,
+                markdown,
+                output_path: output.map(Path::to_path_buf),
+                assets_written: store.written().to_vec(),
+                report,
+            })
+        }
+        Format::Docx => {
+            let output = output.ok_or_else(|| {
+                ConvertError::Invalid("writing .docx requires an --output path".into())
+            })?;
+            ensure_parent(output)?;
+            let file = File::create(output).map_err(|source| ConvertError::Io {
+                path: output.display().to_string(),
                 source,
             })?;
+            let write_report = docsai_office::write_docx(&document, &store, file)?;
+            report.merge(write_report);
+
+            let (markdown, _) = docsai_docmark::serialize(
+                &document,
+                &store,
+                &DocMarkOptions {
+                    fidelity: options.fidelity,
+                    assets_dir: relative_assets_dir(&assets_dir, Some(output)),
+                    source_format,
+                },
+            );
+
+            Ok(Outcome {
+                source_format,
+                target_format: target,
+                markdown,
+                output_path: Some(output.to_path_buf()),
+                assets_written: store.written().to_vec(),
+                report,
+            })
         }
-        std::fs::write(output, markdown.as_bytes()).map_err(|source| ConvertError::Io {
+        other => Err(ConvertError::Unsupported {
+            from: source_format,
+            to: other,
+        }),
+    }
+}
+
+/// Office → DocMark → Office → DocMark idempotence check.
+///
+/// Writes the regenerated Office file to `output` when given, and returns the
+/// second DocMark pass in `markdown`.
+pub fn roundtrip_file(
+    input: &Path,
+    output: Option<&Path>,
+    options: &ConvertOptions,
+) -> Result<RoundtripOutcome, ConvertError> {
+    let assets_dir = options
+        .assets_dir
+        .clone()
+        .unwrap_or_else(|| default_assets_dir(input, output));
+
+    let mut store1 = MemoryAssetStore::new();
+    let (document1, source_format, mut report) = read_path(input, &mut store1)?;
+    if source_format != Format::Docx && source_format != Format::DocMark {
+        return Err(ConvertError::Unsupported {
+            from: source_format,
+            to: Format::Docx,
+        });
+    }
+
+    let (md1, r1) = docsai_docmark::serialize(
+        &document1,
+        &store1,
+        &DocMarkOptions {
+            fidelity: Fidelity::Full,
+            assets_dir: "assets".into(),
+            source_format,
+        },
+    );
+    report.merge(r1);
+
+    let mut store2 = MemoryAssetStore::new();
+    for id in store1.ids() {
+        if let Some(bytes) = store1.get(&id) {
+            let _ = store2.put(bytes);
+        }
+    }
+    let (document2, r2) = docsai_docmark::parse(&md1, &mut store2).map_err(ConvertError::Parse)?;
+    report.merge(r2);
+
+    let mut docx_buf = Cursor::new(Vec::new());
+    let r3 = docsai_office::write_docx(&document2, &store2, &mut docx_buf)?;
+    report.merge(r3);
+
+    if let Some(output) = output {
+        ensure_parent(output)?;
+        std::fs::write(output, docx_buf.get_ref()).map_err(|source| ConvertError::Io {
             path: output.display().to_string(),
             source,
         })?;
     }
 
-    Ok(Outcome {
+    docx_buf.set_position(0);
+    let mut store3 = MemoryAssetStore::new();
+    let (document3, r4) = docsai_office::read_docx(&mut docx_buf, &mut store3)?;
+    report.merge(r4);
+    let (md2, r5) = docsai_docmark::serialize(
+        &document3,
+        &store3,
+        &DocMarkOptions {
+            fidelity: Fidelity::Full,
+            assets_dir: "assets".into(),
+            source_format: Format::Docx,
+        },
+    );
+    report.merge(r5);
+
+    let mut written = Vec::new();
+    if output.is_some() {
+        let dir = assets_dir;
+        for id in store3.ids() {
+            if let (Some(bytes), Some(info)) = (store3.get(&id), store3.info(&id)) {
+                let _ = std::fs::create_dir_all(&dir);
+                let path = dir.join(&info.file_name);
+                if std::fs::write(&path, bytes).is_ok() {
+                    written.push(path);
+                }
+            }
+        }
+    }
+
+    let identical = md1 == md2;
+    if !identical {
+        report.warn(docsai_model::Warning::Degraded {
+            what: "roundtrip".into(),
+            why: "second DocMark pass differs from the first".into(),
+        });
+    }
+    Ok(RoundtripOutcome {
         source_format,
-        target_format: target,
-        markdown,
-        output_path: output.map(Path::to_path_buf),
-        assets_written: store.written().to_vec(),
+        first_markdown: md1,
+        second_markdown: md2,
+        identical,
         report,
+        output_path: output.map(Path::to_path_buf),
     })
 }
 
+fn ensure_parent(output: &Path) -> Result<(), ConvertError> {
+    if let Some(parent) = output.parent().filter(|p| !p.as_os_str().is_empty()) {
+        std::fs::create_dir_all(parent).map_err(|source| ConvertError::Io {
+            path: parent.display().to_string(),
+            source,
+        })?;
+    }
+    Ok(())
+}
+
 fn resolve_target(output: Option<&Path>, options: &ConvertOptions) -> Result<Format, ConvertError> {
     if let Some(target) = options.target {
         return Ok(target);
     }
     let Some(output) = output else {
-        // Writing to stdout: DocMark is the only text format there is.
         return Ok(Format::DocMark);
     };
     let name = output.file_name().and_then(|n| n.to_str()).unwrap_or("");
-    // `.dmk.md` and `.md` both mean DocMark.
+    if name.ends_with(".dmk.md") || name.ends_with(".md") {
+        return Ok(Format::DocMark);
+    }
     match name.rsplit('.').next().and_then(Format::parse) {
         Some(format) => Ok(format),
         None => Err(ConvertError::UnknownFormat(output.display().to_string())),
@@ -159,12 +398,9 @@ fn default_assets_dir(input: &Path, output: Option<&Path>) -> PathBuf {
     base.join("assets")
 }
 
-/// The path DocMark links should use: relative to the output file when
-/// possible, so the `.dmk.md` stays portable.
 fn relative_assets_dir(assets_dir: &Path, output: Option<&Path>) -> String {
     let parent = output.and_then(|o| o.parent()).unwrap_or(Path::new(""));
     let relative = assets_dir.strip_prefix(parent).unwrap_or(assets_dir);
-    // DocMark links always use `/`, on every platform.
     relative.to_string_lossy().replace('\\', "/")
 }
 
@@ -220,9 +456,45 @@ mod tests {
     }
 
     #[test]
-    fn an_unsupported_target_is_rejected_before_reading() {
+    fn docx_target_writes_a_package() {
+        let dir = temp_dir("to-docx");
+        let dmk = dir.join("in.dmk.md");
+        let md = convert_file(&corpus("basic-text.docx"), None, &ConvertOptions::default())
+            .unwrap()
+            .markdown;
+        std::fs::write(&dmk, md).unwrap();
+        let out = dir.join("out.docx");
+        let outcome = convert_file(
+            &dmk,
+            Some(&out),
+            &ConvertOptions {
+                target: Some(Format::Docx),
+                ..Default::default()
+            },
+        )
+        .expect("docx write");
+        assert_eq!(outcome.target_format, Format::Docx);
+        assert!(out.exists());
+        let bytes = std::fs::read(&out).unwrap();
+        assert!(bytes.starts_with(b"PK"));
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn roundtrip_basic_text_is_stable() {
+        let outcome = roundtrip_file(&corpus("basic-text.docx"), None, &ConvertOptions::default())
+            .expect("roundtrip");
+        assert!(
+            outcome.identical,
+            "basic-text should round-trip cleanly\n--- first ---\n{}\n--- second ---\n{}",
+            outcome.first_markdown, outcome.second_markdown
+        );
+    }
+
+    #[test]
+    fn an_unsupported_target_is_rejected() {
         let options = ConvertOptions {
-            target: Some(Format::Docx),
+            target: Some(Format::Odt),
             ..Default::default()
         };
         let error = convert_file(&corpus("basic-text.docx"), None, &options).unwrap_err();
diff --git a/crates/docsai-convert/tests/goldens.rs b/crates/docsai-convert/tests/goldens.rs
index 2f100af..7334357 100644
--- a/crates/docsai-convert/tests/goldens.rs
+++ b/crates/docsai-convert/tests/goldens.rs
@@ -109,7 +109,7 @@ fn serialisation_is_deterministic() {
         assert_eq!(
             first,
             second,
-            "{} serialises differently on a second run",
+            "{} serializes differently on a second run",
             document.display()
         );
     }
@@ -137,8 +137,8 @@ fn every_document_uses_unix_line_endings_and_no_bom() {
     }
 }
 
-/// Fase 1 acceptance criterion: *«La salida en `--fidelity plain` es CommonMark
-/// limpio verificado con comrak»*.
+/// Phase 1 acceptance criterion: *"`--fidelity plain` output is clean CommonMark
+/// verified with comrak"*.
 #[test]
 fn plain_fidelity_is_clean_commonmark() {
     let mut options = comrak::Options::default();
@@ -204,8 +204,8 @@ fn standard_fidelity_drops_raw_blocks_and_says_so() {
     assert_eq!(dropped as u32, full_report.raw_blocks_emitted);
 }
 
-/// Fase 1 acceptance criterion: *«Un docx real de 50+ páginas convierte en
-/// < 1 s con < 10 raw-blocks»*.
+/// Phase 1 acceptance criterion: *"A real 50+ page docx converts in
+/// < 1 s with < 10 raw-blocks"*.
 #[test]
 fn a_fifty_page_document_converts_quickly_with_few_raw_blocks() {
     let path = std::env::temp_dir().join(format!("docsai-perf-{}.docx", std::process::id()));
@@ -230,7 +230,7 @@ fn a_fifty_page_document_converts_quickly_with_few_raw_blocks() {
         report.raw_blocks_emitted
     );
 
-    // The budget of arquitectura §8 is for an optimised build; a debug build
+    // The budget of architecture §8 is for an optimised build; a debug build
     // runs roughly an order of magnitude slower, so it gets a looser bound
     // rather than no bound at all.
     let budget = if cfg!(debug_assertions) {
diff --git a/crates/docsai-docmark/src/attrs.rs b/crates/docsai-docmark/src/attrs.rs
index 8823361..efc1287 100644
--- a/crates/docsai-docmark/src/attrs.rs
+++ b/crates/docsai-docmark/src/attrs.rs
@@ -2,7 +2,7 @@
 //!
 //! The canonical order of spec §8 is enforced here, in one place: id first,
 //! then classes alphabetically, then keys alphabetically. That ordering is
-//! what makes the serialiser deterministic and the golden diffs stable.
+//! what makes the serializer deterministic and the golden diffs stable.
 
 use std::collections::BTreeMap;
 
@@ -99,6 +99,150 @@ impl Attrs {
             format!(" {}", self.render())
         }
     }
+
+    /// The id, if any (`#id`).
+    pub fn id_ref(&self) -> Option<&str> {
+        self.id.as_deref()
+    }
+
+    /// Classes in insertion order.
+    pub fn classes(&self) -> &[String] {
+        &self.classes
+    }
+
+    /// True when `class` is present.
+    pub fn has_class(&self, class: &str) -> bool {
+        self.classes.iter().any(|c| c == class)
+    }
+
+    /// First class, commonly the style id.
+    pub fn first_class(&self) -> Option<&str> {
+        self.classes.first().map(String::as_str)
+    }
+
+    /// Value of `key`, if present.
+    pub fn get(&self, key: &str) -> Option<&str> {
+        self.pairs.get(key).map(String::as_str)
+    }
+
+    /// Removes and returns the value of `key`.
+    pub fn take(&mut self, key: &str) -> Option<String> {
+        self.pairs.remove(key)
+    }
+
+    /// All key/value pairs in sorted order.
+    pub fn pairs(&self) -> &BTreeMap<String, String> {
+        &self.pairs
+    }
+
+    /// Parses a Pandoc-style attribute block, with or without surrounding `{}`.
+    ///
+    /// ```
+    /// use docsai_docmark::attrs::Attrs;
+    /// let a = Attrs::parse(r#"{#img-1 .Quote title="Figura 1" width=450px}"#).unwrap();
+    /// assert_eq!(a.id_ref(), Some("img-1"));
+    /// assert!(a.has_class("Quote"));
+    /// assert_eq!(a.get("width"), Some("450px"));
+    /// assert_eq!(a.get("title"), Some("Figura 1"));
+    /// ```
+    pub fn parse(input: &str) -> Option<Attrs> {
+        let input = input.trim();
+        let inner = if input.starts_with('{') && input.ends_with('}') && input.len() >= 2 {
+            &input[1..input.len() - 1]
+        } else {
+            input
+        };
+        let mut attrs = Attrs::new();
+        let mut rest = inner.trim();
+        while !rest.is_empty() {
+            rest = rest.trim_start();
+            if rest.is_empty() {
+                break;
+            }
+            if let Some(stripped) = rest.strip_prefix('#') {
+                let (id, next) = take_token(stripped);
+                if id.is_empty() {
+                    return None;
+                }
+                attrs.id = Some(id.to_string());
+                rest = next;
+                continue;
+            }
+            if let Some(stripped) = rest.strip_prefix('.') {
+                let (class, next) = take_token(stripped);
+                if class.is_empty() {
+                    return None;
+                }
+                attrs.class(class);
+                rest = next;
+                continue;
+            }
+            let (key, after_key) = take_ident(rest);
+            if key.is_empty() {
+                return None;
+            }
+            let after_key = after_key.trim_start();
+            let after_eq = after_key.strip_prefix('=')?;
+            let after_eq = after_eq.trim_start();
+            let (value, next) = take_value(after_eq)?;
+            attrs.set(key, value);
+            rest = next;
+        }
+        Some(attrs)
+    }
+}
+
+/// Identifier or class/id token: letters, digits, `_`, `-`, `.` (for class names).
+fn take_token(input: &str) -> (&str, &str) {
+    let end = input
+        .char_indices()
+        .find(|(_, c)| !(c.is_ascii_alphanumeric() || matches!(c, '-' | '_' | '.')))
+        .map(|(i, _)| i)
+        .unwrap_or(input.len());
+    (&input[..end], &input[end..])
+}
+
+fn take_ident(input: &str) -> (&str, &str) {
+    let end = input
+        .char_indices()
+        .find(|(_, c)| !(c.is_ascii_alphanumeric() || matches!(c, '-' | '_')))
+        .map(|(i, _)| i)
+        .unwrap_or(input.len());
+    (&input[..end], &input[end..])
+}
+
+fn take_value(input: &str) -> Option<(String, &str)> {
+    if let Some(rest) = input.strip_prefix('"') {
+        let mut out = String::new();
+        let mut chars = rest.char_indices();
+        while let Some((i, c)) = chars.next() {
+            match c {
+                '\\' => match chars.next() {
+                    Some((_, '"')) => out.push('"'),
+                    Some((_, '\\')) => out.push('\\'),
+                    Some((_, 'n')) => out.push('\n'),
+                    Some((_, other)) => {
+                        out.push('\\');
+                        out.push(other);
+                    }
+                    None => out.push('\\'),
+                },
+                '"' => return Some((out, &rest[i + 1..])),
+                other => out.push(other),
+            }
+        }
+        None
+    } else {
+        let end = input
+            .char_indices()
+            .find(|(_, c)| c.is_whitespace())
+            .map(|(i, _)| i)
+            .unwrap_or(input.len());
+        if end == 0 {
+            return None;
+        }
+        Some((input[..end].to_string(), &input[end..]))
+    }
 }
 
 #[cfg(test)]
@@ -152,4 +296,30 @@ mod tests {
         a.set("k", "1").set("k", "2");
         assert_eq!(a.render(), "{k=2}");
     }
+
+    #[test]
+    fn parse_round_trips_with_render() {
+        let samples = [
+            r#"{#img-1 .Quote title="Figura 1" width=450px}"#,
+            "{#x .Alpha .Beta a=2 z=1}",
+            r#"{color=#FF0000 link="https://example.com/a b" name="Logo corporativo" width=450px}"#,
+            "{on=true}",
+            "{.Heading1}",
+            "{align=center indent-first-line=24px}",
+        ];
+        for sample in samples {
+            let parsed = Attrs::parse(sample).unwrap_or_else(|| panic!("parse {sample}"));
+            assert_eq!(parsed.render(), sample, "render mismatch for {sample}");
+        }
+    }
+
+    #[test]
+    fn parse_getters_and_take() {
+        let mut a = Attrs::parse(r#"{#id .A .B k=v}"#).unwrap();
+        assert_eq!(a.id_ref(), Some("id"));
+        assert_eq!(a.classes(), &["A".to_string(), "B".to_string()]);
+        assert_eq!(a.get("k"), Some("v"));
+        assert_eq!(a.take("k"), Some("v".into()));
+        assert_eq!(a.get("k"), None);
+    }
 }
diff --git a/crates/docsai-docmark/src/error.rs b/crates/docsai-docmark/src/error.rs
new file mode 100644
index 0000000..0ac82a5
--- /dev/null
+++ b/crates/docsai-docmark/src/error.rs
@@ -0,0 +1,54 @@
+//! Parser errors for DocMark → IR.
+
+use std::io;
+use std::path::PathBuf;
+
+/// Something went wrong parsing a DocMark document.
+#[derive(Debug, thiserror::Error)]
+pub enum ParseError {
+    #[error("invalid front matter at line {line}: {message}")]
+    InvalidFrontMatter { line: usize, message: String },
+
+    #[error("unexpected content at line {line}: {message}")]
+    Unexpected { line: usize, message: String },
+
+    #[error("unsupported: {what}")]
+    Unsupported { what: String },
+
+    #[error("i/o error{path}: {source}", path = path_suffix(.path))]
+    Io {
+        path: Option<PathBuf>,
+        #[source]
+        source: io::Error,
+    },
+
+    #[error("asset error: {0}")]
+    Asset(#[from] docsai_model::assets::AssetError),
+}
+
+fn path_suffix(path: &Option<PathBuf>) -> String {
+    match path {
+        Some(p) => format!(" on `{}`", p.display()),
+        None => String::new(),
+    }
+}
+
+impl ParseError {
+    pub fn front_matter(line: usize, message: impl Into<String>) -> Self {
+        ParseError::InvalidFrontMatter {
+            line,
+            message: message.into(),
+        }
+    }
+
+    pub fn unexpected(line: usize, message: impl Into<String>) -> Self {
+        ParseError::Unexpected {
+            line,
+            message: message.into(),
+        }
+    }
+
+    pub fn io(path: Option<PathBuf>, source: io::Error) -> Self {
+        ParseError::Io { path, source }
+    }
+}
diff --git a/crates/docsai-docmark/src/escape.rs b/crates/docsai-docmark/src/escape.rs
index b0a6dde..a3774ff 100644
--- a/crates/docsai-docmark/src/escape.rs
+++ b/crates/docsai-docmark/src/escape.rs
@@ -71,6 +71,32 @@ pub fn escape_attr_value(value: &str) -> String {
     out
 }
 
+/// Inverse of [`escape`] for block (and table-cell) content: each backslash
+/// escapes the following character, and is dropped.
+///
+/// ```
+/// use docsai_docmark::escape::{escape, unescape, TextContext};
+/// let raw = r"a*b_c[d]";
+/// let once = escape(raw, TextContext::Block);
+/// assert_eq!(unescape(&once), raw);
+/// ```
+pub fn unescape(text: &str) -> String {
+    let mut out = String::with_capacity(text.len());
+    let mut chars = text.chars();
+    while let Some(c) = chars.next() {
+        if c == '\\' {
+            if let Some(next) = chars.next() {
+                out.push(next);
+            } else {
+                out.push('\\');
+            }
+        } else {
+            out.push(c);
+        }
+    }
+    out
+}
+
 /// True when a value can be written without quotes: a number or a simple
 /// identifier (spec §8).
 pub fn is_bare_value(value: &str) -> bool {
@@ -139,4 +165,24 @@ mod tests {
         let twice = escape(&once, TextContext::Block);
         assert_eq!(twice, r"a\\\*b");
     }
+
+    #[test]
+    fn unescape_inverts_escape() {
+        let samples = [
+            "*asterisco* _guion_ `code` [x] <y> \\z",
+            "# titulo",
+            "- item",
+            "1. uno",
+            "a|b",
+            "a&amp;b",
+            "coma, punto. dos: puntos; ¿eñe?",
+            r"\*asterisco\* \_guion\_",
+        ];
+        for sample in samples {
+            let escaped = escape(sample, TextContext::Block);
+            assert_eq!(unescape(&escaped), sample, "failed on {sample:?}");
+        }
+        assert_eq!(unescape(r"a\|b"), "a|b");
+        assert_eq!(unescape("trailing\\"), "trailing\\");
+    }
 }
diff --git a/crates/docsai-docmark/src/frontmatter.rs b/crates/docsai-docmark/src/frontmatter.rs
index 8063548..5b6a3c8 100644
--- a/crates/docsai-docmark/src/frontmatter.rs
+++ b/crates/docsai-docmark/src/frontmatter.rs
@@ -2,7 +2,7 @@
 //!
 //! Written by hand rather than through a YAML library: the spec demands byte
 //! determinism, and the schema is small and fully known. Doing it here also
-//! keeps a YAML serialiser out of the dependency tree.
+//! keeps a YAML serializer out of the dependency tree.
 
 use docsai_model::list::{ListCatalog, NumFormat};
 use docsai_model::sheet::Workbook;
diff --git a/crates/docsai-docmark/src/frontmatter_parse.rs b/crates/docsai-docmark/src/frontmatter_parse.rs
new file mode 100644
index 0000000..4be4b1b
--- /dev/null
+++ b/crates/docsai-docmark/src/frontmatter_parse.rs
@@ -0,0 +1,396 @@
+//! Front matter → IR catalogues and metadata.
+
+use std::collections::BTreeMap;
+
+use docsai_model::list::{ListCatalog, ListDef, ListId, ListLevel, NumFormat};
+use docsai_model::style::{
+    Align, DocDefaults, FontProps, LineHeight, ParaProps, Style, StyleCatalog, StyleId, StyleType,
+    Underline, VertAlign,
+};
+use docsai_model::text::{DocumentMeta, Margins, Orientation, PageGeometry};
+use docsai_model::units::{Length, Size};
+use docsai_model::{Format, DOCMARK_VERSION};
+
+use crate::error::ParseError;
+use crate::yaml::{self, Value};
+
+#[derive(Debug)]
+pub struct FrontMatter {
+    pub source_format: Format,
+    pub meta: DocumentMeta,
+    pub page: Option<PageGeometry>,
+    pub styles: StyleCatalog,
+    pub list_defs: ListCatalog,
+}
+
+impl Default for FrontMatter {
+    fn default() -> Self {
+        FrontMatter {
+            source_format: Format::DocMark,
+            meta: DocumentMeta::default(),
+            page: None,
+            styles: StyleCatalog::default(),
+            list_defs: ListCatalog::default(),
+        }
+    }
+}
+
+/// Parses the text between the opening and closing `---` fences.
+pub fn parse(text: &str, start_line: usize) -> Result<FrontMatter, ParseError> {
+    let map = yaml::parse_document(text).map_err(|message| {
+        // yaml errors already include line numbers relative to the body;
+        // shift them if needed.
+        let line = message
+            .strip_prefix("line ")
+            .and_then(|s| s.split(':').next())
+            .and_then(|n| n.parse::<usize>().ok())
+            .map(|n| start_line + n.saturating_sub(1))
+            .unwrap_or(start_line);
+        ParseError::front_matter(line, message)
+    })?;
+
+    let mut fm = FrontMatter {
+        source_format: Format::Docx,
+        ..Default::default()
+    };
+
+    if let Some(v) = map.get("docmark") {
+        let version = v.as_str().unwrap_or("").trim();
+        if !version.is_empty() && version != DOCMARK_VERSION {
+            // Accept with a soft approach: still parse; future versions may
+            // need migration, but v1.0 is the only supported contract today.
+            if !version.starts_with('1') {
+                return Err(ParseError::front_matter(
+                    start_line,
+                    format!("unsupported docmark version `{version}`"),
+                ));
+            }
+        }
+    }
+
+    if let Some(v) = map.get("source-format").and_then(|v| v.as_str()) {
+        fm.source_format = Format::parse(v).unwrap_or(Format::Docx);
+    }
+
+    fm.meta = read_meta(&map);
+    if let Some(page) = map.get("page") {
+        fm.page = Some(read_page(page, start_line)?);
+    }
+    if let Some(defaults) = map.get("style-defaults") {
+        fm.styles.defaults = read_defaults(defaults);
+    }
+    if let Some(styles) = map.get("styles").and_then(|v| v.as_map()) {
+        for (id, value) in styles {
+            if let Some(style) = read_style(id, value) {
+                fm.styles.insert(style);
+            }
+        }
+    }
+    if let Some(lists) = map.get("list-definitions").and_then(|v| v.as_map()) {
+        for (id, value) in lists {
+            if let Some(def) = read_list_def(value) {
+                fm.list_defs.insert(ListId::new(id.clone()), def);
+            }
+        }
+    }
+
+    Ok(fm)
+}
+
+fn read_meta(map: &BTreeMap<String, Value>) -> DocumentMeta {
+    let text = |key: &str| map.get(key).and_then(|v| v.as_str()).map(str::to_string);
+    let mut meta = DocumentMeta {
+        title: text("title"),
+        author: text("author"),
+        last_modified_by: text("last-modified-by"),
+        subject: text("subject"),
+        keywords: text("keywords"),
+        description: text("description"),
+        created: map
+            .get("created")
+            .map(|v| v.string_or_empty())
+            .filter(|s| !s.is_empty()),
+        modified: map
+            .get("modified")
+            .map(|v| v.string_or_empty())
+            .filter(|s| !s.is_empty()),
+        language: text("language"),
+        application: text("application"),
+        custom: BTreeMap::new(),
+    };
+    if let Some(custom) = map.get("custom-properties").and_then(|v| v.as_map()) {
+        for (k, v) in custom {
+            meta.custom.insert(k.clone(), v.string_or_empty());
+        }
+    }
+    meta
+}
+
+fn read_page(value: &Value, line: usize) -> Result<PageGeometry, ParseError> {
+    let map = value
+        .as_map()
+        .ok_or_else(|| ParseError::front_matter(line, "page must be a mapping"))?;
+    let mut page = PageGeometry {
+        columns: 1,
+        ..Default::default()
+    };
+
+    if let Some(size) = map.get("size") {
+        if let Some(name) = size.as_str() {
+            page.size = paper_size(name).ok_or_else(|| {
+                ParseError::front_matter(line, format!("unknown paper size `{name}`"))
+            })?;
+        } else if let Some(m) = size.as_map() {
+            page.size = Size::new(
+                len_value(m.get("width")).unwrap_or(Length::ZERO),
+                len_value(m.get("height")).unwrap_or(Length::ZERO),
+            );
+        }
+    }
+
+    if let Some(margins) = map.get("margins").and_then(|v| v.as_map()) {
+        page.margins = Margins {
+            top: len_value(margins.get("top")).unwrap_or(Length::ZERO),
+            bottom: len_value(margins.get("bottom")).unwrap_or(Length::ZERO),
+            left: len_value(margins.get("left")).unwrap_or(Length::ZERO),
+            right: len_value(margins.get("right")).unwrap_or(Length::ZERO),
+            header: len_value(margins.get("header")).unwrap_or(Length::ZERO),
+            footer: len_value(margins.get("footer")).unwrap_or(Length::ZERO),
+        };
+    }
+
+    if let Some(orient) = map.get("orientation").and_then(|v| v.as_str()) {
+        page.orientation = match orient {
+            "landscape" => Orientation::Landscape,
+            _ => Orientation::Portrait,
+        };
+    }
+    if let Some(cols) = map.get("columns").and_then(|v| v.as_u16()) {
+        page.columns = cols.max(1);
+    }
+    if map.get("title-page").and_then(|v| v.as_bool()) == Some(true) {
+        page.title_page = true;
+    }
+    Ok(page)
+}
+
+fn paper_size(name: &str) -> Option<Size> {
+    // Portrait short × long in mm, matching PageGeometry::paper_name.
+    let (w_mm, h_mm) = match name {
+        "A3" => (297.0, 420.0),
+        "A4" => (210.0, 297.0),
+        "A5" => (148.0, 210.0),
+        "Letter" => (215.9, 279.4),
+        "Legal" => (215.9, 355.6),
+        "Tabloid" => (279.4, 431.8),
+        _ => return None,
+    };
+    Some(Size::new(Length::from_mm(w_mm), Length::from_mm(h_mm)))
+}
+
+fn read_defaults(value: &Value) -> DocDefaults {
+    let mut defaults = DocDefaults::default();
+    if let Some(font) = value.get("font") {
+        defaults.font = read_font(font);
+    }
+    if let Some(para) = value.get("paragraph") {
+        defaults.paragraph = read_para(para);
+    }
+    defaults
+}
+
+fn read_style(id: &str, value: &Value) -> Option<Style> {
+    let map = value.as_map()?;
+    let style_type = match map
+        .get("type")
+        .and_then(|v| v.as_str())
+        .unwrap_or("paragraph")
+    {
+        "character" => StyleType::Character,
+        "table" => StyleType::Table,
+        "numbering" => StyleType::Numbering,
+        _ => StyleType::Paragraph,
+    };
+    let mut style = Style::new(id, style_type);
+    if let Some(name) = map.get("name").and_then(|v| v.as_str()) {
+        style.name = name.to_string();
+    }
+    if let Some(based) = map.get("based-on").and_then(|v| v.as_str()) {
+        style.based_on = Some(StyleId::new(based));
+    }
+    if let Some(next) = map.get("next").and_then(|v| v.as_str()) {
+        style.next = Some(StyleId::new(next));
+    }
+    if map.get("default").and_then(|v| v.as_bool()) == Some(true) {
+        style.is_default = true;
+    }
+    if let Some(font) = map.get("font") {
+        style.font = read_font(font);
+    }
+    if let Some(para) = map.get("paragraph") {
+        style.paragraph = read_para(para);
+    }
+    Some(style)
+}
+
+fn read_font(value: &Value) -> FontProps {
+    let mut font = FontProps::default();
+    let Some(map) = value.as_map() else {
+        return font;
+    };
+    if let Some(name) = map.get("name").and_then(|v| v.as_str()) {
+        font.name = Some(name.to_string());
+    }
+    if let Some(size) = map.get("size").and_then(len_value_ref) {
+        font.size = Some(size);
+    }
+    if let Some(color) = map.get("color").and_then(|v| v.as_str()) {
+        font.color = Some(color.to_string());
+    }
+    if let Some(b) = map.get("bold").and_then(|v| v.as_bool()) {
+        font.bold = Some(b);
+    }
+    if let Some(i) = map.get("italic").and_then(|v| v.as_bool()) {
+        font.italic = Some(i);
+    }
+    if let Some(s) = map.get("strike").and_then(|v| v.as_bool()) {
+        font.strike = Some(s);
+    }
+    if let Some(u) = map.get("underline").and_then(|v| v.as_str()) {
+        font.underline = Some(parse_underline(u));
+    }
+    if let Some(h) = map.get("highlight").and_then(|v| v.as_str()) {
+        font.highlight = Some(h.to_string());
+    }
+    if let Some(v) = map.get("vertical-align").and_then(|v| v.as_str()) {
+        font.vert_align = Some(match v {
+            "superscript" => VertAlign::Superscript,
+            "subscript" => VertAlign::Subscript,
+            _ => VertAlign::Baseline,
+        });
+    }
+    if let Some(b) = map.get("small-caps").and_then(|v| v.as_bool()) {
+        font.small_caps = Some(b);
+    }
+    if let Some(b) = map.get("caps").and_then(|v| v.as_bool()) {
+        font.caps = Some(b);
+    }
+    font
+}
+
+fn read_para(value: &Value) -> ParaProps {
+    let mut para = ParaProps::default();
+    let Some(map) = value.as_map() else {
+        return para;
+    };
+    if let Some(a) = map.get("align").and_then(|v| v.as_str()) {
+        para.align = Some(match a {
+            "center" => Align::Center,
+            "right" => Align::Right,
+            "justify" => Align::Justify,
+            _ => Align::Left,
+        });
+    }
+    para.indent_left = map.get("indent-left").and_then(len_value_ref);
+    para.indent_right = map.get("indent-right").and_then(len_value_ref);
+    para.indent_first_line = map.get("indent-first-line").and_then(len_value_ref);
+    para.indent_hanging = map.get("indent-hanging").and_then(len_value_ref);
+    para.space_before = map.get("space-before").and_then(len_value_ref);
+    para.space_after = map.get("space-after").and_then(len_value_ref);
+    if let Some(lh) = map.get("line-height") {
+        para.line_height = parse_line_height(lh);
+    }
+    if let Some(b) = map.get("keep-with-next").and_then(|v| v.as_bool()) {
+        para.keep_with_next = Some(b);
+    }
+    if let Some(b) = map.get("page-break-before").and_then(|v| v.as_bool()) {
+        para.page_break_before = Some(b);
+    }
+    if let Some(bg) = map.get("background").and_then(|v| v.as_str()) {
+        para.background = Some(bg.to_string());
+    }
+    if let Some(level) = map.get("outline-level").and_then(|v| v.as_u8()) {
+        para.outline_level = Some(level);
+    }
+    para
+}
+
+fn parse_line_height(value: &Value) -> Option<LineHeight> {
+    if let Some(n) = value.as_f64() {
+        // Multiple stored in thousandths.
+        return Some(LineHeight::Multiple((n * 1000.0).round() as i32));
+    }
+    let text = value.as_str()?;
+    if let Some(rest) = text.strip_prefix("exact ") {
+        return len_str(rest).map(LineHeight::Exact);
+    }
+    if let Some(rest) = text.strip_prefix("at-least ") {
+        return len_str(rest).map(LineHeight::AtLeast);
+    }
+    text.parse::<f64>()
+        .ok()
+        .map(|n| LineHeight::Multiple((n * 1000.0).round() as i32))
+}
+
+fn read_list_def(value: &Value) -> Option<ListDef> {
+    let levels = value.get("levels")?.as_seq()?;
+    let mut def = ListDef::default();
+    for level in levels {
+        let map = level.as_map()?;
+        let format = match map
+            .get("format")
+            .and_then(|v| v.as_str())
+            .unwrap_or("decimal")
+        {
+            "decimal" => NumFormat::Decimal,
+            "lowerLetter" => NumFormat::LowerLetter,
+            "upperLetter" => NumFormat::UpperLetter,
+            "lowerRoman" => NumFormat::LowerRoman,
+            "upperRoman" => NumFormat::UpperRoman,
+            "bullet" => NumFormat::Bullet,
+            "none" => NumFormat::None,
+            other => NumFormat::Other(other.to_string()),
+        };
+        let text = map
+            .get("text")
+            .map(|v| v.string_or_empty())
+            .unwrap_or_default();
+        let mut item = ListLevel::new(format, text);
+        if let Some(start) = map.get("start").and_then(|v| v.as_i64()) {
+            item.start = Some(start as i32);
+        }
+        item.indent = map.get("indent").and_then(len_value_ref);
+        item.hanging = map.get("hanging").and_then(len_value_ref);
+        def.levels.push(item);
+    }
+    Some(def)
+}
+
+fn len_value(value: Option<&Value>) -> Option<Length> {
+    value.and_then(len_value_ref)
+}
+
+fn len_value_ref(value: &Value) -> Option<Length> {
+    match value {
+        Value::String(s) => len_str(s),
+        Value::Number(n) => Length::parse(&format!("{n}px")),
+        _ => None,
+    }
+}
+
+fn len_str(text: &str) -> Option<Length> {
+    // Typographic measures in front matter may be bare `11pt`.
+    Length::parse(text)
+}
+
+fn parse_underline(value: &str) -> Underline {
+    match value {
+        "none" => Underline::None,
+        "double" => Underline::Double,
+        "thick" => Underline::Thick,
+        "dotted" => Underline::Dotted,
+        "dashed" => Underline::Dashed,
+        "wave" => Underline::Wave,
+        _ => Underline::Single,
+    }
+}
diff --git a/crates/docsai-docmark/src/lib.rs b/crates/docsai-docmark/src/lib.rs
index 24c780d..0e2905f 100644
--- a/crates/docsai-docmark/src/lib.rs
+++ b/crates/docsai-docmark/src/lib.rs
@@ -1,28 +1,36 @@
 //! DocMark: the extended-Markdown pivot format.
 //!
-//! Fase 1 lands the **serialiser** (IR → DocMark). The parser (DocMark → IR)
-//! is Fase 2 and deliberately absent here.
-//!
-//! The output is normative and deterministic (spec §8): two serialisations of
-//! the same IR are byte-identical, line endings are always `\n`, and the
-//! encoding is UTF-8 without BOM.
+//! Serialiser (IR → DocMark) and parser (DocMark → IR). The output is normative
+//! and deterministic (spec §8): two serialisations of the same IR are
+//! byte-identical, line endings are always `\n`, and the encoding is UTF-8
+//! without BOM.
 //!
 //! ```
-//! use docsai_docmark::{serialize, Options};
+//! use docsai_docmark::{serialize, parse, Options};
 //! use docsai_model::{Document, MemoryAssetStore, text::TextDocument};
 //!
 //! let doc = Document::Text(TextDocument::default());
 //! let (markdown, _report) = serialize(&doc, &MemoryAssetStore::new(), &Options::default());
 //! assert!(markdown.starts_with("---\ndocmark: \"1.0\"\n"));
+//! let mut assets = MemoryAssetStore::new();
+//! let (parsed, _) = parse(&markdown, &mut assets).unwrap();
+//! assert!(parsed.is_text());
 //! ```
 
 #![forbid(unsafe_code)]
 
 pub mod attrs;
+mod error;
 pub mod escape;
 mod frontmatter;
+mod frontmatter_parse;
+mod parser;
 pub mod units;
 mod writer;
+mod yaml;
+
+pub use error::ParseError;
+pub use parser::{parse, parse_with_base};
 
 use docsai_model::assets::AssetStore;
 use docsai_model::{ConversionReport, Document, Format};
@@ -103,12 +111,12 @@ pub fn serialize(
             (out, report)
         }
         Document::Workbook(_) => {
-            // Spreadsheet serialisation is Fase 3; emitting a half-formed sheet
+            // Spreadsheet serialisation is Phase 3; emitting a half-formed sheet
             // would be worse than saying so.
             let mut report = ConversionReport::new();
             report.warn(docsai_model::Warning::Degraded {
                 what: "workbook".into(),
-                why: "spreadsheet serialisation arrives in Fase 3".into(),
+                why: "spreadsheet serialisation arrives in Phase 3".into(),
             });
             (out, report)
         }
diff --git a/crates/docsai-docmark/src/parser.rs b/crates/docsai-docmark/src/parser.rs
new file mode 100644
index 0000000..116e5a4
--- /dev/null
+++ b/crates/docsai-docmark/src/parser.rs
@@ -0,0 +1,1900 @@
+//! DocMark → IR body parser.
+//!
+//! Hand-written to mirror `writer.rs`, so `serialize(parse(md))` stays stable
+//! for the shapes our serializer emits.
+
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+
+use docsai_model::assets::AssetStore;
+use docsai_model::image::RawId;
+use docsai_model::image::{
+    AlignKeyword, Anchor, AxisPos, CropRect, Flip, HVPos, ImageGeometry, ImageRef, RelBase,
+    SimpleBorder, WrapMode, WrapSide,
+};
+use docsai_model::list::ListId;
+use docsai_model::report::ConversionReport;
+use docsai_model::style::{Align, FontProps, StyleId, Underline, VertAlign};
+use docsai_model::text::{
+    Block, BreakKind, FieldKind, HeaderFooter, HeaderScope, Heading, Inline, List, ListItem,
+    Orientation, ParaFormat, Paragraph, RawFragment, RunProps, Section, Table, TableCell, TableRow,
+    TextBox, TextDocument,
+};
+use docsai_model::units::{Length, Size};
+use docsai_model::{ConversionReport as Report, Document};
+
+use crate::attrs::Attrs;
+use crate::error::ParseError;
+use crate::escape::unescape;
+use crate::frontmatter_parse::{self, FrontMatter};
+
+/// Parses DocMark markdown into the IR.
+pub fn parse(
+    markdown: &str,
+    assets: &mut dyn AssetStore,
+) -> Result<(Document, ConversionReport), ParseError> {
+    parse_with_base(markdown, None, assets)
+}
+
+/// Parses DocMark, resolving relative image paths against `base_dir`.
+pub fn parse_with_base(
+    markdown: &str,
+    base_dir: Option<&Path>,
+    assets: &mut dyn AssetStore,
+) -> Result<(Document, ConversionReport), ParseError> {
+    let markdown = markdown.replace("\r\n", "\n").replace('\r', "\n");
+    let mut report = ConversionReport::new();
+    let (fm, body, body_line) = split_front_matter(&markdown)?;
+    let fm = match fm {
+        Some(text) => frontmatter_parse::parse(text, 2)?,
+        None => FrontMatter::default(),
+    };
+
+    let mut parser = BodyParser {
+        base_dir: base_dir.map(Path::to_path_buf),
+        assets,
+        report: &mut report,
+        footnotes: BTreeMap::new(),
+        _styles: fm.styles.clone(),
+    };
+
+    let blocks = parser.parse_blocks(body, body_line)?;
+    let (headers, footers, body_blocks, nested_sections) = partition_structure(blocks);
+
+    let mut sections = Vec::new();
+    if nested_sections.is_empty() {
+        let mut section = Section {
+            page: fm.page.unwrap_or_default(),
+            headers,
+            footers,
+            blocks: body_blocks,
+        };
+        if section.page.columns == 0 {
+            section.page.columns = 1;
+        }
+        sections.push(section);
+    } else {
+        // Multi-section documents: headers/footers before the first section
+        // apply to section 0; each `.section` container is its own section.
+        for (index, (attrs, blocks)) in nested_sections.into_iter().enumerate() {
+            let mut section = Section {
+                page: fm.page.unwrap_or_default(),
+                blocks,
+                ..Default::default()
+            };
+            if index == 0 {
+                section.headers = headers.clone();
+                section.footers = footers.clone();
+            }
+            apply_section_attrs(&mut section, &attrs);
+            sections.push(section);
+        }
+        if !body_blocks.is_empty() && sections.is_empty() {
+            sections.push(Section {
+                page: fm.page.unwrap_or_default(),
+                headers,
+                footers,
+                blocks: body_blocks,
+            });
+        }
+    }
+
+    // Attach footnote definitions collected from the body.
+    attach_footnotes(&mut sections, &parser.footnotes);
+
+    let doc = Document::Text(TextDocument {
+        meta: fm.meta,
+        styles: fm.styles,
+        list_defs: fm.list_defs,
+        sections,
+    });
+    report.stats.styles = match &doc {
+        Document::Text(t) => t.styles.styles.len() as u32,
+        Document::Workbook(w) => w.styles.styles.len() as u32,
+    };
+    Ok((doc, report))
+}
+
+fn split_front_matter(markdown: &str) -> Result<(Option<&str>, &str, usize), ParseError> {
+    let text = markdown;
+    if !text.starts_with("---") {
+        return Ok((None, text, 1));
+    }
+    // Opening fence must be a whole line.
+    let after_open = if let Some(rest) = text.strip_prefix("---\n") {
+        rest
+    } else if text == "---" {
+        return Err(ParseError::front_matter(1, "unclosed front matter"));
+    } else {
+        // Not a line-bounded opening fence (e.g. `---foo`).
+        return Ok((None, text, 1));
+    };
+
+    let mut search = after_open;
+    let mut offset = 0usize;
+    loop {
+        if let Some(idx) = search.find("\n---") {
+            let after = &search[idx + 1..]; // starts at ---
+            if after == "---" || after.starts_with("---\n") || after.starts_with("---\r") {
+                let yaml = &after_open[..offset + idx];
+                let body = if let Some(rest) = after.strip_prefix("---\n") {
+                    rest
+                } else if after == "---" {
+                    ""
+                } else if let Some(rest) = after.strip_prefix("---\r\n") {
+                    rest
+                } else if let Some(rest) = after.strip_prefix("---\r") {
+                    rest
+                } else {
+                    after.get(3..).unwrap_or("")
+                };
+                // body starts after the closing fence line
+                let start_line = 2 + yaml.bytes().filter(|b| *b == b'\n').count() + 1;
+                // skip optional blank line after closing fence
+                let body = body.strip_prefix('\n').unwrap_or(body);
+                let start_line = start_line + 1;
+                return Ok((Some(yaml), body, start_line));
+            }
+            offset += idx + 1;
+            search = &after_open[offset..];
+        } else {
+            return Err(ParseError::front_matter(1, "unclosed front matter"));
+        }
+    }
+}
+
+#[allow(clippy::type_complexity)]
+fn partition_structure(
+    blocks: Vec<ParsedBlock>,
+) -> (
+    Vec<HeaderFooter>,
+    Vec<HeaderFooter>,
+    Vec<Block>,
+    Vec<(Attrs, Vec<Block>)>,
+) {
+    let mut headers = Vec::new();
+    let mut footers = Vec::new();
+    let mut body = Vec::new();
+    let mut sections = Vec::new();
+    for block in blocks {
+        match block {
+            ParsedBlock::Header(h) => headers.push(h),
+            ParsedBlock::Footer(f) => footers.push(f),
+            ParsedBlock::Section { attrs, blocks } => sections.push((attrs, blocks)),
+            ParsedBlock::Normal(b) => body.push(b),
+        }
+    }
+    (headers, footers, body, sections)
+}
+
+fn apply_section_attrs(section: &mut Section, attrs: &Attrs) {
+    if let Some(cols) = attrs.get("columns").and_then(|v| v.parse().ok()) {
+        section.page.columns = cols;
+    }
+    if let Some(orient) = attrs.get("orientation") {
+        section.page.orientation = match orient {
+            "landscape" => Orientation::Landscape,
+            _ => Orientation::Portrait,
+        };
+    }
+    if let Some(name) = attrs.get("page-size") {
+        if let Some(size) = paper_size(name) {
+            section.page.size = size;
+        }
+    }
+}
+
+fn paper_size(name: &str) -> Option<Size> {
+    let (w_mm, h_mm) = match name {
+        "A3" => (297.0, 420.0),
+        "A4" => (210.0, 297.0),
+        "A5" => (148.0, 210.0),
+        "Letter" => (215.9, 279.4),
+        "Legal" => (215.9, 355.6),
+        "Tabloid" => (279.4, 431.8),
+        _ => return None,
+    };
+    Some(Size::new(Length::from_mm(w_mm), Length::from_mm(h_mm)))
+}
+
+fn attach_footnotes(sections: &mut [Section], footnotes: &BTreeMap<u32, Vec<Block>>) {
+    if footnotes.is_empty() {
+        return;
+    }
+    for section in sections.iter_mut() {
+        rewrite_blocks(&mut section.blocks, footnotes);
+        for h in &mut section.headers {
+            rewrite_blocks(&mut h.blocks, footnotes);
+        }
+        for f in &mut section.footers {
+            rewrite_blocks(&mut f.blocks, footnotes);
+        }
+    }
+}
+
+fn rewrite_blocks(blocks: &mut [Block], footnotes: &BTreeMap<u32, Vec<Block>>) {
+    for block in blocks.iter_mut() {
+        match block {
+            Block::Paragraph(p) => rewrite_inlines(&mut p.content, footnotes),
+            Block::Heading(h) => rewrite_inlines(&mut h.paragraph.content, footnotes),
+            Block::List(list) => {
+                for item in &mut list.items {
+                    rewrite_blocks(&mut item.blocks, footnotes);
+                }
+            }
+            Block::Table(t) => {
+                for row in &mut t.rows {
+                    for cell in &mut row.cells {
+                        rewrite_blocks(&mut cell.blocks, footnotes);
+                    }
+                }
+            }
+            Block::TextBox(tb) => rewrite_blocks(&mut tb.blocks, footnotes),
+            _ => {}
+        }
+    }
+}
+
+fn rewrite_inlines(inlines: &mut [Inline], footnotes: &BTreeMap<u32, Vec<Block>>) {
+    for inline in inlines.iter_mut() {
+        match inline {
+            Inline::Footnote(blocks) => {
+                // Placeholder: single empty paragraph tagged with index in plain text?
+                // We store index via a temporary Text("\u{0}N") convention during parse.
+                if let Some(Block::Paragraph(p)) = blocks.first() {
+                    if let Some(Inline::Text(t)) = p.content.first() {
+                        if let Some(rest) = t.strip_prefix('\u{1}') {
+                            if let Ok(n) = rest.parse::<u32>() {
+                                if let Some(real) = footnotes.get(&n) {
+                                    *blocks = real.clone();
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            Inline::Styled { content, .. } | Inline::Link { content, .. } => {
+                rewrite_inlines(content, footnotes);
+            }
+            _ => {}
+        }
+    }
+}
+
+#[allow(clippy::large_enum_variant)]
+enum ParsedBlock {
+    Normal(Block),
+    Header(HeaderFooter),
+    Footer(HeaderFooter),
+    Section { attrs: Attrs, blocks: Vec<Block> },
+}
+
+struct BodyParser<'a> {
+    base_dir: Option<PathBuf>,
+    assets: &'a mut dyn AssetStore,
+    report: &'a mut Report,
+    footnotes: BTreeMap<u32, Vec<Block>>,
+    _styles: docsai_model::StyleCatalog,
+}
+
+impl<'a> BodyParser<'a> {
+    fn parse_blocks(
+        &mut self,
+        text: &str,
+        start_line: usize,
+    ) -> Result<Vec<ParsedBlock>, ParseError> {
+        let chunks = split_top_level(text);
+        let mut out = Vec::new();
+        let mut line = start_line;
+        for chunk in chunks {
+            let chunk_line = line;
+            line += chunk.bytes().filter(|b| *b == b'\n').count() + 2; // rough
+            if chunk.trim().is_empty() {
+                continue;
+            }
+            // Footnote definition
+            if let Some((n, body)) = parse_footnote_def(chunk) {
+                let blocks = self.parse_normal_blocks(body, chunk_line)?;
+                self.footnotes.insert(n, blocks);
+                continue;
+            }
+            if let Some(parsed) = self.parse_container_or_block(chunk, chunk_line)? {
+                out.push(parsed);
+            }
+        }
+        // Re-parse more carefully with list grouping
+        let mut regrouped = Vec::new();
+        let list_buf: Vec<(usize, bool, String, usize)> = Vec::new();
+        // Actually lists are inside chunks already if blank-line separated.
+        // Nested lists are in the same chunk. Good.
+        for item in out {
+            regrouped.push(item);
+        }
+        let _ = list_buf;
+        Ok(regrouped)
+    }
+
+    fn parse_normal_blocks(
+        &mut self,
+        text: &str,
+        start_line: usize,
+    ) -> Result<Vec<Block>, ParseError> {
+        let parsed = self.parse_blocks(text, start_line)?;
+        Ok(parsed
+            .into_iter()
+            .filter_map(|b| match b {
+                ParsedBlock::Normal(b) => Some(b),
+                _ => None,
+            })
+            .collect())
+    }
+
+    fn parse_container_or_block(
+        &mut self,
+        chunk: &str,
+        line: usize,
+    ) -> Result<Option<ParsedBlock>, ParseError> {
+        let trimmed = chunk.trim_start_matches('\n');
+        if trimmed.starts_with(":::") {
+            return self.parse_fence(trimmed, line).map(Some);
+        }
+        // Table?
+        if looks_like_table(trimmed) {
+            let table = self.parse_gfm_table(trimmed, line)?;
+            self.report.stats.tables += 1;
+            return Ok(Some(ParsedBlock::Normal(Block::Table(table))));
+        }
+        // List?
+        if looks_like_list(trimmed) {
+            let list = self.parse_list(trimmed, line, 0)?;
+            self.report.stats.lists += 1;
+            return Ok(Some(ParsedBlock::Normal(Block::List(list))));
+        }
+        // Heading
+        if let Some(rest) = strip_heading(trimmed) {
+            let (level, content) = rest;
+            let (para, _) = self.parse_paragraph_line(content, true)?;
+            self.report.stats.headings += 1;
+            self.report.stats.paragraphs += 1;
+            return Ok(Some(ParsedBlock::Normal(Block::Heading(Heading {
+                level,
+                paragraph: para,
+            }))));
+        }
+        // Image-only block
+        if let Some(img) = self.try_parse_block_image(trimmed)? {
+            self.report.stats.images += 1;
+            return Ok(Some(ParsedBlock::Normal(Block::Image(img))));
+        }
+        // Paragraph (possibly multi-line with hard breaks)
+        let para = self.parse_paragraph_block(trimmed)?;
+        self.report.stats.paragraphs += 1;
+        Ok(Some(ParsedBlock::Normal(Block::Paragraph(para))))
+    }
+
+    fn parse_fence(&mut self, text: &str, line: usize) -> Result<ParsedBlock, ParseError> {
+        let mut lines = text.lines();
+        let first = lines.next().unwrap_or("");
+        let attr_src = first.trim_start_matches(':').trim();
+        let attrs = Attrs::parse(attr_src).unwrap_or_default();
+        let mut body_lines: Vec<&str> = Vec::new();
+        let mut depth = 1i32;
+        for l in lines {
+            let t = l.trim();
+            if t.starts_with(":::") && t.trim_start_matches(':').trim().is_empty() {
+                // closing or opening bare :::
+                if t == ":::" || t.chars().all(|c| c == ':') {
+                    depth -= 1;
+                    if depth == 0 {
+                        break;
+                    }
+                    body_lines.push(l);
+                    continue;
+                }
+            }
+            if t.starts_with(":::") {
+                // nested open
+                depth += 1;
+            }
+            body_lines.push(l);
+        }
+        let body = body_lines.join("\n");
+
+        if attrs.has_class("header") {
+            let blocks = self.parse_normal_blocks(&body, line + 1)?;
+            let scope = parse_scope(attrs.get("scope"));
+            return Ok(ParsedBlock::Header(HeaderFooter { scope, blocks }));
+        }
+        if attrs.has_class("footer") {
+            let blocks = self.parse_normal_blocks(&body, line + 1)?;
+            let scope = parse_scope(attrs.get("scope"));
+            return Ok(ParsedBlock::Footer(HeaderFooter { scope, blocks }));
+        }
+        if attrs.has_class("section") {
+            let blocks = self.parse_normal_blocks(&body, line + 1)?;
+            return Ok(ParsedBlock::Section { attrs, blocks });
+        }
+        if attrs.has_class("raw") {
+            let raw = parse_raw_block(&attrs, &body)?;
+            self.report.raw_blocks_emitted += 1;
+            return Ok(ParsedBlock::Normal(Block::Raw(raw)));
+        }
+        if attrs.has_class("textbox") {
+            let blocks = self.parse_normal_blocks(&body, line + 1)?;
+            let tb = TextBox {
+                blocks,
+                size: match (attrs.get("width"), attrs.get("height")) {
+                    (Some(w), Some(h)) => Some(Size::new(
+                        Length::parse(w).unwrap_or(Length::ZERO),
+                        Length::parse(h).unwrap_or(Length::ZERO),
+                    )),
+                    _ => None,
+                },
+                x: attrs.get("x").and_then(Length::parse),
+                y: attrs.get("y").and_then(Length::parse),
+            };
+            return Ok(ParsedBlock::Normal(Block::TextBox(tb)));
+        }
+        if attrs.has_class("table") {
+            let table = if attrs.get("complex") == Some("true") {
+                self.parse_complex_table(&body, line + 1, &attrs)?
+            } else {
+                let mut table = self.parse_gfm_table(body.trim(), line + 1)?;
+                apply_table_attrs(&mut table, &attrs);
+                table
+            };
+            self.report.stats.tables += 1;
+            return Ok(ParsedBlock::Normal(Block::Table(table)));
+        }
+
+        // Unknown container: parse body as normal blocks and ignore wrapper.
+        let blocks = self.parse_normal_blocks(&body, line + 1)?;
+        if blocks.len() == 1 {
+            Ok(ParsedBlock::Normal(blocks.into_iter().next().unwrap()))
+        } else {
+            // Flatten
+            Err(ParseError::unexpected(
+                line,
+                format!("unknown container class {:?}", attrs.classes()),
+            ))
+        }
+    }
+
+    fn parse_complex_table(
+        &mut self,
+        body: &str,
+        line: usize,
+        attrs: &Attrs,
+    ) -> Result<Table, ParseError> {
+        let mut table = Table {
+            header_row: false,
+            ..Default::default()
+        };
+        apply_table_attrs(&mut table, attrs);
+        // Parse nested ::: {.row} / ::: {.cell}
+        let mut rest = body.trim();
+        while !rest.is_empty() {
+            rest = rest.trim_start_matches('\n').trim_start();
+            if rest.is_empty() {
+                break;
+            }
+            if !rest.starts_with(":::") {
+                break;
+            }
+            let (inner_attrs, inner_body, next) = split_one_fence(rest, line)?;
+            rest = next;
+            if !inner_attrs.has_class("row") {
+                continue;
+            }
+            let mut row = TableRow::default();
+            let mut cell_src = inner_body.trim();
+            while !cell_src.is_empty() {
+                cell_src = cell_src.trim_start_matches('\n').trim_start();
+                if !cell_src.starts_with(":::") {
+                    break;
+                }
+                let (cell_attrs, cell_body, next_cell) = split_one_fence(cell_src, line)?;
+                cell_src = next_cell;
+                if !cell_attrs.has_class("cell") {
+                    continue;
+                }
+                let blocks = self.parse_normal_blocks(cell_body, line)?;
+                let mut cell = TableCell {
+                    blocks,
+                    ..Default::default()
+                };
+                if let Some(c) = cell_attrs.get("colspan").and_then(|v| v.parse().ok()) {
+                    cell.colspan = c;
+                }
+                if let Some(r) = cell_attrs.get("rowspan").and_then(|v| v.parse().ok()) {
+                    cell.rowspan = r;
+                }
+                if let Some(bg) = cell_attrs.get("background") {
+                    cell.background = Some(bg.to_string());
+                }
+                row.cells.push(cell);
+            }
+            table.rows.push(row);
+        }
+        Ok(table)
+    }
+
+    fn parse_gfm_table(&mut self, text: &str, _line: usize) -> Result<Table, ParseError> {
+        let mut rows_raw: Vec<Vec<String>> = Vec::new();
+        let mut delimiter_at = None;
+        for (idx, line) in text.lines().enumerate() {
+            let line = line.trim();
+            if line.is_empty() {
+                continue;
+            }
+            if !line.contains('|') {
+                continue;
+            }
+            let cells = split_table_row(line);
+            if cells
+                .iter()
+                .all(|c| c.chars().all(|ch| ch == '-' || ch == ':' || ch == ' '))
+                && cells.iter().any(|c| c.contains('-'))
+            {
+                delimiter_at = Some(idx);
+                continue;
+            }
+            rows_raw.push(cells);
+        }
+        let mut table = Table::default();
+        let has_header = delimiter_at.is_some();
+        table.header_row = has_header;
+        for (i, cells) in rows_raw.into_iter().enumerate() {
+            let mut row = TableRow {
+                is_header: has_header && i == 0,
+                ..Default::default()
+            };
+            for cell_text in cells {
+                row.cells.push(self.parse_table_cell(&cell_text)?);
+            }
+            table.rows.push(row);
+        }
+        // Writer inserts an empty header when header_row is false.
+        if !has_header {
+            // Our rows already are body rows; header_row stays false.
+        } else if let Some(first) = table.rows.first() {
+            // Drop synthetic empty header if all empty — keep as-is.
+            let _ = first;
+        }
+        // When writer had no header it inserted empty header + delimiter.
+        // Parser sees empty header row first. Detect and drop it.
+        if has_header {
+            if let Some(first) = table.rows.first() {
+                let empty = first.cells.iter().all(|c| {
+                    c.blocks.is_empty()
+                        || matches!(
+                            c.blocks.as_slice(),
+                            [Block::Paragraph(p)] if p.is_empty()
+                        )
+                });
+                if empty && table.rows.len() > 1 {
+                    table.rows.remove(0);
+                    table.header_row = false;
+                    for r in &mut table.rows {
+                        r.is_header = false;
+                    }
+                }
+            }
+        }
+        Ok(table)
+    }
+
+    fn parse_table_cell(&mut self, text: &str) -> Result<TableCell, ParseError> {
+        let text = text.trim();
+        let (content, attrs) = split_trailing_attrs(text);
+        let content = unescape(&content.replace("\\|", "|"));
+        let inlines = self.parse_inlines(&content)?;
+        let mut cell = TableCell {
+            blocks: vec![Block::Paragraph(Paragraph::new(inlines))],
+            ..Default::default()
+        };
+        if let Some(attrs) = attrs {
+            if let Some(c) = attrs.get("colspan").and_then(|v| v.parse().ok()) {
+                cell.colspan = c;
+            }
+            if let Some(r) = attrs.get("rowspan").and_then(|v| v.parse().ok()) {
+                cell.rowspan = r;
+            }
+            if let Some(bg) = attrs.get("background") {
+                cell.background = Some(bg.to_string());
+            }
+        }
+        Ok(cell)
+    }
+
+    fn parse_list(&mut self, text: &str, line: usize, depth: u8) -> Result<List, ParseError> {
+        let items = collect_list_items(text);
+        if items.is_empty() {
+            return Err(ParseError::unexpected(line, "empty list"));
+        }
+        let ordered = items[0].ordered;
+        let mut list = List {
+            def: None,
+            ordered,
+            level: depth,
+            items: Vec::new(),
+        };
+        for item in items {
+            let mut blocks = Vec::new();
+            // First line is paragraph content (may include attrs)
+            let first = item.lines.first().map(String::as_str).unwrap_or("");
+            let (para, list_id) = self.parse_paragraph_line(first, false)?;
+            if list.def.is_none() {
+                if let Some(id) = list_id {
+                    list.def = Some(ListId::new(id));
+                }
+            }
+            // Nested content
+            let rest = if item.lines.len() > 1 {
+                item.lines[1..].join("\n")
+            } else {
+                String::new()
+            };
+            let rest = strip_list_indent(&rest, item.marker_len);
+            blocks.push(Block::Paragraph(para));
+            if !rest.trim().is_empty() {
+                // May contain nested list and/or more paragraphs
+                let nested = self.parse_normal_blocks(&rest, line)?;
+                // If first nested is list, keep tight
+                blocks.extend(nested);
+            }
+            // Remove empty trailing?
+            list.items.push(ListItem { blocks });
+        }
+        Ok(list)
+    }
+
+    fn parse_paragraph_block(&mut self, text: &str) -> Result<Paragraph, ParseError> {
+        // Hard breaks: line ending with two spaces
+        let mut joined = String::new();
+        let lines: Vec<&str> = text.lines().collect();
+        for (i, line) in lines.iter().enumerate() {
+            if i + 1 < lines.len() && line.ends_with("  ") {
+                joined.push_str(line.trim_end_matches(' '));
+                joined.push_str("  \n");
+            } else if i + 1 < lines.len() {
+                joined.push_str(line);
+                joined.push('\n');
+            } else {
+                joined.push_str(line);
+            }
+        }
+        let (para, _) = self.parse_paragraph_line(&joined, false)?;
+        Ok(para)
+    }
+
+    fn parse_paragraph_line(
+        &mut self,
+        text: &str,
+        is_heading: bool,
+    ) -> Result<(Paragraph, Option<String>), ParseError> {
+        let text = text.trim_end();
+        // empty marker
+        if text == "[]{.empty}" || text.starts_with("[]{.empty}") {
+            let rest = text.trim_start_matches("[]{.empty}").trim_start();
+            let mut format = ParaFormat::default();
+            let mut list_id = None;
+            if let Some(attrs) = Attrs::parse(rest) {
+                list_id = attrs.get("list").map(str::to_string);
+                format = paragraph_format_from_attrs(&attrs, is_heading);
+            }
+            return Ok((
+                Paragraph {
+                    format,
+                    content: Vec::new(),
+                },
+                list_id,
+            ));
+        }
+
+        let (content, attrs) = split_trailing_attrs(text);
+        let mut list_id = None;
+        let mut format = ParaFormat::default();
+        if let Some(attrs) = attrs {
+            list_id = attrs.get("list").map(str::to_string);
+            format = paragraph_format_from_attrs(&attrs, is_heading);
+        }
+        // Content may still end with `{.empty}` form already handled.
+        if content.trim() == "[]" {
+            // shouldn't happen
+        }
+        let inlines = self.parse_inlines(content.trim_end())?;
+        Ok((
+            Paragraph {
+                format,
+                content: inlines,
+            },
+            list_id,
+        ))
+    }
+
+    fn try_parse_block_image(&mut self, text: &str) -> Result<Option<ImageRef>, ParseError> {
+        let text = text.trim();
+        if !text.starts_with("![") {
+            return Ok(None);
+        }
+        // Only a single image and optional attrs
+        if text.lines().count() > 1 {
+            return Ok(None);
+        }
+        let inlines = self.parse_inlines(text)?;
+        match inlines.as_slice() {
+            [Inline::Image(img)] => Ok(Some(img.clone())),
+            _ => Ok(None),
+        }
+    }
+
+    fn parse_inlines(&mut self, text: &str) -> Result<Vec<Inline>, ParseError> {
+        parse_inlines_inner(text, self)
+    }
+
+    fn load_image(
+        &mut self,
+        path: &str,
+        attrs: Attrs,
+        alt: String,
+    ) -> Result<ImageRef, ParseError> {
+        let mut asset_id = None;
+        if let Some(base) = &self.base_dir {
+            let full = base.join(path);
+            if full.is_file() {
+                let bytes =
+                    std::fs::read(&full).map_err(|e| ParseError::io(Some(full.clone()), e))?;
+                asset_id = Some(self.assets.put(&bytes)?);
+            }
+        }
+        // Also try path as-is relative to cwd when no base
+        if asset_id.is_none() {
+            let p = Path::new(path);
+            if p.is_file() {
+                let bytes =
+                    std::fs::read(p).map_err(|e| ParseError::io(Some(p.to_path_buf()), e))?;
+                asset_id = Some(self.assets.put(&bytes)?);
+            }
+        }
+
+        let width = attrs
+            .get("width")
+            .and_then(Length::parse)
+            .unwrap_or(Length::ZERO);
+        let height = attrs
+            .get("height")
+            .and_then(Length::parse)
+            .unwrap_or(Length::ZERO);
+        let mut geometry = ImageGeometry::inline(Size::new(width, height));
+        if let Some(ns) = attrs.get("native-size") {
+            if let Some((w, h)) = ns.split_once('x') {
+                if let (Ok(w), Ok(h)) = (w.parse(), h.parse()) {
+                    geometry.native_size_px = Some((w, h));
+                }
+            }
+        }
+        if let Some(dpi) = attrs.get("dpi").and_then(|v| v.parse().ok()) {
+            geometry.dpi = Some(dpi);
+        }
+        geometry.anchor = parse_anchor(&attrs);
+        if let Some(rot) = attrs.get("rotation").and_then(|v| v.parse().ok()) {
+            geometry.rotation_deg = rot;
+        }
+        if let Some(flip) = attrs.get("flip") {
+            geometry.flip = match flip {
+                "h" => Flip::H,
+                "v" => Flip::V,
+                "hv" => Flip::HV,
+                _ => Flip::None,
+            };
+        }
+        if let Some(crop) = attrs.get("crop") {
+            let parts: Vec<_> = crop.split(',').collect();
+            if parts.len() == 4 {
+                let parse_pct =
+                    |s: &str| s.trim().trim_end_matches('%').parse::<f32>().unwrap_or(0.0);
+                geometry.crop = Some(CropRect {
+                    left: parse_pct(parts[0]),
+                    top: parse_pct(parts[1]),
+                    right: parse_pct(parts[2]),
+                    bottom: parse_pct(parts[3]),
+                });
+            }
+        }
+        if let Some(border) = attrs.get("border") {
+            let parts: Vec<_> = border.split_whitespace().collect();
+            if parts.len() >= 3 {
+                geometry.border = Some(SimpleBorder {
+                    width: Length::parse(parts[0]).unwrap_or(Length::ZERO),
+                    style: parts[1].to_string(),
+                    color: parts[2].to_string(),
+                });
+            }
+        }
+        if let Some(z) = attrs.get("z-index").and_then(|v| v.parse().ok()) {
+            geometry.z_index = Some(z);
+        }
+
+        let id = asset_id.unwrap_or_else(|| {
+            // Placeholder id from path hash when bytes unavailable.
+            docsai_model::assets::AssetId::new(format!("missing-{}", path.replace('/', "_")))
+        });
+
+        let mut image = ImageRef::new(id, geometry);
+        image.alt = alt;
+        image.title = attrs.get("title").map(str::to_string);
+        image.name = attrs.get("name").map(str::to_string);
+        image.link = attrs.get("link").map(str::to_string);
+        image.external_src = attrs.get("external-src").map(str::to_string);
+        if let Some(raw) = attrs.get("effects-raw") {
+            image.effects_raw = Some(RawId::new(raw));
+        }
+        Ok(image)
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Inline parser
+// ---------------------------------------------------------------------------
+
+fn parse_inlines_inner(text: &str, ctx: &mut BodyParser<'_>) -> Result<Vec<Inline>, ParseError> {
+    let mut out = Vec::new();
+    let chars: Vec<char> = text.chars().collect();
+    let mut i = 0usize;
+    let mut text_buf = String::new();
+
+    let flush_text = |buf: &mut String, out: &mut Vec<Inline>| {
+        if !buf.is_empty() {
+            out.push(Inline::Text(unescape(buf)));
+            buf.clear();
+        }
+    };
+
+    while i < chars.len() {
+        let c = chars[i];
+        // Hard break: two spaces before newline
+        if c == ' ' && i + 2 < chars.len() && chars[i + 1] == ' ' && chars[i + 2] == '\n' {
+            flush_text(&mut text_buf, &mut out);
+            out.push(Inline::Break(BreakKind::Line));
+            i += 3;
+            continue;
+        }
+        if c == '\\' && i + 1 < chars.len() {
+            text_buf.push('\\');
+            text_buf.push(chars[i + 1]);
+            i += 2;
+            continue;
+        }
+        // Footnote ref [^n]
+        if c == '[' && i + 2 < chars.len() && chars[i + 1] == '^' {
+            if let Some(end) = find_closing_bracket(&chars, i + 2) {
+                let inner: String = chars[i + 2..end].iter().collect();
+                if inner.chars().all(|ch| ch.is_ascii_digit()) {
+                    flush_text(&mut text_buf, &mut out);
+                    let n: u32 = inner.parse().unwrap_or(0);
+                    // Placeholder footnote; filled later.
+                    out.push(Inline::Footnote(vec![Block::Paragraph(Paragraph::new(
+                        vec![Inline::Text(format!("\u{1}{n}"))],
+                    ))]));
+                    ctx.report.stats.footnotes += 1;
+                    i = end + 1;
+                    continue;
+                }
+            }
+        }
+        // Image ![alt](path){attrs}
+        if c == '!' && i + 1 < chars.len() && chars[i + 1] == '[' {
+            if let Some((img, next)) = try_parse_image(&chars, i, ctx)? {
+                flush_text(&mut text_buf, &mut out);
+                out.push(Inline::Image(img));
+                i = next;
+                continue;
+            }
+        }
+        // Link or span [text](url) or [text]{attrs} or []{attrs}
+        if c == '[' {
+            if let Some((inline, next)) = try_parse_bracket(&chars, i, ctx)? {
+                flush_text(&mut text_buf, &mut out);
+                out.push(inline);
+                i = next;
+                continue;
+            }
+        }
+        // Bold **
+        if c == '*' && i + 1 < chars.len() && chars[i + 1] == '*' {
+            if let Some(end) = find_closing_delim(&chars, i + 2, "**") {
+                flush_text(&mut text_buf, &mut out);
+                let inner: String = chars[i + 2..end].iter().collect();
+                let content = parse_inlines_inner(&inner, ctx)?;
+                out.push(Inline::Styled {
+                    content,
+                    props: RunProps::direct(FontProps {
+                        bold: Some(true),
+                        ..Default::default()
+                    }),
+                });
+                i = end + 2;
+                continue;
+            }
+        }
+        // Strike ~~
+        if c == '~' && i + 1 < chars.len() && chars[i + 1] == '~' {
+            if let Some(end) = find_closing_delim(&chars, i + 2, "~~") {
+                flush_text(&mut text_buf, &mut out);
+                let inner: String = chars[i + 2..end].iter().collect();
+                let content = parse_inlines_inner(&inner, ctx)?;
+                out.push(Inline::Styled {
+                    content,
+                    props: RunProps::direct(FontProps {
+                        strike: Some(true),
+                        ..Default::default()
+                    }),
+                });
+                i = end + 2;
+                continue;
+            }
+        }
+        // Italic *
+        if c == '*' {
+            if let Some(end) = find_closing_delim(&chars, i + 1, "*") {
+                // avoid matching **
+                if end > i + 1 {
+                    flush_text(&mut text_buf, &mut out);
+                    let inner: String = chars[i + 1..end].iter().collect();
+                    let content = parse_inlines_inner(&inner, ctx)?;
+                    out.push(Inline::Styled {
+                        content,
+                        props: RunProps::direct(FontProps {
+                            italic: Some(true),
+                            ..Default::default()
+                        }),
+                    });
+                    i = end + 1;
+                    continue;
+                }
+            }
+        }
+        text_buf.push(c);
+        i += 1;
+    }
+    flush_text(&mut text_buf, &mut out);
+    Ok(merge_styled(out))
+}
+
+fn merge_styled(inlines: Vec<Inline>) -> Vec<Inline> {
+    // Flatten nested emphasis that the writer would emit as stacked markers
+    // inside a span: already fine as nested Styled.
+    inlines
+}
+
+fn try_parse_image(
+    chars: &[char],
+    start: usize,
+    ctx: &mut BodyParser<'_>,
+) -> Result<Option<(ImageRef, usize)>, ParseError> {
+    // ![alt](path){attrs}?
+    if start + 1 >= chars.len() || chars[start] != '!' || chars[start + 1] != '[' {
+        return Ok(None);
+    }
+    let alt_end = match find_closing_bracket(chars, start + 2) {
+        Some(e) => e,
+        None => return Ok(None),
+    };
+    let alt: String = chars[start + 2..alt_end].iter().collect();
+    let alt = unescape(&alt);
+    let mut i = alt_end + 1;
+    if i >= chars.len() || chars[i] != '(' {
+        return Ok(None);
+    }
+    i += 1;
+    let (path, next) = read_link_dest(chars, i)?;
+    i = next;
+    let mut attrs = Attrs::new();
+    if i < chars.len() && chars[i] == '{' {
+        if let Some(end) = find_closing_brace(chars, i + 1) {
+            let raw: String = chars[i..=end].iter().collect();
+            attrs = Attrs::parse(&raw).unwrap_or_default();
+            i = end + 1;
+        }
+    }
+    let img = ctx.load_image(&path, attrs, alt)?;
+    Ok(Some((img, i)))
+}
+
+fn try_parse_bracket(
+    chars: &[char],
+    start: usize,
+    ctx: &mut BodyParser<'_>,
+) -> Result<Option<(Inline, usize)>, ParseError> {
+    if chars[start] != '[' {
+        return Ok(None);
+    }
+    let end = match find_closing_bracket(chars, start + 1) {
+        Some(e) => e,
+        None => return Ok(None),
+    };
+    let inner: String = chars[start + 1..end].iter().collect();
+    let mut i = end + 1;
+    // Link [text](url){attrs}?
+    if i < chars.len() && chars[i] == '(' {
+        i += 1;
+        let (url, next) = read_link_dest(chars, i)?;
+        i = next;
+        let content = parse_inlines_inner(&inner, ctx)?;
+        let mut props = RunProps::default();
+        if i < chars.len() && chars[i] == '{' {
+            if let Some(aend) = find_closing_brace(chars, i + 1) {
+                let raw: String = chars[i..=aend].iter().collect();
+                if let Some(attrs) = Attrs::parse(&raw) {
+                    props = run_props_from_attrs(&attrs);
+                }
+                i = aend + 1;
+            }
+        }
+        return Ok(Some((
+            Inline::Link {
+                target: url,
+                content,
+                props,
+            },
+            i,
+        )));
+    }
+    // Span [text]{attrs} or []{attrs}
+    if i < chars.len() && chars[i] == '{' {
+        if let Some(aend) = find_closing_brace(chars, i + 1) {
+            let raw: String = chars[i..=aend].iter().collect();
+            let attrs = Attrs::parse(&raw).unwrap_or_default();
+            i = aend + 1;
+            // breaks
+            if attrs.has_class("break") {
+                let kind = match attrs.get("kind").unwrap_or("line") {
+                    "page" => BreakKind::Page,
+                    "column" => BreakKind::Column,
+                    _ => BreakKind::Line,
+                };
+                return Ok(Some((Inline::Break(kind), i)));
+            }
+            // empty paragraph marker handled at block level
+            if attrs.has_class("empty") && inner.is_empty() {
+                return Ok(None);
+            }
+            // field
+            if attrs.has_class("field") {
+                let kind = match attrs.get("field").unwrap_or("") {
+                    "PAGE" => FieldKind::Page,
+                    "NUMPAGES" => FieldKind::NumPages,
+                    "DATE" => FieldKind::Date,
+                    "TIME" => FieldKind::Time,
+                    "TOC" => FieldKind::Toc,
+                    "REF" => FieldKind::Ref,
+                    other => FieldKind::Other(other.to_string()),
+                };
+                let instruction = attrs.get("instr").unwrap_or(kind.as_str()).to_string();
+                return Ok(Some((
+                    Inline::Field {
+                        kind,
+                        cached: unescape(&inner),
+                        instruction,
+                    },
+                    i,
+                )));
+            }
+            let content = if inner.is_empty() {
+                Vec::new()
+            } else {
+                parse_inlines_inner(&inner, ctx)?
+            };
+            // Strip emphasis markers that are also represented as attrs? Writer
+            // nests markers then wraps span. Content already has Styled nodes.
+            let props = run_props_from_attrs(&attrs);
+            if props.is_empty() {
+                return Ok(Some((
+                    Inline::Styled {
+                        content,
+                        props: RunProps::default(),
+                    },
+                    i,
+                )));
+            }
+            return Ok(Some((Inline::Styled { content, props }, i)));
+        }
+    }
+    Ok(None)
+}
+
+fn read_link_dest(chars: &[char], mut i: usize) -> Result<(String, usize), ParseError> {
+    if i < chars.len() && chars[i] == '<' {
+        i += 1;
+        let start = i;
+        while i < chars.len() && chars[i] != '>' {
+            i += 1;
+        }
+        let path: String = chars[start..i].iter().collect();
+        if i < chars.len() {
+            i += 1; // >
+        }
+        if i < chars.len() && chars[i] == ')' {
+            i += 1;
+        }
+        return Ok((path.replace("%3E", ">"), i));
+    }
+    let start = i;
+    while i < chars.len() && chars[i] != ')' {
+        i += 1;
+    }
+    let path: String = chars[start..i].iter().collect();
+    if i < chars.len() {
+        i += 1; // )
+    }
+    Ok((path, i))
+}
+
+fn find_closing_bracket(chars: &[char], mut i: usize) -> Option<usize> {
+    let mut depth = 1i32;
+    while i < chars.len() {
+        match chars[i] {
+            '\\' => i += 2,
+            '[' => {
+                depth += 1;
+                i += 1;
+            }
+            ']' => {
+                depth -= 1;
+                if depth == 0 {
+                    return Some(i);
+                }
+                i += 1;
+            }
+            _ => i += 1,
+        }
+    }
+    None
+}
+
+fn find_closing_brace(chars: &[char], mut i: usize) -> Option<usize> {
+    let mut depth = 1i32;
+    let mut in_str = false;
+    while i < chars.len() {
+        let c = chars[i];
+        if in_str {
+            if c == '\\' {
+                i += 2;
+                continue;
+            }
+            if c == '"' {
+                in_str = false;
+            }
+            i += 1;
+            continue;
+        }
+        match c {
+            '"' => {
+                in_str = true;
+                i += 1;
+            }
+            '{' => {
+                depth += 1;
+                i += 1;
+            }
+            '}' => {
+                depth -= 1;
+                if depth == 0 {
+                    return Some(i);
+                }
+                i += 1;
+            }
+            _ => i += 1,
+        }
+    }
+    None
+}
+
+fn find_closing_delim(chars: &[char], start: usize, delim: &str) -> Option<usize> {
+    let d: Vec<char> = delim.chars().collect();
+    let mut i = start;
+    while i + d.len() <= chars.len() {
+        if chars[i] == '\\' {
+            i += 2;
+            continue;
+        }
+        if chars[i..].starts_with(&d) {
+            // For single *, don't match the first * of **
+            if delim == "*" && i + 1 < chars.len() && chars[i + 1] == '*' {
+                i += 1;
+                continue;
+            }
+            return Some(i);
+        }
+        i += 1;
+    }
+    None
+}
+
+// ---------------------------------------------------------------------------
+// Attr → IR helpers
+// ---------------------------------------------------------------------------
+
+fn paragraph_format_from_attrs(attrs: &Attrs, is_heading: bool) -> ParaFormat {
+    let mut format = ParaFormat::default();
+    // Style = first class that is not a known structural class
+    for class in attrs.classes() {
+        if matches!(
+            class.as_str(),
+            "empty"
+                | "table"
+                | "row"
+                | "cell"
+                | "header"
+                | "footer"
+                | "section"
+                | "raw"
+                | "textbox"
+        ) {
+            continue;
+        }
+        format.style = Some(StyleId::new(class.clone()));
+        break;
+    }
+    let mut direct = docsai_model::style::ParaProps::default();
+    if let Some(a) = attrs.get("align") {
+        direct.align = Some(match a {
+            "center" => Align::Center,
+            "right" => Align::Right,
+            "justify" => Align::Justify,
+            _ => Align::Left,
+        });
+    }
+    direct.indent_left = attrs.get("indent-left").and_then(Length::parse);
+    direct.indent_right = attrs.get("indent-right").and_then(Length::parse);
+    direct.indent_first_line = attrs.get("indent-first-line").and_then(Length::parse);
+    direct.indent_hanging = attrs.get("indent-hanging").and_then(Length::parse);
+    direct.space_before = attrs.get("space-before").and_then(Length::parse);
+    direct.space_after = attrs.get("space-after").and_then(Length::parse);
+    if let Some(bg) = attrs.get("background") {
+        direct.background = Some(bg.to_string());
+    }
+    if attrs.get("keep-with-next") == Some("true") {
+        direct.keep_with_next = Some(true);
+    }
+    if attrs.get("page-break-before") == Some("true") {
+        direct.page_break_before = Some(true);
+    }
+    if !is_heading {
+        if let Some(level) = attrs.get("outline-level").and_then(|v| v.parse().ok()) {
+            direct.outline_level = Some(level);
+        }
+    }
+    format.direct = direct;
+    format
+}
+
+fn run_props_from_attrs(attrs: &Attrs) -> RunProps {
+    let mut props = RunProps::default();
+    let mut font = FontProps::default();
+    for class in attrs.classes() {
+        match class.as_str() {
+            "underline" => {
+                font.underline = Some(match attrs.get("underline") {
+                    Some("double") => Underline::Double,
+                    Some("thick") => Underline::Thick,
+                    Some("dotted") => Underline::Dotted,
+                    Some("dashed") => Underline::Dashed,
+                    Some("wave") => Underline::Wave,
+                    Some("none") => Underline::None,
+                    _ => Underline::Single,
+                });
+            }
+            "sup" => font.vert_align = Some(VertAlign::Superscript),
+            "sub" => font.vert_align = Some(VertAlign::Subscript),
+            "small-caps" => font.small_caps = Some(true),
+            "caps" => font.caps = Some(true),
+            "field" | "break" | "empty" => {}
+            other => {
+                if props.style.is_none() {
+                    props.style = Some(StyleId::new(other));
+                }
+            }
+        }
+    }
+    if attrs.get("bold") == Some("false") {
+        font.bold = Some(false);
+    }
+    if attrs.get("italic") == Some("false") {
+        font.italic = Some(false);
+    }
+    if let Some(c) = attrs.get("color") {
+        font.color = Some(c.to_string());
+    }
+    if let Some(h) = attrs.get("highlight") {
+        font.highlight = Some(h.to_string());
+    }
+    if let Some(f) = attrs.get("font") {
+        font.name = Some(f.to_string());
+    }
+    if let Some(s) = attrs.get("size").and_then(Length::parse) {
+        font.size = Some(s);
+    }
+    props.direct = font;
+    props
+}
+
+fn parse_anchor(attrs: &Attrs) -> Anchor {
+    match attrs.get("anchor").unwrap_or("inline") {
+        "floating" | "behind" => {
+            let behind = attrs.get("anchor") == Some("behind");
+            let rel_h = parse_rel(attrs.get("relative-to").unwrap_or("margin"));
+            let rel_v = attrs.get("relative-to-v").map(parse_rel).unwrap_or(rel_h);
+            let h = if let Some(a) = attrs.get("align-h") {
+                AxisPos::Align(parse_align_kw(a))
+            } else {
+                AxisPos::Offset(
+                    attrs
+                        .get("x")
+                        .and_then(Length::parse)
+                        .unwrap_or(Length::ZERO),
+                )
+            };
+            let v = if let Some(a) = attrs.get("align-v") {
+                AxisPos::Align(parse_align_kw(a))
+            } else {
+                AxisPos::Offset(
+                    attrs
+                        .get("y")
+                        .and_then(Length::parse)
+                        .unwrap_or(Length::ZERO),
+                )
+            };
+            let wrap = match attrs.get("wrap").unwrap_or("square") {
+                "tight" => WrapMode::Tight,
+                "through" => WrapMode::Through,
+                "top-bottom" => WrapMode::TopBottom,
+                "none" => WrapMode::None,
+                _ => WrapMode::Square,
+            };
+            let wrap_side = match attrs.get("wrap-side").unwrap_or("both") {
+                "left" => WrapSide::Left,
+                "right" => WrapSide::Right,
+                "largest" => WrapSide::Largest,
+                _ => WrapSide::Both,
+            };
+            Anchor::Floating {
+                relative_to_h: rel_h,
+                relative_to_v: rel_v,
+                position: HVPos { h, v },
+                wrap,
+                wrap_side,
+                behind_text: behind,
+            }
+        }
+        "absolute" => Anchor::SheetAbsolute {
+            pos: docsai_model::units::Point::new(
+                attrs
+                    .get("x")
+                    .and_then(Length::parse)
+                    .unwrap_or(Length::ZERO),
+                attrs
+                    .get("y")
+                    .and_then(Length::parse)
+                    .unwrap_or(Length::ZERO),
+            ),
+        },
+        _ => Anchor::Inline,
+    }
+}
+
+fn parse_rel(v: &str) -> RelBase {
+    match v {
+        "page" => RelBase::Page,
+        "paragraph" => RelBase::Paragraph,
+        "character" => RelBase::Character,
+        "line" => RelBase::Line,
+        "column" => RelBase::Column,
+        _ => RelBase::Margin,
+    }
+}
+
+fn parse_align_kw(v: &str) -> AlignKeyword {
+    match v {
+        "center" => AlignKeyword::Center,
+        "right" => AlignKeyword::Right,
+        "inside" => AlignKeyword::Inside,
+        "outside" => AlignKeyword::Outside,
+        "top" => AlignKeyword::Top,
+        "middle" => AlignKeyword::Middle,
+        "bottom" => AlignKeyword::Bottom,
+        _ => AlignKeyword::Left,
+    }
+}
+
+fn parse_scope(v: Option<&str>) -> HeaderScope {
+    match v.unwrap_or("default") {
+        "first" => HeaderScope::First,
+        "even" => HeaderScope::Even,
+        _ => HeaderScope::Default,
+    }
+}
+
+fn apply_table_attrs(table: &mut Table, attrs: &Attrs) {
+    if let Some(style) = attrs.get("style") {
+        table.style = Some(StyleId::new(style));
+    }
+    if let Some(widths) = attrs.get("col-widths") {
+        table.col_widths = widths
+            .split(',')
+            .filter_map(|w| Length::parse(w.trim()))
+            .collect();
+    }
+    if attrs.get("header-row") == Some("false") {
+        table.header_row = false;
+    }
+}
+
+fn parse_raw_block(attrs: &Attrs, body: &str) -> Result<RawFragment, ParseError> {
+    let format = attrs.get("format").unwrap_or("ooxml").to_string();
+    let part = attrs.get("part").unwrap_or("").to_string();
+    let id = attrs
+        .id_ref()
+        .map(RawId::new)
+        .unwrap_or_else(|| RawId::new("raw"));
+    // Body is a fenced code block
+    let mut lines = body.lines();
+    let first = lines.next().unwrap_or("");
+    let fence = first.chars().take_while(|c| *c == '`').count();
+    let content = if fence >= 3 {
+        let mut content_lines: Vec<&str> = Vec::new();
+        for l in lines {
+            if l.chars().take_while(|c| *c == '`').count() >= fence
+                && l.trim().chars().all(|c| c == '`')
+            {
+                break;
+            }
+            content_lines.push(l);
+        }
+        content_lines.join("\n")
+    } else {
+        body.trim().to_string()
+    };
+    Ok(RawFragment {
+        id,
+        format,
+        part,
+        content,
+    })
+}
+
+// ---------------------------------------------------------------------------
+// Chunk / list / table utilities
+// ---------------------------------------------------------------------------
+
+fn split_top_level(text: &str) -> Vec<&str> {
+    let mut chunks = Vec::new();
+    let mut start = 0usize;
+    let bytes = text.as_bytes();
+    let mut i = 0usize;
+    let mut fence_depth = 0i32;
+    while i < bytes.len() {
+        if bytes[i] == b'\n' {
+            // Check blank line
+            let mut j = i + 1;
+            while j < bytes.len() && bytes[j] == b'\r' {
+                j += 1;
+            }
+            if j < bytes.len() && bytes[j] == b'\n' {
+                // blank line at j
+                if fence_depth == 0 {
+                    let chunk = &text[start..i];
+                    if !chunk.trim().is_empty() {
+                        chunks.push(chunk);
+                    }
+                    start = j + 1;
+                    i = j + 1;
+                    continue;
+                }
+            }
+            // track fences on this line
+            let line_start = text[..i].rfind('\n').map(|p| p + 1).unwrap_or(0);
+            let line = &text[line_start..i];
+            let t = line.trim();
+            if t.starts_with(":::") {
+                let rest = t.trim_start_matches(':').trim();
+                if rest.is_empty() {
+                    fence_depth = (fence_depth - 1).max(0);
+                } else {
+                    fence_depth += 1;
+                }
+            }
+        }
+        i += 1;
+    }
+    if start < text.len() {
+        let chunk = &text[start..];
+        if !chunk.trim().is_empty() {
+            chunks.push(chunk);
+        }
+    }
+    chunks
+}
+
+fn split_one_fence(text: &str, line: usize) -> Result<(Attrs, &str, &str), ParseError> {
+    let text = text.trim_start_matches('\n');
+    let mut lines = text.lines();
+    let first = lines
+        .next()
+        .ok_or_else(|| ParseError::unexpected(line, "expected fenced container"))?;
+    if !first.trim_start().starts_with(":::") {
+        return Err(ParseError::unexpected(line, "expected :::"));
+    }
+    let attr_src = first.trim_start().trim_start_matches(':').trim();
+    let attrs = Attrs::parse(attr_src).unwrap_or_default();
+    let after_first = first.len() + 1; // + newline; careful with end
+    let body_start = if text.len() > first.len() {
+        // account for \n
+        first.len() + 1
+    } else {
+        first.len()
+    };
+    let mut depth = 1i32;
+    let mut consumed = body_start;
+    let mut body_end = body_start;
+    for l in text[body_start..].lines() {
+        let t = l.trim();
+        let line_len = l.len() + 1; // include \n
+        if t.starts_with(":::") {
+            let rest = t.trim_start_matches(':').trim();
+            if rest.is_empty() {
+                depth -= 1;
+                if depth == 0 {
+                    let body = &text[body_start..consumed];
+                    let _next = if consumed + l.len() < text.len() {
+                        text[consumed + l.len()..].trim_start_matches('\n')
+                    } else {
+                        ""
+                    };
+                    // fix next offset
+                    let next_start = consumed + l.len();
+                    let next = if next_start < text.len() {
+                        let n = &text[next_start..];
+                        n.strip_prefix('\n').unwrap_or(n)
+                    } else {
+                        ""
+                    };
+                    let _ = after_first;
+                    let _ = body_end;
+                    return Ok((attrs, body.trim_end_matches('\n'), next));
+                }
+            } else {
+                depth += 1;
+            }
+        }
+        consumed += line_len;
+        body_end = consumed;
+    }
+    Err(ParseError::unexpected(line, "unclosed fenced container"))
+}
+
+fn looks_like_table(text: &str) -> bool {
+    let mut lines = text.lines().filter(|l| !l.trim().is_empty());
+    let Some(first) = lines.next() else {
+        return false;
+    };
+    if !first.contains('|') {
+        return false;
+    }
+    let Some(second) = lines.next() else {
+        return false;
+    };
+    second.contains('|') && second.chars().all(|c| matches!(c, '|' | '-' | ':' | ' '))
+}
+
+fn looks_like_list(text: &str) -> bool {
+    let first = text.lines().find(|l| !l.trim().is_empty()).unwrap_or("");
+    let t = first.trim_start();
+    t.starts_with("- ")
+        || t.starts_with("* ")
+        || t.chars().next().is_some_and(|c| c.is_ascii_digit())
+            && t.split_whitespace().next().is_some_and(|w| {
+                w.ends_with('.') && w[..w.len() - 1].chars().all(|c| c.is_ascii_digit())
+            })
+}
+
+struct ListItemRaw {
+    ordered: bool,
+    marker_len: usize,
+    lines: Vec<String>,
+}
+
+fn collect_list_items(text: &str) -> Vec<ListItemRaw> {
+    let mut items = Vec::new();
+    let mut current: Option<ListItemRaw> = None;
+    for line in text.lines() {
+        let indent = line.chars().take_while(|c| *c == ' ').count();
+        let trimmed = &line[indent..];
+        if let Some((ordered, marker_len, content)) = match_list_marker(trimmed) {
+            if indent == 0 {
+                if let Some(item) = current.take() {
+                    items.push(item);
+                }
+                current = Some(ListItemRaw {
+                    ordered,
+                    marker_len,
+                    lines: vec![content.to_string()],
+                });
+                continue;
+            }
+        }
+        if let Some(item) = current.as_mut() {
+            item.lines.push(line.to_string());
+        }
+    }
+    if let Some(item) = current {
+        items.push(item);
+    }
+    items
+}
+
+fn match_list_marker(trimmed: &str) -> Option<(bool, usize, &str)> {
+    if let Some(rest) = trimmed.strip_prefix("- ") {
+        return Some((false, 2, rest));
+    }
+    if let Some(rest) = trimmed.strip_prefix("* ") {
+        return Some((false, 2, rest));
+    }
+    let mut i = 0usize;
+    while i < trimmed.len() && trimmed.as_bytes()[i].is_ascii_digit() {
+        i += 1;
+    }
+    if i > 0 && trimmed[i..].starts_with(". ") {
+        return Some((true, i + 2, &trimmed[i + 2..]));
+    }
+    None
+}
+
+fn strip_list_indent(text: &str, marker_len: usize) -> String {
+    let mut out = String::new();
+    for line in text.lines() {
+        let stripped =
+            if line.len() >= marker_len && line.chars().take(marker_len).all(|c| c == ' ') {
+                &line[marker_len..]
+            } else {
+                line.trim_start()
+            };
+        if !out.is_empty() {
+            out.push('\n');
+        }
+        out.push_str(stripped);
+    }
+    out
+}
+
+fn strip_heading(text: &str) -> Option<(u8, &str)> {
+    let mut n = 0usize;
+    let bytes = text.as_bytes();
+    while n < bytes.len() && bytes[n] == b'#' && n < 6 {
+        n += 1;
+    }
+    if n == 0 || n > 6 {
+        return None;
+    }
+    if n < bytes.len() && bytes[n] == b' ' {
+        Some((n as u8, text[n + 1..].trim_end()))
+    } else {
+        None
+    }
+}
+
+fn split_trailing_attrs(text: &str) -> (&str, Option<Attrs>) {
+    let text = text.trim_end();
+    // Paragraph-level attrs are always emitted with a leading space (`Attrs::suffix`).
+    // Span/link/image attrs attach tightly: `[text]{.underline}`, `![](p){width=1}`.
+    // Only peel a trailing `{...}` when whitespace precedes it (or it is the whole line).
+    let bytes = text.as_bytes();
+    if !bytes.last().is_some_and(|b| *b == b'}') {
+        return (text, None);
+    }
+    let chars: Vec<char> = text.chars().collect();
+    let mut i = chars.len() - 1;
+    let mut depth = 0i32;
+    let mut in_str = false;
+    loop {
+        let c = chars[i];
+        if in_str {
+            if c == '"' && i > 0 && chars[i - 1] != '\\' {
+                in_str = false;
+            }
+        } else {
+            match c {
+                '"' => in_str = true,
+                '}' => depth += 1,
+                '{' => {
+                    depth -= 1;
+                    if depth == 0 {
+                        // Require whitespace before `{`, or attrs-only line.
+                        if i > 0 && !chars[i - 1].is_whitespace() {
+                            return (text, None);
+                        }
+                        let attr_str: String = chars[i..].iter().collect();
+                        if let Some(attrs) = Attrs::parse(&attr_str) {
+                            let mut end = i;
+                            while end > 0 && chars[end - 1].is_whitespace() {
+                                end -= 1;
+                            }
+                            let byte_end = text
+                                .char_indices()
+                                .nth(end)
+                                .map(|(b, _)| b)
+                                .unwrap_or(text.len());
+                            return (&text[..byte_end], Some(attrs));
+                        }
+                        return (text, None);
+                    }
+                }
+                _ => {}
+            }
+        }
+        if i == 0 {
+            break;
+        }
+        i -= 1;
+    }
+    (text, None)
+}
+
+fn split_table_row(line: &str) -> Vec<String> {
+    let line = line.trim().trim_matches('|');
+    let mut cells = Vec::new();
+    let mut cur = String::new();
+    let mut chars = line.chars().peekable();
+    while let Some(c) = chars.next() {
+        if c == '\\' {
+            if let Some(n) = chars.next() {
+                cur.push('\\');
+                cur.push(n);
+            } else {
+                cur.push('\\');
+            }
+            continue;
+        }
+        if c == '|' {
+            cells.push(cur.trim().to_string());
+            cur.clear();
+            continue;
+        }
+        cur.push(c);
+    }
+    cells.push(cur.trim().to_string());
+    cells
+}
+
+fn parse_footnote_def(chunk: &str) -> Option<(u32, &str)> {
+    let t = chunk.trim_start();
+    let rest = t.strip_prefix("[^")?;
+    let end = rest.find("]:")?;
+    let n: u32 = rest[..end].parse().ok()?;
+    let body = rest[end + 2..].trim_start();
+    Some((n, body))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use docsai_model::MemoryAssetStore;
+
+    #[test]
+    fn parses_basic_styles_golden() {
+        let path = concat!(
+            env!("CARGO_MANIFEST_DIR"),
+            "/../../corpus/docx/basic-styles.expected.dmk.md"
+        );
+        let md = std::fs::read_to_string(path).unwrap();
+        let mut assets = MemoryAssetStore::new();
+        let (doc, _report) = parse(&md, &mut assets).expect("parse");
+        let Document::Text(text) = doc else {
+            panic!("expected text");
+        };
+        assert!(text.blocks().any(|b| matches!(b, Block::Heading(_))));
+        let plain: String = text
+            .blocks()
+            .filter_map(|b| match b {
+                Block::Paragraph(p) => Some(p.plain_text()),
+                Block::Heading(h) => Some(h.paragraph.plain_text()),
+                _ => None,
+            })
+            .collect::<Vec<_>>()
+            .join("\n");
+        assert!(plain.contains("negrita"));
+        assert!(plain.contains("Titulo de nivel 1"));
+    }
+
+    #[test]
+    fn round_trip_basic_text() {
+        let path = concat!(
+            env!("CARGO_MANIFEST_DIR"),
+            "/../../corpus/docx/basic-text.expected.dmk.md"
+        );
+        let md = std::fs::read_to_string(path).unwrap();
+        let mut assets = MemoryAssetStore::new();
+        let (doc, _) = parse(&md, &mut assets).expect("parse");
+        let (out, _) = crate::serialize(
+            &doc,
+            &assets,
+            &crate::Options {
+                fidelity: crate::Fidelity::Full,
+                assets_dir: "assets".into(),
+                source_format: docsai_model::Format::Docx,
+            },
+        );
+        assert_eq!(out, md, "serialize(parse(md)) must equal md");
+    }
+
+    fn round_trip_golden(name: &str) {
+        let path = format!(
+            "{}/../../corpus/docx/{name}.expected.dmk.md",
+            env!("CARGO_MANIFEST_DIR")
+        );
+        let md = std::fs::read_to_string(&path).unwrap_or_else(|e| panic!("{path}: {e}"));
+        let mut assets = MemoryAssetStore::new();
+        let base = std::path::Path::new(&path).parent();
+        let (doc, _) =
+            parse_with_base(&md, base, &mut assets).unwrap_or_else(|e| panic!("{name}: {e}"));
+        let (out, _) = crate::serialize(
+            &doc,
+            &assets,
+            &crate::Options {
+                fidelity: crate::Fidelity::Full,
+                assets_dir: "assets".into(),
+                source_format: docsai_model::Format::Docx,
+            },
+        );
+        assert_eq!(out, md, "{name}: serialize(parse(md)) must equal md");
+    }
+
+    #[test]
+    fn round_trip_basic_styles() {
+        round_trip_golden("basic-styles");
+    }
+
+    #[test]
+    fn round_trip_nested_lists() {
+        round_trip_golden("nested-lists");
+    }
+
+    #[test]
+    fn parses_nested_lists_golden() {
+        let path = concat!(
+            env!("CARGO_MANIFEST_DIR"),
+            "/../../corpus/docx/nested-lists.expected.dmk.md"
+        );
+        let md = std::fs::read_to_string(path).unwrap();
+        let mut assets = MemoryAssetStore::new();
+        let (doc, _) = parse(&md, &mut assets).expect("parse nested-lists");
+        let Document::Text(text) = doc else {
+            panic!("expected text");
+        };
+        assert!(
+            text.blocks().any(|b| matches!(b, Block::List(_))),
+            "expected at least one list"
+        );
+    }
+}
diff --git a/crates/docsai-docmark/src/units.rs b/crates/docsai-docmark/src/units.rs
index bb26789..9d46406 100644
--- a/crates/docsai-docmark/src/units.rs
+++ b/crates/docsai-docmark/src/units.rs
@@ -1,7 +1,7 @@
 //! How lengths and numbers appear in DocMark.
 //!
 //! Centralised so that every attribute renders a length the same way, which
-//! the idempotence test of Fase 2 will depend on.
+//! the idempotence test of Phase 2 will depend on.
 
 use docsai_model::units::{trim_float, Length};
 
diff --git a/crates/docsai-docmark/src/writer.rs b/crates/docsai-docmark/src/writer.rs
index 9ad1238..651c85e 100644
--- a/crates/docsai-docmark/src/writer.rs
+++ b/crates/docsai-docmark/src/writer.rs
@@ -1,8 +1,8 @@
 //! IR → DocMark (spec §3, §7, §8).
 //!
-//! The serialiser is written by hand rather than delegated to a Markdown
+//! The serializer is written by hand rather than delegated to a Markdown
 //! library so that every byte of the output is under our control: the
-//! idempotence test of Fase 2 (`serialize(parse(md)) == md`) has no room for a
+//! idempotence test of Phase 2 (`serialize(parse(md)) == md`) has no room for a
 //! library's own formatting opinions.
 
 use docsai_model::assets::AssetStore;
diff --git a/crates/docsai-docmark/src/yaml.rs b/crates/docsai-docmark/src/yaml.rs
new file mode 100644
index 0000000..d3606bb
--- /dev/null
+++ b/crates/docsai-docmark/src/yaml.rs
@@ -0,0 +1,487 @@
+//! Small YAML subset used by DocMark front matter.
+//!
+//! Only the shapes the serialiser emits are accepted: scalars, flow maps,
+//! nested block maps and simple sequences of flow maps.
+
+use std::collections::BTreeMap;
+
+#[derive(Debug, Clone, PartialEq)]
+pub enum Value {
+    Null,
+    Bool(bool),
+    Number(f64),
+    String(String),
+    Seq(Vec<Value>),
+    Map(BTreeMap<String, Value>),
+}
+
+impl Value {
+    pub fn as_str(&self) -> Option<&str> {
+        match self {
+            Value::String(s) => Some(s),
+            _ => None,
+        }
+    }
+
+    pub fn as_bool(&self) -> Option<bool> {
+        match self {
+            Value::Bool(b) => Some(*b),
+            _ => None,
+        }
+    }
+
+    pub fn as_f64(&self) -> Option<f64> {
+        match self {
+            Value::Number(n) => Some(*n),
+            Value::String(s) => s.parse().ok(),
+            _ => None,
+        }
+    }
+
+    pub fn as_i64(&self) -> Option<i64> {
+        self.as_f64().map(|n| n as i64)
+    }
+
+    pub fn as_u16(&self) -> Option<u16> {
+        self.as_f64().and_then(|n| {
+            if n >= 0.0 && n <= u16::MAX as f64 {
+                Some(n as u16)
+            } else {
+                None
+            }
+        })
+    }
+
+    pub fn as_u8(&self) -> Option<u8> {
+        self.as_f64().and_then(|n| {
+            if n >= 0.0 && n <= u8::MAX as f64 {
+                Some(n as u8)
+            } else {
+                None
+            }
+        })
+    }
+
+    pub fn as_map(&self) -> Option<&BTreeMap<String, Value>> {
+        match self {
+            Value::Map(m) => Some(m),
+            _ => None,
+        }
+    }
+
+    pub fn as_seq(&self) -> Option<&[Value]> {
+        match self {
+            Value::Seq(s) => Some(s),
+            _ => None,
+        }
+    }
+
+    pub fn get(&self, key: &str) -> Option<&Value> {
+        self.as_map()?.get(key)
+    }
+
+    pub fn string_or_empty(&self) -> String {
+        match self {
+            Value::String(s) => s.clone(),
+            Value::Number(n) => {
+                let mut s = format!("{n}");
+                if s.contains('.') {
+                    while s.ends_with('0') {
+                        s.pop();
+                    }
+                    if s.ends_with('.') {
+                        s.pop();
+                    }
+                }
+                s
+            }
+            Value::Bool(b) => b.to_string(),
+            _ => String::new(),
+        }
+    }
+}
+
+/// Parses a YAML document body (without the `---` fences) into a map.
+pub fn parse_document(text: &str) -> Result<BTreeMap<String, Value>, String> {
+    let lines: Vec<&str> = text.lines().collect();
+    let mut parser = Parser {
+        lines: &lines,
+        index: 0,
+    };
+    parser.parse_block_map(0)
+}
+
+struct Parser<'a> {
+    lines: &'a [&'a str],
+    index: usize,
+}
+
+impl<'a> Parser<'a> {
+    fn line_no(&self) -> usize {
+        self.index + 1
+    }
+
+    fn peek(&self) -> Option<&'a str> {
+        self.lines.get(self.index).copied()
+    }
+
+    fn bump(&mut self) {
+        self.index += 1;
+    }
+
+    fn parse_block_map(&mut self, indent: usize) -> Result<BTreeMap<String, Value>, String> {
+        let mut map = BTreeMap::new();
+        while let Some(raw) = self.peek() {
+            if raw.trim().is_empty() {
+                self.bump();
+                continue;
+            }
+            let current = leading_spaces(raw);
+            if current < indent {
+                break;
+            }
+            if current > indent {
+                return Err(format!(
+                    "line {}: unexpected indent {current}, expected {indent}",
+                    self.line_no()
+                ));
+            }
+            let content = &raw[indent..];
+            let (key, rest) = split_key(content)
+                .ok_or_else(|| format!("line {}: expected mapping key", self.line_no()))?;
+            self.bump();
+            let value = if rest.is_empty() {
+                self.parse_nested(indent + 2)?
+            } else {
+                parse_flow(rest.trim()).map_err(|e| format!("line {}: {e}", self.line_no() - 1))?
+            };
+            map.insert(key, value);
+        }
+        Ok(map)
+    }
+
+    fn parse_nested(&mut self, indent: usize) -> Result<Value, String> {
+        let Some(raw) = self.peek() else {
+            return Ok(Value::Null);
+        };
+        if raw.trim().is_empty() {
+            self.bump();
+            return self.parse_nested(indent);
+        }
+        let current = leading_spaces(raw);
+        if current < indent {
+            return Ok(Value::Null);
+        }
+        let content = raw.trim_start();
+        if content.starts_with("- ") || content == "-" {
+            return self.parse_block_seq(indent).map(Value::Seq);
+        }
+        self.parse_block_map(indent).map(Value::Map)
+    }
+
+    fn parse_block_seq(&mut self, indent: usize) -> Result<Vec<Value>, String> {
+        let mut items = Vec::new();
+        while let Some(raw) = self.peek() {
+            if raw.trim().is_empty() {
+                self.bump();
+                continue;
+            }
+            let current = leading_spaces(raw);
+            if current < indent {
+                break;
+            }
+            if current > indent {
+                return Err(format!(
+                    "line {}: unexpected indent in sequence",
+                    self.line_no()
+                ));
+            }
+            let content = raw[indent..].trim_start();
+            let Some(rest) = content.strip_prefix('-') else {
+                break;
+            };
+            let rest = rest.strip_prefix(' ').unwrap_or(rest).trim();
+            self.bump();
+            let value = if rest.is_empty() {
+                self.parse_nested(indent + 2)?
+            } else {
+                parse_flow(rest).map_err(|e| format!("line {}: {e}", self.line_no() - 1))?
+            };
+            items.push(value);
+        }
+        Ok(items)
+    }
+}
+
+fn leading_spaces(line: &str) -> usize {
+    line.chars().take_while(|c| *c == ' ').count()
+}
+
+fn split_key(content: &str) -> Option<(String, &str)> {
+    let content = content.trim_end();
+    if let Some(rest) = content.strip_prefix('"') {
+        let mut out = String::new();
+        let mut idx = 0usize;
+        let bytes = rest.as_bytes();
+        while idx < bytes.len() {
+            if bytes[idx] == b'\\' {
+                let next = rest[idx + 1..].chars().next()?;
+                match next {
+                    '"' => out.push('"'),
+                    '\\' => out.push('\\'),
+                    'n' => out.push('\n'),
+                    other => {
+                        out.push('\\');
+                        out.push(other);
+                    }
+                }
+                idx += 1 + next.len_utf8();
+                continue;
+            }
+            if bytes[idx] == b'"' {
+                let after = rest[idx + 1..].trim_start();
+                let after = after.strip_prefix(':')?;
+                return Some((out, after.trim_start()));
+            }
+            let ch = rest[idx..].chars().next()?;
+            out.push(ch);
+            idx += ch.len_utf8();
+        }
+        return None;
+    }
+    let colon = content.find(':')?;
+    let key = content[..colon].trim();
+    if key.is_empty() {
+        return None;
+    }
+    Some((key.to_string(), content[colon + 1..].trim_start()))
+}
+
+/// Parses a flow scalar, map or sequence.
+pub fn parse_flow(input: &str) -> Result<Value, String> {
+    let input = input.trim();
+    if input.is_empty() {
+        return Ok(Value::Null);
+    }
+    if input.starts_with('{') {
+        return parse_flow_map(input);
+    }
+    if input.starts_with('[') {
+        return parse_flow_seq(input);
+    }
+    Ok(parse_scalar(input))
+}
+
+fn parse_scalar(input: &str) -> Value {
+    let input = input.trim();
+    if let Some(s) = unquote(input) {
+        return Value::String(s);
+    }
+    match input {
+        "true" | "True" | "TRUE" => return Value::Bool(true),
+        "false" | "False" | "FALSE" => return Value::Bool(false),
+        "null" | "Null" | "~" | "" => return Value::Null,
+        _ => {}
+    }
+    if input
+        .chars()
+        .all(|c| c.is_ascii_digit() || matches!(c, '-' | '+' | '.' | 'e' | 'E'))
+    {
+        if let Ok(n) = input.parse::<f64>() {
+            return Value::Number(n);
+        }
+    }
+    Value::String(input.to_string())
+}
+
+fn unquote(input: &str) -> Option<String> {
+    if !input.starts_with('"') || !input.ends_with('"') || input.len() < 2 {
+        return None;
+    }
+    // Ensure the last quote is not escaped.
+    let inner = &input[1..input.len() - 1];
+    let mut out = String::new();
+    let mut chars = inner.chars();
+    while let Some(c) = chars.next() {
+        match c {
+            '\\' => match chars.next() {
+                Some('"') => out.push('"'),
+                Some('\\') => out.push('\\'),
+                Some('n') => out.push('\n'),
+                Some('r') => out.push('\r'),
+                Some('t') => out.push('\t'),
+                Some(other) => {
+                    out.push('\\');
+                    out.push(other);
+                }
+                None => out.push('\\'),
+            },
+            other => out.push(other),
+        }
+    }
+    Some(out)
+}
+
+fn parse_flow_map(input: &str) -> Result<Value, String> {
+    let inner = strip_wrappers(input, '{', '}')?;
+    let mut map = BTreeMap::new();
+    if inner.trim().is_empty() {
+        return Ok(Value::Map(map));
+    }
+    for item in split_flow_items(inner)? {
+        let (key, value) = split_flow_pair(item)?;
+        map.insert(key, parse_flow(value)?);
+    }
+    Ok(Value::Map(map))
+}
+
+fn parse_flow_seq(input: &str) -> Result<Value, String> {
+    let inner = strip_wrappers(input, '[', ']')?;
+    if inner.trim().is_empty() {
+        return Ok(Value::Seq(Vec::new()));
+    }
+    let mut items = Vec::new();
+    for item in split_flow_items(inner)? {
+        items.push(parse_flow(item)?);
+    }
+    Ok(Value::Seq(items))
+}
+
+fn strip_wrappers(input: &str, open: char, close: char) -> Result<&str, String> {
+    let input = input.trim();
+    if !input.starts_with(open) || !input.ends_with(close) {
+        return Err(format!("expected {open}...{close}"));
+    }
+    Ok(&input[open.len_utf8()..input.len() - close.len_utf8()])
+}
+
+fn split_flow_pair(item: &str) -> Result<(String, &str), String> {
+    let item = item.trim();
+    if let Some(rest) = item.strip_prefix('"') {
+        let mut i = 0usize;
+        let bytes = rest.as_bytes();
+        while i < bytes.len() {
+            if bytes[i] == b'\\' {
+                i += 2;
+                continue;
+            }
+            if bytes[i] == b'"' {
+                let key = unquote(&item[..i + 2]).ok_or_else(|| "bad quoted key".to_string())?;
+                let after = item[i + 2..].trim_start();
+                let after = after
+                    .strip_prefix(':')
+                    .ok_or_else(|| "expected ':' after key".to_string())?;
+                return Ok((key, after.trim_start()));
+            }
+            i += 1;
+        }
+        return Err("unterminated quoted key".into());
+    }
+    let colon = item
+        .find(':')
+        .ok_or_else(|| format!("expected key: value in `{item}`"))?;
+    Ok((item[..colon].trim().to_string(), item[colon + 1..].trim()))
+}
+
+fn split_flow_items(input: &str) -> Result<Vec<&str>, String> {
+    let mut items = Vec::new();
+    let mut start = 0usize;
+    let mut depth = 0i32;
+    let mut in_string = false;
+    let mut escape = false;
+    for (i, c) in input.char_indices() {
+        if in_string {
+            if escape {
+                escape = false;
+            } else if c == '\\' {
+                escape = true;
+            } else if c == '"' {
+                in_string = false;
+            }
+            continue;
+        }
+        match c {
+            '"' => in_string = true,
+            '{' | '[' => depth += 1,
+            '}' | ']' => depth -= 1,
+            ',' if depth == 0 => {
+                items.push(input[start..i].trim());
+                start = i + c.len_utf8();
+            }
+            _ => {}
+        }
+    }
+    let tail = input[start..].trim();
+    if !tail.is_empty() {
+        items.push(tail);
+    }
+    Ok(items)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_flow_map_with_quoted_values() {
+        let v = parse_flow(r##"{ name: "Calibri Light", size: 16pt, color: "#2E74B5" }"##).unwrap();
+        let map = v.as_map().unwrap();
+        assert_eq!(
+            map.get("name").and_then(|v| v.as_str()),
+            Some("Calibri Light")
+        );
+        assert_eq!(map.get("size").and_then(|v| v.as_str()), Some("16pt"));
+        assert_eq!(map.get("color").and_then(|v| v.as_str()), Some("#2E74B5"));
+    }
+
+    #[test]
+    fn parses_nested_block_map() {
+        let text = "\
+docmark: \"1.0\"
+page:
+  size: A4
+  margins: { top: 70.85pt, bottom: 70.85pt }
+styles:
+  Heading1:
+    type: paragraph
+    name: \"heading 1\"
+";
+        let map = parse_document(text).unwrap();
+        assert_eq!(map.get("docmark").and_then(|v| v.as_str()), Some("1.0"));
+        assert_eq!(
+            map.get("page")
+                .and_then(|v| v.get("size"))
+                .and_then(|v| v.as_str()),
+            Some("A4")
+        );
+        assert_eq!(
+            map.get("styles")
+                .and_then(|v| v.get("Heading1"))
+                .and_then(|v| v.get("name"))
+                .and_then(|v| v.as_str()),
+            Some("heading 1")
+        );
+    }
+
+    #[test]
+    fn parses_list_definition_sequence() {
+        let text = "\
+list-definitions:
+  L1:
+    levels:
+      - { format: decimal, text: \"%1.\", start: 1 }
+";
+        let map = parse_document(text).unwrap();
+        let levels = map
+            .get("list-definitions")
+            .and_then(|v| v.get("L1"))
+            .and_then(|v| v.get("levels"))
+            .and_then(|v| v.as_seq())
+            .unwrap();
+        assert_eq!(levels.len(), 1);
+        assert_eq!(
+            levels[0].get("format").and_then(|v| v.as_str()),
+            Some("decimal")
+        );
+    }
+}
diff --git a/crates/docsai-mcp/src/lib.rs b/crates/docsai-mcp/src/lib.rs
index ef35a84..f75b5c3 100644
--- a/crates/docsai-mcp/src/lib.rs
+++ b/crates/docsai-mcp/src/lib.rs
@@ -1,15 +1,15 @@
 //! MCP server over stdio.
 //!
-//! Scheduled for **Fase 7** of `docs/plan-desarrollo.md`. It is a library, not
+//! Scheduled for **Phase 7** of `docs/development-plan.md`. It is a library, not
 //! a binary, so that `docsai mcp` runs inside the single distributed
-//! executable (arquitectura §2).
+//! executable (architecture §2).
 //!
 //! One rule already applies to anything added here: **stdout carries the
 //! JSON-RPC protocol and nothing else**; every log goes to stderr.
 
 #![forbid(unsafe_code)]
 
-/// Names of the tools the server will expose (arquitectura §6).
+/// Names of the tools the server will expose (architecture §6).
 pub const TOOLS: &[&str] = &[
     "convert_to_markdown",
     "convert_from_markdown",
diff --git a/crates/docsai-model/src/assets.rs b/crates/docsai-model/src/assets.rs
index d8c2251..fe0d09c 100644
--- a/crates/docsai-model/src/assets.rs
+++ b/crates/docsai-model/src/assets.rs
@@ -1,4 +1,4 @@
-//! Media storage abstraction (arquitectura §3.2).
+//! Media storage abstraction (architecture §3.2).
 //!
 //! The IR never holds image bytes: an [`ImageRef`](crate::image::ImageRef)
 //! points at an [`AssetId`] resolved by an [`AssetStore`]. `docsai-convert`
diff --git a/crates/docsai-model/src/image.rs b/crates/docsai-model/src/image.rs
index dc7685c..3be8d4f 100644
--- a/crates/docsai-model/src/image.rs
+++ b/crates/docsai-model/src/image.rs
@@ -1,4 +1,4 @@
-//! Normalised image model (arquitectura §3.1).
+//! Normalised image model (architecture §3.1).
 //!
 //! Every source format has its own graphics model — DrawingML, VML, Escher,
 //! SpreadsheetDrawingML, ODF `draw:frame`. Readers translate *into* this model
@@ -48,7 +48,7 @@ pub struct ImageRef {
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub link: Option<String>,
     /// Set when the image was *linked* rather than embedded. The referenced
-    /// content is never fetched (arquitectura §3.2, security).
+    /// content is never fetched (architecture §3.2, security).
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub external_src: Option<String>,
     /// Effects with no DocMark representation, kept as an associated raw-block.
diff --git a/crates/docsai-model/src/lib.rs b/crates/docsai-model/src/lib.rs
index 20d2213..740950f 100644
--- a/crates/docsai-model/src/lib.rs
+++ b/crates/docsai-model/src/lib.rs
@@ -1,7 +1,7 @@
 //! The docsai intermediate document model (IR).
 //!
 //! Every converter reads *into* this model and writes *from* it; no converter
-//! ever talks to another converter (arquitectura §1). The crate is
+//! ever talks to another converter (architecture §1). The crate is
 //! deliberately free of I/O and of heavy dependencies: it knows nothing about
 //! ZIP, XML or the filesystem, and media live behind the
 //! [`AssetStore`] trait.
diff --git a/crates/docsai-model/src/report.rs b/crates/docsai-model/src/report.rs
index 19b5d1a..468aa19 100644
--- a/crates/docsai-model/src/report.rs
+++ b/crates/docsai-model/src/report.rs
@@ -31,7 +31,7 @@ pub enum Warning {
     },
     /// Something was mapped, but imperfectly.
     Degraded { what: String, why: String },
-    /// Image geometry could not be mapped in full (arquitectura §3.1).
+    /// Image geometry could not be mapped in full (architecture §3.1).
     ImageGeometryDegraded { what: String, why: String },
     /// A media part could not be stored or read.
     AssetIssue { asset: String, why: String },
diff --git a/crates/docsai-model/src/sheet.rs b/crates/docsai-model/src/sheet.rs
index 4053ee5..2cf2b83 100644
--- a/crates/docsai-model/src/sheet.rs
+++ b/crates/docsai-model/src/sheet.rs
@@ -1,6 +1,6 @@
 //! Spreadsheet side of the IR.
 //!
-//! Populated from Fase 3 onwards; defined now because [`CellRef`] is part of
+//! Populated from Phase 3 onwards; defined now because [`CellRef`] is part of
 //! the shared image model and because the IR validator must know the
 //! `Workbook`-only invariants from day one.
 
diff --git a/crates/docsai-model/src/style.rs b/crates/docsai-model/src/style.rs
index 0000e24..95e8f9b 100644
--- a/crates/docsai-model/src/style.rs
+++ b/crates/docsai-model/src/style.rs
@@ -1,6 +1,6 @@
 //! Named styles with inheritance.
 //!
-//! The cardinal rule (análisis §5.2): the IR stores **a reference plus a
+//! The cardinal rule (analysis §5.2): the IR stores **a reference plus a
 //! delta**, never flattened formatting. Every field of [`FontProps`] and
 //! [`ParaProps`] is an `Option`; `None` means "inherit", not "off".
 
@@ -126,7 +126,7 @@ impl FontProps {
 
     /// The subset of `self` that is not already implied by `base`.
     ///
-    /// Used by the serialiser to honour the "economy rule" of the spec (§3.1):
+    /// Used by the serializer to honour the "economy rule" of the spec (§3.1):
     /// formatting identical to the applied style is not emitted.
     pub fn minus(&self, base: &FontProps) -> FontProps {
         macro_rules! drop_same {
diff --git a/crates/docsai-model/src/units.rs b/crates/docsai-model/src/units.rs
index 98e92af..de33baf 100644
--- a/crates/docsai-model/src/units.rs
+++ b/crates/docsai-model/src/units.rs
@@ -144,6 +144,40 @@ impl Length {
     pub const fn is_zero(self) -> bool {
         self.0 == 0
     }
+
+    /// Parses a DocMark length (`450px`, `3.5cm`, `70.85pt`, `123emu`, or a bare
+    /// number treated as pixels at 96 dpi).
+    ///
+    /// ```
+    /// use docsai_model::units::Length;
+    /// assert_eq!(Length::parse("450px"), Some(Length::from_px(450.0)));
+    /// assert_eq!(Length::parse("3.5cm"), Some(Length::from_cm(3.5)));
+    /// assert_eq!(Length::parse("70.85pt"), Some(Length::from_pt(70.85)));
+    /// assert_eq!(Length::parse("123emu"), Some(Length::from_emu(123)));
+    /// assert_eq!(Length::parse("96"), Some(Length::from_px(96.0)));
+    /// assert_eq!(Length::parse("nope"), None);
+    /// ```
+    pub fn parse(text: &str) -> Option<Length> {
+        let text = text.trim();
+        if text.is_empty() {
+            return None;
+        }
+        let split = text
+            .find(|c: char| c.is_ascii_alphabetic())
+            .unwrap_or(text.len());
+        let (number, unit) = text.split_at(split);
+        let value: f64 = number.parse().ok()?;
+        match unit {
+            "" | "px" => Some(Length::from_px(value)),
+            "cm" => Some(Length::from_cm(value)),
+            "mm" => Some(Length::from_mm(value)),
+            "pt" => Some(Length::from_pt(value)),
+            "in" | "inch" => Some(Length::from_inch(value)),
+            "emu" => Some(Length::from_emu(value.round() as i64)),
+            "twip" | "twips" => Some(Length::from_twips(value.round() as i64)),
+            _ => None,
+        }
+    }
 }
 
 const fn div_round(value: i64, divisor: i64) -> i64 {
@@ -186,7 +220,7 @@ impl fmt::Display for Length {
 
 /// Formats a float with at most `decimals` digits and no trailing zeros.
 ///
-/// Used by every unit rendered into DocMark, so that the serialiser stays
+/// Used by every unit rendered into DocMark, so that the serializer stays
 /// deterministic (`2.5cm`, never `2.50cm` or `2.4999999cm`).
 pub fn trim_float(value: f64, decimals: usize) -> String {
     let mut s = format!("{value:.decimals$}");
@@ -292,20 +326,6 @@ mod tests {
 
     #[test]
     fn display_is_always_lossless() {
-        // Parsing back what Display wrote must give the very same EMU, or a
-        // round-trip would move margins and image sizes.
-        fn reparse(text: &str) -> Length {
-            let split = text.find(|c: char| c.is_alphabetic()).unwrap();
-            let (number, unit) = text.split_at(split);
-            let value: f64 = number.parse().unwrap();
-            match unit {
-                "px" => Length::from_px(value),
-                "cm" => Length::from_cm(value),
-                "pt" => Length::from_pt(value),
-                "emu" => Length::from_emu(value as i64),
-                other => panic!("unexpected unit {other}"),
-            }
-        }
         let samples = [
             Length::from_twips(1417), // a Word margin: not a whole px or cm
             Length::from_twips(2500), // a table column width
@@ -317,12 +337,26 @@ mod tests {
         ];
         for length in samples {
             let text = length.to_string();
-            assert_eq!(reparse(&text), length, "`{text}` did not round-trip");
+            assert_eq!(
+                Length::parse(&text),
+                Some(length),
+                "`{text}` did not round-trip"
+            );
         }
         assert_eq!(Length::from_twips(1417).to_string(), "70.85pt");
         assert_eq!(Length::from_emu(1).to_string(), "1emu");
     }
 
+    #[test]
+    fn parse_accepts_bare_pixels_and_rejects_garbage() {
+        assert_eq!(Length::parse("450px"), Some(Length::from_px(450.0)));
+        assert_eq!(Length::parse("  3.5cm "), Some(Length::from_cm(3.5)));
+        assert_eq!(Length::parse("123"), Some(Length::from_px(123.0)));
+        assert_eq!(Length::parse(""), None);
+        assert_eq!(Length::parse("cm"), None);
+        assert_eq!(Length::parse("12xy"), None);
+    }
+
     #[test]
     fn trim_float_is_deterministic() {
         assert_eq!(trim_float(2.500, 3), "2.5");
diff --git a/crates/docsai-model/src/validate.rs b/crates/docsai-model/src/validate.rs
index 3f26766..71c94b5 100644
--- a/crates/docsai-model/src/validate.rs
+++ b/crates/docsai-model/src/validate.rs
@@ -1,7 +1,7 @@
 //! IR invariant checking.
 //!
 //! The invariants a reader can violate but the writers rely on. Chief among
-//! them (arquitectura §3.1): sheet anchors are only legal inside a
+//! them (architecture §3.1): sheet anchors are only legal inside a
 //! [`crate::sheet::Workbook`], and document anchors only inside a
 //! [`crate::text::TextDocument`]. Cross-anchoring does not
 //! exist, and the validator is what makes that a checked rule instead of a
diff --git a/crates/docsai-model/tests/json_roundtrip.rs b/crates/docsai-model/tests/json_roundtrip.rs
index 5ee077a..73c190d 100644
--- a/crates/docsai-model/tests/json_roundtrip.rs
+++ b/crates/docsai-model/tests/json_roundtrip.rs
@@ -1,4 +1,4 @@
-//! Fase 0 acceptance criterion: the IR serialises to JSON and back
+//! Phase 0 acceptance criterion: the IR serializes to JSON and back
 //! identically. Checked with hand-written documents covering every node kind
 //! and with `proptest` over randomly generated IRs.
 
@@ -13,8 +13,8 @@ use docsai_model::Document;
 use proptest::prelude::*;
 
 fn assert_json_round_trip(doc: &Document) {
-    let json = serde_json::to_string(doc).expect("serialises");
-    let back: Document = serde_json::from_str(&json).expect("deserialises");
+    let json = serde_json::to_string(doc).expect("serializes");
+    let back: Document = serde_json::from_str(&json).expect("deserializes");
     assert_eq!(doc, &back, "round-trip changed the document\n{json}");
     // Serialising the reconstructed value must produce the very same bytes.
     assert_eq!(json, serde_json::to_string(&back).unwrap());
diff --git a/crates/docsai-odf/src/lib.rs b/crates/docsai-odf/src/lib.rs
index 4322616..865d425 100644
--- a/crates/docsai-odf/src/lib.rs
+++ b/crates/docsai-odf/src/lib.rs
@@ -1,7 +1,7 @@
 //! OpenDocument readers and writers (`.odt`, `.ods`).
 //!
-//! Scheduled for **Fase 4** of `docs/plan-desarrollo.md`. The crate exists
-//! from Fase 0 so that the workspace layout and the dependency rules of
+//! Scheduled for **Phase 4** of `docs/development-plan.md`. The crate exists
+//! from Phase 0 so that the workspace layout and the dependency rules of
 //! `AGENTS.md` §3 are enforced by the compiler from the start: this crate may
 //! depend on `docsai-model` and on nothing else in the workspace.
 
diff --git a/crates/docsai-office/src/detect.rs b/crates/docsai-office/src/detect.rs
index f5b252d..267739e 100644
--- a/crates/docsai-office/src/detect.rs
+++ b/crates/docsai-office/src/detect.rs
@@ -1,4 +1,4 @@
-//! Format detection **by content**, not by extension (arquitectura §4).
+//! Format detection **by content**, not by extension (architecture §4).
 //!
 //! A file called `informe.txt` that is really a `.docx` must still convert,
 //! and a `.docx` extension on a ZIP of holiday photos must not.
@@ -34,7 +34,7 @@ pub fn detect<R: Read + Seek>(mut reader: R, hint: Option<&str>) -> (Format, Det
 
     if read >= 8 && magic == OLE2_MAGIC {
         // Both legacy formats are the same container; only the name tells them
-        // apart without parsing the directory (Fase 5 does that properly).
+        // apart without parsing the directory (Phase 5 does that properly).
         let format = match extension(hint).as_deref() {
             Some("xls") | Some("xlt") => Format::Xls,
             _ => Format::Doc,
@@ -89,7 +89,15 @@ fn read_head<R: Read>(reader: &mut R, buffer: &mut [u8; 8]) -> usize {
 }
 
 fn looks_like_docmark(head: &[u8]) -> bool {
-    head.starts_with(b"---")
+    if !head.starts_with(b"---") {
+        return false;
+    }
+    // Prefer a stronger signal when the probe buffer already holds it.
+    if head.windows(8).any(|w| w == b"docmark:") {
+        return true;
+    }
+    // `---` alone is still a maybe for DocMark (Phase 2).
+    true
 }
 
 fn extension(hint: Option<&str>) -> Option<String> {
diff --git a/crates/docsai-office/src/docx/drawing.rs b/crates/docsai-office/src/docx/drawing.rs
index 17ffbe5..1cc2e90 100644
--- a/crates/docsai-office/src/docx/drawing.rs
+++ b/crates/docsai-office/src/docx/drawing.rs
@@ -1,5 +1,5 @@
 //! DrawingML (`w:drawing`) and legacy VML (`w:pict`) → the normalised image
-//! model of arquitectura §3.1.
+//! model of architecture §3.1.
 //!
 //! This is where the spike (docs/spikes/R1) concluded the existing crates fall
 //! short, so it is deliberately exhaustive: wrap mode and side, `behindDoc`,
@@ -294,7 +294,7 @@ fn resolve_media(
 
     if let Some(link) = blip.attr_qualified("r:link") {
         // Linked images are never fetched: doing so would turn a document into
-        // an outbound network request (arquitectura §3.2).
+        // an outbound network request (architecture §3.2).
         let url = ctx
             .rels
             .get(link)
@@ -331,7 +331,7 @@ fn warn_if_unrenderable(image: &ImageRef, assets: &dyn AssetStore, report: &mut
 
 /// Reads a legacy VML picture (`w:pict`), typical of documents that once were
 /// `.doc`. Only what the normalised model covers is mapped; the rest is
-/// reported as degraded (análisis §1.4).
+/// reported as degraded (analysis §1.4).
 pub fn read_vml_picture(
     pict: &Element,
     ctx: &DrawingContext<'_>,
diff --git a/crates/docsai-office/src/docx/format.rs b/crates/docsai-office/src/docx/format.rs
index 4e1dc98..ffeac99 100644
--- a/crates/docsai-office/src/docx/format.rs
+++ b/crates/docsai-office/src/docx/format.rs
@@ -90,7 +90,8 @@ pub fn paragraph_props(ppr: &Element) -> ParaProps {
                 // `auto` counts in 240ths of a line; the IR stores 1000ths.
                 Some("exact") => LineHeight::Exact(Length::from_twips(line)),
                 Some("atLeast") => LineHeight::AtLeast(Length::from_twips(line)),
-                _ => LineHeight::Multiple((line * 1000 / 240) as i32),
+                // Round half-up so writer↔reader stays stable for common multiples.
+                _ => LineHeight::Multiple(((line * 1000 + 120) / 240) as i32),
             });
         }
     }
diff --git a/crates/docsai-office/src/docx/mod.rs b/crates/docsai-office/src/docx/mod.rs
index 906edc2..35db5b9 100644
--- a/crates/docsai-office/src/docx/mod.rs
+++ b/crates/docsai-office/src/docx/mod.rs
@@ -1,7 +1,7 @@
-//! The `.docx` reader (Fase 1).
+//! The `.docx` reader (Phase 1).
 //!
 //! Built directly on `zip` + `quick-xml` after the R1 spike
-//! (`docs/spikes/R1-estrategia-docx.md`): one pass over `document.xml` that
+//! (`docs/spikes/R1-docx-strategy.md`): one pass over `document.xml` that
 //! produces the IR and preserves everything it does not recognise.
 
 mod body;
@@ -9,6 +9,7 @@ mod drawing;
 mod format;
 mod numbering;
 mod styles;
+pub(crate) mod write;
 
 use std::collections::BTreeMap;
 use std::io::{Read, Seek};
@@ -52,7 +53,7 @@ pub(crate) fn read_package(
     let mut report = ConversionReport::new();
 
     if package.part_names().any(|n| n.ends_with("vbaProject.bin")) {
-        // Macros are ignored always and by design (AGENTS.md §7, plan Fase 8).
+        // Macros are ignored always and by design (AGENTS.md §7, plan Phase 8).
         report.warn(Warning::MacrosIgnored {
             part: "word/vbaProject.bin".into(),
         });
diff --git a/crates/docsai-office/src/docx/write.rs b/crates/docsai-office/src/docx/write.rs
new file mode 100644
index 0000000..a3fe600
--- /dev/null
+++ b/crates/docsai-office/src/docx/write.rs
@@ -0,0 +1,1427 @@
+//! IR → `.docx` writer (Phase 2).
+
+use std::collections::BTreeMap;
+use std::io::{Seek, Write};
+
+use docsai_model::assets::AssetStore;
+use docsai_model::image::{Anchor, ImageRef};
+use docsai_model::list::{ListCatalog, ListDef, ListId, NumFormat};
+use docsai_model::report::{ConversionReport, Warning};
+use docsai_model::style::{
+    Align, FontProps, LineHeight, ParaProps, StyleCatalog, StyleType, Underline, VertAlign,
+};
+use docsai_model::text::{
+    Block, BreakKind, HeaderFooter, HeaderScope, Heading, Inline, List, ListItem, Orientation,
+    Paragraph, RawFragment, RunProps, Section, Table, TableCell, TextDocument,
+};
+use docsai_model::Document;
+
+use crate::package::Package;
+use crate::write_error::WriteError;
+
+const NS_W: &str = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+const NS_R: &str = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+const NS_WP: &str = "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing";
+const NS_A: &str = "http://schemas.openxmlformats.org/drawingml/2006/main";
+const NS_PIC: &str = "http://schemas.openxmlformats.org/drawingml/2006/picture";
+const NS_CT: &str = "http://schemas.openxmlformats.org/package/2006/content-types";
+const NS_PKG_REL: &str = "http://schemas.openxmlformats.org/package/2006/relationships";
+const NS_CORE: &str = "http://schemas.openxmlformats.org/package/2006/metadata/core-properties";
+const NS_DC: &str = "http://purl.org/dc/elements/1.1/";
+const NS_DCTERMS: &str = "http://purl.org/dc/terms/";
+const NS_XSI: &str = "http://www.w3.org/2001/XMLSchema-instance";
+const NS_EP: &str = "http://schemas.openxmlformats.org/officeDocument/2006/extended-properties";
+const NS_VT: &str = "http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes";
+const NS_CUST: &str = "http://schemas.openxmlformats.org/officeDocument/2006/custom-properties";
+
+const REL_OFFICE: &str = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+const REL_PKG: &str = "http://schemas.openxmlformats.org/package/2006/relationships";
+
+/// Writes a text document as a `.docx` package.
+pub fn write_docx<W: Write + Seek>(
+    document: &Document,
+    assets: &dyn AssetStore,
+    writer: W,
+) -> Result<ConversionReport, WriteError> {
+    let text = match document {
+        Document::Text(t) => t,
+        Document::Workbook(_) => {
+            return Err(WriteError::Invalid(
+                "cannot write a workbook as .docx".into(),
+            ));
+        }
+    };
+    let mut report = ConversionReport::new();
+    let package = build_package(text, assets, &mut report)?;
+    package.write_to(writer)?;
+    Ok(report)
+}
+
+struct Rel {
+    id: String,
+    kind: String,
+    target: String,
+    external: bool,
+}
+
+struct WriterCtx<'a> {
+    assets: &'a dyn AssetStore,
+    report: &'a mut ConversionReport,
+    /// document.xml relationships (styles, numbering, media, headers…).
+    doc_rels: Vec<Rel>,
+    next_rid: u32,
+    /// asset id → (rId, part name)
+    media: BTreeMap<String, (String, String)>,
+    media_seq: u32,
+    /// header/footer parts: part name → xml
+    header_parts: BTreeMap<String, String>,
+    footer_parts: BTreeMap<String, String>,
+    hf_seq: u32,
+    /// footnotes: id → blocks xml already rendered? collect first
+    footnotes: Vec<(i64, Vec<Block>)>,
+    next_footnote: i64,
+    /// list id string → numId
+    list_nums: BTreeMap<String, i64>,
+    /// drawing unique ids
+    drawing_id: u32,
+}
+
+impl<'a> WriterCtx<'a> {
+    fn new(assets: &'a dyn AssetStore, report: &'a mut ConversionReport) -> Self {
+        Self {
+            assets,
+            report,
+            doc_rels: Vec::new(),
+            next_rid: 1,
+            media: BTreeMap::new(),
+            media_seq: 0,
+            header_parts: BTreeMap::new(),
+            footer_parts: BTreeMap::new(),
+            hf_seq: 0,
+            footnotes: Vec::new(),
+            next_footnote: 1,
+            list_nums: BTreeMap::new(),
+            drawing_id: 1,
+        }
+    }
+
+    fn add_rel(&mut self, kind_suffix: &str, target: &str, external: bool) -> String {
+        let id = format!("rId{}", self.next_rid);
+        self.next_rid += 1;
+        self.doc_rels.push(Rel {
+            id: id.clone(),
+            kind: format!("{REL_OFFICE}/{kind_suffix}"),
+            target: target.to_string(),
+            external,
+        });
+        id
+    }
+
+    fn ensure_media(&mut self, image: &ImageRef) -> Option<(String, i64, i64)> {
+        let asset_key = image.asset.as_str().to_string();
+        let (rid, _) = if let Some(entry) = self.media.get(&asset_key) {
+            entry.clone()
+        } else {
+            let _bytes = match self.assets.get(&image.asset) {
+                Some(b) => b,
+                None => {
+                    self.report.warn(Warning::Degraded {
+                        what: format!("image {}", image.asset),
+                        why: "asset bytes missing".into(),
+                    });
+                    return None;
+                }
+            };
+            let info = self.assets.info(&image.asset);
+            let ext = info
+                .map(|i| i.file_name.rsplit('.').next().unwrap_or("bin").to_string())
+                .unwrap_or_else(|| "bin".into());
+            self.media_seq += 1;
+            let part = format!("media/image{}.{}", self.media_seq, ext);
+            let rid = self.add_rel("image", &part, false);
+            // store bytes later via package — keep mapping of rid→part; bytes via asset id
+            self.media
+                .insert(asset_key.clone(), (rid.clone(), part.clone()));
+            // stash bytes under a side channel: part name is enough; package build pulls assets
+            (rid, part)
+        };
+        let cx = image.geometry.display_size.width.emu().max(1);
+        let cy = image.geometry.display_size.height.emu().max(1);
+        Some((rid, cx, cy))
+    }
+}
+
+fn build_package(
+    doc: &TextDocument,
+    assets: &dyn AssetStore,
+    report: &mut ConversionReport,
+) -> Result<Package, WriteError> {
+    let mut ctx = WriterCtx::new(assets, report);
+
+    // Pre-assign list numIds from catalog + any lists without defs
+    assign_list_ids(doc, &mut ctx);
+
+    // Always reference styles
+    let _styles_rid = ctx.add_rel("styles", "styles.xml", false);
+    let has_numbering = !ctx.list_nums.is_empty() || !doc.list_defs.is_empty();
+    if has_numbering {
+        let _ = ctx.add_rel("numbering", "numbering.xml", false);
+    }
+
+    // Build section content first so headers get registered
+    let body_xml = write_body(doc, &mut ctx);
+
+    let has_footnotes = !ctx.footnotes.is_empty();
+    if has_footnotes {
+        let _ = ctx.add_rel("footnotes", "footnotes.xml", false);
+    }
+
+    let mut package = Package::new();
+
+    // Content types
+    package.insert(
+        "[Content_Types].xml",
+        content_types_xml(&ctx, has_numbering, has_footnotes),
+    );
+
+    // Package relationships
+    package.insert("_rels/.rels", package_rels_xml());
+
+    // Core / app / custom props
+    package.insert("docProps/core.xml", core_props_xml(&doc.meta));
+    package.insert("docProps/app.xml", app_props_xml(&doc.meta));
+    if !doc.meta.custom.is_empty() {
+        package.insert("docProps/custom.xml", custom_props_xml(&doc.meta));
+        // add relationship from package? custom is via app usually via Override only
+    }
+
+    // Document
+    package.insert("word/document.xml", document_xml(&body_xml));
+    package.insert("word/_rels/document.xml.rels", document_rels_xml(&ctx));
+
+    // Styles + numbering
+    package.insert("word/styles.xml", styles_xml(&doc.styles));
+    if has_numbering {
+        package.insert(
+            "word/numbering.xml",
+            numbering_xml(&doc.list_defs, &ctx.list_nums),
+        );
+    }
+
+    // Footnotes
+    if has_footnotes {
+        package.insert("word/footnotes.xml", footnotes_xml(&ctx));
+    }
+
+    // Headers / footers
+    for (name, xml) in &ctx.header_parts {
+        package.insert(format!("word/{name}"), xml.clone());
+    }
+    for (name, xml) in &ctx.footer_parts {
+        package.insert(format!("word/{name}"), xml.clone());
+    }
+
+    // Media
+    for (asset_id, (_rid, part)) in &ctx.media {
+        let id = docsai_model::assets::AssetId::new(asset_id.clone());
+        if let Some(bytes) = assets.get(&id) {
+            package.insert(format!("word/{part}"), bytes.to_vec());
+        }
+    }
+
+    Ok(package)
+}
+
+fn assign_list_ids(doc: &TextDocument, ctx: &mut WriterCtx<'_>) {
+    let mut next = 1i64;
+    for id in doc.list_defs.defs.keys() {
+        if !ctx.list_nums.contains_key(id.as_str()) {
+            // Prefer numeric suffix of L{n}
+            let n = id
+                .as_str()
+                .strip_prefix('L')
+                .and_then(|s| s.parse().ok())
+                .unwrap_or(next);
+            ctx.list_nums.insert(id.as_str().to_string(), n);
+            next = next.max(n + 1);
+        }
+    }
+    // Walk lists that may lack catalog entries
+    for section in &doc.sections {
+        walk_blocks_for_lists(&section.blocks, ctx, &mut next);
+        for h in section.headers.iter().chain(section.footers.iter()) {
+            walk_blocks_for_lists(&h.blocks, ctx, &mut next);
+        }
+    }
+}
+
+fn walk_blocks_for_lists(blocks: &[Block], ctx: &mut WriterCtx<'_>, next: &mut i64) {
+    for block in blocks {
+        match block {
+            Block::List(list) => {
+                let key = list
+                    .def
+                    .as_ref()
+                    .map(|d| d.as_str().to_string())
+                    .unwrap_or_else(|| {
+                        if list.ordered {
+                            format!("__auto_ol_{}", list.level)
+                        } else {
+                            format!("__auto_ul_{}", list.level)
+                        }
+                    });
+                if let std::collections::btree_map::Entry::Vacant(e) = ctx.list_nums.entry(key) {
+                    e.insert(*next);
+                    *next += 1;
+                }
+                for item in &list.items {
+                    walk_blocks_for_lists(&item.blocks, ctx, next);
+                }
+            }
+            Block::Table(t) => {
+                for row in &t.rows {
+                    for cell in &row.cells {
+                        walk_blocks_for_lists(&cell.blocks, ctx, next);
+                    }
+                }
+            }
+            Block::TextBox(tb) => walk_blocks_for_lists(&tb.blocks, ctx, next),
+            _ => {}
+        }
+    }
+}
+
+fn write_body(doc: &TextDocument, ctx: &mut WriterCtx<'_>) -> String {
+    let mut out = String::new();
+    let sections = if doc.sections.is_empty() {
+        vec![Section::default()]
+    } else {
+        doc.sections.clone()
+    };
+
+    for (idx, section) in sections.iter().enumerate() {
+        let last = idx + 1 == sections.len();
+        for block in &section.blocks {
+            write_block(block, ctx, &mut out, None);
+        }
+        // sectPr: for non-last sections it sits inside the last paragraph's pPr;
+        // for the last section it trails the body. We always emit trailing sectPr
+        // for the last section, and for earlier ones append an empty paragraph
+        // carrying sectPr (Word accepts both).
+        let sect = sect_pr_xml(section, ctx);
+        if last {
+            out.push_str(&sect);
+        } else {
+            out.push_str("<w:p><w:pPr>");
+            // strip outer <w:sectPr>..</w:sectPr> already is sect
+            out.push_str(&sect);
+            out.push_str("</w:pPr></w:p>");
+        }
+    }
+    out
+}
+
+fn write_block(
+    block: &Block,
+    ctx: &mut WriterCtx<'_>,
+    out: &mut String,
+    list_ctx: Option<(&str, u8)>,
+) {
+    match block {
+        Block::Paragraph(p) => write_paragraph(p, ctx, out, list_ctx, None),
+        Block::Heading(h) => write_heading(h, ctx, out),
+        Block::List(list) => write_list(list, ctx, out),
+        Block::Table(table) => write_table(table, ctx, out),
+        Block::Image(img) => {
+            // Block image as a paragraph containing the drawing
+            out.push_str("<w:p>");
+            write_image_run(img, ctx, out);
+            out.push_str("</w:p>");
+        }
+        Block::TextBox(tb) => {
+            ctx.report.warn(Warning::Degraded {
+                what: "text-box".into(),
+                why: "text boxes are flattened to paragraphs on write".into(),
+            });
+            for b in &tb.blocks {
+                write_block(b, ctx, out, None);
+            }
+        }
+        Block::Raw(raw) => write_raw_block(raw, ctx, out),
+    }
+}
+
+fn write_heading(h: &Heading, ctx: &mut WriterCtx<'_>, out: &mut String) {
+    let style = h
+        .paragraph
+        .format
+        .style
+        .as_ref()
+        .map(|s| s.as_str().to_string())
+        .unwrap_or_else(|| format!("Heading{}", h.level.min(9)));
+    write_paragraph(&h.paragraph, ctx, out, None, Some(&style));
+}
+
+fn write_list(list: &List, ctx: &mut WriterCtx<'_>, out: &mut String) {
+    let key = list
+        .def
+        .as_ref()
+        .map(|d| d.as_str().to_string())
+        .unwrap_or_else(|| {
+            if list.ordered {
+                format!("__auto_ol_{}", list.level)
+            } else {
+                format!("__auto_ul_{}", list.level)
+            }
+        });
+    // Ensure num id
+    if !ctx.list_nums.contains_key(&key) {
+        let n = ctx.list_nums.values().copied().max().unwrap_or(0) + 1;
+        ctx.list_nums.insert(key.clone(), n);
+    }
+    for item in &list.items {
+        write_list_item(item, &key, list.level, ctx, out);
+    }
+}
+
+fn write_list_item(
+    item: &ListItem,
+    list_key: &str,
+    level: u8,
+    ctx: &mut WriterCtx<'_>,
+    out: &mut String,
+) {
+    let mut first = true;
+    for block in &item.blocks {
+        match block {
+            Block::List(nested) => write_list(nested, ctx, out),
+            Block::Paragraph(p) if first => {
+                write_paragraph(p, ctx, out, Some((list_key, level)), None);
+                first = false;
+            }
+            other => {
+                if first {
+                    // list item starting with non-paragraph: empty marker para
+                    let empty = Paragraph::default();
+                    write_paragraph(&empty, ctx, out, Some((list_key, level)), None);
+                    first = false;
+                }
+                write_block(other, ctx, out, None);
+            }
+        }
+    }
+    if first {
+        let empty = Paragraph::default();
+        write_paragraph(&empty, ctx, out, Some((list_key, level)), None);
+    }
+}
+
+fn write_paragraph(
+    p: &Paragraph,
+    ctx: &mut WriterCtx<'_>,
+    out: &mut String,
+    list_ctx: Option<(&str, u8)>,
+    style_override: Option<&str>,
+) {
+    out.push_str("<w:p>");
+    let style = style_override
+        .map(str::to_string)
+        .or_else(|| p.format.style.as_ref().map(|s| s.as_str().to_string()));
+    let needs_ppr = style.is_some()
+        || !p.format.direct.is_empty()
+        || !p.format.run_direct.is_empty()
+        || list_ctx.is_some();
+    if needs_ppr {
+        out.push_str("<w:pPr>");
+        if let Some(s) = &style {
+            out.push_str(&format!(r#"<w:pStyle w:val="{}"/>"#, esc_attr(s)));
+        }
+        if let Some((key, level)) = list_ctx {
+            if let Some(&num_id) = ctx.list_nums.get(key) {
+                out.push_str(&format!(
+                    "<w:numPr><w:ilvl w:val=\"{level}\"/><w:numId w:val=\"{num_id}\"/></w:numPr>"
+                ));
+            }
+        }
+        write_para_props(&p.format.direct, out);
+        if !p.format.run_direct.is_empty() {
+            out.push_str("<w:rPr>");
+            write_font_props(&p.format.run_direct, out);
+            out.push_str("</w:rPr>");
+        }
+        out.push_str("</w:pPr>");
+    }
+    write_inlines(&p.content, ctx, out, &RunProps::default());
+    out.push_str("</w:p>");
+}
+
+fn write_inlines(inlines: &[Inline], ctx: &mut WriterCtx<'_>, out: &mut String, base: &RunProps) {
+    for inline in inlines {
+        match inline {
+            Inline::Text(t) => write_text_run(t, base, out),
+            Inline::Styled { content, props } => {
+                let merged = merge_run(base, props);
+                write_inlines(content, ctx, out, &merged);
+            }
+            Inline::Link {
+                target,
+                content,
+                props,
+            } => {
+                // Simple hyperlink
+                let rid = ctx.add_rel("hyperlink", target, true);
+                let merged = merge_run(base, props);
+                out.push_str(&format!(r#"<w:hyperlink r:id="{}">"#, esc_attr(&rid)));
+                write_inlines(content, ctx, out, &merged);
+                out.push_str("</w:hyperlink>");
+            }
+            Inline::Footnote(blocks) => {
+                let id = ctx.next_footnote;
+                ctx.next_footnote += 1;
+                ctx.footnotes.push((id, blocks.clone()));
+                out.push_str("<w:r><w:rPr><w:rStyle w:val=\"FootnoteReference\"/></w:rPr>");
+                out.push_str(&format!(r#"<w:footnoteReference w:id="{id}"/>"#));
+                out.push_str("</w:r>");
+            }
+            Inline::Field {
+                kind,
+                cached,
+                instruction,
+            } => {
+                let instr = if instruction.is_empty() {
+                    format!(" {} ", kind.as_str())
+                } else {
+                    instruction.clone()
+                };
+                out.push_str(r#"<w:r><w:fldChar w:fldCharType="begin"/></w:r>"#);
+                out.push_str("<w:r><w:instrText xml:space=\"preserve\">");
+                out.push_str(&esc_text(&instr));
+                out.push_str("</w:instrText></w:r>");
+                out.push_str(r#"<w:r><w:fldChar w:fldCharType="separate"/></w:r>"#);
+                write_text_run(cached, base, out);
+                out.push_str(r#"<w:r><w:fldChar w:fldCharType="end"/></w:r>"#);
+                let _ = kind;
+            }
+            Inline::Break(kind) => {
+                let ty = match kind {
+                    BreakKind::Line => None,
+                    BreakKind::Page => Some("page"),
+                    BreakKind::Column => Some("column"),
+                };
+                out.push_str("<w:r>");
+                match ty {
+                    Some(t) => out.push_str(&format!(r#"<w:br w:type="{t}"/>"#)),
+                    None => out.push_str("<w:br/>"),
+                }
+                out.push_str("</w:r>");
+            }
+            Inline::Image(img) => write_image_run(img, ctx, out),
+            Inline::Raw(raw) => {
+                if raw.format == "ooxml" && looks_like_run_xml(&raw.content) {
+                    out.push_str(&raw.content);
+                } else {
+                    ctx.report.warn(Warning::Degraded {
+                        what: format!("raw {}", raw.id.0),
+                        why: "inline raw fragment not re-injected".into(),
+                    });
+                }
+            }
+        }
+    }
+}
+
+fn merge_run(base: &RunProps, over: &RunProps) -> RunProps {
+    RunProps {
+        style: over.style.clone().or_else(|| base.style.clone()),
+        direct: over.direct.over(&base.direct),
+    }
+}
+
+fn write_text_run(text: &str, props: &RunProps, out: &mut String) {
+    if text.is_empty() {
+        return;
+    }
+    // Split on newlines → soft breaks
+    let parts: Vec<&str> = text.split('\n').collect();
+    for (i, part) in parts.iter().enumerate() {
+        if i > 0 {
+            out.push_str("<w:r>");
+            write_rpr(props, out);
+            out.push_str("<w:br/></w:r>");
+        }
+        if part.is_empty() {
+            continue;
+        }
+        out.push_str("<w:r>");
+        write_rpr(props, out);
+        // Preserve spaces
+        let preserve = part.starts_with(' ') || part.ends_with(' ') || part.contains("  ");
+        if preserve {
+            out.push_str(r#"<w:t xml:space="preserve">"#);
+        } else {
+            out.push_str("<w:t>");
+        }
+        out.push_str(&esc_text(part));
+        out.push_str("</w:t></w:r>");
+    }
+}
+
+fn write_rpr(props: &RunProps, out: &mut String) {
+    if props.is_empty() {
+        return;
+    }
+    out.push_str("<w:rPr>");
+    if let Some(s) = &props.style {
+        out.push_str(&format!(r#"<w:rStyle w:val="{}"/>"#, esc_attr(s.as_str())));
+    }
+    write_font_props(&props.direct, out);
+    out.push_str("</w:rPr>");
+}
+
+fn write_font_props(font: &FontProps, out: &mut String) {
+    if let Some(name) = &font.name {
+        out.push_str(&format!(
+            r#"<w:rFonts w:ascii="{0}" w:hAnsi="{0}" w:cs="{0}"/>"#,
+            esc_attr(name)
+        ));
+    }
+    if let Some(size) = font.size {
+        let hp = size.half_points().max(1);
+        out.push_str(&format!(r#"<w:sz w:val="{hp}"/><w:szCs w:val="{hp}"/>"#));
+    }
+    if font.bold == Some(true) {
+        out.push_str("<w:b/><w:bCs/>");
+    } else if font.bold == Some(false) {
+        out.push_str(r#"<w:b w:val="0"/><w:bCs w:val="0"/>"#);
+    }
+    if font.italic == Some(true) {
+        out.push_str("<w:i/><w:iCs/>");
+    } else if font.italic == Some(false) {
+        out.push_str(r#"<w:i w:val="0"/><w:iCs w:val="0"/>"#);
+    }
+    if font.strike == Some(true) {
+        out.push_str("<w:strike/>");
+    }
+    if let Some(u) = font.underline {
+        let val = match u {
+            Underline::None => "none",
+            Underline::Single => "single",
+            Underline::Double => "double",
+            Underline::Dotted => "dotted",
+            Underline::Dashed => "dash",
+            Underline::Wave => "wave",
+            Underline::Thick => "thick",
+        };
+        out.push_str(&format!(r#"<w:u w:val="{val}"/>"#));
+    }
+    if let Some(color) = &font.color {
+        let hex = color.trim_start_matches('#');
+        out.push_str(&format!(r#"<w:color w:val="{}"/>"#, esc_attr(hex)));
+    }
+    if let Some(hl) = &font.highlight {
+        out.push_str(&format!(r#"<w:highlight w:val="{}"/>"#, esc_attr(hl)));
+    }
+    if let Some(va) = font.vert_align {
+        let val = match va {
+            VertAlign::Baseline => "baseline",
+            VertAlign::Superscript => "superscript",
+            VertAlign::Subscript => "subscript",
+        };
+        out.push_str(&format!(r#"<w:vertAlign w:val="{val}"/>"#));
+    }
+    if font.small_caps == Some(true) {
+        out.push_str("<w:smallCaps/>");
+    }
+    if font.caps == Some(true) {
+        out.push_str("<w:caps/>");
+    }
+}
+
+fn write_para_props(p: &ParaProps, out: &mut String) {
+    if let Some(a) = p.align {
+        let val = match a {
+            Align::Left => "left",
+            Align::Center => "center",
+            Align::Right => "right",
+            Align::Justify => "both",
+        };
+        out.push_str(&format!(r#"<w:jc w:val="{val}"/>"#));
+    }
+    let has_ind = p.indent_left.is_some()
+        || p.indent_right.is_some()
+        || p.indent_first_line.is_some()
+        || p.indent_hanging.is_some();
+    if has_ind {
+        out.push_str("<w:ind");
+        if let Some(v) = p.indent_left {
+            out.push_str(&format!(r#" w:left="{}""#, v.twips()));
+        }
+        if let Some(v) = p.indent_right {
+            out.push_str(&format!(r#" w:right="{}""#, v.twips()));
+        }
+        if let Some(v) = p.indent_first_line {
+            out.push_str(&format!(r#" w:firstLine="{}""#, v.twips()));
+        }
+        if let Some(v) = p.indent_hanging {
+            out.push_str(&format!(r#" w:hanging="{}""#, v.twips()));
+        }
+        out.push_str("/>");
+    }
+    let has_sp = p.space_before.is_some() || p.space_after.is_some() || p.line_height.is_some();
+    if has_sp {
+        out.push_str("<w:spacing");
+        if let Some(v) = p.space_before {
+            out.push_str(&format!(r#" w:before="{}""#, v.twips()));
+        }
+        if let Some(v) = p.space_after {
+            out.push_str(&format!(r#" w:after="{}""#, v.twips()));
+        }
+        if let Some(lh) = p.line_height {
+            match lh {
+                LineHeight::Multiple(thousandths) => {
+                    // IR stores thousandths of a line; OOXML uses 240ths.
+                    let ooxml = ((i64::from(thousandths) * 240 + 500) / 1000).max(1);
+                    out.push_str(&format!(r#" w:line="{ooxml}" w:lineRule="auto""#));
+                }
+                LineHeight::Exact(l) => {
+                    out.push_str(&format!(r#" w:line="{}" w:lineRule="exact""#, l.twips()));
+                }
+                LineHeight::AtLeast(l) => {
+                    out.push_str(&format!(r#" w:line="{}" w:lineRule="atLeast""#, l.twips()));
+                }
+            }
+        }
+        out.push_str("/>");
+    }
+    if p.keep_with_next == Some(true) {
+        out.push_str("<w:keepNext/>");
+    }
+    if p.page_break_before == Some(true) {
+        out.push_str("<w:pageBreakBefore/>");
+    }
+    if let Some(bg) = &p.background {
+        let hex = bg.trim_start_matches('#');
+        out.push_str(&format!(
+            r#"<w:shd w:val="clear" w:color="auto" w:fill="{}"/>"#,
+            esc_attr(hex)
+        ));
+    }
+    if let Some(lvl) = p.outline_level {
+        out.push_str(&format!(r#"<w:outlineLvl w:val="{lvl}"/>"#));
+    }
+}
+
+fn write_image_run(img: &ImageRef, ctx: &mut WriterCtx<'_>, out: &mut String) {
+    let Some((rid, cx, cy)) = ctx.ensure_media(img) else {
+        return;
+    };
+    let doc_pr_id = ctx.drawing_id;
+    ctx.drawing_id += 1;
+    let name = img
+        .name
+        .clone()
+        .unwrap_or_else(|| format!("Picture {doc_pr_id}"));
+    let alt = esc_attr(&img.alt);
+    let inline = matches!(
+        img.geometry.anchor,
+        Anchor::Inline | Anchor::Floating { .. }
+    );
+    // Always write inline for simplicity; floating degrades with warning
+    if matches!(img.geometry.anchor, Anchor::Floating { .. }) {
+        ctx.report.warn(Warning::Degraded {
+            what: format!("image {}", img.asset),
+            why: "floating anchors written as inline".into(),
+        });
+    }
+    let _ = inline;
+    out.push_str("<w:r><w:drawing>");
+    out.push_str(&format!(
+        r#"<wp:inline distT="0" distB="0" distL="0" distR="0">
+  <wp:extent cx="{cx}" cy="{cy}"/>
+  <wp:docPr id="{doc_pr_id}" name="{}" descr="{alt}"/>
+  <wp:cNvGraphicFramePr>
+    <a:graphicFrameLocks xmlns:a="{NS_A}" noChangeAspect="1"/>
+  </wp:cNvGraphicFramePr>
+  <a:graphic xmlns:a="{NS_A}">
+    <a:graphicData uri="{NS_PIC}">
+      <pic:pic xmlns:pic="{NS_PIC}">
+        <pic:nvPicPr>
+          <pic:cNvPr id="0" name="{}"/>
+          <pic:cNvPicPr/>
+        </pic:nvPicPr>
+        <pic:blipFill>
+          <a:blip r:embed="{}"/>
+          <a:stretch><a:fillRect/></a:stretch>
+        </pic:blipFill>
+        <pic:spPr>
+          <a:xfrm>
+            <a:off x="0" y="0"/>
+            <a:ext cx="{cx}" cy="{cy}"/>
+          </a:xfrm>
+          <a:prstGeom prst="rect"><a:avLst/></a:prstGeom>
+        </pic:spPr>
+      </pic:pic>
+    </a:graphicData>
+  </a:graphic>
+</wp:inline>"#,
+        esc_attr(&name),
+        esc_attr(&name),
+        esc_attr(&rid),
+    ));
+    out.push_str("</w:drawing></w:r>");
+}
+
+fn write_table(table: &Table, ctx: &mut WriterCtx<'_>, out: &mut String) {
+    out.push_str("<w:tbl>");
+    out.push_str("<w:tblPr>");
+    if let Some(s) = &table.style {
+        out.push_str(&format!(
+            r#"<w:tblStyle w:val="{}"/>"#,
+            esc_attr(s.as_str())
+        ));
+    }
+    out.push_str(r#"<w:tblW w:w="0" w:type="auto"/>"#);
+    out.push_str("</w:tblPr>");
+    if !table.col_widths.is_empty() {
+        out.push_str("<w:tblGrid>");
+        for w in &table.col_widths {
+            out.push_str(&format!(r#"<w:gridCol w:w="{}"/>"#, w.twips().max(1)));
+        }
+        out.push_str("</w:tblGrid>");
+    }
+    // Track vertical merges: col → remaining rowspan
+    let ncols = table.width().max(1);
+    let mut vmerge_remain = vec![0u16; ncols];
+    for row in &table.rows {
+        out.push_str("<w:tr>");
+        if row.is_header || table.header_row {
+            out.push_str("<w:trPr><w:tblHeader/></w:trPr>");
+        }
+        let mut col = 0usize;
+        for cell in &row.cells {
+            if cell.covered {
+                // Writer of source already expanded; skip covered placeholders
+                // but if vmerge continuation needed without explicit cell, emit
+                continue;
+            }
+            // Skip columns consumed by ongoing vmerge
+            while col < ncols && vmerge_remain[col] > 0 {
+                // emit continue vmerge cell
+                out.push_str(r#"<w:tc><w:tcPr><w:vMerge/></w:tcPr><w:p/></w:tc>"#);
+                vmerge_remain[col] -= 1;
+                col += 1;
+            }
+            write_cell(cell, ctx, out);
+            let span = cell.colspan.max(1) as usize;
+            if cell.rowspan > 1 {
+                for slot in vmerge_remain
+                    .iter_mut()
+                    .skip(col)
+                    .take(span.min(ncols.saturating_sub(col)))
+                {
+                    *slot = cell.rowspan - 1;
+                }
+            }
+            col += span;
+        }
+        while col < ncols && vmerge_remain[col] > 0 {
+            out.push_str(r#"<w:tc><w:tcPr><w:vMerge/></w:tcPr><w:p/></w:tc>"#);
+            vmerge_remain[col] -= 1;
+            col += 1;
+        }
+        out.push_str("</w:tr>");
+    }
+    out.push_str("</w:tbl>");
+}
+
+fn write_cell(cell: &TableCell, ctx: &mut WriterCtx<'_>, out: &mut String) {
+    out.push_str("<w:tc>");
+    out.push_str("<w:tcPr>");
+    if let Some(w) = cell.width {
+        out.push_str(&format!(
+            r#"<w:tcW w:w="{}" w:type="dxa"/>"#,
+            w.twips().max(1)
+        ));
+    }
+    if cell.colspan > 1 {
+        out.push_str(&format!(r#"<w:gridSpan w:val="{}"/>"#, cell.colspan));
+    }
+    if cell.rowspan > 1 {
+        out.push_str(r#"<w:vMerge w:val="restart"/>"#);
+    }
+    if let Some(bg) = &cell.background {
+        let hex = bg.trim_start_matches('#');
+        out.push_str(&format!(
+            r#"<w:shd w:val="clear" w:color="auto" w:fill="{}"/>"#,
+            esc_attr(hex)
+        ));
+    }
+    out.push_str("</w:tcPr>");
+    if cell.blocks.is_empty() {
+        out.push_str("<w:p/>");
+    } else {
+        for b in &cell.blocks {
+            write_block(b, ctx, out, None);
+        }
+    }
+    out.push_str("</w:tc>");
+}
+
+fn write_raw_block(raw: &RawFragment, ctx: &mut WriterCtx<'_>, out: &mut String) {
+    if raw.format == "ooxml" {
+        // Re-inject if it looks like a block-level element
+        let trimmed = raw.content.trim();
+        if trimmed.starts_with('<') {
+            out.push_str(trimmed);
+            return;
+        }
+    }
+    ctx.report.warn(Warning::Degraded {
+        what: format!("raw {}", raw.id.0),
+        why: format!("raw-block format={} not re-injected", raw.format),
+    });
+}
+
+fn sect_pr_xml(section: &Section, ctx: &mut WriterCtx<'_>) -> String {
+    let mut s = String::from("<w:sectPr>");
+    // headers
+    for h in &section.headers {
+        let (part, typ) = register_hf(h, true, ctx);
+        s.push_str(&format!(
+            r#"<w:headerReference w:type="{}" r:id="{}"/>"#,
+            typ,
+            esc_attr(&part)
+        ));
+    }
+    for f in &section.footers {
+        let (part, typ) = register_hf(f, false, ctx);
+        s.push_str(&format!(
+            r#"<w:footerReference w:type="{}" r:id="{}"/>"#,
+            typ,
+            esc_attr(&part)
+        ));
+    }
+    let page = &section.page;
+    if !page.size.width.is_zero() && !page.size.height.is_zero() {
+        let mut orient = "";
+        if page.orientation == Orientation::Landscape {
+            orient = r#" w:orient="landscape""#;
+        }
+        s.push_str(&format!(
+            r#"<w:pgSz w:w="{}" w:h="{}"{orient}/>"#,
+            page.size.width.twips().max(1),
+            page.size.height.twips().max(1),
+        ));
+    }
+    let m = &page.margins;
+    if !(m.top.is_zero()
+        && m.right.is_zero()
+        && m.bottom.is_zero()
+        && m.left.is_zero()
+        && m.header.is_zero()
+        && m.footer.is_zero())
+    {
+        s.push_str(&format!(
+            r#"<w:pgMar w:top="{}" w:right="{}" w:bottom="{}" w:left="{}" w:header="{}" w:footer="{}" w:gutter="0"/>"#,
+            m.top.twips(),
+            m.right.twips(),
+            m.bottom.twips(),
+            m.left.twips(),
+            m.header.twips(),
+            m.footer.twips(),
+        ));
+    }
+    if page.columns > 1 {
+        s.push_str(&format!(r#"<w:cols w:num="{}"/>"#, page.columns));
+    }
+    if page.title_page {
+        s.push_str("<w:titlePg/>");
+    }
+    s.push_str("</w:sectPr>");
+    s
+}
+
+fn register_hf(
+    hf: &HeaderFooter,
+    is_header: bool,
+    ctx: &mut WriterCtx<'_>,
+) -> (String, &'static str) {
+    ctx.hf_seq += 1;
+    let n = ctx.hf_seq;
+    let file = if is_header {
+        format!("header{n}.xml")
+    } else {
+        format!("footer{n}.xml")
+    };
+    let kind = if is_header { "header" } else { "footer" };
+    let rid = ctx.add_rel(kind, &file, false);
+
+    let mut body = String::new();
+    for b in &hf.blocks {
+        write_block(b, ctx, &mut body, None);
+    }
+    if body.is_empty() {
+        body.push_str("<w:p/>");
+    }
+    let root = if is_header { "hdr" } else { "ftr" };
+    let xml = format!(
+        r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w:{root} xmlns:w="{NS_W}" xmlns:r="{NS_R}" xmlns:wp="{NS_WP}" xmlns:a="{NS_A}" xmlns:pic="{NS_PIC}">
+{body}
+</w:{root}>"#
+    );
+    if is_header {
+        ctx.header_parts.insert(file, xml);
+    } else {
+        ctx.footer_parts.insert(file, xml);
+    }
+    let typ = match hf.scope {
+        HeaderScope::Default => "default",
+        HeaderScope::First => "first",
+        HeaderScope::Even => "even",
+    };
+    (rid, typ)
+}
+
+fn document_xml(body: &str) -> String {
+    format!(
+        r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w:document xmlns:w="{NS_W}" xmlns:r="{NS_R}" xmlns:wp="{NS_WP}" xmlns:a="{NS_A}" xmlns:pic="{NS_PIC}">
+  <w:body>
+{body}
+  </w:body>
+</w:document>"#
+    )
+}
+
+fn document_rels_xml(ctx: &WriterCtx<'_>) -> String {
+    let mut s = format!(
+        r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="{NS_PKG_REL}">"#
+    );
+    for rel in &ctx.doc_rels {
+        if rel.external {
+            s.push_str(&format!(
+                r#"<Relationship Id="{}" Type="{}" Target="{}" TargetMode="External"/>"#,
+                esc_attr(&rel.id),
+                esc_attr(&rel.kind),
+                esc_attr(&rel.target),
+            ));
+        } else {
+            s.push_str(&format!(
+                r#"<Relationship Id="{}" Type="{}" Target="{}"/>"#,
+                esc_attr(&rel.id),
+                esc_attr(&rel.kind),
+                esc_attr(&rel.target),
+            ));
+        }
+    }
+    s.push_str("</Relationships>");
+    s
+}
+
+fn package_rels_xml() -> String {
+    format!(
+        r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="{NS_PKG_REL}">
+  <Relationship Id="rId1" Type="{REL_PKG}/metadata/core-properties" Target="docProps/core.xml"/>
+  <Relationship Id="rId2" Type="{REL_OFFICE}/extended-properties" Target="docProps/app.xml"/>
+  <Relationship Id="rId3" Type="{REL_OFFICE}/officeDocument" Target="word/document.xml"/>
+</Relationships>"#
+    )
+}
+
+fn content_types_xml(ctx: &WriterCtx<'_>, numbering: bool, footnotes: bool) -> String {
+    let mut s = format!(
+        r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Types xmlns="{NS_CT}">
+  <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
+  <Default Extension="xml" ContentType="application/xml"/>
+  <Default Extension="png" ContentType="image/png"/>
+  <Default Extension="jpg" ContentType="image/jpeg"/>
+  <Default Extension="jpeg" ContentType="image/jpeg"/>
+  <Default Extension="gif" ContentType="image/gif"/>
+  <Default Extension="bmp" ContentType="image/bmp"/>
+  <Default Extension="tif" ContentType="image/tiff"/>
+  <Default Extension="tiff" ContentType="image/tiff"/>
+  <Default Extension="emf" ContentType="image/x-emf"/>
+  <Default Extension="wmf" ContentType="image/x-wmf"/>
+  <Default Extension="bin" ContentType="application/octet-stream"/>
+  <Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>
+  <Override PartName="/word/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml"/>
+  <Override PartName="/docProps/core.xml" ContentType="application/vnd.openxmlformats-package.core-properties+xml"/>
+  <Override PartName="/docProps/app.xml" ContentType="application/vnd.openxmlformats-officedocument.extended-properties+xml"/>"#
+    );
+    if numbering {
+        s.push_str(r#"
+  <Override PartName="/word/numbering.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml"/>"#);
+    }
+    if footnotes {
+        s.push_str(r#"
+  <Override PartName="/word/footnotes.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.footnotes+xml"/>"#);
+    }
+    for name in ctx.header_parts.keys() {
+        s.push_str(&format!(
+            r#"
+  <Override PartName="/word/{name}" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.header+xml"/>"#
+        ));
+    }
+    for name in ctx.footer_parts.keys() {
+        s.push_str(&format!(
+            r#"
+  <Override PartName="/word/{name}" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.footer+xml"/>"#
+        ));
+    }
+    s.push_str("\n</Types>");
+    s
+}
+
+fn core_props_xml(meta: &docsai_model::DocumentMeta) -> String {
+    let mut s = format!(
+        r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<cp:coreProperties xmlns:cp="{NS_CORE}" xmlns:dc="{NS_DC}" xmlns:dcterms="{NS_DCTERMS}" xmlns:xsi="{NS_XSI}">"#
+    );
+    if let Some(t) = &meta.title {
+        s.push_str(&format!("<dc:title>{}</dc:title>", esc_text(t)));
+    }
+    if let Some(a) = &meta.author {
+        s.push_str(&format!("<dc:creator>{}</dc:creator>", esc_text(a)));
+    }
+    if let Some(v) = &meta.last_modified_by {
+        s.push_str(&format!(
+            "<cp:lastModifiedBy>{}</cp:lastModifiedBy>",
+            esc_text(v)
+        ));
+    }
+    if let Some(v) = &meta.subject {
+        s.push_str(&format!("<dc:subject>{}</dc:subject>", esc_text(v)));
+    }
+    if let Some(v) = &meta.keywords {
+        s.push_str(&format!("<cp:keywords>{}</cp:keywords>", esc_text(v)));
+    }
+    if let Some(v) = &meta.description {
+        s.push_str(&format!("<dc:description>{}</dc:description>", esc_text(v)));
+    }
+    if let Some(v) = &meta.language {
+        s.push_str(&format!("<dc:language>{}</dc:language>", esc_text(v)));
+    }
+    if let Some(v) = &meta.created {
+        s.push_str(&format!(
+            r#"<dcterms:created xsi:type="dcterms:W3CDTF">{}</dcterms:created>"#,
+            esc_text(v)
+        ));
+    }
+    if let Some(v) = &meta.modified {
+        s.push_str(&format!(
+            r#"<dcterms:modified xsi:type="dcterms:W3CDTF">{}</dcterms:modified>"#,
+            esc_text(v)
+        ));
+    }
+    s.push_str("</cp:coreProperties>");
+    s
+}
+
+fn app_props_xml(meta: &docsai_model::DocumentMeta) -> String {
+    let app = meta.application.clone().unwrap_or_else(|| "docsai".into());
+    format!(
+        r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Properties xmlns="{NS_EP}" xmlns:vt="{NS_VT}">
+  <Application>{}</Application>
+</Properties>"#,
+        esc_text(&app)
+    )
+}
+
+fn custom_props_xml(meta: &docsai_model::DocumentMeta) -> String {
+    let mut s = format!(
+        r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Properties xmlns="{NS_CUST}" xmlns:vt="{NS_VT}">"#
+    );
+    for (i, (k, v)) in meta.custom.iter().enumerate() {
+        s.push_str(&format!(
+            r#"<property fmtid="{{D5CDD505-2E9C-101B-9397-08002B2CF9AE}}" pid="{}" name="{}"><vt:lpwstr>{}</vt:lpwstr></property>"#,
+            i + 2,
+            esc_attr(k),
+            esc_text(v)
+        ));
+    }
+    s.push_str("</Properties>");
+    s
+}
+
+fn styles_xml(styles: &StyleCatalog) -> String {
+    let mut s = format!(
+        r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w:styles xmlns:w="{NS_W}">
+  <w:docDefaults>
+    <w:rPrDefault><w:rPr>"#
+    );
+    write_font_props(&styles.defaults.font, &mut s);
+    s.push_str("</w:rPr></w:rPrDefault><w:pPrDefault><w:pPr>");
+    write_para_props(&styles.defaults.paragraph, &mut s);
+    s.push_str("</w:pPr></w:pPrDefault></w:docDefaults>");
+
+    // Always ensure Normal exists
+    let has_normal = styles.styles.values().any(|st| st.id.as_str() == "Normal");
+    if !has_normal {
+        s.push_str(
+            r#"<w:style w:type="paragraph" w:default="1" w:styleId="Normal"><w:name w:val="Normal"/></w:style>"#,
+        );
+    }
+    // Heading styles are emitted only when present in the catalogue.
+
+    for style in styles.styles.values() {
+        let ty = match style.style_type {
+            StyleType::Paragraph => "paragraph",
+            StyleType::Character => "character",
+            StyleType::Table => "table",
+            StyleType::Numbering => "numbering",
+        };
+        s.push_str(&format!(
+            r#"<w:style w:type="{ty}" w:styleId="{}""#,
+            esc_attr(style.id.as_str())
+        ));
+        if style.is_default {
+            s.push_str(r#" w:default="1""#);
+        }
+        s.push('>');
+        s.push_str(&format!(r#"<w:name w:val="{}"/>"#, esc_attr(&style.name)));
+        if let Some(b) = &style.based_on {
+            s.push_str(&format!(r#"<w:basedOn w:val="{}"/>"#, esc_attr(b.as_str())));
+        }
+        if let Some(n) = &style.next {
+            s.push_str(&format!(r#"<w:next w:val="{}"/>"#, esc_attr(n.as_str())));
+        }
+        if !style.paragraph.is_empty() {
+            s.push_str("<w:pPr>");
+            write_para_props(&style.paragraph, &mut s);
+            s.push_str("</w:pPr>");
+        }
+        if !style.font.is_empty() {
+            s.push_str("<w:rPr>");
+            write_font_props(&style.font, &mut s);
+            s.push_str("</w:rPr>");
+        }
+        s.push_str("</w:style>");
+    }
+    s.push_str("</w:styles>");
+    s
+}
+
+fn numbering_xml(catalog: &ListCatalog, list_nums: &BTreeMap<String, i64>) -> String {
+    let mut s = format!(
+        r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w:numbering xmlns:w="{NS_W}">"#
+    );
+
+    // abstractNums
+    let mut abstracts: Vec<(i64, ListDef, String)> = Vec::new();
+    for (key, &num_id) in list_nums {
+        let def = if let Some(id) = key.strip_prefix("__auto_") {
+            // synthetic
+            let ordered = id.starts_with("ol");
+            synthetic_list_def(ordered)
+        } else {
+            catalog
+                .get(&ListId::new(key))
+                .cloned()
+                .unwrap_or_else(|| synthetic_list_def(true))
+        };
+        abstracts.push((num_id, def, key.clone()));
+    }
+    abstracts.sort_by_key(|(id, _, _)| *id);
+
+    for (num_id, def, _) in &abstracts {
+        s.push_str(&format!(r#"<w:abstractNum w:abstractNumId="{num_id}">"#));
+        if def.levels.is_empty() {
+            write_lvl(&mut s, 0, &default_level(true));
+        } else {
+            for (ilvl, level) in def.levels.iter().enumerate() {
+                write_lvl(&mut s, ilvl, level);
+            }
+        }
+        s.push_str("</w:abstractNum>");
+    }
+    for (num_id, _, _) in &abstracts {
+        s.push_str(&format!(
+            r#"<w:num w:numId="{num_id}"><w:abstractNumId w:val="{num_id}"/></w:num>"#
+        ));
+    }
+    s.push_str("</w:numbering>");
+    s
+}
+
+fn synthetic_list_def(ordered: bool) -> ListDef {
+    let mut def = ListDef::default();
+    for i in 0..9 {
+        def.levels.push(if ordered {
+            docsai_model::list::ListLevel::new(NumFormat::Decimal, format!("%{}.", i + 1))
+        } else {
+            docsai_model::list::ListLevel::new(NumFormat::Bullet, "•")
+        });
+    }
+    def
+}
+
+fn default_level(ordered: bool) -> docsai_model::list::ListLevel {
+    if ordered {
+        docsai_model::list::ListLevel::new(NumFormat::Decimal, "%1.")
+    } else {
+        docsai_model::list::ListLevel::new(NumFormat::Bullet, "•")
+    }
+}
+
+fn write_lvl(s: &mut String, ilvl: usize, level: &docsai_model::list::ListLevel) {
+    s.push_str(&format!(r#"<w:lvl w:ilvl="{ilvl}">"#));
+    if let Some(start) = level.start {
+        s.push_str(&format!(r#"<w:start w:val="{start}"/>"#));
+    } else {
+        s.push_str(r#"<w:start w:val="1"/>"#);
+    }
+    s.push_str(&format!(
+        r#"<w:numFmt w:val="{}"/>"#,
+        esc_attr(level.format.as_str())
+    ));
+    s.push_str(&format!(
+        r#"<w:lvlText w:val="{}"/>"#,
+        esc_attr(&level.text)
+    ));
+    s.push_str(r#"<w:lvlJc w:val="left"/>"#);
+    s.push_str("<w:pPr><w:ind");
+    if let Some(ind) = level.indent {
+        s.push_str(&format!(r#" w:left="{}""#, ind.twips()));
+    } else {
+        s.push_str(&format!(r#" w:left="{}""#, 720 * (ilvl as i64 + 1)));
+    }
+    if let Some(h) = level.hanging {
+        s.push_str(&format!(r#" w:hanging="{}""#, h.twips()));
+    } else {
+        s.push_str(r#" w:hanging="360""#);
+    }
+    s.push_str("/></w:pPr>");
+    s.push_str("</w:lvl>");
+}
+
+fn footnotes_xml(ctx: &WriterCtx<'_>) -> String {
+    let mut s = format!(
+        r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w:footnotes xmlns:w="{NS_W}" xmlns:r="{NS_R}">
+  <w:footnote w:type="separator" w:id="-1"><w:p><w:r><w:separator/></w:r></w:p></w:footnote>
+  <w:footnote w:type="continuationSeparator" w:id="0"><w:p><w:r><w:continuationSeparator/></w:r></w:p></w:footnote>"#
+    );
+    // We need a mutable-like write for footnote bodies; rebuild lightly
+    // Footnote blocks were stored; create a throwaway report sink
+    for (id, blocks) in &ctx.footnotes {
+        s.push_str(&format!(r#"<w:footnote w:id="{id}">"#));
+        // Render with a nested minimal path: paragraphs only via a fresh string
+        // We cannot borrow ctx mutably; re-render simply
+        if blocks.is_empty() {
+            s.push_str("<w:p/>");
+        } else {
+            for b in blocks {
+                match b {
+                    Block::Paragraph(p) => {
+                        s.push_str("<w:p>");
+                        // simple text dump
+                        let text = p.plain_text();
+                        if !text.is_empty() {
+                            s.push_str("<w:r><w:t>");
+                            s.push_str(&esc_text(&text));
+                            s.push_str("</w:t></w:r>");
+                        }
+                        s.push_str("</w:p>");
+                    }
+                    _ => {
+                        s.push_str("<w:p/>");
+                    }
+                }
+            }
+        }
+        s.push_str("</w:footnote>");
+    }
+    s.push_str("</w:footnotes>");
+    s
+}
+
+fn looks_like_run_xml(s: &str) -> bool {
+    let t = s.trim_start();
+    t.starts_with("<w:r") || t.starts_with("<w:hyperlink") || t.starts_with("<m:")
+}
+
+fn esc_text(s: &str) -> String {
+    let mut out = String::with_capacity(s.len());
+    for c in s.chars() {
+        match c {
+            '&' => out.push_str("&amp;"),
+            '<' => out.push_str("&lt;"),
+            '>' => out.push_str("&gt;"),
+            _ => out.push(c),
+        }
+    }
+    out
+}
+
+fn esc_attr(s: &str) -> String {
+    let mut out = esc_text(s);
+    out = out.replace('"', "&quot;");
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use docsai_model::MemoryAssetStore;
+    use std::io::Cursor;
+
+    #[test]
+    fn write_then_read_preserves_basic_text() {
+        let doc = Document::Text(TextDocument {
+            meta: docsai_model::DocumentMeta {
+                title: Some("Hola".into()),
+                author: Some("docsai".into()),
+                ..Default::default()
+            },
+            sections: vec![Section {
+                page: docsai_model::text::PageGeometry {
+                    size: docsai_model::units::Size::new(
+                        docsai_model::units::Length::from_twips(11906),
+                        docsai_model::units::Length::from_twips(16838),
+                    ),
+                    ..Default::default()
+                },
+                blocks: vec![
+                    Block::Paragraph(Paragraph::text("Primer parrafo")),
+                    Block::Heading(Heading {
+                        level: 1,
+                        paragraph: Paragraph::text("Titulo"),
+                    }),
+                    Block::Paragraph(Paragraph::text("Segundo")),
+                ],
+                ..Default::default()
+            }],
+            ..Default::default()
+        });
+        let assets = MemoryAssetStore::new();
+        let mut buf = Cursor::new(Vec::new());
+        write_docx(&doc, &assets, &mut buf).expect("write");
+        buf.set_position(0);
+        let mut assets2 = MemoryAssetStore::new();
+        let (read_back, _) = crate::docx::read(buf, &mut assets2).expect("read");
+        let text = match read_back {
+            Document::Text(t) => t,
+            _ => panic!("expected text"),
+        };
+        assert_eq!(text.meta.title.as_deref(), Some("Hola"));
+        let plain: Vec<String> = text
+            .blocks()
+            .filter_map(|b| match b {
+                Block::Paragraph(p) => Some(p.plain_text()),
+                Block::Heading(h) => Some(h.paragraph.plain_text()),
+                _ => None,
+            })
+            .collect();
+        assert!(plain.iter().any(|p| p.contains("Primer parrafo")));
+        assert!(plain.iter().any(|p| p.contains("Titulo")));
+        assert!(plain.iter().any(|p| p.contains("Segundo")));
+    }
+}
diff --git a/crates/docsai-office/src/error.rs b/crates/docsai-office/src/error.rs
index 3e67b22..e1cf409 100644
--- a/crates/docsai-office/src/error.rs
+++ b/crates/docsai-office/src/error.rs
@@ -1,6 +1,6 @@
 //! Reader errors.
 //!
-//! Fase 1 acceptance criterion: *no panics on corrupt input, always `Err`*.
+//! Phase 1 acceptance criterion: *no panics on corrupt input, always `Err`*.
 //! Every failure path in this crate ends in one of these variants.
 
 /// Something went wrong reading an Office document.
diff --git a/crates/docsai-office/src/lib.rs b/crates/docsai-office/src/lib.rs
index b5ec7a0..c6b65cc 100644
--- a/crates/docsai-office/src/lib.rs
+++ b/crates/docsai-office/src/lib.rs
@@ -1,7 +1,7 @@
 //! Office readers and writers for docsai.
 //!
-//! Fase 1 lands the `.docx` reader; `.xlsx`/`.xls` arrive in Fase 3 and `.doc`
-//! in Fase 5. The crate depends on `docsai-model` and on nothing else in the
+//! Phase 1 lands the `.docx` reader; `.xlsx`/`.xls` arrive in Phase 3 and `.doc`
+//! in Phase 5. The crate depends on `docsai-model` and on nothing else in the
 //! workspace (`AGENTS.md` §3).
 //!
 //! ```no_run
@@ -19,10 +19,12 @@ pub mod detect;
 mod docx;
 mod error;
 mod package;
+mod write_error;
 mod xml;
 
 pub use detect::{detect, DetectScore};
 pub use error::ReadError;
+pub use write_error::WriteError;
 
 use docsai_model::assets::AssetStore;
 use docsai_model::{ConversionReport, Document, Format};
@@ -32,7 +34,7 @@ use std::io::{Read, Seek};
 pub const READABLE: &[Format] = &[Format::Docx];
 
 /// Formats this crate can write today.
-pub const WRITABLE: &[Format] = &[];
+pub const WRITABLE: &[Format] = &[Format::Docx];
 
 /// Reads a `.docx` document.
 pub fn read_docx<R: Read + Seek>(
@@ -56,3 +58,25 @@ pub fn read<R: Read + Seek>(
         }),
     }
 }
+
+/// Writes a `.docx` document.
+pub fn write_docx<W: std::io::Write + std::io::Seek>(
+    document: &Document,
+    assets: &dyn AssetStore,
+    writer: W,
+) -> Result<ConversionReport, WriteError> {
+    docx::write::write_docx(document, assets, writer)
+}
+
+/// Writes any Office document this crate supports.
+pub fn write<W: std::io::Write + std::io::Seek>(
+    format: Format,
+    document: &Document,
+    assets: &dyn AssetStore,
+    writer: W,
+) -> Result<ConversionReport, WriteError> {
+    match format {
+        Format::Docx => write_docx(document, assets, writer),
+        other => Err(WriteError::Unsupported(other.to_string())),
+    }
+}
diff --git a/crates/docsai-office/src/package.rs b/crates/docsai-office/src/package.rs
index f922d7a..b1e8d1a 100644
--- a/crates/docsai-office/src/package.rs
+++ b/crates/docsai-office/src/package.rs
@@ -8,7 +8,7 @@ use crate::xml::Element;
 
 /// Cap on the total uncompressed size of a package.
 ///
-/// A first line of defence against decompression bombs; Fase 8 hardens this
+/// A first line of defence against decompression bombs; Phase 8 hardens this
 /// further with a dedicated adversarial suite.
 const MAX_TOTAL_BYTES: u64 = 512 * 1024 * 1024;
 /// Cap on a single part.
@@ -21,6 +21,37 @@ pub struct Package {
 }
 
 impl Package {
+    /// Builds an empty package.
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Inserts or replaces a part.
+    pub fn insert(&mut self, name: impl Into<String>, bytes: impl Into<Vec<u8>>) {
+        self.parts.insert(name.into(), bytes.into());
+    }
+
+    /// Writes the package as a ZIP archive with deterministic part order.
+    pub fn write_to<W: std::io::Write + std::io::Seek>(
+        &self,
+        writer: W,
+    ) -> Result<(), crate::write_error::WriteError> {
+        use std::io::Write;
+        let mut zip = zip::ZipWriter::new(writer);
+        let options = zip::write::SimpleFileOptions::default()
+            .compression_method(zip::CompressionMethod::Deflated)
+            .last_modified_time(
+                zip::DateTime::from_date_and_time(2020, 1, 1, 0, 0, 0)
+                    .unwrap_or_else(|_| zip::DateTime::default_for_write()),
+            );
+        for (name, bytes) in &self.parts {
+            zip.start_file(name.as_str(), options)?;
+            zip.write_all(bytes)?;
+        }
+        zip.finish()?;
+        Ok(())
+    }
+
     /// Reads every part of the ZIP container.
     pub fn open<R: Read + Seek>(reader: R) -> Result<Package, ReadError> {
         let mut zip = zip::ZipArchive::new(reader)?;
@@ -171,7 +202,7 @@ impl Relationships {
 /// Normalises a ZIP member name, rejecting anything that escapes the package.
 ///
 /// Media file names inside a document are attacker-controlled, so a member
-/// called `../../etc/passwd` must never become a part name (arquitectura §3.2).
+/// called `../../etc/passwd` must never become a part name (architecture §3.2).
 fn normalise_part_name(raw: &str) -> Option<String> {
     let raw = raw.replace('\\', "/");
     if raw.starts_with('/') || raw.contains(':') {
diff --git a/crates/docsai-office/src/write_error.rs b/crates/docsai-office/src/write_error.rs
new file mode 100644
index 0000000..049618b
--- /dev/null
+++ b/crates/docsai-office/src/write_error.rs
@@ -0,0 +1,26 @@
+//! Writer errors.
+
+/// Something went wrong writing an Office document.
+#[derive(Debug, thiserror::Error)]
+pub enum WriteError {
+    #[error("unsupported write format: {0}")]
+    Unsupported(String),
+
+    #[error("i/o error: {0}")]
+    Io(#[from] std::io::Error),
+
+    #[error("zip error: {0}")]
+    Zip(String),
+
+    #[error("asset error: {0}")]
+    Asset(#[from] docsai_model::assets::AssetError),
+
+    #[error("invalid document: {0}")]
+    Invalid(String),
+}
+
+impl From<zip::result::ZipError> for WriteError {
+    fn from(e: zip::result::ZipError) -> Self {
+        WriteError::Zip(e.to_string())
+    }
+}
diff --git a/crates/docsai-office/tests/docx_images.rs b/crates/docsai-office/tests/docx_images.rs
index 5ead7a9..209f711 100644
--- a/crates/docsai-office/tests/docx_images.rs
+++ b/crates/docsai-office/tests/docx_images.rs
@@ -1,4 +1,4 @@
-//! The image half of the Fase 1 acceptance criteria: floating, transformed and
+//! The image half of the Phase 1 acceptance criteria: floating, transformed and
 //! duplicated pictures must reach the IR with their geometry intact.
 
 use docsai_model::assets::AssetStore;
diff --git a/crates/docsai-office/tests/robustness.rs b/crates/docsai-office/tests/robustness.rs
index 870d1e8..b39b9c4 100644
--- a/crates/docsai-office/tests/robustness.rs
+++ b/crates/docsai-office/tests/robustness.rs
@@ -1,5 +1,5 @@
-//! Fase 1 acceptance criterion: *«Cero pánicos con corpus corrupto sintético
-//! (ZIP truncado, XML malformado): siempre `Err`»*.
+//! Phase 1 acceptance criterion: *"Zero panics on synthetic corrupt corpus
+//! (truncated ZIP, malformed XML): always `Err`"*.
 //!
 //! The R1 spike measured 204 panics out of 903 corrupt inputs for `docx-rs`;
 //! this test is the standing guarantee that the own parser does better.
diff --git a/docs/analisis-tecnico.md b/docs/analisis-tecnico.md
deleted file mode 100644
index 99ea37c..0000000
--- a/docs/analisis-tecnico.md
+++ /dev/null
@@ -1,258 +0,0 @@
-# Análisis técnico
-
-Documento de análisis previo al desarrollo de `docsai`. Cubre: (1) los formatos de entrada/salida
-y su complejidad real, (2) el estado del arte en proyectos open source comparables, (3) las
-variantes de Markdown extendido candidatas como formato pivote, (4) la evaluación de librerías
-Rust disponibles y (5) las decisiones tomadas con sus riesgos.
-
-Fecha del análisis: agosto de 2026.
-
----
-
-## 1. Los formatos de entrada/salida
-
-### 1.1 OOXML: `.docx` y `.xlsx` (ECMA-376 / ISO 29500)
-
-Ambos son contenedores ZIP con XML dentro. Son los formatos con mejor documentación pública y
-mejor soporte de librerías, y por eso anclan las fases 1–3 del plan.
-
-**`.docx` (WordprocessingML)** — partes relevantes dentro del ZIP:
-
-| Parte | Contenido | Relevancia para docsai |
-|---|---|---|
-| `word/document.xml` | Cuerpo: párrafos (`w:p`), runs (`w:r`), tablas (`w:tbl`) | Núcleo de la conversión |
-| `word/styles.xml` | Catálogo de estilos (párrafo, carácter, tabla) + herencia `basedOn` | Debe volcarse al front matter DocMark |
-| `word/numbering.xml` | Definiciones de listas (numeración, viñetas, niveles) | Crítico: las listas en OOXML no son anidadas sintácticamente, se reconstruyen desde `numId`/`ilvl` |
-| `word/media/*` | Imágenes embebidas (png, jpeg, gif, **wmf/emf**) | Extraer a `assets/` |
-| `word/_rels/*.rels` | Relaciones (imágenes, hipervínculos) | Resolución de referencias |
-| `word/header*.xml`, `word/footer*.xml` | Cabeceras y pies | Contenedores DocMark dedicados |
-| `docProps/core.xml`, `docProps/app.xml` | Propiedades (título, autor, fechas…) | Front matter |
-| `word/settings.xml`, secciones `w:sectPr` | Tamaño página, márgenes, columnas | Metadatos de sección |
-
-Puntos duros conocidos de `.docx`:
-- **Herencia de formato en 4 niveles**: defaults del documento → estilo de párrafo → estilo de
-  carácter → formato directo (`rPr`/`pPr`). Para una conversión fiel hay que *resolver* la cascada
-  pero *almacenar* solo la referencia al estilo + los deltas directos (si se aplana todo, la
-  conversión inversa produce documentos monstruosos sin estilos reutilizables).
-- **Listas**: reconstrucción del árbol a partir de pares `(numId, ilvl)` planos.
-- **Campos** (`w:fldSimple`, `w:instrText`): TOC, referencias cruzadas, números de página. Se
-  conservan como raw-blocks en v1.
-- **Imágenes WMF/EMF**: formatos vectoriales legados de Windows sin soporte de renderizado
-  multiplataforma sencillo. Estrategia: extraer tal cual + advertencia; conversión opcional en fases tardías.
-- **Revisiones/comentarios** (`w:ins`, `w:del`, `w:comment*`): fuera del alcance v1; se aceptan
-  documentos con revisiones tomando la versión "aceptada" y emitiendo advertencia.
-
-**`.xlsx` (SpreadsheetML)** — partes relevantes: `xl/workbook.xml`, `xl/worksheets/sheet*.xml`,
-`xl/sharedStrings.xml`, `xl/styles.xml` (formatos de número, fuentes, rellenos, bordes — todo por
-índices cruzados), `xl/calcChain.xml`.
-
-Puntos duros de `.xlsx`:
-- **Las celdas guardan valor cacheado + fórmula** (`<c><f>SUM(A1:A3)</f><v>42</v></c>`). DocMark
-  debe conservar ambos: la fórmula para la bidireccionalidad, el valor para la legibilidad.
-- **Fórmulas compartidas** (`t="shared"`) y de matriz (`t="array"`): hay que expandirlas o
-  conservar su metadato de rango.
-- **Formatos de número** (`numFmt`): son la diferencia entre `45123` y `15/07/2023` — las fechas
-  en Excel son números de serie + formato. Conservar `numFmtId`/código de formato por celda es
-  obligatorio para no corromper datos en el round-trip.
-- Celdas combinadas (`mergeCells`), anchos de columna/altos de fila, paneles congelados,
-  validaciones, formato condicional (los tres últimos: metadatos en v1, sin semántica).
-
-### 1.2 ODF: `.odt` y `.ods` (ISO 26300, OASIS OpenDocument)
-
-También ZIP+XML (`content.xml`, `styles.xml`, `meta.xml`, `settings.xml`, `Pictures/`). Modelo
-conceptual muy parecido a OOXML pero con diferencias importantes:
-
-- Los **estilos automáticos** (`office:automatic-styles`) representan el formato directo: cada
-  fragmento con formato manual genera un estilo anónimo. Hay que "des-automatizar" al leer
-  (mapear estilos automáticos a deltas de formato directo en el IR).
-- Las fórmulas de `.ods` usan **OpenFormula** con prefijo de espacio de nombres
-  (`of:=SUM([.A1:.A3])`) y sintaxis de referencia distinta (`[.A1]` vs `A1`). Para la
-  bidireccionalidad OOXML⇄ODF haría falta traducir sintaxis de fórmulas; en v1 se conserva la
-  fórmula en su dialecto original anotando `formula-dialect` en la celda.
-- ODF está mejor especificado y es más regular que OOXML; el esfuerzo de un parser propio con
-  `quick-xml` es asumible y de hecho es el plan para `.odt` (ver §4.3).
-
-### 1.3 Formatos binarios legados: `.doc` (MS-DOC) y `.xls` (BIFF8)
-
-- **`.xls`**: resuelto — `calamine` lo lee de forma nativa (valores y fórmulas). Solo lectura.
-- **`.doc`**: es el mayor riesgo técnico del proyecto. Es un formato binario sobre contenedor
-  OLE2/CFB con estructuras internas complejas (piece table, FIB, FKPs…). **No existe ningún
-  crate Rust maduro que lo lea con estilos e imágenes.** Opciones evaluadas:
-
-| Opción | Esfuerzo | Fidelidad | Dependencias |
-|---|---|---|---|
-| Parser propio sobre crate `cfb` (spec MS-DOC) | Muy alto (meses) | Alta | Ninguna externa |
-| Fallback a LibreOffice headless (`soffice --headless --convert-to docx`) y reusar pipeline docx | Bajo | Muy alta | LibreOffice instalado (opcional, detectado en runtime) |
-| `antiword`/`wvWare` como proceso externo | Bajo | Baja (pierde estilos) | Binario externo |
-| Extracción de texto plano propia (piece table only) | Medio | Solo texto | Ninguna |
-
-  **Decisión**: estrategia en dos niveles. (a) Fallback LibreOffice headless si está instalado —
-  fidelidad máxima con esfuerzo mínimo; (b) extractor nativo de texto+estructura básica sobre
-  `cfb` como modo degradado sin dependencias. El parser MS-DOC completo no se aborda salvo que
-  la demanda real lo justifique. Esto mantiene el principio "binario único sin runtime externo
-  obligatorio": LibreOffice mejora `.doc` pero nunca es requisito.
-
-### 1.4 Imágenes y objetos gráficos: análisis transversal
-
-Las imágenes son un requisito de primera clase del proyecto: **todos** los formatos de entrada
-las llevan, con modelos de geometría distintos, y la conversión debe extraerlas y conservar
-tamaño, posición, anclaje y demás propiedades para el round-trip. Modelo por formato:
-
-| Formato | Dónde viven | Modelo de geometría/anclaje |
-|---|---|---|
-| `.docx` | `word/media/*` + `<w:drawing>` (DrawingML) o `<w:pict>` (VML legado) | `wp:inline` (en línea, solo `wp:extent`) o `wp:anchor` (flotante: posición relativa a página/margen/párrafo/carácter, offsets EMU, wrap `square/tight/through/topAndBottom/none`, z-order, `behindDoc`) |
-| `.xlsx` | `xl/media/*` + `xl/drawings/drawing*.xml` (SpreadsheetDrawingML) | Tres anclajes: `xdr:twoCellAnchor` (de celda a celda + offsets, se estira con la rejilla), `xdr:oneCellAnchor` (celda origen + tamaño fijo), `xdr:absoluteAnchor` (posición absoluta en EMU) |
-| `.odt` | `Pictures/*` + `<draw:frame><draw:image>` | `text:anchor-type` = `as-char/char/paragraph/page/frame`; `svg:width/height/x/y`; wrap vía estilo gráfico (`style:wrap`) |
-| `.ods` | `Pictures/*` + `<draw:frame>` dentro de `<table:shapes>` o anclado a celda | Anclaje a celda (`table:end-cell-address` + offsets) o a hoja |
-| `.doc` | Stream `Data`/Escher (OfficeArt) | Binario Escher; en la ruta LibreOffice-fallback se convierte gratis; en la ruta nativa degradada se extraen los BLIPs (imágenes) sin geometría fina |
-
-Propiedades a conservar en todos los casos (definen el modelo normalizado del IR, ver
-`arquitectura.md` §3.1): dimensiones mostradas vs dimensiones nativas del bitmap (y por tanto el
-factor de escala), DPI, recorte (`srcRect` en OOXML, `fo:clip` en ODF), rotación y volteos,
-anclaje y posición con sus offsets, modo de ajuste de texto (wrap), orden Z, texto alternativo y
-título (accesibilidad, `descr`/`svg:desc`), nombre interno del objeto e hipervínculo sobre la
-imagen.
-
-Puntos duros específicos:
-- **Coordenadas heterogéneas**: EMU en OOXML (914 400/pulgada), cm/in en ODF, twips en `.doc`.
-  El IR normaliza todo a EMU con newtypes; DocMark expone `px`/`pt`/`cm` legibles.
-- **VML legado en docx**: documentos antiguos (o convertidos desde `.doc`) usan `<w:pict>` con
-  VML en lugar de DrawingML. Hay que soportar lectura de ambos; la escritura emite siempre
-  DrawingML.
-- **Anclajes twoCell en xlsx**: el tamaño real depende de anchos de columna/altos de fila; para
-  conservar la geometría hay que guardar el anclaje simbólico (celdas + offsets), no el tamaño
-  resuelto — y a la inversa al escribir.
-- **WMF/EMF**: se extraen tal cual (round-trip perfecto) pero no son visualizables en visores
-  Markdown; conversión a PNG/SVG queda en backlog post-1.0. La imagen se referencia igualmente
-  con su geometría completa.
-- **Duplicados**: el mismo bitmap puede aparecer N veces con geometrías distintas; el
-  `AssetStore` deduplica por hash de contenido y cada aparición conserva su geometría propia.
-- **Imágenes enlazadas (no embebidas)**: OOXML/ODF permiten `r:link`/`xlink:href` externo; se
-  conserva la URL con advertencia (no se descarga contenido remoto — implicación de seguridad).
-
----
-
-## 2. Estado del arte open source (qué aprender y qué reutilizar)
-
-| Proyecto | Lenguaje | Qué hace | Lecciones para docsai |
-|---|---|---|---|
-| **Pandoc** | Haskell | Conversión universal vía AST pivote; su Markdown extendido (atributos `{...}`, divs `:::`, front matter) es el más expresivo del mercado | El patrón arquitectónico completo: readers → AST → writers. Su sintaxis de atributos es la base de DocMark. Limitación conocida: fidelidad media-baja en docx complejos (estilos custom, cajas de texto) y soporte xlsx inexistente |
-| **MarkItDown** (Microsoft) | Python | Office/PDF/HTML → Markdown "LLM-ready", unidireccional | Valida la demanda del caso de uso MCP/LLM; su pérdida total de estilos es exactamente el hueco que docsai cubre |
-| **Docling** (IBM) | Python | Documentos → Markdown/JSON con modelo propio `DoclingDocument` | Confirma la necesidad de un modelo de documento rico como pivote y de exportar a la vez MD legible + metadatos estructurados |
-| **mammoth** (.js/Python) | JS/Python | docx → HTML semántico mediante **mapa de estilos configurable** (`Heading1 ⇒ h1`) | El concepto de style-map configurable por el usuario se adopta en docsai (`--style-map`) |
-| **html2md / turndown, marker, unoconv/unoserver** | varios | Conversores parciales | unoserver documenta el patrón de fallback LibreOffice headless |
-| **rdocx** | Rust | docx read/write + render a PDF/HTML/MD (crate reciente, 2026) | A vigilar como alternativa; demasiado joven para anclar el proyecto hoy |
-
-**Conclusión del estado del arte**: nadie combina hoy (1) binario nativo sin runtime,
-(2) bidireccionalidad con estilos, (3) hojas de cálculo con fórmulas y (4) servidor MCP.
-Pandoc es el techo de referencia en texto; MarkItDown/Docling en integración LLM. docsai se
-posiciona en la intersección vacía.
-
----
-
-## 3. El formato pivote: variantes de Markdown extendido evaluadas
-
-Requisitos: legible por humanos y visores estándar, atributos arbitrarios en inline y bloque,
-metadatos de documento, extensible sin romper parsers, y con ecosistema.
-
-| Candidato | Atributos | Ecosistema | Veredicto |
-|---|---|---|---|
-| **CommonMark + GFM puro** | ❌ No tiene | Enorme | Insuficiente: sin atributos no hay estilos |
-| **Pandoc Markdown** (atributos + fenced divs + spans + YAML) | ✅ Completo | Grande (pandoc lo consume) | **Base elegida.** Sintaxis probada durante una década para exactamente este problema |
-| **MyST Markdown** | ✅ (directivas/roles) | Científico/Sphinx | Directivas más verbosas; orientado a publicación, no a round-trip |
-| **Djot** (Jyrki/MacFarlane) | ✅ nativo | Pequeño | Técnicamente superior pero rompe la compatibilidad "se ve bien en GitHub" |
-| **MDX** | JSX | Web/React | Descartado: no es Markdown legible para no programadores |
-
-**Decisión**: **DocMark = CommonMark + GFM (tablas, tachado, task lists) + subconjunto de
-extensiones Pandoc** (atributos `{...}` en encabezados/imágenes/spans/código, fenced divs
-`:::`, front matter YAML) **+ extensiones propias para hojas de cálculo** (metadatos de celda)
-documentadas en `especificacion-docmark.md`. Beneficio adicional: un fichero DocMark es
-procesable por Pandoc directamente con degradación aceptable, lo que da interoperabilidad
-gratuita con todo el ecosistema Pandoc (PDF vía LaTeX, HTML, EPUB…).
-
----
-
-## 4. Evaluación de librerías Rust
-
-### 4.1 Lectura/escritura de documentos
-
-| Crate | Rol propuesto | Estado (2026) | Notas de la evaluación |
-|---|---|---|---|
-| **`calamine`** | Lectura `.xls`, `.xlsx`, `.xlsb`, `.ods` (valores **y fórmulas**) | Maduro, mantenido, muy usado | Lectura perezosa y rápida; lee fórmulas vía `worksheet_formula()`. **No lee estilos/formatos de número con detalle suficiente** → se complementa con lectura propia de `xl/styles.xml` |
-| **`umya-spreadsheet`** | Lectura+escritura `.xlsx` con estilos | Mantenido | Único crate que lee Y escribe xlsx con estilos; parsea todo el workbook en memoria (coste en ficheros grandes; existe `lazy_read`). Candidato principal para la **escritura** xlsx |
-| **`rust_xlsxwriter`** | Escritura `.xlsx` (alternativa) | Muy mantenido (port de XlsxWriter) | Excelente API de escritura con fórmulas y formatos, pero solo escritura y no permite "editar" — válido porque docsai regenera desde IR. Decidir vs umya en spike de Fase 3 |
-| **`docx-rs` (bokuweb)** | ~~Lectura~~ + posible escritura `.docx` | El más usado (1M+ descargas) | **Descartado para la lectura** tras el spike R1 (`docs/spikes/R1-estrategia-docx.md`, agosto 2026): resuelve bien estilos y numeración, pero pierde casi todo el modelo de imagen (wrap, `behindDoc`, recorte, volteo, rotación, alt, título, hipervínculo), las notas al pie y el `w:instr` de los campos simples, no conserva elementos desconocidos para raw-blocks, y entra en *panic* en el 23 % de 903 entradas corruptas medidas. La lectura docx usa parser propio sobre `zip` + `quick-xml`. Sigue siendo candidato para el **writer** de la Fase 2, decisión independiente |
-| **`docx-rust`** | Alternativa lectura `.docx` | Menor actividad | Mapeo XML más directo; mantener como referencia |
-| **`spreadsheet-ods`** | Lectura+escritura `.ods` | Mantenido | Cubre estilos y fórmulas ODS; evita escribir un writer ODF-spreadsheet propio |
-| **(ninguno)** | `.odt` | — | No hay crate maduro para ODT con estilos: **parser/writer propio** sobre `zip` + `quick-xml` (ODF es regular; esfuerzo acotado) |
-| **`cfb`** | Contenedor OLE2 para `.doc`/`.xls` legados | Estable | Base del extractor degradado de `.doc` |
-
-### 4.2 Markdown (ruta inversa)
-
-| Crate | Rol | Notas |
-|---|---|---|
-| **`comrak`** | Parser Markdown del pipeline DocMark→IR | CommonMark+GFM completo, mantiene posiciones, soporta front matter, tiene extensión de atributos limitada; los atributos `{...}` completos y los fenced divs `:::` se procesan en una pasada propia sobre su AST (o pre-lexer) |
-| `markdown-rs` / `pulldown-cmark` | Alternativas | pulldown-cmark es más rápido pero orientado a eventos (incómodo para transformación); markdown-rs tiene AST mdast agradable pero menos extensiones nativas |
-
-**Decisión**: `comrak` + capa propia de atributos/divs. El **serializador** DocMark (IR→MD) se
-escribe a mano (no se delega en comrak) para controlar byte a byte la salida y garantizar la
-idempotencia del round-trip.
-
-### 4.3 Infraestructura
-
-| Crate | Rol |
-|---|---|
-| `zip` | Contenedores OOXML/ODF |
-| `quick-xml` (+ `serde`) | Parsing XML de alto rendimiento donde los crates de formato no llegan |
-| `serde` / `serde_yaml` / `serde_json` | Front matter, `inspect --json`, config |
-| `clap` (derive) | CLI |
-| `rmcp` (SDK oficial de MCP, transporte stdio) | Servidor MCP; macros `#[tool]`; implementa spec 2026-07-28 con compatibilidad hacia atrás |
-| ~~`image`~~ | **No se usa en la Fase 1.** docsai nunca recodifica un mapa de bits, solo necesita nombrarlo y medirlo, y eso se resuelve leyendo la cabecera del formato (PNG, JPEG, GIF, BMP, TIFF, WebP, EMF, WMF) en `docsai-model::assets`, sin dependencia pesada. Se reevaluará si alguna fase necesita recodificar de verdad |
-| ~~`serde_yaml`~~ | **No se usa.** El front matter tiene un esquema pequeño y conocido y la spec exige determinismo byte a byte, así que se escribe a mano; además el crate está sin mantenimiento activo |
-| `thiserror` / `anyhow` | Errores |
-| `tracing` + `tracing-subscriber` | Logs (siempre a stderr) |
-| `tokio` | Solo en `docsai-mcp` (rmcp lo requiere); el núcleo de conversión es síncrono |
-| ~~`insta`~~ | **No se usa.** Los golden files son `.expected.dmk.md` junto al corpus, como prescribe `AGENTS.md` §6: se revisan como texto normal en el diff y no dependen de un formato de snapshot |
-| `cargo-fuzz` | Fuzzing de parsers (Fase 8) |
-| `cargo-dist` | Empaquetado de releases multiplataforma |
-
----
-
-## 5. Decisiones de arquitectura derivadas (resumen)
-
-1. **IR pivote obligatorio** (`docsai-model`): árbol de documento con dos raíces posibles
-   (`TextDocument`, `Workbook`) — detalle en `arquitectura.md`. N formatos → 2N conversores en
-   lugar de N².
-2. **Estilos por referencia + delta**: el IR guarda `style_id` + propiedades directas, y el
-   catálogo de estilos viaja completo en el front matter. Así el round-trip reconstruye
-   `styles.xml` real y el Markdown sigue limpio.
-3. **Assets externos con manifiesto**: imágenes a `assets/` con nombre determinista
-   (hash de contenido) para que el round-trip no duplique medios.
-4. **`ConversionReport` estructurado**: toda conversión devuelve documento + lista de
-   advertencias tipadas (elemento no soportado, degradación, raw-block emitido). La CLI lo
-   muestra; el MCP lo devuelve en la respuesta de la tool.
-5. **Fallbacks externos opcionales**: LibreOffice headless solo para `.doc`, detectado en
-   runtime (`--use-loffice=auto|never|require`).
-
-## 6. Riesgos principales y mitigaciones
-
-| # | Riesgo | Prob. | Impacto | Mitigación |
-|---|---|---|---|---|
-| R1 | La cascada de estilos OOXML resulta más costosa de lo previsto y retrasa Fase 1 | Alta | Alto | Spike de 1 semana en Fase 0 con documentos reales; limitar v1 a la resolución de 4 niveles sin `tblStyle` condicional |
-| R2 | Ningún crate xlsx cubre lectura de estilos con suficiente detalle | Media | Medio | Ya asumido: lectura complementaria propia de `xl/styles.xml` con quick-xml (esfuerzo acotado, formato documentado) |
-| R3 | Round-trip no idempotente por ambigüedades de Markdown (escapes, espacios) | Media | Alto | Serializador propio con reglas deterministas + test de idempotencia en CI desde Fase 2 |
-| R4 | `.doc` sin LibreOffice decepciona a usuarios | Media | Bajo | Mensajes claros de modo degradado; documentar en README |
-| R5 | Divergencia de dialectos de fórmula OOXML/OpenFormula | Alta | Medio | v1 conserva dialecto original + campo `formula-dialect`; traducción automática pospuesta (Fase 9/backlog) |
-| R6 | Crates de terceros abandonados a mitad de proyecto | Baja | Medio | Los cuatro crates críticos son de los más usados del ecosistema; el diseño por IR permite sustituir un reader sin tocar el resto |
-| R7 | Tamaño del binario crece descontrolado | Baja | Bajo | `cargo bloat` en CI, features opcionales, LTO en release |
-| R8 | Diversidad de modelos de imagen (DrawingML vs VML vs Escher vs draw:frame) fragmenta el esfuerzo | Media | Medio | Modelo `ImageGeometry` normalizado en el IR definido en Fase 0 (arquitectura §3.1); lectura VML limitada a los atributos del modelo; Escher solo BLIPs en la ruta nativa `.doc` |
-
-## 7. Fuentes consultadas
-
-- [Pandoc User's Guide](https://pandoc.org/MANUAL.html) — sintaxis de atributos, divs y front matter
-- [calamine (GitHub)](https://github.com/tafia/calamine) y [docs.rs/calamine](https://docs.rs/calamine)
-- [umya-spreadsheet (GitHub)](https://github.com/mathnya/umya-spreadsheet) y comparativa [calamine vs umya-spreadsheet](https://umaranis.com/2026/05/04/reading-excel-files-in-rust-calamine-vs-umya-spreadsheet/)
-- [docx-rs (crates.io)](https://crates.io/crates/docx-rs) · [docx-rust (crates.io)](https://crates.io/crates/docx-rust) · [rdocx (lib.rs)](https://lib.rs/crates/rdocx)
-- [SDK oficial Rust de MCP — rmcp](https://github.com/modelcontextprotocol/rust-sdk) y [docs.rs/rmcp](https://docs.rs/rmcp)
-- Comparativas de conversores: [MarkItDown vs Pandoc](https://www.file2markdown.ai/blog/markitdown-vs-pandoc), [Docling vs MarkItDown](https://www.file2markdown.ai/blog/docling-vs-markitdown), [Real Python sobre MarkItDown](https://realpython.com/python-markitdown/)
-- ECMA-376 (OOXML), ISO/IEC 26300 (ODF), especificaciones [MS-DOC]/[MS-XLS] de Microsoft Open Specifications
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..b31bb1d
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,252 @@
+# docsai architecture
+
+Describes the software structure: crate workspace, intermediate document model (IR),
+conversion pipelines, CLI and MCP server. Complements `technical-analysis.md` (the why)
+and `development-plan.md` (the when).
+
+## 1. Overview
+
+```
+                 ┌────────────────────────── docsai-convert ──────────────────────────┐
+  .docx ─┐       │                                                                    │
+  .doc  ─┤  readers (docsai-office / docsai-odf)          writers                     │
+  .odt  ─┼──────────────►  IR (docsai-model)  ◄──────────────────────┐                │
+  .xlsx ─┤                    ▲        │                             │                │
+  .xls  ─┤                    │        ▼                             │                │
+  .ods  ─┘             DocMark parser  DocMark serializer     .docx/.xlsx/.odt/.ods   │
+                        (docsai-docmark)                             ▲                │
+                              ▲        │                             │                │
+                              │        ▼                             │                │
+                          .dmk.md file + assets/ ────────────────────┘                │
+                 └─────────────────────────────────────────────────────────────────────┘
+                                   ▲                          ▲
+                            docsai-cli (clap)          docsai-mcp (rmcp, stdio)
+```
+
+Central rule: **no converter talks to another converter**. Everything goes through the IR.
+
+## 2. Crate workspace
+
+| Crate | Type | Responsibility | Internal dependencies |
+|---|---|---|---|
+| `docsai-model` | lib | IR + common types (`Style`, `ConversionReport`, units) | none |
+| `docsai-docmark` | lib | DocMark serializer and parser (IR ⇄ .dmk.md + assets) | model |
+| `docsai-office` | lib | docx/xlsx/xls/doc readers and docx/xlsx writers | model |
+| `docsai-odf` | lib | odt/ods readers/writers | model |
+| `docsai-convert` | lib | Orchestration: format detection, pipelines, asset management, LibreOffice fallback, reports | all of the above |
+| `docsai-cli` | bin | `docsai` binary (convert/inspect/roundtrip/mcp subcommands) | convert |
+| `docsai-mcp` | lib | MCP server implementation (CLI starts it with `docsai mcp`) | convert |
+
+Notes:
+- A single distributed binary (`docsai`); `docsai-mcp` is a lib so the `mcp` subcommand
+  lives inside the same executable.
+- Cargo features per format (`office-doc`, `odf`, …) to compile minimal variants.
+
+## 3. The intermediate model (IR) — `docsai-model`
+
+Two roots:
+
+```rust
+pub enum Document {
+    Text(TextDocument),
+    Workbook(Workbook),
+}
+
+pub struct TextDocument {
+    pub meta: DocumentMeta,          // title, author, dates, custom props, language
+    pub styles: StyleCatalog,        // named styles with inheritance (based_on)
+    pub list_defs: ListCatalog,
+    pub sections: Vec<Section>,      // page geometry + headers/footers + blocks
+}
+
+pub enum Block {
+    Paragraph(Paragraph),            // Vec<Inline> + ParaProps (style_id + direct deltas)
+    Heading(Heading),                // outline level + Paragraph
+    List(List),                      // already reconstructed tree (not numId/ilvl pairs)
+    Table(Table),                    // grid with spans, col-widths, style
+    Image(ImageRef),                 // AssetStore reference + geometry/anchor
+    TextBox(TextBox),
+    Raw(RawFragment),                // fidelity hatch (source format + XML bytes)
+    // …
+}
+
+pub enum Inline {
+    Text(String),
+    Styled(Vec<Inline>, RunProps),   // RunProps = optional style_id + deltas (bold, color…)
+    Link { target: String, content: Vec<Inline>, props: RunProps },
+    Footnote(Vec<Block>),
+    Field { kind: FieldKind, cached: String },
+    Break(BreakKind),
+    ImageInline(ImageRef),
+}
+
+pub struct Workbook {
+    pub meta: DocumentMeta,
+    pub styles: StyleCatalog,
+    pub defined_names: Vec<DefinedName>,
+    pub sheets: Vec<Sheet>,          // Sheet = sparse Cell grid + col/row props + merges
+}                                    //         + panes + images: Vec<ImageRef> (sheet-anchored)
+
+pub struct Cell {
+    pub value: CellValue,            // Number | Text | Bool | DateTime | Error | Empty
+    pub formula: Option<Formula>,    // text + dialect (Ooxml | OpenFormula) + shared/array info
+    pub num_fmt: Option<NumFmt>,
+    pub style_id: Option<StyleId>,
+}
+```
+
+### 3.1 Normalized image model (`ImageRef` + `ImageGeometry`)
+
+Each input format has its own graphics model (DrawingML, VML, SpreadsheetDrawingML,
+ODF `draw:frame`, Escher — see analysis §1.4). The IR normalizes them to a single model,
+which DocMark spec §3.5/§4.1 serializes attribute by attribute:
+
+```rust
+pub struct ImageRef {
+    pub asset: AssetId,                  // key in the AssetStore (content hash)
+    pub geometry: ImageGeometry,
+    pub alt: String,                     // alternative text (accessibility)
+    pub title: Option<String>,
+    pub name: Option<String>,            // internal object name (docPr @name)
+    pub link: Option<String>,            // hyperlink on the image
+    pub external_src: Option<String>,    // linked image, not embedded
+    pub effects_raw: Option<RawId>,      // unmodeled DrawingML effects → associated raw-block
+}
+
+pub struct ImageGeometry {
+    pub display_size: Size,              // EMU; displayed size (≠ native size)
+    pub native_size_px: Option<(u32, u32)>,
+    pub dpi: Option<u32>,
+    pub anchor: Anchor,
+    pub rotation_deg: f32,
+    pub flip: Flip,                      // None | H | V | HV
+    pub crop: Option<CropRect>,          // % of original per side
+    pub border: Option<SimpleBorder>,
+    pub z_index: Option<i32>,
+}
+
+pub enum Anchor {
+    Inline,                                              // flows with text
+    Floating { relative_to: RelBase,                     // Page | Margin | Paragraph | Character
+               position: HVPos,                          // EMU offsets or symbolic alignment
+               wrap: WrapMode, wrap_side: WrapSide,
+               behind_text: bool },
+    // Spreadsheets only:
+    SheetTwoCell { from: CellAnchor, to: CellAnchor,     // CellAnchor = (col,row) + EMU offsets
+                   move_with_cells: bool, size_with_cells: bool },
+    SheetOneCell { from: CellAnchor },                   // + fixed display_size
+    SheetAbsolute { pos: Point },
+}
+```
+
+Model rules:
+- Readers **translate into this model, they do not bypass it**: an image attribute a reader
+  cannot map is degraded with a typed warning (`Warning::ImageGeometryDegraded`), and
+  unrepresentable effects go to raw-block via `effects_raw` — never silently discarded.
+- Writers do the full reverse translation (e.g. `Anchor::Floating` → `wp:anchor`
+  with `positionH/V`, wrap and z-order; `SheetTwoCell` → `xdr:twoCellAnchor`).
+- Cross conversion of anchors (text document ⇄ sheet) does not exist: each sheet `Anchor`
+  is only valid inside a `Workbook` (invariant checked by the IR validator).
+
+### 3.2 `AssetStore`
+
+Trait that abstracts media storage; `docsai-convert` provides the implementations
+(`assets/` directory in CLI, memory/base64 in MCP):
+
+- **Content-hash deduplication**: `put(bytes) -> AssetId` returns the same id for the same
+  content; N appearances of a bitmap share a file, each `ImageRef` keeps its own geometry.
+- **Deterministic names** `img-<hash8>.<ext>` (extension derived from content sniffing,
+  not the source) → round-trips do not duplicate media and `assets/` diffs are stable.
+- **Manifest**: the store records content-type, byte size and detected native dimensions
+  (`image` crate); `inspect --json` exposes it and the writer uses it to fill required
+  destination fields without re-reading files.
+- **Security**: asset names are sanitized (never derived from internal document paths →
+  no path traversal); external linked images are never downloaded.
+
+IR principles:
+- **Style = reference + delta**, never flattened format (see analysis §5.2).
+- **No I/O dependency**: `docsai-model` knows nothing about ZIP or XML; `ImageRef`s point to an
+  abstract `AssetStore` (trait) materialized by `docsai-convert`.
+- All types are `serde`-serializable → free `inspect --json` and simple debugging.
+- Units normalized to EMU/twips internally with newtypes (`Length`), converting to
+  `pt/cm/px` only when serializing DocMark.
+
+## 4. Conversion contracts
+
+```rust
+pub trait DocumentReader {
+    fn detect(path: &Path, sniff: &[u8]) -> DetectScore;      // by content, not only extension
+    fn read(&self, input: &mut dyn ReadSeek, assets: &mut dyn AssetStore)
+        -> Result<(Document, ConversionReport), ReadError>;
+}
+
+pub trait DocumentWriter {
+    fn write(&self, doc: &Document, assets: &dyn AssetStore, out: &mut dyn Write)
+        -> Result<ConversionReport, WriteError>;
+}
+
+pub struct ConversionReport {
+    pub warnings: Vec<Warning>,       // typed: UnsupportedElement { kind, location, action }
+    pub raw_blocks_emitted: u32,      //          Degraded { what, why } · AssetIssue { … }
+    pub stats: ConversionStats,       // paragraphs, cells, images, formulas processed
+}
+```
+
+- Readers **never panic** on corrupt input: always typed `Err`.
+- `ConversionReport` flows to CLI (readable stderr / `--json`) and to the MCP response.
+- The `roundtrip` command compares original IR vs IR after round-trip with a **structural
+  diff of normalized IR** and produces a fidelity metric (% nodes preserved per category).
+
+## 5. CLI (`docsai-cli`)
+
+```
+docsai convert <in> [-o <out>] [--to <fmt>] [--fidelity full|standard|plain]
+               [--assets-dir <dir>] [--style-map <yaml>] [--max-cells N]
+               [--use-loffice auto|never|require] [--json]
+docsai inspect <in> [--json]        # metadata, styles, sheets, media, without converting
+docsai roundtrip <in> [--report <path>] [--json]
+docsai formats                       # current support matrix
+docsai mcp                           # MCP server over stdio
+```
+
+- Destination format inferred from `-o` extension, forceable with `--to`.
+- stdin/stdout supported (`-` as name) for pipelines, except binary output formats on a
+  terminal (standard protection).
+- Exit codes: 0 OK, 1 conversion with severe warnings (`--strict` makes them fatal),
+  2 input error, 3 unsupported format.
+
+## 6. MCP server (`docsai-mcp`)
+
+Based on `rmcp` (official SDK), **stdio** transport. Logs to stderr exclusively.
+
+Tools exposed (v1):
+
+| Tool | Input | Output |
+|---|---|---|
+| `convert_to_markdown` | `path` (or `content_base64` + `filename`), `fidelity`, `assets` = `inline-base64`\|`files` | DocMark (text), assets, `report` |
+| `convert_from_markdown` | `markdown`, `target_format`, optional assets | base64 file or written `path`, `report` |
+| `inspect_document` | `path`/`content_base64` | structure JSON (same shape as `inspect --json`) |
+| `list_supported_formats` | — | support matrix with status per direction |
+
+Decisions:
+- Dual **path/base64** mode: local MCP clients (Claude Desktop/Code) pass paths; remote
+  ones can pass embedded content. Size limit configurable via environment variable.
+- Large responses: DocMark as `text content`; binaries as base64 resource with correct MIME.
+- The server is stateless; each tool call is an independent conversion (no persistent temp
+  files unless the client asks for `assets=files`).
+
+## 7. Cross-platform and distribution
+
+- No system dependencies on the main path (pure Rust). `soffice` is searched at runtime
+  in standard locations per OS only for `.doc`.
+- CI: GitHub Actions, ubuntu/windows/macos matrix; release artifacts with `cargo-dist`
+  (tar.gz/zip + shell/powershell installers; optional: Homebrew tap, Scoop/winget, cargo-binstall).
+- Targets: `x86_64-unknown-linux-gnu`, `aarch64-unknown-linux-gnu`, `x86_64-pc-windows-msvc`,
+  `aarch64-apple-darwin`, `x86_64-apple-darwin`. LTO + `strip` on release.
+
+## 8. Performance (indicative budgets)
+
+- 100-page docx → DocMark: < 1 s on ordinary hardware.
+- 100k-cell xlsx: < 3 s and < 500 MB RAM (avoid cloning sharedStrings; use `Cow`).
+- Readers stream where the crate allows (calamine is lazy per sheet).
+- Benchmarks with `criterion` on the corpus from Phase 8; regressions > 20% block PRs.
diff --git a/docs/arquitectura.md b/docs/arquitectura.md
deleted file mode 100644
index 936e074..0000000
--- a/docs/arquitectura.md
+++ /dev/null
@@ -1,254 +0,0 @@
-# Arquitectura de docsai
-
-Describe la estructura del software: workspace de crates, modelo de documento intermedio (IR),
-pipelines de conversión, CLI y servidor MCP. Complementa a `analisis-tecnico.md` (el porqué)
-y a `plan-desarrollo.md` (el cuándo).
-
-## 1. Visión general
-
-```
-                 ┌────────────────────────── docsai-convert ──────────────────────────┐
-  .docx ─┐       │                                                                    │
-  .doc  ─┤  readers (docsai-office / docsai-odf)          writers                     │
-  .odt  ─┼──────────────►  IR (docsai-model)  ◄──────────────────────┐                │
-  .xlsx ─┤                    ▲        │                             │                │
-  .xls  ─┤                    │        ▼                             │                │
-  .ods  ─┘             parser DocMark  serializador DocMark   .docx/.xlsx/.odt/.ods   │
-                        (docsai-docmark)                             ▲                │
-                              ▲        │                             │                │
-                              │        ▼                             │                │
-                          fichero .dmk.md + assets/ ─────────────────┘                │
-                 └─────────────────────────────────────────────────────────────────────┘
-                                   ▲                          ▲
-                            docsai-cli (clap)          docsai-mcp (rmcp, stdio)
-```
-
-Regla central: **ningún conversor habla con otro conversor**. Todo pasa por el IR.
-
-## 2. Workspace de crates
-
-| Crate | Tipo | Responsabilidad | Dependencias internas |
-|---|---|---|---|
-| `docsai-model` | lib | IR + tipos comunes (`Style`, `ConversionReport`, unidades) | ninguna |
-| `docsai-docmark` | lib | Serializador y parser DocMark (IR ⇄ .dmk.md + assets) | model |
-| `docsai-office` | lib | Readers docx/xlsx/xls/doc y writers docx/xlsx | model |
-| `docsai-odf` | lib | Readers/writers odt/ods | model |
-| `docsai-convert` | lib | Orquestación: detección de formato, pipelines, gestión de assets, fallback LibreOffice, informes | todas las anteriores |
-| `docsai-cli` | bin | Binario `docsai` (subcomandos convert/inspect/roundtrip/mcp) | convert |
-| `docsai-mcp` | lib | Implementación del servidor MCP (la CLI lo arranca con `docsai mcp`) | convert |
-
-Notas:
-- Un solo binario distribuido (`docsai`); `docsai-mcp` es lib para que el subcomando `mcp`
-  viva dentro del mismo ejecutable.
-- Features de Cargo por formato (`office-doc`, `odf`, …) para poder compilar variantes mínimas.
-
-## 3. El modelo intermedio (IR) — `docsai-model`
-
-Dos raíces:
-
-```rust
-pub enum Document {
-    Text(TextDocument),
-    Workbook(Workbook),
-}
-
-pub struct TextDocument {
-    pub meta: DocumentMeta,          // título, autor, fechas, custom props, idioma
-    pub styles: StyleCatalog,        // estilos nombrados con herencia (based_on)
-    pub list_defs: ListCatalog,
-    pub sections: Vec<Section>,      // geometría de página + headers/footers + bloques
-}
-
-pub enum Block {
-    Paragraph(Paragraph),            // Vec<Inline> + ParaProps (style_id + deltas directos)
-    Heading(Heading),                // nivel de esquema + Paragraph
-    List(List),                      // árbol ya reconstruido (no pares numId/ilvl)
-    Table(Table),                    // grid con spans, col-widths, estilo
-    Image(ImageRef),                 // referencia a AssetStore + geometría/anclaje
-    TextBox(TextBox),
-    Raw(RawFragment),                // escotilla de fidelidad (formato origen + bytes XML)
-    // …
-}
-
-pub enum Inline {
-    Text(String),
-    Styled(Vec<Inline>, RunProps),   // RunProps = style_id opcional + deltas (bold, color…)
-    Link { target: String, content: Vec<Inline>, props: RunProps },
-    Footnote(Vec<Block>),
-    Field { kind: FieldKind, cached: String },
-    Break(BreakKind),
-    ImageInline(ImageRef),
-}
-
-pub struct Workbook {
-    pub meta: DocumentMeta,
-    pub styles: StyleCatalog,
-    pub defined_names: Vec<DefinedName>,
-    pub sheets: Vec<Sheet>,          // Sheet = grid dispersa de Cell + col/row props + merges
-}                                    //         + panes + images: Vec<ImageRef> (ancladas a la hoja)
-
-pub struct Cell {
-    pub value: CellValue,            // Number | Text | Bool | DateTime | Error | Empty
-    pub formula: Option<Formula>,    // texto + dialecto (Ooxml | OpenFormula) + shared/array info
-    pub num_fmt: Option<NumFmt>,
-    pub style_id: Option<StyleId>,
-}
-```
-
-### 3.1 Modelo normalizado de imágenes (`ImageRef` + `ImageGeometry`)
-
-Cada formato de entrada tiene su propio modelo gráfico (DrawingML, VML, SpreadsheetDrawingML,
-`draw:frame` ODF, Escher — ver análisis §1.4). El IR los normaliza a un único modelo, que es el
-que la spec DocMark §3.5/§4.1 serializa atributo a atributo:
-
-```rust
-pub struct ImageRef {
-    pub asset: AssetId,                  // clave en el AssetStore (hash de contenido)
-    pub geometry: ImageGeometry,
-    pub alt: String,                     // texto alternativo (accesibilidad)
-    pub title: Option<String>,
-    pub name: Option<String>,            // nombre interno del objeto (docPr @name)
-    pub link: Option<String>,            // hipervínculo sobre la imagen
-    pub external_src: Option<String>,    // imagen enlazada, no embebida
-    pub effects_raw: Option<RawId>,      // efectos DrawingML sin modelo → raw-block asociado
-}
-
-pub struct ImageGeometry {
-    pub display_size: Size,              // EMU; tamaño mostrado (≠ tamaño nativo)
-    pub native_size_px: Option<(u32, u32)>,
-    pub dpi: Option<u32>,
-    pub anchor: Anchor,
-    pub rotation_deg: f32,
-    pub flip: Flip,                      // None | H | V | HV
-    pub crop: Option<CropRect>,          // % del original por lado
-    pub border: Option<SimpleBorder>,
-    pub z_index: Option<i32>,
-}
-
-pub enum Anchor {
-    Inline,                                              // fluye con el texto
-    Floating { relative_to: RelBase,                     // Page | Margin | Paragraph | Character
-               position: HVPos,                          // offsets EMU o alineación simbólica
-               wrap: WrapMode, wrap_side: WrapSide,
-               behind_text: bool },
-    // Solo en hojas de cálculo:
-    SheetTwoCell { from: CellAnchor, to: CellAnchor,     // CellAnchor = (col,row) + offsets EMU
-                   move_with_cells: bool, size_with_cells: bool },
-    SheetOneCell { from: CellAnchor },                   // + display_size fijo
-    SheetAbsolute { pos: Point },
-}
-```
-
-Reglas del modelo:
-- Los readers **traducen a este modelo, no lo esquivan**: un atributo de imagen que un reader
-  no pueda mapear se degrada con advertencia tipada (`Warning::ImageGeometryDegraded`), y los
-  efectos irrepresentables van a raw-block vía `effects_raw` — nunca se descartan en silencio.
-- Los writers hacen la traducción inversa completa (p. ej. `Anchor::Floating` → `wp:anchor`
-  con `positionH/V`, wrap y z-order; `SheetTwoCell` → `xdr:twoCellAnchor`).
-- La conversión cruzada de anclajes (documento de texto ⇄ hoja) no existe: cada `Anchor` de
-  hoja solo es válido dentro de `Workbook` (invariante verificada por el validador del IR).
-
-### 3.2 `AssetStore`
-
-Trait que abstrae el almacenamiento de medios; `docsai-convert` aporta las implementaciones
-(directorio `assets/` en CLI, memoria/base64 en MCP):
-
-- **Deduplicación por hash de contenido**: `put(bytes) -> AssetId` devuelve el mismo id para
-  el mismo contenido; N apariciones de un bitmap comparten fichero, cada `ImageRef` conserva
-  su geometría propia.
-- **Nombres deterministas** `img-<hash8>.<ext>` (la extensión se deriva del sniffing del
-  contenido, no de la fuente) → los round-trips no duplican medios y los diffs de `assets/`
-  son estables.
-- **Manifiesto**: el store registra content-type, tamaño en bytes y dimensiones nativas
-  detectadas (crate `image`); `inspect --json` lo expone y el writer lo usa para rellenar
-  los campos obligatorios del destino sin releer ficheros.
-- **Seguridad**: nombres de asset saneados (nunca derivados de rutas internas del documento →
-  sin path traversal); las imágenes enlazadas externas no se descargan jamás.
-
-Principios del IR:
-- **Estilo = referencia + delta**, nunca formato aplanado (ver análisis §5.2).
-- **Sin dependencia de I/O**: `docsai-model` no sabe de ZIP ni XML; los `ImageRef` apuntan a un
-  `AssetStore` abstracto (trait) que materializa `docsai-convert`.
-- Todos los tipos `serde`-serializables → `inspect --json` gratis y debugging sencillo.
-- Unidades normalizadas a EMU/twips internamente con newtypes (`Length`), con conversión a
-  `pt/cm/px` solo al serializar DocMark.
-
-## 4. Contratos de conversión
-
-```rust
-pub trait DocumentReader {
-    fn detect(path: &Path, sniff: &[u8]) -> DetectScore;      // por contenido, no solo extensión
-    fn read(&self, input: &mut dyn ReadSeek, assets: &mut dyn AssetStore)
-        -> Result<(Document, ConversionReport), ReadError>;
-}
-
-pub trait DocumentWriter {
-    fn write(&self, doc: &Document, assets: &dyn AssetStore, out: &mut dyn Write)
-        -> Result<ConversionReport, WriteError>;
-}
-
-pub struct ConversionReport {
-    pub warnings: Vec<Warning>,       // tipadas: UnsupportedElement { kind, location, action }
-    pub raw_blocks_emitted: u32,      //          Degraded { what, why } · AssetIssue { … }
-    pub stats: ConversionStats,       // párrafos, celdas, imágenes, fórmulas procesadas
-}
-```
-
-- Los readers **nunca hacen pánico** con entrada corrupta: siempre `Err` tipado.
-- `ConversionReport` fluye hasta CLI (stderr legible / `--json`) y hasta la respuesta MCP.
-- El comando `roundtrip` compara IR original vs IR tras ida-y-vuelta con un **diff estructural
-  de IR normalizado** y produce una métrica de fidelidad (% nodos preservados por categoría).
-
-## 5. CLI (`docsai-cli`)
-
-```
-docsai convert <in> [-o <out>] [--to <fmt>] [--fidelity full|standard|plain]
-               [--assets-dir <dir>] [--style-map <yaml>] [--max-cells N]
-               [--use-loffice auto|never|require] [--json]
-docsai inspect <in> [--json]        # metadatos, estilos, hojas, medios, sin convertir
-docsai roundtrip <in> [--report <path>] [--json]
-docsai formats                       # matriz de soporte actual
-docsai mcp                           # servidor MCP por stdio
-```
-
-- Formato de destino inferido por extensión de `-o`, forzable con `--to`.
-- Entrada/salida por stdin/stdout soportadas (`-` como nombre) para pipelines, excepto formatos
-  binarios de salida sobre terminal (protección estándar).
-- Códigos de salida: 0 OK, 1 conversión con advertencias severas (`--strict` las hace fatales),
-  2 error de entrada, 3 formato no soportado.
-
-## 6. Servidor MCP (`docsai-mcp`)
-
-Basado en `rmcp` (SDK oficial), transporte **stdio**. Logs a stderr exclusivamente.
-
-Tools expuestas (v1):
-
-| Tool | Entrada | Salida |
-|---|---|---|
-| `convert_to_markdown` | `path` (o `content_base64` + `filename`), `fidelity`, `assets` = `inline-base64`\|`files` | DocMark (texto), assets, `report` |
-| `convert_from_markdown` | `markdown`, `target_format`, assets opcionales | fichero base64 o `path` escrito, `report` |
-| `inspect_document` | `path`/`content_base64` | JSON de estructura (mismo shape que `inspect --json`) |
-| `list_supported_formats` | — | matriz de soporte con estado por dirección |
-
-Decisiones:
-- Modo dual **path/base64**: los clientes MCP locales (Claude Desktop/Code) pasan rutas; los
-  remotos pueden pasar contenido embebido. Límite de tamaño configurable con variable de entorno.
-- Respuestas grandes: DocMark como `text content`; binarios como recurso base64 con MIME correcto.
-- El servidor es sin estado; cada tool call es una conversión independiente (sin ficheros
-  temporales persistentes salvo que el cliente pida `assets=files`).
-
-## 7. Multiplataforma y distribución
-
-- Sin dependencias de sistema en el camino principal (pure Rust). `soffice` se busca en runtime
-  en ubicaciones estándar por SO solo para `.doc`.
-- CI: GitHub Actions, matriz ubuntu/windows/macos; artefactos de release con `cargo-dist`
-  (tar.gz/zip + instaladores shell/powershell; opcional: Homebrew tap, Scoop/winget, cargo-binstall).
-- Targets: `x86_64-unknown-linux-gnu`, `aarch64-unknown-linux-gnu`, `x86_64-pc-windows-msvc`,
-  `aarch64-apple-darwin`, `x86_64-apple-darwin`. LTO + `strip` en release.
-
-## 8. Rendimiento (presupuestos orientativos)
-
-- docx de 100 páginas → DocMark: < 1 s en hardware corriente.
-- xlsx de 100k celdas: < 3 s y < 500 MB de RAM (evitar clonar sharedStrings; usar `Cow`).
-- Los readers hacen streaming donde el crate lo permita (calamine es lazy por hoja).
-- Benchmarks con `criterion` sobre el corpus a partir de la Fase 8; regresiones > 20 % bloquean PR.
diff --git a/docs/development-plan.md b/docs/development-plan.md
new file mode 100644
index 0000000..c53792e
--- /dev/null
+++ b/docs/development-plan.md
@@ -0,0 +1,335 @@
+# Development plan
+
+Phased plan to implement `docsai`. Each phase has an objective, tasks, deliverables,
+acceptance criteria, and an indicative estimate (in person-weeks for a senior Rust
+developer; adjust for team size). Phases 1–3 are the heart of the product; from
+Phase 6 there is room to parallelize.
+
+**Management rule**: a phase is not opened until the previous phase's acceptance criteria
+are closed (except those marked parallelizable). Each phase ends with a `v0.x.0` tag.
+
+---
+
+## Phase 0 — Foundations (2–3 weeks)
+
+**Objective**: compiling workspace, designed IR, frozen DocMark specification, initial corpus,
+and green multiplatform CI. This is the phase that de-risks everything else.
+
+Tasks:
+1. Create the Cargo workspace with the 7 crates from `architecture.md` §2 (even if nearly empty).
+2. Implement `docsai-model` v1: IR types (architecture §3), `StyleCatalog` with
+   inheritance, `ConversionReport`, unit newtypes (`Length` with EMU/twips/pt/cm).
+   Includes the **normalized image model** `ImageRef`/`ImageGeometry`/`Anchor`
+   (architecture §3.1) with its invariant validator (sheet anchors only in `Workbook`),
+   and the `AssetStore` trait (architecture §3.2). Everything `serde`-serializable, with unit
+   tests for unit conversions (EMU⇄pt⇄cm⇄px at 96 dpi).
+3. **Risk spike R1** (1-week timebox): read three real docx documents with custom styles
+   using `docx-rs` + `quick-xml` and verify that the 4-level cascade is resolvable with the
+   information exposed. Result written under `docs/spikes/` with a decision: crate + custom
+   complement, or full custom OOXML parser.
+4. Freeze `docmark-specification.md` v1.0 (team review, resolve the TODOs in annex A
+   on complex tables).
+5. Initial corpus in `corpus/`: ~15 minimal hand-made documents (one trait per file):
+   `docx/basic-text`, `basic-styles`, `nested-lists`, `table-simple`, `table-merged`,
+   `images-inline`, `images-floating` (wrap + position relative to page/margin),
+   `images-transformed` (crop, rotation, flip, scale ≠ 100 %), `images-duplicated`
+   (same bitmap N times with different geometries), `headers-footers`, `footnotes`,
+   `custom-styles`; `xlsx/values-types`, `formulas-basic`, `formulas-shared`,
+   `number-formats`, `merged-cells`, `images-anchored` (all three anchors: two-cell,
+   one-cell, absolute).
+   Script of how each was created in `corpus/README.md`.
+6. GitHub Actions CI: build+test+clippy+fmt on a 3-OS matrix; cargo cache; badge in README.
+7. CLI skeleton (`docsai formats`, `--version`) and `insta` template for golden tests.
+
+Deliverables: green workspace in CI, `docsai-model` v1, frozen spec, corpus v1, spike report.
+
+Acceptance criteria:
+- [x] `cargo test --workspace` green on all 3 platforms.
+- [x] IR serializes/deserializes to JSON with identical round-trip (basic proptest).
+- [x] Spike documented with a signed decision on the docx strategy.
+- [x] DocMark v1.0 with no open TODOs.
+
+**Status**: closed. Execution notes:
+- Spike R1 (`docs/spikes/R1-docx-strategy.md`) discarded `docx-rs`: it loses almost the entire
+  image model, footnotes and simple fields, and panics on 23 % of corrupt
+  inputs. docx reading is done with a custom parser over `zip` + `quick-xml`.
+- The corpus is **generated** with `corpus/generate.py` instead of drawn by hand: the XML is
+  reviewable in the diff and packages are byte-for-byte reproducible (see `corpus/README.md`).
+- Golden files are `.expected.dmk.md` next to the corpus, as prescribed by `AGENTS.md` §6, instead
+  of `insta` snapshots; `insta` leaves the dependency tree.
+
+---
+
+## Phase 1 — DOCX reading → DocMark (4–6 weeks)
+
+**Objective**: `docsai convert x.docx -o x.dmk.md` with styles, images, tables, lists,
+headers/footers and properties. This is the longest phase: it sets the patterns reused by all others.
+
+Tasks:
+1. docx reader (`docsai-office`): ZIP open, `document.xml`, relationship resolution.
+2. Styles: full parse of `styles.xml` → `StyleCatalog`; reference+delta resolution
+   (never flatten); document defaults (`docDefaults`).
+3. Paragraphs and runs: all inline formatting from spec table §3.2; hyperlinks; breaks.
+4. Lists: tree reconstruction from `numbering.xml` + `(numId, ilvl)` pairs → `ListCatalog`.
+5. Tables: grid, `gridSpan`/`vMerge` → IR rowspan/colspan, widths, table style.
+6. Images (spec §3.5, architecture §3.1): DrawingML `wp:inline` and `wp:anchor` → `ImageRef` +
+   extraction to `AssetStore` with hash deduplication. Full geometry mapping: displayed vs native
+   size, relative position (page/margin/paragraph/character) with offsets or
+   symbolic alignment, wrap and side, z-order/behind-text, rotation, flips, crop
+   (`a:srcRect`), simple border, alt/title/name, hyperlink on image, linked
+   images (`r:link`, no download). Also read **legacy VML** (`w:pict`) limited
+   to the normalized model. DrawingML effects without a model → associated raw-block (`effects_raw`).
+   WMF/EMF extracted as-is with full geometry and a warning.
+7. Headers/footers/sections (`sectPr`), footnotes/endnotes, simple fields (PAGE, TOC as
+   raw/field), document properties (core+app+custom).
+8. DocMark serializer (`docsai-docmark`): IR → Markdown per spec §8 (deterministic); asset
+   management and front matter; `--fidelity` modes.
+9. Every unrecognized OOXML element → raw-block + typed warning (measurable coverage).
+10. Golden tests for the whole docx corpus; add 5+ anonymized "real-world" documents.
+
+Acceptance criteria:
+- [x] Corpus docx goldens pass (including the three image ones: floating,
+      transformed and duplicated — with full geometry in DocMark attributes).
+- [x] Zero panics on synthetic corrupt corpus (truncated ZIP, malformed XML): always `Err`.
+- [x] A real 50+ page docx converts in < 1 s with < 10 raw-blocks.
+- [x] Output in `--fidelity plain` is clean CommonMark verified with comrak.
+
+**Status**: closed except task 10 (anonymized real documents), which depends on having
+real documents available and does not block Phase 2. Execution notes:
+- DrawingML text boxes (`wps:txbx`) are preserved as raw-block, not as
+  `::: {.textbox}`: the type exists in the IR and the spec, but emitting it is deferred to Phase 2,
+  where the writer will need to reconstruct them.
+- Three defects the corpus uncovered and that are now fixed: length formatting was
+  crippled by rounding (a 1417-twip margin was written as `2.499cm`), empty paragraphs
+  silently disappeared, and a hyperlink's character style was emitted twice.
+
+---
+
+## Phase 2 — DocMark → DOCX writing + round-trip (3–5 weeks)
+
+**Objective**: close the bidirectional text cycle and stand up the fidelity infrastructure.
+
+**Status: core delivered.** Hand-written DocMark parser, OOXML writer, bidirectional
+`convert`, and CLI `roundtrip` are in tree. Remaining work is fidelity polish
+(floating DrawingML, full footnote parts, corpus-wide idempotence, proptest IR
+generators) rather than scaffolding.
+
+Tasks:
+1. [x] DocMark parser (`docsai-docmark`): hand-written mirror of the serializer for
+   `{...}` attributes and fenced divs `:::` → IR. Front-matter validation with useful
+   line errors. (Comrak remains available for plain-fidelity paths later.)
+2. [x] docx writer: IR → `document.xml` + `styles.xml` + `numbering.xml` + media + props
+   via direct ZIP/XML. Re-injection of `format=ooxml` raw-blocks; inline DrawingML images
+   from the `AssetStore` without recompression. Floating anchors currently degrade to
+   inline with a warning.
+3. [x] `roundtrip` command: docx→md→docx→md with identity check and `--json` report.
+4. [ ] **Serializer idempotence** test in CI: `serialize(parse(md)) == md` byte for byte
+   over all goldens (unit coverage exists for basic-text / basic-styles).
+5. [ ] Property testing (proptest): generate valid random IRs and verify IR→md→IR == identity.
+6. [ ] External validation: generated docx open without a repair dialog in Word and LibreOffice
+   (manual checklist documented per release; later automatable via headless LibreOffice on Linux CI).
+
+Acceptance criteria:
+- [x] Idempotent round-trip on `basic-text` (CLI + pipeline test).
+- [ ] Idempotent round-trip (2nd pass == 1st pass) on the whole corpus.
+- [ ] Fidelity metric ≥ 95 % on text/styles/tables/lists of the corpus.
+- [x] Images rewrite without recompression (bytes from `AssetStore`); geometry for inline
+      images preserved. Floating wrap/position still partial.
+- [ ] Generated docx open cleanly in Word and LibreOffice (checklist).
+- [x] Hand-editing a `.dmk.md` and regenerating docx works (`convert` DocMark → Docx).
+
+---
+
+## Phase 3 — Spreadsheets: XLSX/XLS ⇄ DocMark (4–5 weeks)
+
+**Objective**: bidirectional `xlsx` with values, formulas and formats; `xls` reading.
+
+Tasks:
+1. **Spike (3 days)**: decide xlsx writer — `umya-spreadsheet` (reads and writes styles) vs
+   `rust_xlsxwriter` (better pure-write API). Criterion: which regenerates with higher fidelity
+   styles+numFmt from the IR. Document in `docs/spikes/`.
+2. xlsx reader: `calamine` for values and formulas; complementary custom reading of
+   `xl/styles.xml` (numFmt, fonts, fills, borders by index) and of dimensions/merges/panes
+   with `quick-xml`. Shared and array formulas expanded with metadata.
+3. Cell typing: date/time detection via numFmt (serial→ISO-8601 and back); booleans,
+   errors (`#DIV/0!`…).
+4. Sheet serialization to DocMark per spec §4 (value table + `cell-meta` with compacted
+   ranges) and reverse parser.
+5. xlsx writer from IR (crate chosen in the spike): values, formulas (recalc delegated to
+   Excel/LibreOffice on open: write formula without cached value or with the preserved value),
+   numFmt, styles, merges, widths, defined names.
+6. **Sheet images** (spec §4.1): custom reading of `xl/drawings/drawing*.xml` with
+   `quick-xml` (calamine/umya do not cover them with full geometry) → `ImageRef` with anchors
+   `SheetTwoCell`/`SheetOneCell`/`SheetAbsolute`, in-cell offsets,
+   `move-with-cells`/`size-with-cells`, and the rest of the common model (rotation, crop, alt,
+   hyperlink). Writing of `drawing*.xml` + relationships from the IR. Native charts →
+   raw-block with warning.
+7. xls reader (calamine) → same pipeline (read-only; document in `formats`).
+8. Corpus: add workbooks with dates, percentages, currencies, cross-sheet formulas, defined
+   names, images with all three anchor types, 100k cells (performance).
+
+Acceptance criteria:
+- [ ] xlsx round-trip: values, formulas and numFmt intact on the corpus (fidelity ≥ 95 %).
+- [ ] Sheet image round-trip: all three anchors preserved symbolically (two-cell
+      still stretches with the grid after the round trip), bitmaps without recompression.
+- [ ] An xlsx with dates survives round-trip without corrupting serials (dedicated test).
+- [ ] 100k-cell xlsx: < 3 s, < 500 MB RAM.
+- [ ] Excel and LibreOffice recalculate generated files without errors (checklist).
+
+---
+
+## Phase 4 — ODF: ODT and ODS ⇄ DocMark (3–4 weeks) — *parallelizable with Phase 5*
+
+**Objective**: LibreOffice parity with the already-supported OOXML formats.
+
+Tasks:
+1. Custom ODT reader/writer (`docsai-odf`, `zip`+`quick-xml`): content/styles/meta;
+   **de-automatization** of automatic styles on read (→ deltas) and regeneration on write.
+2. ODT images: `<draw:frame>/<draw:image>` + `Pictures/*` → same `ImageGeometry` model
+   (`as-char/char/paragraph/page` anchors → `Inline`/`Floating`; `svg:x/y/width/height`,
+   `style:wrap`, rotation and `fo:clip`); reverse write with ODF graphic styles.
+3. ODS reader with `calamine` (values/formulas) + custom styles; ODS writer with
+   `spreadsheet-ods` (evaluate in a mini-spike; if it falls short, custom writer). ODS sheet
+   images (`draw:frame` anchored to cell/sheet) mapped to the same IR sheet anchors.
+4. OpenFormula formulas: keep dialect (`formula-dialect=openformula`); do NOT translate yet.
+5. ODF corpus mirroring OOXML (same traits, including image documents),
+   generated with LibreOffice.
+6. Scope note: cross conversion docx⇄odt "works" via the IR, but raw-blocks of one
+   dialect are dropped with a warning in the other. Document in README.
+
+Acceptance criteria:
+- [ ] odt and ods round-trip on ODF corpus with fidelity ≥ 90 % (including image
+      geometry: size, position, anchor and wrap).
+- [ ] docx→DocMark→odt produces a correct document for the basic corpus (common traits).
+
+---
+
+## Phase 5 — Legacy DOC (2–3 weeks) — *parallelizable with Phase 4*
+
+**Objective**: `.doc` reading with the two-level strategy from the analysis (§1.3).
+
+Tasks:
+1. Runtime LibreOffice detection per OS (standard paths + PATH); flag
+   `--use-loffice auto|never|require`; conversion `soffice --headless --convert-to docx` in a
+   sandboxed temporary directory and re-entry through the Phase 1 docx pipeline.
+2. Degraded native extractor: `cfb` + FIB + piece table → text with paragraphs and basic
+   properties; extraction of embedded images (BLIPs from the Escher/OfficeArt stream) to the
+   `AssetStore` — without fine geometry: emitted with `anchor=inline` and native size, with
+   `ImageGeometryDegraded` warning. Mark output as degraded in the `ConversionReport`.
+3. Clear messaging: if LibreOffice is missing, the user knows exactly what is being lost and how
+   to improve the result.
+4. Tests: `.doc` corpus generated by saving the docx corpus as .doc with Word/LibreOffice.
+
+Acceptance criteria:
+- [ ] With LibreOffice installed: fidelity equivalent to the docx path.
+- [ ] Without LibreOffice: full text and correct paragraph structure, no panics.
+- [ ] Encrypted/protected `.doc` rejected with a clear error.
+
+---
+
+## Phase 6 — Full CLI and distribution (2–3 weeks)
+
+**Objective**: product experience: the definitive CLI and installable binaries on 3 OSes.
+
+Tasks:
+1. Final CLI per `architecture.md` §5: `convert`, `inspect`, `roundtrip`, `formats`;
+   `--json`, `--strict`, stdin/stdout, exit codes; `--style-map` (mammoth mode, spec §5).
+2. Polished error messages and warnings (with `miette` or similar for nice diagnostics);
+   `--verbose`/`RUST_LOG`.
+3. Batch processing: `docsai convert *.docx --out-dir md/` with parallelism (`rayon`) and
+   aggregated summary.
+4. `cargo-dist`: automatic releases per tag with signed binaries for the 5 targets;
+   shell/powershell installers; Homebrew/Scoop formulas; crates.io publication.
+5. User documentation: definitive README with real examples, carefully written `--help`,
+   CHANGELOG (keep-a-changelog).
+
+Acceptance criteria:
+- [ ] Installation on a clean machine of each OS with one command and a successful test conversion.
+- [ ] `docsai convert` over a folder with 100 mixed documents finishes with a correct summary.
+- [ ] All foreseeable user errors have an actionable message (written UX review).
+
+---
+
+## Phase 7 — MCP server (2 weeks)
+
+**Objective**: `docsai mcp` operational with real clients.
+
+Tasks:
+1. Implement `docsai-mcp` with `rmcp` (stdio): the 4 tools from `architecture.md` §6 with documented
+   JSON schemas and input validation.
+2. Path mode and base64 mode; size limits; timeouts; inline assets vs files.
+3. Clean-stdout guarantee: automatic test that no code path writes to stdout outside
+   the protocol (logs → stderr).
+4. Integration tests with MCP Inspector and real Claude Desktop/Claude Code; configuration
+   recipes in README.
+5. Consider (backlog, non-blocking): `apply_edits` tool for guided document editing via
+   DocMark in the future.
+
+Acceptance criteria:
+- [ ] A real MCP client converts docx→markdown and markdown→docx end to end.
+- [ ] Malformed inputs return correct MCP errors, never hang the server.
+- [ ] Session of 100 consecutive conversions with no memory leaks or orphan temporary files.
+
+---
+
+## Phase 8 — Hardening and quality (2–3 weeks, partially continuous)
+
+**Objective**: production robustness.
+
+Tasks:
+1. Fuzzing with `cargo-fuzz` of the 4 input parsers (docx, xlsx, odf, docmark); fuzzing
+   corpus seeded with the test corpus; run on scheduled CI (weekly cron).
+2. Adversarial document suite: ZIP bombs (decompression limits), XML entity expansion
+   (verify quick-xml does not expand external entities), malicious asset paths
+   (path traversal in media names), extreme sizes.
+3. `criterion` benchmarks + performance budget in CI (regression > 20 % blocks).
+4. `cargo audit`/`cargo deny` in CI (licenses + vulnerabilities); informative `cargo bloat`.
+5. Expand corpus with varied real documents (reports, corporate templates, financial
+   sheets) and publish the **fidelity matrix** by trait in the documentation.
+6. Security review: the MCP server never writes outside the indicated directories;
+   path normalization; no execution of document content (macros ALWAYS ignored —
+   `.docm/.xlsm` are read as their macro-free equivalents, with a warning).
+
+Acceptance criteria:
+- [ ] 72 h of accumulated fuzzing without crashes on the 4 parsers.
+- [ ] Full adversarial suite green.
+- [ ] Fidelity matrix published and ≥ per-phase targets.
+
+---
+
+## Phase 9 — v1.0 and post-1.0 backlog (1 week + continuous)
+
+**v1.0 close**: freeze stable CLI and DocMark 1.0 format, release notes, announcement.
+
+Prioritized post-1.0 backlog (not committed):
+- OOXML ⇄ OpenFormula formula dialect translation (risk R5).
+- PowerPoint (`.pptx`/`.odp`) → read-only DocMark.
+- WMF/EMF → PNG/SVG conversion (`emf` crate / custom library or fallback).
+- Comments and track changes (`w:ins`/`w:del`) as DocMark extensions (CriticMarkup syntax).
+- Incremental MCP edit tool (`apply_edits`).
+- Library mode: publish `docsai-convert` as a stable crate for third parties + WASM bindings.
+- `.doc`/`.xls` writing via LibreOffice fallback if demand warrants it.
+
+---
+
+## Schedule summary (indicative, 1 senior developer)
+
+| Phase | Duration | Cumulative |
+|---|---|---|
+| 0 Foundations | 2–3 wk | 3 |
+| 1 DOCX reading | 4–6 wk | 9 |
+| 2 DOCX writing + round-trip | 3–5 wk | 14 |
+| 3 XLSX/XLS | 4–5 wk | 19 |
+| 4 ODF | 3–4 wk | 22* |
+| 5 DOC | 2–3 wk | 22* (*parallel 4‖5 with 2 devs) |
+| 6 CLI + distribution | 2–3 wk | 25 |
+| 7 MCP | 2 wk | 27 |
+| 8 Hardening | 2–3 wk | 30 |
+| 9 v1.0 | 1 wk | ~31 wk (~7 months; ~5–5.5 with 2 devs from Phase 3) |
+
+## Project tracking metrics
+
+- **Fidelity per category** (`roundtrip` command on corpus): target ≥ 95 % OOXML, ≥ 90 % ODF.
+- **Raw-blocks per real corpus document**: downward trend per phase.
+- **Test coverage** of library crates ≥ 80 %.
+- **Performance**: budgets from `architecture.md` §8 in CI.
diff --git a/docs/docmark-specification.md b/docs/docmark-specification.md
new file mode 100644
index 0000000..ef561ba
--- /dev/null
+++ b/docs/docmark-specification.md
@@ -0,0 +1,416 @@
+# DocMark Specification v1.0
+
+**DocMark** is the extended Markdown profile used by `docsai` as its textual pivot format.
+Goal: represent text documents (docx/odt/doc) and spreadsheets (xlsx/xls/ods) in a way that is
+**readable, hand-editable, and rich enough to regenerate the original document with minimal
+loss**.
+
+Status: **frozen (v1.0)** at the close of Phase 0. Any later change bumps the version declared
+in the front matter and requires documenting the migration (`AGENTS.md` §2).
+
+Annex A (complex tables) is resolved in §3.4. Draft TODOs are closed; additions made explicit by
+the Phase 1 implementation are marked in the text and collected in §10.
+
+## 0. Principles
+
+1. **Downward compatibility**: a DocMark file is valid CommonMark+GFM. A viewer that ignores
+   attributes and containers still shows a useful document.
+2. **Pandoc attribute syntax**: `{#id .class key="value"}` — no new syntax is invented where
+   Pandoc already has one.
+3. **Everything non-representable is preserved**, never discarded: the `raw-block` mechanism
+   (§7).
+4. **Determinism**: two serializations of the same IR produce identical bytes (required for
+   golden tests and round-trip idempotence). Line endings are always `\n`, UTF-8 without BOM.
+
+## 1. File conventions
+
+- Recommended extension: `.dmk.md` (double extension: editors treat it as Markdown).
+- One text document ⇒ one file. One workbook ⇒ one file with one H1 section per sheet.
+- Media are extracted to a sibling `assets/` directory (configurable with `--assets-dir`).
+
+## 2. Front matter (YAML)
+
+Initial YAML block delimited by `---`. Defined fields:
+
+```yaml
+---
+docmark: "1.0"                  # version of this specification (required)
+source-format: docx             # docx | doc | odt | xlsx | xls | ods (required when converting)
+title: "Annual Report"          # docProps / meta.xml
+author: "Ana Perez"
+created: 2026-03-01T10:00:00Z
+modified: 2026-07-15T09:30:00Z
+language: en-US
+custom-properties:              # document custom properties, as-is
+  Department: "Sales"
+
+page:                           # default page / section geometry (text documents)
+  size: A4                      # or explicit width/height
+  margins: { top: 2.5cm, bottom: 2.5cm, left: 3cm, right: 3cm }
+  orientation: portrait
+
+style-defaults:                 # OOXML `w:docDefaults`: the base of the cascade
+  font: { name: "Calibri", size: 11pt }
+  paragraph: { space-after: 8pt }
+
+styles:                         # style catalog from the original document (§3)
+  Heading1:
+    type: paragraph
+    based-on: Normal
+    font: { name: "Calibri Light", size: 16pt, color: "#2E74B5", bold: true }
+    paragraph: { space-before: 12pt, space-after: 4pt, keep-with-next: true }
+  Emphatic:
+    type: character
+    font: { italic: true, color: "#C00000" }
+
+list-definitions:               # numbering.xml / normalized ODF list styles
+  L1:
+    levels:
+      - { format: decimal, text: "%1.", indent: 0.63cm }
+      - { format: lowerLetter, text: "%2)", indent: 1.27cm }
+---
+```
+
+Rules:
+- Keys in kebab-case. Explicit units (`px`, `cm`, `pt`, `emu`, `%`); colors `#RRGGBB`.
+- **Unit rule (normative)**: the serializer chooses the **first unit that represents the length
+  exactly**, in the order `px` (at 96 dpi) → `cm` → `pt` → `emu`. Readability yields to exactness:
+  a Word margin of 1417 twips is written `70.85pt`, never an approximate `2.499cm`, because
+  rounding would shift the margin on every round-trip. `emu` is the final escape hatch and always
+  exists.
+- The `styles` block is a **catalog**: the body references styles by name via classes
+  (`{.Heading1}`); the inverse writer uses it to regenerate `styles.xml` / ODF `styles.xml`.
+- Unknown fields are preserved (parsers must not reject them): forward-compatible.
+
+## 3. Text blocks
+
+### 3.1 Headings and paragraphs
+
+```markdown
+# Chapter title {.Heading1}
+
+A normal paragraph (default style, no attributes).
+
+Paragraph with style and direct formatting. {.Quote align=center space-after=12pt}
+```
+
+- The `#` level reflects the outline level; the class indicates the actual style.
+- Paragraph attributes go in `{...}` **at the end of the block**: `align`,
+  `indent-left`, `indent-right`, `indent-first-line`, `indent-hanging`,
+  `space-before`, `space-after`, `line-height`, `background`, `keep-with-next`,
+  `page-break-before`, `outline-level`.
+- An **empty** paragraph is real content (documents are spaced that way) and a blank line cannot
+  represent it, because Markdown absorbs it: in `full` mode it is written `[]{.empty}`.
+  `standard` and `plain` modes discard it, which is exactly what they promise (§6).
+- Economy rule: if formatting matches exactly what the style defines, redundant attributes are
+  **not** emitted (keeps Markdown clean and diffs stable).
+
+### 3.2 Inline formatting
+
+| Original | DocMark |
+|---|---|
+| bold / italic / strikethrough | `**x**`, `*x*`, `~~x~~` (native GFM) |
+| underline | `[text]{.underline}` |
+| color, highlight, font, size | `[text]{color="#FF0000" highlight="yellow" font="Arial" size=14pt}` |
+| character style | `[text]{.Emphatic}` |
+| sub/superscript | `[x]{.sub}` / `[x]{.sup}` |
+| small caps / all caps | `[x]{.small-caps}` / `[x]{.caps}` |
+| non-simple underline | `[x]{.underline underline=double}` (values: `double`, `thick`, `dotted`, `dashed`, `wave`) |
+| formatting turned off over a style | `[x]{bold=false}` / `[x]{italic=false}` |
+| manual line break | trailing double space (hard break) |
+| page or column break | `[]{.break kind=page}` / `[]{.break kind=column}` |
+| hyperlink | `[text](https://...)` — with attributes if styled: `[text](url){.Hyperlink}` |
+| footnote | `[^1]` + definition at the end (Pandoc/GFM footnotes syntax) |
+| dynamic field | `[value]{.field field=PAGE}`, with `instr="…"` in `full` mode |
+
+### 3.3 Lists
+
+Standard Markdown lists; typographic definition lives in `list-definitions` and is referenced on
+the first item when it is not the default list:
+
+```markdown
+1. First point {.ListParagraph list=L1}
+2. Second point {.ListParagraph}
+   1. Sub-point (the real marker is defined by L1 level 2) {.ListParagraph list=L1}
+```
+
+- `list=` travels **inside the first item's attribute block**, not in a separate block: an item
+  never carries two `{...}`.
+- Nested lists are written *tight* (no blank line between the item and its sublist) so a
+  CommonMark viewer does not wrap each item in a `<p>`.
+- The ordinal marker written is `1.`, `2.`… The real presentation marker is defined by the
+  corresponding level of `list-definitions`.
+
+### 3.4 Tables (text documents)
+
+GFM tables when they are regular. A table with merged cells, fixed widths, or a table style is
+wrapped in a container that supplies the metadata:
+
+```markdown
+::: {.table style=TableGrid col-widths="3cm,5cm,5cm"}
+| Concept | T1 | T2 |
+|---|---|---|
+| Sales {rowspan=2} | 100 | 200 |
+| | 300 | 400 |
+:::
+```
+
+- `rowspan`/`colspan` on the **first cell** of the merged area; absorbed cells are left empty.
+- The container accepts `style`, `col-widths`, and `header-row=false`. GFM requires a header row:
+  when the original had none, an empty row is emitted and `header-row=false` records that, so the
+  round-trip does not invent a header.
+- If the structure exceeds what GFM can represent (nested tables, multi-paragraph cells), the
+  full table is emitted as a `::: {.table complex=true}` container with rows and cells as
+  sub-blocks:
+
+````markdown
+::: {.table complex=true style=TableGrid}
+::: {.row}
+::: {.cell rowspan=2}
+First paragraph of the cell.
+
+Second paragraph of the same cell.
+:::
+::: {.cell}
+Another cell.
+:::
+:::
+:::
+````
+
+  Complex format rules: one `::: {.row}` per row, one `::: {.cell}` per cell **including
+  absorbed ones** (which are empty), `colspan`/`rowspan` on the cell that opens the area, and
+  inside each cell any valid DocMark block. This closes draft annex A.
+
+### 3.5 Images and objects
+
+Every image is extracted to `assets/` and referenced with standard Markdown image syntax plus a
+normalized set of attributes that capture the original's full geometry (size, position, anchor,
+crop, rotation…). The same attribute model applies in text documents and spreadsheets (§4.1).
+
+```markdown
+Inline image (flows with the text):
+
+![Sales diagram](assets/img-3f2a91.png){width=450px height=300px title="Figure 1"}
+
+Floating image with position and text wrap:
+
+![Logo](assets/img-9c04b7.png){#img-logo width=3.5cm height=3.5cm
+  anchor=floating relative-to=margin x=1.2cm y=0.5cm
+  wrap=square wrap-side=right z-index=2
+  rotation=0 crop="0,0,10%,0" native-size=800x800 dpi=300
+  name="Corporate logo" link="https://example.com"}
+```
+
+**Normalized image attributes** (inapplicable ones are omitted; units explicit):
+
+| Attribute | Meaning | Typical origin |
+|---|---|---|
+| `width`, `height` | **Displayed** size (always required) | `wp:extent`, `svg:width/height` |
+| `native-size` | Pixel dimensions of the original bitmap (`AxB`) | file header |
+| `dpi` | Declared resolution, if other than 96 | bitmap metadata |
+| `anchor` | `inline` (default) \| `floating` \| `behind` \| `front` | `wp:inline`/`wp:anchor`, `text:anchor-type` |
+| `relative-to` | Horizontal position reference: `page` \| `margin` \| `paragraph` \| `character` \| `line` \| `column` | `wp:positionH @relativeFrom` |
+| `relative-to-v` | Vertical reference, **only if it differs** from `relative-to` | `wp:positionV @relativeFrom` |
+| `x`, `y` | Offsets from the reference (floating only) | `wp:posOffset`, `svg:x/y` |
+| `align-h`, `align-v` | Symbolic alignment (`left/center/right`, `top/middle/bottom`) when the original uses alignment instead of offset | `wp:align` |
+| `wrap` | `square` \| `tight` \| `through` \| `top-bottom` \| `none` | `wp:wrapSquare…`, `style:wrap` |
+| `wrap-side` | `both` \| `left` \| `right` \| `largest` | `@wrapText` |
+| `z-index` | Stacking order among floating objects | `@relativeHeight` |
+| `rotation` | Degrees clockwise | `a:xfrm @rot` |
+| `flip` | `h` \| `v` \| `hv` | `a:xfrm @flipH/V` |
+| `crop` | Crop `"left,top,right,bottom"`, all four sides with `%` suffix | `a:srcRect`, `fo:clip` |
+| `border` | Simple border `"1pt solid #000000"` (complex borders → raw) | `pic:spPr` |
+| `name` | Internal object name in the document | `wp:docPr @name` |
+| `title` | Title/caption | `wp:docPr @title` |
+| `link` | Hyperlink on the image | `a:hlinkClick` |
+| `external-src` | Original URL if the image was **linked**, not embedded | `r:link`, `xlink:href` |
+| `render` | `unsupported` for formats a Markdown viewer cannot draw (WMF/EMF) | content sniffing |
+| `effects-raw` | Id of the raw-block holding non-representable effects | `a:effectLst`, `a:scene3d` |
+
+Rules:
+- Alternative text (accessibility, `wp:docPr @descr` / `svg:desc`) goes in the standard Markdown
+  alt field `![…]`, not in an attribute — so every viewer shows it.
+- File name: `img-<hash8>.<ext>` (content hash → stable across conversions and with
+  deduplication: N appearances of the same bitmap share a file, each with its own geometry
+  attributes).
+- `width`/`height` are **always** required in serialization even when they match native size:
+  the round-trip must not depend on re-reading the bitmap.
+- WMF/EMF are extracted with their original extension and full geometry; the serializer adds
+  `render=unsupported` as a hint for viewers (warning in the report).
+- Image effects with no representation (shadows, bevels, DrawingML 3D styles) are preserved as a
+  raw-block associated via `effects-raw=<id>` referencing a contiguous `::: {.raw}`.
+- Non-image objects (OLE, SmartArt, embedded charts): extracted to `assets/` and referenced as
+  `![...](assets/obj-xxx.bin){.embedded-object content-type="..."}`, plus a warning in the
+  report.
+
+### 3.6 Sections, headers and footers, text boxes
+
+```markdown
+::: {.header scope=default}
+Header text — page [n.]{.field field=PAGE}
+:::
+
+::: {.section columns=2 page-size=A4 orientation=landscape}
+… section content …
+:::
+
+::: {.textbox x=5cm y=2cm width=6cm}
+Text box content.
+:::
+```
+
+Dynamic fields (page number, date, TOC) are represented as `{.field field=...}` spans with their
+last known value as visible text.
+
+## 4. Spreadsheets
+
+Each sheet is a `#` section with a metadata container; data go in a GFM table.
+**Golden rule: the cell shows the value; the formula and format travel in metadata.**
+
+```markdown
+---
+docmark: "1.0"
+source-format: xlsx
+workbook:
+  active-sheet: Sales
+  defined-names:
+    TOTAL_ANNUAL: "Sales!$D$10"
+---
+
+# Sales {.sheet cols="A:D" col-widths="12,9,9,11" frozen="A2"}
+
+| | A | B | C | D |
+|---|---|---|---|---|
+| **1** | Product | T1 | T2 | Total |
+| **2** | Widgets | 100 | 200 | 300 |
+| **3** | Gadgets | 150 | 250 | 400 |
+
+::: {.cell-meta}
+- D2: formula="SUM(B2:C2)" num-fmt="#,##0"
+- D3: formula="SUM(B3:C3)" num-fmt="#,##0"
+- A1:D1: style=HeaderRow
+- B2:D3: type=number num-fmt="#,##0"
+:::
+```
+
+Rules:
+- First column/row of the table = coordinates (generated, bold); they let the `cell-meta` block
+  use readable A1 references.
+- `cell-meta` accepts ranges (`B2:D3`) to compact repeated metadata; the parser expands them.
+- `formula` is stored **without** a leading `=` and in the original dialect; `formula-dialect:
+  openformula` is added when the source is ODS.
+- Cell types: `number | text | bool | date | error` (+ `num-fmt` with the format code).
+  Dates are shown in the table as ISO-8601 and restored as serial+format on write.
+- Merged cells: `A5:C5: merge=true` (the value lives in the top-left cell).
+- Cell styles (font, border, fill) are catalogued in front-matter `styles:` and referenced with
+  `style=`.
+- Huge sheets: by default the full used range is dumped; `--max-cells` allows truncating
+  **only in unidirectional mode** (never when preparing a round-trip; truncating invalidates the
+  return trip).
+
+### 4.1 Images in spreadsheets
+
+Sheets also carry images (logos, screenshots, diagrams) anchored to the grid. They are declared
+in a `sheet-images` block at the end of each sheet, using the same syntax and image attributes
+from §3.5 plus spreadsheet-specific anchor attributes:
+
+```markdown
+::: {.sheet-images}
+![Company logo](assets/img-9c04b7.png){anchor=two-cell
+  from="B2" from-offset="12px,3px" to="D8" to-offset="0,0" move-with-cells=true size-with-cells=false}
+
+![Signature](assets/img-11ab42.png){anchor=one-cell from="F20" from-offset="0,0" width=180px height=60px}
+
+![Watermark](assets/img-77cd01.png){anchor=absolute x=5cm y=8cm width=10cm height=10cm}
+:::
+```
+
+Rules:
+- `anchor` on sheets: `two-cell` (cell to cell; the image moves/stretches with the grid,
+  according to `move-with-cells`/`size-with-cells`) | `one-cell` (origin cell + fixed size) |
+  `absolute` (absolute position). They correspond to OOXML `xdr:twoCellAnchor`/`oneCellAnchor`/
+  `absoluteAnchor` and to ODF cell/sheet anchors.
+- In `two-cell`, `width`/`height` are **not serialized** (size is defined by the grid); in
+  `one-cell` and `absolute` they are required, as in §3.5.
+- `from`/`to` use A1 references; offsets within the cell go in `from-offset`/`to-offset`.
+- Remaining properties (rotation, crop, alt, hyperlink, `native-size`…) work the same as in
+  §3.5.
+- Native sheet charts are not images: in v1 they are preserved as a raw-block with a warning
+  (backlog: also export them as a courtesy image in unidirectional mode).
+
+## 5. Configurable style mapping ("publication" mode)
+
+Inspired by mammoth: an optional `style-map.yaml` file lets you project custom styles onto pure
+Markdown elements (`MyTitle ⇒ h2`, `SourceCode ⇒ code-block`) for those who want clean output
+without metadata. This mode is **unidirectional by definition** and the CLI marks it as such.
+
+## 6. Fidelity levels (`--fidelity`)
+
+| Mode | Content | Use |
+|---|---|---|
+| `full` (default) | Everything: attributes, catalogs, raw-blocks | Round-trip |
+| `standard` | Main attributes, no raw-blocks or full catalog | Readable rich Markdown |
+| `plain` | Pure CommonMark+GFM, no attributes | LLM/RAG consumption MarkItDown-style |
+
+## 7. Fidelity escape hatch: raw-blocks
+
+Fragments with no DocMark representation (complex fields, SmartArt, DrawingML drawings, signed
+content…) are preserved opaquely:
+
+````markdown
+::: {.raw format=ooxml part="word/document.xml" id=raw-0007}
+```xml
+<w:sdt>…original content…</w:sdt>
+```
+:::
+````
+
+- The inverse writer re-injects the fragment as-is if the destination matches `format`;
+  otherwise it omits it with a warning.
+- A human editor can delete a raw-block knowing they only lose that element.
+- The `docsai convert` command reports how many raw-blocks it emitted (coverage metric: each
+  phase aims to reduce them).
+
+## 8. Escape rules and serializer determinism
+
+- Only characters that would change meaning in CommonMark are escaped (`*_#|[]<>` depending on
+  context), with a fixed decision table documented in the code.
+- Attributes: canonical order (id, alphabetically sorted classes, sorted keys); values always
+  double-quoted except simple numbers/identifiers.
+- GFM tables: columns aligned with fixed padding if the table has < 120 columns; no padding if
+  it exceeds that.
+- These rules are **normative**: the idempotence test (`parse(serialize(ir)) == ir` and
+  `serialize(parse(md)) == md`) verifies them in CI.
+
+## 9. Pandoc compatibility
+
+DocMark in `full` mode is parseable by `pandoc -f markdown` with these documented caveats:
+`cell-meta` and `raw` blocks appear as generic divs, and non-standard attributes are kept as
+div/span attributes. This is intentional: it gives free PDF/HTML/EPUB output via Pandoc without
+docsai having to implement it.
+
+---
+
+## 10. v1.0 change log
+
+Additions relative to the draft, decided during Phase 1 while implementing the serializer. All
+are additions: no document written against the draft becomes invalid.
+
+| Change | Reason |
+|---|---|
+| Exact unit rule (§2) with `emu` as escape hatch | The draft left the unit up to the serializer; rounding to `cm` shifted margins and sizes on every round-trip |
+| `style-defaults` in the front matter | `w:docDefaults` is the base of the 4-level cascade and had no home |
+| `indent-left/right/first-line/hanging` instead of a single `indent` | OOXML and ODF distinguish all four; a single one lost information |
+| `[]{.empty}` for empty paragraphs | A blank line does not survive Markdown, and empty paragraphs are real content |
+| `[]{.break kind=page\|column}` | The draft only covered line breaks |
+| `.small-caps`, `.caps`, `underline=<style>`, `bold=false`, `italic=false` | Direct formatting that table §3.2 did not cover |
+| `{.field field=X instr="…"}` | The draft described fields in prose but did not fix the syntax |
+| `list=` inside the first item's attribute block | Avoids an item carrying two consecutive `{...}` |
+| `header-row=false` on the table container | GFM requires a header row the original may not have had |
+| Full `::: {.table complex=true}` format | Closes draft annex A |
+| `relative-to-v`, `render=unsupported`, `effects-raw` on images | Axes with different references, non-drawable media, and effects without a model |
+
+**Extensions not yet implemented** (the spec defines them; Phase 1 does not emit them): paragraph
+`border`, `::: {.textbox}` (text boxes travel as raw-block), and everything in §4
+(spreadsheets), which arrives in Phase 3.
diff --git a/docs/especificacion-docmark.md b/docs/especificacion-docmark.md
deleted file mode 100644
index ac087e2..0000000
--- a/docs/especificacion-docmark.md
+++ /dev/null
@@ -1,415 +0,0 @@
-# Especificación DocMark v1.0
-
-**DocMark** es el perfil de Markdown extendido usado por `docsai` como formato pivote textual.
-Objetivo: representar documentos de texto (docx/odt/doc) y hojas de cálculo (xlsx/xls/ods) de
-forma **legible, editable a mano y con información suficiente para regenerar el documento
-original con pérdida mínima**.
-
-Estado: **congelada (v1.0)** al cierre de la Fase 0. Todo cambio posterior incrementa la versión
-declarada en el front matter y exige documentar la migración (`AGENTS.md` §2).
-
-El anexo A (tablas complejas) queda resuelto en §3.4. Los TODO del borrador están cerrados; las
-adiciones que la implementación de la Fase 1 hizo explícitas están marcadas en el texto y
-recogidas en §10.
-
-## 0. Principios
-
-1. **Compatibilidad descendente**: un fichero DocMark es CommonMark+GFM válido. Un visor que
-   ignore atributos y contenedores muestra un documento útil.
-2. **Sintaxis de atributos Pandoc**: `{#id .clase clave="valor"}` — no se inventa sintaxis nueva
-   donde Pandoc ya la tiene.
-3. **Todo lo no representable se conserva**, nunca se descarta: mecanismo `raw-block` (§7).
-4. **Determinismo**: dos serializaciones del mismo IR producen bytes idénticos (necesario para
-   golden tests e idempotencia del round-trip). Final de línea siempre `\n`, UTF-8 sin BOM.
-
-## 1. Convenciones de fichero
-
-- Extensión recomendada: `.dmk.md` (doble extensión: los editores lo tratan como Markdown).
-- Un documento de texto ⇒ un fichero. Un libro de cálculo ⇒ un fichero con una sección H1 por hoja.
-- Los medios se extraen a un directorio hermano `assets/` (configurable con `--assets-dir`).
-
-## 2. Front matter (YAML)
-
-Bloque YAML inicial delimitado por `---`. Campos definidos:
-
-```yaml
----
-docmark: "1.0"                  # versión de esta especificación (obligatorio)
-source-format: docx             # docx | doc | odt | xlsx | xls | ods (obligatorio al convertir)
-title: "Informe Anual"          # docProps / meta.xml
-author: "Ana Pérez"
-created: 2026-03-01T10:00:00Z
-modified: 2026-07-15T09:30:00Z
-language: es-ES
-custom-properties:              # propiedades personalizadas del documento, tal cual
-  Departamento: "Ventas"
-
-page:                           # geometría de página / sección por defecto (documentos de texto)
-  size: A4                      # o width/height explícitos
-  margins: { top: 2.5cm, bottom: 2.5cm, left: 3cm, right: 3cm }
-  orientation: portrait
-
-style-defaults:                 # `w:docDefaults` de OOXML: el fondo de la cascada
-  font: { name: "Calibri", size: 11pt }
-  paragraph: { space-after: 8pt }
-
-styles:                         # catálogo de estilos del documento original (§3)
-  Heading1:
-    type: paragraph
-    based-on: Normal
-    font: { name: "Calibri Light", size: 16pt, color: "#2E74B5", bold: true }
-    paragraph: { space-before: 12pt, space-after: 4pt, keep-with-next: true }
-  Emphatic:
-    type: character
-    font: { italic: true, color: "#C00000" }
-
-list-definitions:               # numbering.xml / estilos de lista ODF normalizados
-  L1:
-    levels:
-      - { format: decimal, text: "%1.", indent: 0.63cm }
-      - { format: lowerLetter, text: "%2)", indent: 1.27cm }
----
-```
-
-Reglas:
-- Claves en kebab-case. Unidades explícitas (`px`, `cm`, `pt`, `emu`, `%`); colores `#RRGGBB`.
-- **Regla de unidades (normativa)**: el serializador elige la **primera unidad que representa la
-  longitud de forma exacta**, en el orden `px` (a 96 dpi) → `cm` → `pt` → `emu`. La legibilidad
-  cede ante la exactitud: un margen de Word de 1417 twips se escribe `70.85pt`, nunca un
-  `2.499cm` aproximado, porque redondear movería el margen en cada ida y vuelta. `emu` es la
-  escotilla final y siempre existe.
-- El bloque `styles` es un **catálogo**: el cuerpo referencia estilos por nombre mediante clases
-  (`{.Heading1}`); el writer inverso lo usa para regenerar `styles.xml`/`styles.xml` ODF.
-- Los campos desconocidos se conservan (los parsers no deben rechazarlos): forward-compatible.
-
-## 3. Bloques de texto
-
-### 3.1 Encabezados y párrafos
-
-```markdown
-# Título del capítulo {.Heading1}
-
-Un párrafo normal (estilo por defecto, sin atributos).
-
-Párrafo con estilo y formato directo. {.Quote align=center space-after=12pt}
-```
-
-- El nivel `#` refleja el nivel de esquema (outline level); la clase indica el estilo real.
-- Atributos de párrafo van en `{...}` **al final del bloque**: `align`,
-  `indent-left`, `indent-right`, `indent-first-line`, `indent-hanging`,
-  `space-before`, `space-after`, `line-height`, `background`, `keep-with-next`,
-  `page-break-before`, `outline-level`.
-- Un párrafo **vacío** es contenido real (así se espacia un documento) y una línea en blanco no
-  puede representarlo, porque Markdown la absorbe: en modo `full` se escribe `[]{.empty}`. Los
-  modos `standard` y `plain` lo descartan, que es justo lo que prometen (§6).
-- Regla de economía: si el formato coincide exactamente con lo que define el estilo, **no** se
-  emiten atributos redundantes (mantiene el Markdown limpio y el diff estable).
-
-### 3.2 Formato inline
-
-| Original | DocMark |
-|---|---|
-| negrita / cursiva / tachado | `**x**`, `*x*`, `~~x~~` (nativo GFM) |
-| subrayado | `[texto]{.underline}` |
-| color, resaltado, fuente, tamaño | `[texto]{color="#FF0000" highlight="yellow" font="Arial" size=14pt}` |
-| estilo de carácter | `[texto]{.Emphatic}` |
-| sub/superíndice | `[x]{.sub}` / `[x]{.sup}` |
-| versalitas / mayúsculas | `[x]{.small-caps}` / `[x]{.caps}` |
-| subrayado no simple | `[x]{.underline underline=double}` (valores: `double`, `thick`, `dotted`, `dashed`, `wave`) |
-| formato desactivado sobre un estilo | `[x]{bold=false}` / `[x]{italic=false}` |
-| salto de línea manual | doble espacio final (hard break) |
-| salto de página o columna | `[]{.break kind=page}` / `[]{.break kind=column}` |
-| hipervínculo | `[texto](https://...)` — con atributos si tiene estilo: `[texto](url){.Hyperlink}` |
-| nota al pie | `[^1]` + definición al final (sintaxis Pandoc/GFM footnotes) |
-| campo dinámico | `[valor]{.field field=PAGE}`, con `instr="…"` en modo `full` |
-
-### 3.3 Listas
-
-Listas Markdown estándar; la definición tipográfica vive en `list-definitions` y se referencia
-en el primer ítem cuando no es la lista por defecto:
-
-```markdown
-1. Primer punto {.ListParagraph list=L1}
-2. Segundo punto {.ListParagraph}
-   1. Sub-punto (el marcador real lo define L1 nivel 2) {.ListParagraph list=L1}
-```
-
-- `list=` viaja **dentro del bloque de atributos del primer ítem**, no en un bloque aparte: un
-  ítem nunca lleva dos `{...}`.
-- Las listas anidadas se escriben *tight* (sin línea en blanco entre el ítem y su sublista) para
-  que un visor CommonMark no envuelva cada ítem en un `<p>`.
-- El marcador ordinal que se escribe es `1.`, `2.`… El marcador real de presentación lo define
-  el nivel correspondiente de `list-definitions`.
-
-### 3.4 Tablas (documentos de texto)
-
-Tablas GFM cuando son regulares. Una tabla con celdas combinadas, anchos fijos o estilo de tabla
-se envuelve en un contenedor que aporta los metadatos:
-
-```markdown
-::: {.table style=TableGrid col-widths="3cm,5cm,5cm"}
-| Concepto | T1 | T2 |
-|---|---|---|
-| Ventas {rowspan=2} | 100 | 200 |
-| | 300 | 400 |
-:::
-```
-
-- `rowspan`/`colspan` en la **primera celda** del área combinada; las celdas absorbidas quedan vacías.
-- El contenedor admite `style`, `col-widths` y `header-row=false`. GFM exige una fila de
-  cabecera: cuando el original no la tenía se emite una fila vacía y `header-row=false` lo
-  registra, de modo que la vuelta no invente una cabecera.
-- Si la estructura excede lo representable en GFM (tablas anidadas, celdas multipárrafo), la tabla
-  completa se emite como contenedor `::: {.table complex=true}` con filas y celdas como
-  sub-bloques:
-
-````markdown
-::: {.table complex=true style=TableGrid}
-::: {.row}
-::: {.cell rowspan=2}
-Primer párrafo de la celda.
-
-Segundo párrafo de la misma celda.
-:::
-::: {.cell}
-Otra celda.
-:::
-:::
-:::
-````
-
-  Reglas del formato complejo: un `::: {.row}` por fila, un `::: {.cell}` por celda **incluidas
-  las absorbidas** (que van vacías), `colspan`/`rowspan` en la celda que abre el área, y dentro
-  de cada celda cualquier bloque DocMark válido. Esto cierra el anexo A del borrador.
-
-### 3.5 Imágenes y objetos
-
-Toda imagen se extrae a `assets/` y se referencia con la sintaxis estándar de imagen Markdown
-más un conjunto normalizado de atributos que capturan la geometría completa del original
-(tamaño, posición, anclaje, recorte, rotación…). El mismo modelo de atributos aplica en
-documentos de texto y en hojas de cálculo (§4.1).
-
-```markdown
-Imagen en línea (fluye con el texto):
-
-![Diagrama de ventas](assets/img-3f2a91.png){width=450px height=300px title="Figura 1"}
-
-Imagen flotante con posición y ajuste de texto:
-
-![Logo](assets/img-9c04b7.png){#img-logo width=3.5cm height=3.5cm
-  anchor=floating relative-to=margin x=1.2cm y=0.5cm
-  wrap=square wrap-side=right z-index=2
-  rotation=0 crop="0,0,10%,0" native-size=800x800 dpi=300
-  name="Logo corporativo" link="https://example.com"}
-```
-
-**Atributos de imagen normalizados** (los no aplicables se omiten; unidades explícitas):
-
-| Atributo | Significado | Origen típico |
-|---|---|---|
-| `width`, `height` | Tamaño **mostrado** (obligatorios siempre) | `wp:extent`, `svg:width/height` |
-| `native-size` | Dimensiones en píxeles del bitmap original (`AxB`) | cabecera del fichero |
-| `dpi` | Resolución declarada, si difiere de 96 | metadatos del bitmap |
-| `anchor` | `inline` (defecto) \| `floating` \| `behind` \| `front` | `wp:inline`/`wp:anchor`, `text:anchor-type` |
-| `relative-to` | Referencia de posición horizontal: `page` \| `margin` \| `paragraph` \| `character` \| `line` \| `column` | `wp:positionH @relativeFrom` |
-| `relative-to-v` | Referencia vertical, **solo si difiere** de `relative-to` | `wp:positionV @relativeFrom` |
-| `x`, `y` | Offsets desde la referencia (solo flotantes) | `wp:posOffset`, `svg:x/y` |
-| `align-h`, `align-v` | Alineación simbólica (`left/center/right`, `top/middle/bottom`) cuando el original usa alineación en vez de offset | `wp:align` |
-| `wrap` | `square` \| `tight` \| `through` \| `top-bottom` \| `none` | `wp:wrapSquare…`, `style:wrap` |
-| `wrap-side` | `both` \| `left` \| `right` \| `largest` | `@wrapText` |
-| `z-index` | Orden de apilamiento entre objetos flotantes | `@relativeHeight` |
-| `rotation` | Grados en sentido horario | `a:xfrm @rot` |
-| `flip` | `h` \| `v` \| `hv` | `a:xfrm @flipH/V` |
-| `crop` | Recorte `"izq,arr,der,abj"`, los cuatro lados con sufijo `%` | `a:srcRect`, `fo:clip` |
-| `border` | Borde simple `"1pt solid #000000"` (bordes complejos → raw) | `pic:spPr` |
-| `name` | Nombre interno del objeto en el documento | `wp:docPr @name` |
-| `title` | Título/leyenda | `wp:docPr @title` |
-| `link` | Hipervínculo sobre la imagen | `a:hlinkClick` |
-| `external-src` | URL original si la imagen estaba **enlazada**, no embebida | `r:link`, `xlink:href` |
-| `render` | `unsupported` para formatos que un visor Markdown no dibuja (WMF/EMF) | sniffing del contenido |
-| `effects-raw` | Id del raw-block con los efectos irrepresentables | `a:effectLst`, `a:scene3d` |
-
-Reglas:
-- El texto alternativo (accesibilidad, `wp:docPr @descr` / `svg:desc`) va en el campo alt
-  estándar de Markdown `![…]`, no en un atributo — así lo muestran todos los visores.
-- Nombre de fichero: `img-<hash8>.<ext>` (hash del contenido → estable entre conversiones y
-  con deduplicación: N apariciones del mismo bitmap comparten fichero, cada una con sus
-  atributos de geometría propios).
-- `width`/`height` son **siempre** obligatorios en la serialización aunque coincidan con el
-  tamaño nativo: el round-trip no debe depender de releer el bitmap.
-- WMF/EMF se extraen con su extensión original y geometría completa; el serializador añade
-  `render=unsupported` como pista para visores (advertencia en el informe).
-- Efectos de imagen sin representación (sombras, biseles, estilos 3D DrawingML) se conservan
-  como raw-block asociado mediante `effects-raw=<id>` que referencia un `::: {.raw}` contiguo.
-- Objetos no imagen (OLE, SmartArt, gráficos incrustados): se extraen a `assets/` y se
-  referencian con `![...](assets/obj-xxx.bin){.embedded-object content-type="..."}`, más
-  advertencia en el informe.
-
-### 3.6 Secciones, cabeceras y pies, cuadros de texto
-
-```markdown
-::: {.header scope=default}
-Texto de cabecera — página [n.º]{.field field=PAGE}
-:::
-
-::: {.section columns=2 page-size=A4 orientation=landscape}
-… contenido de la sección …
-:::
-
-::: {.textbox x=5cm y=2cm width=6cm}
-Contenido del cuadro de texto.
-:::
-```
-
-Los campos dinámicos (número de página, fecha, TOC) se representan como spans `{.field field=...}`
-con su último valor conocido como texto visible.
-
-## 4. Hojas de cálculo
-
-Cada hoja es una sección `#` con contenedor de metadatos; los datos van en tabla GFM.
-**Regla de oro: la celda muestra el valor; la fórmula y el formato viajan en metadatos.**
-
-```markdown
----
-docmark: "1.0"
-source-format: xlsx
-workbook:
-  active-sheet: Ventas
-  defined-names:
-    TOTAL_ANUAL: "Ventas!$D$10"
----
-
-# Ventas {.sheet cols="A:D" col-widths="12,9,9,11" frozen="A2"}
-
-| | A | B | C | D |
-|---|---|---|---|---|
-| **1** | Producto | T1 | T2 | Total |
-| **2** | Widgets | 100 | 200 | 300 |
-| **3** | Gadgets | 150 | 250 | 400 |
-
-::: {.cell-meta}
-- D2: formula="SUM(B2:C2)" num-fmt="#,##0"
-- D3: formula="SUM(B3:C3)" num-fmt="#,##0"
-- A1:D1: style=HeaderRow
-- B2:D3: type=number num-fmt="#,##0"
-:::
-```
-
-Reglas:
-- Primera columna/fila de la tabla = coordenadas (generadas, en negrita); permiten que el bloque
-  `cell-meta` use referencias A1 legibles.
-- `cell-meta` admite rangos (`B2:D3`) para compactar metadatos repetidos; el parser expande.
-- `formula` se guarda **sin** `=` inicial y en el dialecto original; `formula-dialect: openformula`
-  se añade cuando la fuente es ODS.
-- Tipos de celda: `number | text | bool | date | error` (+ `num-fmt` con el código de formato).
-  Las fechas se muestran en la tabla en ISO-8601 y se restauran como serial+formato al escribir.
-- Celdas combinadas: `A5:C5: merge=true` (el valor vive en la celda superior-izquierda).
-- Estilos de celda (fuente, borde, relleno) se catalogan en `styles:` del front matter y se
-  referencian con `style=`.
-- Hojas enormes: por defecto se vuelca el rango usado completo; `--max-cells` permite truncar
-  **solo en modo unidireccional** (nunca al preparar un round-trip; truncar invalida la vuelta).
-
-### 4.1 Imágenes en hojas de cálculo
-
-Las hojas también llevan imágenes (logos, capturas, diagramas) ancladas a la rejilla. Se
-declaran en un bloque `sheet-images` al final de cada hoja, usando la misma sintaxis y los
-mismos atributos de imagen de §3.5 más los atributos de anclaje propios de hoja de cálculo:
-
-```markdown
-::: {.sheet-images}
-![Logo de la empresa](assets/img-9c04b7.png){anchor=two-cell
-  from="B2" from-offset="12px,3px" to="D8" to-offset="0,0" move-with-cells=true size-with-cells=false}
-
-![Firma](assets/img-11ab42.png){anchor=one-cell from="F20" from-offset="0,0" width=180px height=60px}
-
-![Marca de agua](assets/img-77cd01.png){anchor=absolute x=5cm y=8cm width=10cm height=10cm}
-:::
-```
-
-Reglas:
-- `anchor` en hojas: `two-cell` (de celda a celda; la imagen se mueve/estira con la rejilla,
-  según `move-with-cells`/`size-with-cells`) | `one-cell` (celda origen + tamaño fijo) |
-  `absolute` (posición absoluta). Corresponden a `xdr:twoCellAnchor`/`oneCellAnchor`/
-  `absoluteAnchor` de OOXML y a los anclajes celda/hoja de ODF.
-- En `two-cell` **no se serializan** `width`/`height` (el tamaño lo define la rejilla); en
-  `one-cell` y `absolute` son obligatorios, como en §3.5.
-- `from`/`to` usan referencias A1; los offsets dentro de la celda van en `from-offset`/`to-offset`.
-- El resto de propiedades (rotación, recorte, alt, hipervínculo, `native-size`…) funcionan igual
-  que en §3.5.
-- Gráficos (charts) nativos de la hoja no son imágenes: en v1 se conservan como raw-block con
-  advertencia (backlog: exportarlos también como imagen de cortesía en modo unidireccional).
-
-## 5. Mapeo de estilos configurable (modo "publicación")
-
-Inspirado en mammoth: un fichero opcional `style-map.yaml` permite proyectar estilos propios a
-elementos Markdown puros (`MiTítulo ⇒ h2`, `CódigoFuente ⇒ code-block`) para quien quiera salida
-limpia sin metadatos. Este modo es **unidireccional por definición** y la CLI lo marca así.
-
-## 6. Grados de fidelidad (`--fidelity`)
-
-| Modo | Contenido | Uso |
-|---|---|---|
-| `full` (defecto) | Todo: atributos, catálogos, raw-blocks | Round-trip |
-| `standard` | Atributos principales, sin raw-blocks ni catálogo completo | Markdown rico legible |
-| `plain` | CommonMark+GFM puro, sin atributos | Consumo LLM/RAG estilo MarkItDown |
-
-## 7. Escotilla de fidelidad: raw-blocks
-
-Fragmentos sin representación DocMark (campos complejos, SmartArt, dibujos DrawingML, contenido
-firmado…) se conservan opacos:
-
-````markdown
-::: {.raw format=ooxml part="word/document.xml" id=raw-0007}
-```xml
-<w:sdt>…contenido original…</w:sdt>
-```
-:::
-````
-
-- El writer inverso re-inyecta el fragmento tal cual si el destino coincide con `format`;
-  si no, lo omite con advertencia.
-- Un editor humano puede borrar un raw-block sabiendo que solo pierde ese elemento.
-- El comando `docsai convert` reporta cuántos raw-blocks emitió (métrica de cobertura: el
-  objetivo de cada fase es reducirlos).
-
-## 8. Reglas de escape y determinismo del serializador
-
-- Se escapan solo los caracteres que cambiarían el significado en CommonMark (`*_#|[]<>` según
-  contexto), con tabla de decisión fija documentada en el código.
-- Atributos: orden canónico (id, clases ordenadas alfabéticamente, claves ordenadas); valores
-  siempre con comillas dobles salvo números/identificadores simples.
-- Tablas GFM: columnas alineadas con padding fijo si la tabla < 120 cols; sin padding si excede.
-- Estas reglas son **normativas**: el test de idempotencia (`parse(serialize(ir)) == ir` y
-  `serialize(parse(md)) == md`) las verifica en CI.
-
-## 9. Compatibilidad con Pandoc
-
-DocMark en modo `full` es parseable por `pandoc -f markdown` con estas salvedades documentadas:
-los bloques `cell-meta` y `raw` aparecen como divs genéricos, y los atributos no estándar se
-conservan como atributos de div/span. Esto es intencional: da salida gratuita a PDF/HTML/EPUB
-vía Pandoc sin que docsai tenga que implementarla.
-
----
-
-## 10. Registro de cambios de la v1.0
-
-Añadidos respecto al borrador, decididos durante la Fase 1 al implementar el serializador. Todos
-son adiciones: ningún documento escrito contra el borrador deja de ser válido.
-
-| Cambio | Motivo |
-|---|---|
-| Regla de unidades exactas (§2) con `emu` como escotilla | El borrador dejaba la unidad al gusto del serializador; redondear a `cm` movía márgenes y tamaños en cada ida y vuelta |
-| `style-defaults` en el front matter | `w:docDefaults` es el fondo de la cascada de 4 niveles y no tenía sitio |
-| `indent-left/right/first-line/hanging` en vez de un `indent` único | OOXML y ODF distinguen los cuatro; uno solo perdía información |
-| `[]{.empty}` para párrafos vacíos | Una línea en blanco no sobrevive a Markdown, y los párrafos vacíos son contenido real |
-| `[]{.break kind=page\|column}` | El borrador solo cubría el salto de línea |
-| `.small-caps`, `.caps`, `underline=<estilo>`, `bold=false`, `italic=false` | Formato directo que la tabla §3.2 no cubría |
-| `{.field field=X instr="…"}` | El borrador describía los campos en prosa pero no fijaba la sintaxis |
-| `list=` dentro del bloque de atributos del primer ítem | Evita que un ítem lleve dos `{...}` seguidos |
-| `header-row=false` en el contenedor de tabla | GFM obliga a una fila de cabecera que el original podía no tener |
-| Formato completo de `::: {.table complex=true}` | Cierra el anexo A del borrador |
-| `relative-to-v`, `render=unsupported`, `effects-raw` en imágenes | Ejes con referencias distintas, medios no dibujables y efectos sin modelo |
-
-**Extensiones no implementadas todavía** (la spec las define, la Fase 1 no las emite): `border` de
-párrafo, `::: {.textbox}` (los cuadros de texto viajan como raw-block), y todo lo de §4 (hojas de
-cálculo), que llega en la Fase 3.
diff --git a/docs/plan-desarrollo.md b/docs/plan-desarrollo.md
deleted file mode 100644
index 681c575..0000000
--- a/docs/plan-desarrollo.md
+++ /dev/null
@@ -1,331 +0,0 @@
-# Plan de desarrollo
-
-Plan por fases para implementar `docsai`. Cada fase tiene objetivo, tareas, entregables,
-criterios de aceptación y una estimación orientativa (en semanas-persona de un desarrollador
-Rust senior; ajustar según equipo). Las fases 1–3 son el corazón del producto; a partir de la
-Fase 6 hay margen para paralelizar.
-
-**Regla de gestión**: no se abre una fase sin cerrar los criterios de aceptación de la anterior
-(excepto las marcadas como paralelizables). Cada fase termina con un tag `v0.x.0`.
-
----
-
-## Fase 0 — Fundamentos (2–3 semanas)
-
-**Objetivo**: workspace compilando, IR diseñado, especificación DocMark congelada, corpus inicial
-y CI multiplataforma en verde. Es la fase que des-riesga todo lo demás.
-
-Tareas:
-1. Crear workspace Cargo con los 7 crates de `arquitectura.md` §2 (aunque casi vacíos).
-2. Implementar `docsai-model` v1: tipos del IR (§3 de arquitectura), `StyleCatalog` con
-   herencia, `ConversionReport`, newtypes de unidades (`Length` con EMU/twips/pt/cm).
-   Incluye el **modelo normalizado de imágenes** `ImageRef`/`ImageGeometry`/`Anchor`
-   (arquitectura §3.1) con su validador de invariantes (anclajes de hoja solo en `Workbook`),
-   y el trait `AssetStore` (arquitectura §3.2). Todo `serde`-serializable, con tests
-   unitarios de las conversiones de unidades (EMU⇄pt⇄cm⇄px a 96 dpi).
-3. **Spike de riesgo R1** (timebox 1 semana): leer con `docx-rs` + `quick-xml` tres documentos
-   docx reales con estilos custom y verificar que la cascada de 4 niveles es resoluble con la
-   información expuesta. Resultado escrito en `docs/spikes/` con decisión: crate + complemento
-   propio, o parser OOXML propio completo.
-4. Congelar `especificacion-docmark.md` v1.0 (revisión del equipo, resolver los TODO del anexo A
-   de tablas complejas).
-5. Corpus inicial en `corpus/`: ~15 documentos mínimos hechos a mano (uno por rasgo):
-   `docx/basic-text`, `basic-styles`, `nested-lists`, `table-simple`, `table-merged`,
-   `images-inline`, `images-floating` (wrap + posición relativa a página/margen),
-   `images-transformed` (recorte, rotación, volteo, escala ≠ 100 %), `images-duplicated`
-   (mismo bitmap N veces con geometrías distintas), `headers-footers`, `footnotes`,
-   `custom-styles`; `xlsx/values-types`, `formulas-basic`, `formulas-shared`,
-   `number-formats`, `merged-cells`, `images-anchored` (los tres anclajes: two-cell,
-   one-cell, absolute).
-   Guion de cómo se creó cada uno en `corpus/README.md`.
-6. CI GitHub Actions: build+test+clippy+fmt en matriz de 3 SO; caché de cargo; badge en README.
-7. Esqueleto CLI (`docsai formats`, `--version`) y plantilla de `insta` para golden tests.
-
-Entregables: workspace verde en CI, `docsai-model` v1, spec congelada, corpus v1, informe del spike.
-
-Criterios de aceptación:
-- [x] `cargo test --workspace` verde en las 3 plataformas.
-- [x] IR serializa/deserializa a JSON con round-trip idéntico (proptest básico).
-- [x] Spike documentado con decisión firmada sobre la estrategia docx.
-- [x] DocMark v1.0 sin TODOs abiertos.
-
-**Estado**: cerrada. Notas de ejecución:
-- El spike R1 (`docs/spikes/R1-estrategia-docx.md`) descartó `docx-rs`: pierde el modelo de
-  imagen casi entero, las notas al pie y los campos simples, y provoca *panic* en el 23 % de las
-  entradas corruptas. La lectura docx se hace con parser propio sobre `zip` + `quick-xml`.
-- El corpus se **genera** con `corpus/generate.py` en vez de dibujarse a mano: el XML queda
-  revisable en el diff y los paquetes son reproducibles byte a byte (ver `corpus/README.md`).
-- Los golden files son `.expected.dmk.md` junto al corpus, como prescribe `AGENTS.md` §6, en
-  lugar de snapshots de `insta`; `insta` sale del árbol de dependencias.
-
----
-
-## Fase 1 — Lectura DOCX → DocMark (4–6 semanas)
-
-**Objetivo**: `docsai convert x.docx -o x.dmk.md` con estilos, imágenes, tablas, listas,
-cabeceras/pies y propiedades. Es la fase más larga: fija los patrones que reutilizan todas las demás.
-
-Tareas:
-1. Reader docx (`docsai-office`): apertura ZIP, `document.xml`, resolución de relaciones.
-2. Estilos: parseo completo de `styles.xml` → `StyleCatalog`; resolución referencia+delta
-   (nunca aplanar); defaults del documento (`docDefaults`).
-3. Párrafos y runs: todo el formato inline de la tabla §3.2 de la spec; hipervínculos; breaks.
-4. Listas: reconstrucción del árbol desde `numbering.xml` + pares `(numId, ilvl)` → `ListCatalog`.
-5. Tablas: grid, `gridSpan`/`vMerge` → rowspan/colspan del IR, anchos, estilo de tabla.
-6. Imágenes (spec §3.5, arquitectura §3.1): DrawingML `wp:inline` y `wp:anchor` → `ImageRef` +
-   extracción a `AssetStore` con deduplicación por hash. Mapeo completo de geometría: tamaño
-   mostrado vs nativo, posición relativa (page/margin/paragraph/character) con offsets o
-   alineación simbólica, wrap y lado, z-order/behind-text, rotación, volteos, recorte
-   (`a:srcRect`), borde simple, alt/título/nombre, hipervínculo sobre imagen, imágenes
-   enlazadas (`r:link`, sin descarga). Lectura también de **VML legado** (`w:pict`) limitada
-   al modelo normalizado. Efectos DrawingML sin modelo → raw-block asociado (`effects_raw`).
-   WMF/EMF extraídos tal cual con geometría completa y advertencia.
-7. Cabeceras/pies/secciones (`sectPr`), notas al pie/al final, campos simples (PAGE, TOC como
-   raw/field), propiedades de documento (core+app+custom).
-8. Serializador DocMark (`docsai-docmark`): IR → Markdown según spec §8 (determinista); gestión
-   de assets y front matter; modos `--fidelity`.
-9. Todo elemento OOXML no reconocido → raw-block + advertencia tipada (cobertura medible).
-10. Golden tests de todo el corpus docx; añadir 5+ documentos "del mundo real" anonimizados.
-
-Criterios de aceptación:
-- [x] Los golden docx del corpus pasan (incluidos los tres de imágenes: flotantes,
-      transformadas y duplicadas — con geometría completa en los atributos DocMark).
-- [x] Cero pánicos con corpus corrupto sintético (ZIP truncado, XML malformado): siempre `Err`.
-- [x] Un docx real de 50+ páginas convierte en < 1 s con < 10 raw-blocks.
-- [x] La salida en `--fidelity plain` es CommonMark limpio verificado con comrak.
-
-**Estado**: cerrada salvo la tarea 10 (documentos reales anonimizados), que depende de disponer
-de documentos reales y no bloquea la Fase 2. Notas de ejecución:
-- Los cuadros de texto DrawingML (`wps:txbx`) se conservan como raw-block, no como
-  `::: {.textbox}`: el tipo existe en el IR y en la spec, pero emitirlo se pospone a la Fase 2,
-  donde el writer tendrá que reconstruirlos.
-- Tres defectos que el corpus destapó y que quedan corregidos: el formato de longitudes era
-  lisiado por redondeo (un margen de 1417 twips se escribía `2.499cm`), los párrafos vacíos
-  desaparecían en silencio, y el estilo de carácter de un hipervínculo se emitía dos veces.
-
----
-
-## Fase 2 — Escritura DocMark → DOCX + round-trip (3–5 semanas)
-
-**Objetivo**: cerrar el ciclo bidireccional de texto y montar la infraestructura de fidelidad.
-
-Tareas:
-1. Parser DocMark (`docsai-docmark`): comrak + capa propia de atributos `{...}` y fenced divs
-   `:::` → IR. Validación de front matter con errores de línea/columna útiles.
-2. Writer docx: IR → `document.xml` + `styles.xml` + `numbering.xml` + media + props
-   (con `docx-rs` donde llegue; XML directo donde no). Re-inyección de raw-blocks `format=ooxml`.
-   Imágenes: re-empaquetado de `word/media/*` desde el `AssetStore` (sin recomprimir bitmaps) y
-   emisión de DrawingML completo desde `ImageGeometry` — inline y flotante con posición, wrap,
-   z-order, rotación, recorte y alt/título; siempre DrawingML aunque la fuente fuese VML.
-3. Comando `roundtrip`: docx→md→docx→md; diff estructural de IR normalizado; métrica de
-   fidelidad por categoría (texto, estilos, tablas, imágenes, listas) y salida `--json`.
-4. Test de **idempotencia del serializador** en CI: `serialize(parse(md)) == md` byte a byte
-   sobre todos los goldens.
-5. Property testing (proptest): generar IRs aleatorios válidos y verificar IR→md→IR == identidad.
-6. Validación externa: los docx generados abren sin diálogo de reparación en Word y LibreOffice
-   (checklist manual documentada por release; automatizable después vía LibreOffice headless en CI Linux).
-
-Criterios de aceptación:
-- [ ] Round-trip idempotente (2ª pasada == 1ª pasada) en todo el corpus.
-- [ ] Métrica de fidelidad ≥ 95 % en texto/estilos/tablas/listas del corpus.
-- [ ] Imágenes en round-trip: bytes del bitmap idénticos (sin recompresión), sin duplicados en
-      media, y geometría (tamaño, posición, anclaje, wrap, rotación, recorte) preservada — las
-      imágenes aparecen en el mismo sitio y tamaño al abrir el docx regenerado en Word/LibreOffice.
-- [ ] docx generados abren limpios en Word y LibreOffice (checklist).
-- [ ] Editar un `.dmk.md` a mano (añadir párrafo con estilo existente) y regenerar docx funciona.
-
----
-
-## Fase 3 — Hojas de cálculo: XLSX/XLS ⇄ DocMark (4–5 semanas)
-
-**Objetivo**: `xlsx` bidireccional con valores, fórmulas y formatos; `xls` lectura.
-
-Tareas:
-1. **Spike (3 días)**: decidir writer xlsx — `umya-spreadsheet` (lee y escribe estilos) vs
-   `rust_xlsxwriter` (mejor API de escritura pura). Criterio: cuál regenera con mayor fidelidad
-   estilos+numFmt desde el IR. Documentar en `docs/spikes/`.
-2. Reader xlsx: `calamine` para valores y fórmulas; lectura complementaria propia de
-   `xl/styles.xml` (numFmt, fuentes, rellenos, bordes por índice) y de dimensiones/merges/panes
-   con `quick-xml`. Fórmulas compartidas y de matriz expandidas con metadato.
-3. Tipado de celdas: detección fecha/hora vía numFmt (serial→ISO-8601 y vuelta); booleanos,
-   errores (`#DIV/0!`…).
-4. Serialización de hojas a DocMark según spec §4 (tabla de valores + `cell-meta` con rangos
-   compactados) y parser inverso.
-5. Writer xlsx desde IR (crate elegido en el spike): valores, fórmulas (recálculo delegado a
-   Excel/LibreOffice al abrir: escribir fórmula sin valor cacheado o con el valor conservado),
-   numFmt, estilos, merges, anchos, defined names.
-6. **Imágenes de hoja** (spec §4.1): lectura propia de `xl/drawings/drawing*.xml` con
-   `quick-xml` (calamine/umya no las cubren con geometría completa) → `ImageRef` con anclajes
-   `SheetTwoCell`/`SheetOneCell`/`SheetAbsolute`, offsets dentro de celda,
-   `move-with-cells`/`size-with-cells`, y el resto del modelo común (rotación, recorte, alt,
-   hipervínculo). Escritura de `drawing*.xml` + relaciones desde el IR. Charts nativos →
-   raw-block con advertencia.
-7. Reader xls (calamine) → mismo pipeline (solo lectura; documentar en `formats`).
-8. Corpus: añadir libros con fechas, porcentajes, monedas, fórmulas entre hojas, nombres
-   definidos, imágenes con los tres tipos de anclaje, 100k celdas (rendimiento).
-
-Criterios de aceptación:
-- [ ] Round-trip xlsx: valores, fórmulas y numFmt intactos en el corpus (fidelidad ≥ 95 %).
-- [ ] Round-trip de imágenes de hoja: los tres anclajes conservados simbólicamente (two-cell
-      sigue estirándose con la rejilla tras la vuelta), bitmaps sin recompresión.
-- [ ] Un xlsx con fechas sobrevive al round-trip sin corromper serials (test dedicado).
-- [ ] xlsx de 100k celdas: < 3 s, < 500 MB RAM.
-- [ ] Excel y LibreOffice recalculan sin errores los ficheros generados (checklist).
-
----
-
-## Fase 4 — ODF: ODT y ODS ⇄ DocMark (3–4 semanas) — *paralelizable con Fase 5*
-
-**Objetivo**: paridad de LibreOffice con los formatos OOXML ya soportados.
-
-Tareas:
-1. Reader/writer ODT propio (`docsai-odf`, `zip`+`quick-xml`): content/styles/meta;
-   **des-automatización** de estilos automáticos al leer (→ deltas) y re-generación al escribir.
-2. Imágenes ODT: `<draw:frame>/<draw:image>` + `Pictures/*` → mismo modelo `ImageGeometry`
-   (anclajes `as-char/char/paragraph/page` → `Inline`/`Floating`; `svg:x/y/width/height`,
-   `style:wrap`, rotación y `fo:clip`); escritura inversa con estilos gráficos ODF.
-3. Reader ODS con `calamine` (valores/fórmulas) + estilos propios; writer ODS con
-   `spreadsheet-ods` (evaluar en mini-spike; si no da la talla, writer propio). Imágenes de
-   hoja ODS (`draw:frame` anclado a celda/hoja) mapeadas a los mismos anclajes de hoja del IR.
-4. Fórmulas OpenFormula: conservar dialecto (`formula-dialect=openformula`); NO traducir aún.
-5. Corpus ODF espejo del OOXML (los mismos rasgos, incluidos los documentos de imágenes),
-   generado con LibreOffice.
-6. Nota de alcance: la conversión cruzada docx⇄odt "funciona" vía IR, pero los raw-blocks de un
-   dialecto se descartan con advertencia en el otro. Documentar en README.
-
-Criterios de aceptación:
-- [ ] Round-trip odt y ods sobre corpus ODF con fidelidad ≥ 90 % (incluida la geometría de
-      imágenes: tamaño, posición, anclaje y wrap).
-- [ ] docx→DocMark→odt produce documento correcto para el corpus básico (rasgos comunes).
-
----
-
-## Fase 5 — DOC legado (2–3 semanas) — *paralelizable con Fase 4*
-
-**Objetivo**: lectura de `.doc` con la estrategia de dos niveles del análisis (§1.3).
-
-Tareas:
-1. Detección de LibreOffice en runtime por SO (rutas estándar + PATH); flag
-   `--use-loffice auto|never|require`; conversión `soffice --headless --convert-to docx` en
-   directorio temporal sandbox y reentrada por el pipeline docx de Fase 1.
-2. Extractor nativo degradado: `cfb` + FIB + piece table → texto con párrafos y propiedades
-   básicas; extracción de imágenes embebidas (BLIPs del stream Escher/OfficeArt) al
-   `AssetStore` — sin geometría fina: se emiten con `anchor=inline` y tamaño nativo, con
-   advertencia `ImageGeometryDegraded`. Marcar salida como degradada en el `ConversionReport`.
-3. Mensajería clara: si no hay LibreOffice, el usuario sabe exactamente qué está perdiendo y cómo
-   mejorar el resultado.
-4. Tests: corpus `.doc` generado guardando el corpus docx como .doc con Word/LibreOffice.
-
-Criterios de aceptación:
-- [ ] Con LibreOffice instalado: fidelidad equivalente a la ruta docx.
-- [ ] Sin LibreOffice: texto completo y estructura de párrafos correcta, sin pánicos.
-- [ ] `.doc` cifrados/protegidos rechazados con error claro.
-
----
-
-## Fase 6 — CLI completa y distribución (2–3 semanas)
-
-**Objetivo**: experiencia de producto: la CLI definitiva y binarios instalables en 3 SO.
-
-Tareas:
-1. CLI final según `arquitectura.md` §5: `convert`, `inspect`, `roundtrip`, `formats`;
-   `--json`, `--strict`, stdin/stdout, códigos de salida; `--style-map` (modo mammoth, spec §5).
-2. Mensajes de error y advertencias pulidos (con `miette` o similar para diagnósticos bonitos);
-   `--verbose`/`RUST_LOG`.
-3. Procesado por lotes: `docsai convert *.docx --out-dir md/` con paralelismo (`rayon`) y
-   resumen agregado.
-4. `cargo-dist`: releases automáticas por tag con binarios firmados para los 5 targets;
-   instaladores shell/powershell; fórmulas Homebrew/Scoop; publicación en crates.io.
-5. Documentación de usuario: README definitivo con ejemplos reales, página `--help` cuidada,
-   CHANGELOG (keep-a-changelog).
-
-Criterios de aceptación:
-- [ ] Instalación en máquina limpia de cada SO con un comando y conversión de prueba OK.
-- [ ] `docsai convert` sobre carpeta con 100 documentos mezclados termina con resumen correcto.
-- [ ] Todos los errores de usuario previsibles tienen mensaje accionable (revisión de UX escrita).
-
----
-
-## Fase 7 — Servidor MCP (2 semanas)
-
-**Objetivo**: `docsai mcp` operativo con clientes reales.
-
-Tareas:
-1. Implementar `docsai-mcp` con `rmcp` (stdio): las 4 tools de `arquitectura.md` §6 con schemas
-   JSON documentados y validación de entrada.
-2. Modo path y modo base64; límites de tamaño; timeouts; assets inline vs ficheros.
-3. Garantía stdout-limpio: test automático de que ninguna ruta de código escribe en stdout fuera
-   del protocolo (logs → stderr).
-4. Pruebas de integración con MCP Inspector y con Claude Desktop/Claude Code reales; recetas de
-   configuración en README.
-5. Considerar (backlog, no bloqueo): tool `apply_edits` para edición guiada de documentos vía
-   DocMark en el futuro.
-
-Criterios de aceptación:
-- [ ] Un cliente MCP real convierte docx→markdown y markdown→docx de extremo a extremo.
-- [ ] Entradas malformadas devuelven errores MCP correctos, nunca cuelgan el servidor.
-- [ ] Sesión de 100 conversiones seguidas sin fugas de memoria ni ficheros temporales huérfanos.
-
----
-
-## Fase 8 — Endurecimiento y calidad (2–3 semanas, parcialmente continua)
-
-**Objetivo**: robustez de producción.
-
-Tareas:
-1. Fuzzing con `cargo-fuzz` de los 4 parsers de entrada (docx, xlsx, odf, docmark); corpus de
-   fuzzing sembrado con el corpus de tests; ejecutar en CI programada (cron semanal).
-2. Suite de documentos adversarios: ZIP bombs (límites de descompresión), XML entity expansion
-   (verificar que quick-xml no expande entidades externas), rutas de assets maliciosas
-   (path traversal en nombres de media), tamaños extremos.
-3. Benchmarks `criterion` + presupuesto de rendimiento en CI (regresión > 20 % bloquea).
-4. `cargo audit`/`cargo deny` en CI (licencias + vulnerabilidades); `cargo bloat` informativo.
-5. Ampliar corpus con documentos reales variados (informes, plantillas corporativas, hojas
-   financieras) y publicar la **matriz de fidelidad** por rasgo en la documentación.
-6. Revisión de seguridad: el servidor MCP nunca escribe fuera de los directorios indicados;
-   normalización de rutas; sin ejecución de contenido del documento (macros ignoradas SIEMPRE —
-   los `.docm/.xlsm` se leen como sus equivalentes sin macros, con advertencia).
-
-Criterios de aceptación:
-- [ ] 72 h de fuzzing acumulado sin crashes en los 4 parsers.
-- [ ] Suite adversaria completa en verde.
-- [ ] Matriz de fidelidad publicada y ≥ objetivos por fase.
-
----
-
-## Fase 9 — v1.0 y backlog post-1.0 (1 semana + continuo)
-
-**Cierre v1.0**: congelar CLI y formato DocMark 1.0 estable, release notes, anuncio.
-
-Backlog priorizado post-1.0 (no comprometido):
-- Traducción de dialectos de fórmula OOXML ⇄ OpenFormula (riesgo R5).
-- PowerPoint (`.pptx`/`.odp`) → DocMark de solo lectura.
-- Conversión WMF/EMF → PNG/SVG (crate `emf`/librería propia o fallback).
-- Comentarios y control de cambios (`w:ins`/`w:del`) como extensiones DocMark (sintaxis CriticMarkup).
-- Tool MCP de edición incremental (`apply_edits`).
-- Modo biblioteca: publicar `docsai-convert` como crate estable para terceros + bindings WASM.
-- Escritura `.doc`/`.xls` vía LibreOffice fallback si hay demanda.
-
----
-
-## Resumen de calendario (orientativo, 1 desarrollador senior)
-
-| Fase | Duración | Acumulado |
-|---|---|---|
-| 0 Fundamentos | 2–3 sem | 3 |
-| 1 DOCX lectura | 4–6 sem | 9 |
-| 2 DOCX escritura + round-trip | 3–5 sem | 14 |
-| 3 XLSX/XLS | 4–5 sem | 19 |
-| 4 ODF | 3–4 sem | 22* |
-| 5 DOC | 2–3 sem | 22* (*paralelas 4‖5 con 2 devs) |
-| 6 CLI + distribución | 2–3 sem | 25 |
-| 7 MCP | 2 sem | 27 |
-| 8 Endurecimiento | 2–3 sem | 30 |
-| 9 v1.0 | 1 sem | ~31 sem (~7 meses; ~5–5,5 con 2 devs desde Fase 3) |
-
-## Métricas de seguimiento del proyecto
-
-- **Fidelidad por categoría** (comando `roundtrip` sobre corpus): objetivo ≥ 95 % OOXML, ≥ 90 % ODF.
-- **Raw-blocks por documento del corpus real**: tendencia descendente por fase.
-- **Cobertura de tests** de los crates de biblioteca ≥ 80 %.
-- **Rendimiento**: presupuestos de `arquitectura.md` §8 en CI.
diff --git a/docs/spikes/R1-docx-strategy.md b/docs/spikes/R1-docx-strategy.md
new file mode 100644
index 0000000..48065b9
--- /dev/null
+++ b/docs/spikes/R1-docx-strategy.md
@@ -0,0 +1,157 @@
+# Spike R1 — DOCX reading strategy
+
+**Risk mitigated**: R1 from technical analysis §6 — *«The OOXML style cascade turns out more
+expensive than expected and delays Phase 1»*.
+
+**Question**: is `docx-rs` (+ a custom complement with `quick-xml` where it falls short) enough
+for Phase 1, or is a full custom OOXML parser required?
+
+**Date**: August 2026 · **Version evaluated**: `docx-rs` 0.4.22 · **Toolchain**: rustc 1.94.1
+
+**Decision**: **custom parser on `zip` + `quick-xml`.** `docx-rs` is not used on the read path.
+It is kept as an XML mapping reference and as a possible base for the Phase 2 *writer*
+(independent decision, to be revisited in due course).
+
+---
+
+## 1. Method
+
+The Phase 0 corpus was generated (`corpus/generate.py`) and read with `docx_rs::read_docx`,
+serializing the result to JSON to inspect what information survives. Each trait was checked
+against what the DocMark specification and the IR in `architecture.md` §3 require.
+
+Additionally the reader was subjected to 903 synthetic corrupt inputs (truncations every 7 bytes
+and single-byte flips every 13 bytes on `images-floating.docx`) capturing *panics*.
+
+Documents used: `basic-styles`, `custom-styles`, `nested-lists`, `footnotes`, `fields-raw`,
+`headers-footers`, `images-inline`, `images-floating`, `images-transformed`, `images-vml`.
+
+## 2. Results
+
+### 2.1 What `docx-rs` does resolve
+
+| Trait | Status | Note |
+|---|---|---|
+| `styles.xml` with `docDefaults` | ✅ | `runPropertyDefault` and `paragraphPropertyDefault` exposed |
+| `basedOn`, `styleType`, `name` | ✅ | Enough to rebuild inheritance |
+| Paragraph/run formatting as a **delta** | ✅ | The model separates `property.style` from direct formatting, which is exactly the «reference + delta» principle |
+| `numbering.xml` | ✅ | `abstractNums` + `numberings` + levels with `format`, `lvlText`, indentation |
+| Headers and footers | ✅ | Resolved and attached to `sectionProperty` (`header`, `firstHeader`, `footer`) |
+| `sectPr` (size, margins, `titlePg`) | ✅ | `columns` is exposed but not the rest of `w:cols` |
+| Complex fields (`fldChar`/`instrText`) | ✅ | `instrTextString` preserved |
+| Tables with `gridSpan`/`vMerge` | ✅ | Present in `tableCellProperty` |
+
+The 4-level cascade **is solvable** with what it exposes: risk R1, as originally framed (the
+*styles*), does not materialize. It is the rest that fails.
+
+### 2.2 What `docx-rs` loses
+
+Measured on the corpus, not inferred from documentation.
+
+**Images** — the `Pic` model exposes `size`, `positionType`, `positionH/V`, `relativeFromH/V`,
+`distT/B/L/R`, `relativeHeight`, and `rot`. It does not expose:
+
+| DocMark §3.5 attribute | OOXML origin | In `docx-rs` |
+|---|---|---|
+| `wrap`, `wrap-side` | `wp:wrapSquare/Tight/Through/TopAndBottom` | ❌ absent |
+| `anchor=behind` | `wp:anchor @behindDoc` | ❌ absent |
+| `crop` | `a:srcRect` | ❌ absent |
+| `flip` | `a:xfrm @flipH/@flipV` | ❌ absent |
+| `rotation` | `a:xfrm @rot` | ⚠️ field `rot: u16` present but returns `0` for `rot="2700000"` (45°); also `u16` cannot represent 60000ths of a degree nor negative values |
+| alt (`![…]`) | `wp:docPr @descr` | ❌ absent |
+| `title`, `name` | `wp:docPr @title/@name` | ❌ absent |
+| `link` | `a:hlinkClick` | ❌ absent |
+| `external-src` | `r:link` | ❌ absent |
+| `border` | `pic:spPr/a:ln` | ❌ absent |
+| media bytes | `word/media/*` | ❌ not loaded on read (`image` is «for writer only») |
+
+**Legacy VML** (`w:pict`, `images-vml.docx`): collapses to a generic `shape` node of 813 bytes
+of total JSON; the `r:id` of `v:imagedata`, the `style` (position and size), the `alt`, and
+`w10:wrap` are lost. Total loss of the object.
+
+**Footnotes** (`footnotes.docx`): `w:footnoteReference` is discarded — the run ends with
+`children: []`. `word/footnotes.xml` is not exposed in the API.
+
+**Simple fields** (`fields-raw.docx`): `w:fldSimple` loses the `w:instr` attribute; only the
+cached text remains. «Date: 01/01/2026» stops being a `DATE` field.
+
+**Fidelity escape hatch**: `w:sdt` is represented as `structuredDataTag` with `alias: null` and
+without the original XML. There is no generic mechanism that preserves the bytes of an unknown
+element, which is exactly what the `raw-block` of the spec §7 and the measurable coverage
+criterion of Phase 1 (task 9) need.
+
+**Noise in the model**: every style read comes out with a `tableProperty` with invented borders
+(`single/2/000000`) even when the style is paragraph — it would have to be filtered so as not to
+contaminate the front-matter catalog.
+
+### 2.3 Robustness against corrupt input
+
+```
+903 corrupt inputs (truncations + byte flips)
+  → Ok: 88   Err: 611   PANIC: 204
+```
+
+23% of corrupt inputs cause a *panic*. The Phase 1 acceptance criterion is explicit: *«Zero
+panics with synthetic corrupt corpus (truncated ZIP, malformed XML): always `Err`»*. Wrapping the
+whole reader in `catch_unwind` is not an acceptable mitigation (it does not work with
+`panic=abort`, and `AGENTS.md` §6 requires parsers to return `Err`, not to recover).
+
+## 3. Analysis
+
+The custom complement needed to close the gaps includes: all of `w:drawing` (full DrawingML),
+all of `w:pict` (VML), `word/footnotes.xml`, `w:fldSimple`, capture of unknown elements for
+raw-blocks, and loading `word/media/*`. That is: **the bulk of `document.xml`**. What would
+remain delegated to `docx-rs` is `styles.xml`, `numbering.xml`, and the paragraph/table tree —
+the most mechanical and best-documented part of the format.
+
+Keeping both paths also implies:
+
+- Two XML parsers in the binary (`xml-rs` inside `docx-rs`, `quick-xml` in ours).
+- Reconciling two distinct trees of the same `document.xml` (`docx-rs`'s and ours for
+  drawings/fields), with the risk of position desynchronization.
+- A dependency we rely on for the easy part and not the hard part, with a *panic* risk that must
+  be assumed or patched upstream.
+
+## 4. Decision
+
+**Custom parser on `zip` + `quick-xml`** in `docsai-office`, with these consequences:
+
+1. **No `docx-rs` in `docsai-office`.** Noted in `technical-analysis.md` §4.1 per the
+   `AGENTS.md` §2 rule (a key dependency is not replaced without leaving a record).
+2. **A single pass** over `document.xml` with event-mode `quick-xml`, producing the IR
+   directly and capturing any unrecognized element as a raw-block, with its part and path. This
+   makes coverage measurable from day one.
+3. **No `unwrap`/`expect`/unchecked indexes** on the read path: every error is a typed
+   `ReadError`. The «zero panics» criterion is verified with a synthetic corruption test
+   equivalent to this spike's, run in CI from Phase 1.
+4. **`quick-xml` with external entities disabled** (default behavior: does not expand external
+   entities), which advances part of Phase 8.
+5. The estimated cost of the custom parser (≈2 of the 4–6 weeks of Phase 1) is comparable to the
+   complement that would have to be written anyway, and eliminates tree reconciliation.
+
+### Risks this decision introduces
+
+| Risk | Mitigation |
+|---|---|
+| More custom surface to maintain | Corpus + golden tests from Phase 0; the parser covers only what the IR models, the rest goes to raw-block |
+| OOXML traits forgotten through ignorance | Generic capture of unknown elements makes them **visible** (warning + raw-block) instead of silent |
+| The Phase 2 writer might need `docx-rs` | Independent later decision; writing is much simpler than reading (we control the output XML) and will likely also be done by hand |
+
+## 5. Status of risk R1
+
+**Closed.** The style cascade is not the bottleneck; the image model was, and the custom-parser
+decision neutralizes it. R8 (diversity of image models) is covered by the same decision:
+DrawingML and VML are read in the same pass into `ImageGeometry`.
+
+## 6. Reproducing this spike
+
+The probe program lived outside the tree (a discarded dependency is not versioned). To
+reproduce:
+
+```bash
+python3 corpus/generate.py
+cargo new /tmp/spike-docx && cd /tmp/spike-docx
+cargo add docx-rs@0.4.22 serde_json
+# read corpus/docx documents with read_docx() and serialize `docx.document` to JSON;
+# for the robustness test, truncate and flip bytes of the .docx and count catch_unwind(Err)
+```
diff --git a/docs/spikes/R1-estrategia-docx.md b/docs/spikes/R1-estrategia-docx.md
deleted file mode 100644
index 6e0eb8f..0000000
--- a/docs/spikes/R1-estrategia-docx.md
+++ /dev/null
@@ -1,157 +0,0 @@
-# Spike R1 — Estrategia de lectura DOCX
-
-**Riesgo mitigado**: R1 del análisis técnico §6 — *«La cascada de estilos OOXML resulta más
-costosa de lo previsto y retrasa Fase 1»*.
-
-**Pregunta**: ¿basta `docx-rs` (+ complemento propio con `quick-xml` donde falte) para la
-Fase 1, o hace falta un parser OOXML propio completo?
-
-**Fecha**: agosto 2026 · **Versión evaluada**: `docx-rs` 0.4.22 · **Toolchain**: rustc 1.94.1
-
-**Decisión**: **parser propio sobre `zip` + `quick-xml`.** `docx-rs` no se usa en el camino de
-lectura. Se mantiene como referencia de mapeo XML y como posible base del *writer* de Fase 2
-(decisión independiente, a revisar en su momento).
-
----
-
-## 1. Método
-
-Se generó el corpus de la Fase 0 (`corpus/generate.py`) y se leyó con `docx_rs::read_docx`,
-serializando el resultado a JSON para inspeccionar qué información sobrevive. Se comprobó
-rasgo a rasgo contra lo que exige la especificación DocMark y el IR de `arquitectura.md` §3.
-
-Adicionalmente se sometió al lector a 903 entradas corruptas sintéticas (truncados cada 7 bytes
-y volteos de un byte cada 13 bytes sobre `images-floating.docx`) capturando *panics*.
-
-Documentos usados: `basic-styles`, `custom-styles`, `nested-lists`, `footnotes`, `fields-raw`,
-`headers-footers`, `images-inline`, `images-floating`, `images-transformed`, `images-vml`.
-
-## 2. Resultados
-
-### 2.1 Lo que `docx-rs` sí resuelve
-
-| Rasgo | Estado | Nota |
-|---|---|---|
-| `styles.xml` con `docDefaults` | ✅ | `runPropertyDefault` y `paragraphPropertyDefault` expuestos |
-| `basedOn`, `styleType`, `name` | ✅ | Suficiente para reconstruir la herencia |
-| Formato de párrafo/run como **delta** | ✅ | El modelo separa `property.style` del formato directo, que es exactamente el principio «referencia + delta» |
-| `numbering.xml` | ✅ | `abstractNums` + `numberings` + niveles con `format`, `lvlText`, indentación |
-| Cabeceras y pies | ✅ | Resueltos y adjuntos a `sectionProperty` (`header`, `firstHeader`, `footer`) |
-| `sectPr` (tamaño, márgenes, `titlePg`) | ✅ | `columns` se expone pero no el resto de `w:cols` |
-| Campos complejos (`fldChar`/`instrText`) | ✅ | `instrTextString` conservado |
-| Tablas con `gridSpan`/`vMerge` | ✅ | Presentes en `tableCellProperty` |
-
-La cascada de 4 niveles **es resoluble** con lo que expone: el riesgo R1, tal como estaba
-formulado (los *estilos*), no se materializa. Es el resto lo que falla.
-
-### 2.2 Lo que `docx-rs` pierde
-
-Medido sobre el corpus, no inferido de la documentación.
-
-**Imágenes** — el modelo `Pic` expone `size`, `positionType`, `positionH/V`, `relativeFromH/V`,
-`distT/B/L/R`, `relativeHeight` y `rot`. No expone:
-
-| Atributo DocMark §3.5 | Origen OOXML | En `docx-rs` |
-|---|---|---|
-| `wrap`, `wrap-side` | `wp:wrapSquare/Tight/Through/TopAndBottom` | ❌ ausente |
-| `anchor=behind` | `wp:anchor @behindDoc` | ❌ ausente |
-| `crop` | `a:srcRect` | ❌ ausente |
-| `flip` | `a:xfrm @flipH/@flipV` | ❌ ausente |
-| `rotation` | `a:xfrm @rot` | ⚠️ campo `rot: u16` presente pero devuelve `0` para `rot="2700000"` (45°); además `u16` no puede representar 60000ᵃᵛᵒˢ de grado ni valores negativos |
-| alt (`![…]`) | `wp:docPr @descr` | ❌ ausente |
-| `title`, `name` | `wp:docPr @title/@name` | ❌ ausente |
-| `link` | `a:hlinkClick` | ❌ ausente |
-| `external-src` | `r:link` | ❌ ausente |
-| `border` | `pic:spPr/a:ln` | ❌ ausente |
-| bytes del medio | `word/media/*` | ❌ no se cargan al leer (`image` es «for writer only») |
-
-**VML legado** (`w:pict`, `images-vml.docx`): se colapsa a un nodo `shape` genérico de 813 bytes
-de JSON total; se pierden el `r:id` de `v:imagedata`, el `style` (posición y tamaño), el `alt`
-y el `w10:wrap`. Pérdida total del objeto.
-
-**Notas al pie** (`footnotes.docx`): `w:footnoteReference` se descarta — el run queda con
-`children: []`. `word/footnotes.xml` no se expone en la API.
-
-**Campos simples** (`fields-raw.docx`): `w:fldSimple` pierde el atributo `w:instr`; solo queda
-el texto cacheado. «Fecha: 01/01/2026» deja de ser un campo `DATE`.
-
-**Escotilla de fidelidad**: `w:sdt` se representa como `structuredDataTag` con `alias: null` y
-sin el XML original. No hay ningún mecanismo genérico que conserve los bytes de un elemento
-desconocido, que es justo lo que necesita el `raw-block` de la spec §7 y el criterio de
-cobertura medible de la Fase 1 (tarea 9).
-
-**Ruido en el modelo**: cada estilo leído sale con un `tableProperty` con bordes inventados
-(`single/2/000000`) aunque el estilo sea de párrafo — habría que filtrarlo para no contaminar
-el catálogo del front matter.
-
-### 2.3 Robustez frente a entrada corrupta
-
-```
-903 entradas corruptas (truncados + volteos de byte)
-  → Ok: 88   Err: 611   PANIC: 204
-```
-
-Un 23 % de las entradas corruptas provoca *panic*. El criterio de aceptación de la Fase 1 es
-explícito: *«Cero pánicos con corpus corrupto sintético (ZIP truncado, XML malformado): siempre
-`Err`»*. Envolver todo el reader en `catch_unwind` no es una mitigación aceptable (no funciona
-con `panic=abort`, y `AGENTS.md` §6 exige que los parsers devuelvan `Err`, no que se recuperen).
-
-## 3. Análisis
-
-El complemento propio que haría falta para cerrar los huecos incluye: todo `w:drawing`
-(DrawingML completo), todo `w:pict` (VML), `word/footnotes.xml`, `w:fldSimple`, la captura de
-elementos desconocidos para raw-blocks y la carga de `word/media/*`. Es decir: **el grueso de
-`document.xml`**. Lo que quedaría delegado en `docx-rs` es `styles.xml`, `numbering.xml` y el
-árbol de párrafos/tablas — la parte más mecánica y mejor documentada del formato.
-
-Mantener las dos rutas implica además:
-
-- Dos parsers XML en el binario (`xml-rs` dentro de `docx-rs`, `quick-xml` en el nuestro).
-- Reconciliar dos árboles distintos del mismo `document.xml` (el de `docx-rs` y el nuestro para
-  drawings/campos), con el riesgo de desincronización de posiciones.
-- Una dependencia de la que dependemos para lo fácil y no para lo difícil, con un riesgo de
-  *panic* que hay que asumir o parchear aguas arriba.
-
-## 4. Decisión
-
-**Parser propio sobre `zip` + `quick-xml`** en `docsai-office`, con estas consecuencias:
-
-1. **Sin `docx-rs` en `docsai-office`.** Se anota en `analisis-tecnico.md` §4.1 conforme a la
-   regla de `AGENTS.md` §2 (no se sustituye una dependencia clave sin dejar constancia).
-2. **Un solo recorrido** de `document.xml` con `quick-xml` en modo evento, que produce el IR
-   directamente y captura como raw-block cualquier elemento no reconocido, con su parte y su
-   ruta. Esto hace la cobertura medible desde el primer día.
-3. **Sin `unwrap`/`expect`/índices sin comprobar** en el camino de lectura: todo error es un
-   `ReadError` tipado. El criterio «cero pánicos» se verifica con un test de corrupción
-   sintética equivalente al de este spike, ejecutado en CI desde la Fase 1.
-4. **`quick-xml` con entidades externas deshabilitadas** (comportamiento por defecto: no expande
-   entidades externas), lo que adelanta parte de la Fase 8.
-5. El coste estimado del parser propio (≈2 semanas de las 4–6 de la Fase 1) es comparable al del
-   complemento que habría que escribir de todos modos, y elimina la reconciliación de árboles.
-
-### Riesgos que introduce esta decisión
-
-| Riesgo | Mitigación |
-|---|---|
-| Más superficie propia que mantener | Corpus + golden tests desde la Fase 0; el parser cubre solo lo que el IR modela, el resto va a raw-block |
-| Rasgos OOXML olvidados por desconocimiento | La captura genérica de elementos desconocidos los hace **visibles** (advertencia + raw-block) en vez de silenciosos |
-| El writer de Fase 2 podría necesitar `docx-rs` | Decisión independiente y posterior; escribir es mucho más simple que leer (controlamos el XML de salida) y probablemente también se haga a mano |
-
-## 5. Estado del riesgo R1
-
-**Cerrado.** La cascada de estilos no es el cuello de botella; el modelo de imágenes sí lo era, y
-la decisión de parser propio lo neutraliza. R8 (diversidad de modelos de imagen) queda cubierto
-por la misma decisión: DrawingML y VML se leen en el mismo recorrido hacia `ImageGeometry`.
-
-## 6. Reproducir este spike
-
-El programa de sondeo vivió fuera del árbol (no se versiona una dependencia que hemos
-descartado). Para reproducirlo:
-
-```bash
-python3 corpus/generate.py
-cargo new /tmp/spike-docx && cd /tmp/spike-docx
-cargo add docx-rs@0.4.22 serde_json
-# leer los documentos de corpus/docx con read_docx() y serializar `docx.document` a JSON;
-# para la prueba de robustez, truncar y voltear bytes del .docx y contar catch_unwind(Err)
-```
diff --git a/docs/technical-analysis.md b/docs/technical-analysis.md
new file mode 100644
index 0000000..92cf109
--- /dev/null
+++ b/docs/technical-analysis.md
@@ -0,0 +1,256 @@
+# Technical analysis
+
+Pre-development analysis document for `docsai`. Covers: (1) input/output formats and their real
+complexity, (2) the state of the art in comparable open-source projects, (3) candidate extended
+Markdown variants as pivot format, (4) evaluation of available Rust libraries, and (5) decisions
+taken with their risks.
+
+Analysis date: August 2026.
+
+---
+
+## 1. Input/output formats
+
+### 1.1 OOXML: `.docx` and `.xlsx` (ECMA-376 / ISO 29500)
+
+Both are ZIP containers with XML inside. They are the formats with the best public documentation
+and library support, and therefore anchor phases 1–3 of the plan.
+
+**`.docx` (WordprocessingML)** — relevant parts inside the ZIP:
+
+| Part | Content | Relevance for docsai |
+|---|---|---|
+| `word/document.xml` | Body: paragraphs (`w:p`), runs (`w:r`), tables (`w:tbl`) | Core of the conversion |
+| `word/styles.xml` | Style catalog (paragraph, character, table) + `basedOn` inheritance | Must be dumped into DocMark front matter |
+| `word/numbering.xml` | List definitions (numbering, bullets, levels) | Critical: lists in OOXML are not syntactically nested; they are rebuilt from `numId`/`ilvl` |
+| `word/media/*` | Embedded images (png, jpeg, gif, **wmf/emf**) | Extract to `assets/` |
+| `word/_rels/*.rels` | Relationships (images, hyperlinks) | Reference resolution |
+| `word/header*.xml`, `word/footer*.xml` | Headers and footers | Dedicated DocMark containers |
+| `docProps/core.xml`, `docProps/app.xml` | Properties (title, author, dates…) | Front matter |
+| `word/settings.xml`, `w:sectPr` sections | Page size, margins, columns | Section metadata |
+
+Known hard points of `.docx`:
+- **4-level formatting inheritance**: document defaults → paragraph style → character style →
+  direct formatting (`rPr`/`pPr`). For a faithful conversion you must *resolve* the cascade but
+  *store* only the style reference + direct deltas (if everything is flattened, the inverse
+  conversion produces monstrous documents with no reusable styles).
+- **Lists**: rebuild the tree from flat `(numId, ilvl)` pairs.
+- **Fields** (`w:fldSimple`, `w:instrText`): TOC, cross-references, page numbers. Preserved as
+  raw-blocks in v1.
+- **WMF/EMF images**: legacy Windows vector formats without simple multiplatform rendering
+  support. Strategy: extract as-is + warning; optional conversion in later phases.
+- **Revisions/comments** (`w:ins`, `w:del`, `w:comment*`): out of scope for v1; documents with
+  revisions are accepted by taking the "accepted" version and emitting a warning.
+
+**`.xlsx` (SpreadsheetML)** — relevant parts: `xl/workbook.xml`, `xl/worksheets/sheet*.xml`,
+`xl/sharedStrings.xml`, `xl/styles.xml` (number formats, fonts, fills, borders — all via cross
+indexes), `xl/calcChain.xml`.
+
+Hard points of `.xlsx`:
+- **Cells store cached value + formula** (`<c><f>SUM(A1:A3)</f><v>42</v></c>`). DocMark must keep
+  both: the formula for bidirectionality, the value for readability.
+- **Shared formulas** (`t="shared"`) and array formulas (`t="array"`): expand them or preserve
+  their range metadata.
+- **Number formats** (`numFmt`): the difference between `45123` and `15/07/2023` — Excel dates
+  are serial numbers + format. Keeping `numFmtId`/format code per cell is mandatory to avoid
+  corrupting data on round-trip.
+- Merged cells (`mergeCells`), column widths/row heights, frozen panes, validations, conditional
+  formatting (the last three: metadata in v1, no semantics).
+
+### 1.2 ODF: `.odt` and `.ods` (ISO 26300, OASIS OpenDocument)
+
+Also ZIP+XML (`content.xml`, `styles.xml`, `meta.xml`, `settings.xml`, `Pictures/`). Conceptual
+model very similar to OOXML but with important differences:
+
+- **Automatic styles** (`office:automatic-styles`) represent direct formatting: every fragment
+  with manual formatting generates an anonymous style. They must be "de-automated" on read
+  (map automatic styles to direct-formatting deltas in the IR).
+- `.ods` formulas use **OpenFormula** with a namespace prefix (`of:=SUM([.A1:.A3])`) and a
+  different reference syntax (`[.A1]` vs `A1`). For OOXML⇄ODF bidirectionality, formula syntax
+  would need translating; in v1 the formula is kept in its original dialect, annotating
+  `formula-dialect` on the cell.
+- ODF is better specified and more regular than OOXML; the effort of a custom parser with
+  `quick-xml` is manageable and is in fact the plan for `.odt` (see §4.3).
+
+### 1.3 Legacy binary formats: `.doc` (MS-DOC) and `.xls` (BIFF8)
+
+- **`.xls`**: solved — `calamine` reads it natively (values and formulas). Read-only.
+- **`.doc`**: the project's largest technical risk. It is a binary format on an OLE2/CFB
+  container with complex internal structures (piece table, FIB, FKPs…). **No mature Rust crate
+  reads it with styles and images.** Options evaluated:
+
+| Option | Effort | Fidelity | Dependencies |
+|---|---|---|---|
+| Custom parser on the `cfb` crate (MS-DOC spec) | Very high (months) | High | No external deps |
+| Fallback to LibreOffice headless (`soffice --headless --convert-to docx`) and reuse the docx pipeline | Low | Very high | LibreOffice installed (optional, detected at runtime) |
+| `antiword`/`wvWare` as external process | Low | Low (loses styles) | External binary |
+| Custom plain-text extraction (piece table only) | Medium | Text only | None |
+
+  **Decision**: two-level strategy. (a) LibreOffice headless fallback if installed — maximum
+  fidelity with minimum effort; (b) native text+basic-structure extractor on `cfb` as a degraded
+  mode without dependencies. A full MS-DOC parser is not pursued unless real demand justifies it.
+  This keeps the principle "single binary with no mandatory external runtime": LibreOffice
+  improves `.doc` but is never a requirement.
+
+### 1.4 Images and graphic objects: cross-cutting analysis
+
+Images are a first-class project requirement: **all** input formats carry them, with different
+geometry models, and conversion must extract them and preserve size, position, anchor, and other
+properties for round-trip. Model by format:
+
+| Format | Where they live | Geometry/anchor model |
+|---|---|---|
+| `.docx` | `word/media/*` + `<w:drawing>` (DrawingML) or `<w:pict>` (legacy VML) | `wp:inline` (inline, only `wp:extent`) or `wp:anchor` (floating: position relative to page/margin/paragraph/character, EMU offsets, wrap `square/tight/through/topAndBottom/none`, z-order, `behindDoc`) |
+| `.xlsx` | `xl/media/*` + `xl/drawings/drawing*.xml` (SpreadsheetDrawingML) | Three anchors: `xdr:twoCellAnchor` (cell to cell + offsets, stretches with the grid), `xdr:oneCellAnchor` (origin cell + fixed size), `xdr:absoluteAnchor` (absolute position in EMU) |
+| `.odt` | `Pictures/*` + `<draw:frame><draw:image>` | `text:anchor-type` = `as-char/char/paragraph/page/frame`; `svg:width/height/x/y`; wrap via graphic style (`style:wrap`) |
+| `.ods` | `Pictures/*` + `<draw:frame>` inside `<table:shapes>` or cell-anchored | Cell anchor (`table:end-cell-address` + offsets) or sheet anchor |
+| `.doc` | `Data`/Escher stream (OfficeArt) | Binary Escher; on the LibreOffice-fallback path conversion is free; on the degraded native path BLIPs (images) are extracted without fine geometry |
+
+Properties to preserve in all cases (they define the IR's normalized model; see
+`architecture.md` §3.1): displayed dimensions vs native bitmap dimensions (and thus the scale
+factor), DPI, crop (`srcRect` in OOXML, `fo:clip` in ODF), rotation and flips, anchor and
+position with their offsets, text wrap mode, Z-order, alternative text and title (accessibility,
+`descr`/`svg:desc`), internal object name and hyperlink on the image.
+
+Specific hard points:
+- **Heterogeneous coordinates**: EMU in OOXML (914,400/inch), cm/in in ODF, twips in `.doc`.
+  The IR normalizes everything to EMU with newtypes; DocMark exposes readable `px`/`pt`/`cm`.
+- **Legacy VML in docx**: old documents (or converted from `.doc`) use `<w:pict>` with VML
+  instead of DrawingML. Both must be readable; writing always emits DrawingML.
+- **twoCell anchors in xlsx**: real size depends on column widths/row heights; to preserve
+  geometry the symbolic anchor (cells + offsets) must be stored, not the resolved size — and the
+  inverse on write.
+- **WMF/EMF**: extracted as-is (perfect round-trip) but not viewable in Markdown viewers;
+  conversion to PNG/SVG stays in the post-1.0 backlog. The image is still referenced with its
+  full geometry.
+- **Duplicates**: the same bitmap may appear N times with different geometries; the
+  `AssetStore` deduplicates by content hash and each appearance keeps its own geometry.
+- **Linked (non-embedded) images**: OOXML/ODF allow external `r:link`/`xlink:href`; the URL is
+  preserved with a warning (remote content is not downloaded — security implication).
+
+---
+
+## 2. Open-source state of the art (what to learn and reuse)
+
+| Project | Language | What it does | Lessons for docsai |
+|---|---|---|---|
+| **Pandoc** | Haskell | Universal conversion via pivot AST; its extended Markdown (attributes `{...}`, divs `:::`, front matter) is the most expressive on the market | The full architectural pattern: readers → AST → writers. Its attribute syntax is the base of DocMark. Known limitation: medium-low fidelity on complex docx (custom styles, text boxes) and no xlsx support |
+| **MarkItDown** (Microsoft) | Python | Office/PDF/HTML → "LLM-ready" Markdown, unidirectional | Validates demand for the MCP/LLM use case; its total loss of styles is exactly the gap docsai fills |
+| **Docling** (IBM) | Python | Documents → Markdown/JSON with its own `DoclingDocument` model | Confirms the need for a rich document model as pivot and for exporting both readable MD + structured metadata |
+| **mammoth** (.js/Python) | JS/Python | docx → semantic HTML via a **configurable style map** (`Heading1 ⇒ h1`) | The user-configurable style-map concept is adopted in docsai (`--style-map`) |
+| **html2md / turndown, marker, unoconv/unoserver** | various | Partial converters | unoserver documents the LibreOffice headless fallback pattern |
+| **rdocx** | Rust | docx read/write + render to PDF/HTML/MD (recent crate, 2026) | Watch as an alternative; too young to anchor the project today |
+
+**State-of-the-art conclusion**: nobody today combines (1) native binary with no runtime,
+(2) bidirectionality with styles, (3) spreadsheets with formulas, and (4) an MCP server.
+Pandoc is the reference ceiling for text; MarkItDown/Docling for LLM integration. docsai
+positions itself in the empty intersection.
+
+---
+
+## 3. The pivot format: evaluated extended Markdown variants
+
+Requirements: readable by humans and standard viewers, arbitrary attributes on inline and block,
+document metadata, extensible without breaking parsers, and with an ecosystem.
+
+| Candidate | Attributes | Ecosystem | Verdict |
+|---|---|---|---|
+| **Pure CommonMark + GFM** | ❌ None | Huge | Insufficient: without attributes there are no styles |
+| **Pandoc Markdown** (attributes + fenced divs + spans + YAML) | ✅ Complete | Large (pandoc consumes it) | **Chosen base.** Syntax proven for a decade for exactly this problem |
+| **MyST Markdown** | ✅ (directives/roles) | Scientific/Sphinx | More verbose directives; oriented to publishing, not round-trip |
+| **Djot** (Jyrki/MacFarlane) | ✅ native | Small | Technically superior but breaks "looks fine on GitHub" compatibility |
+| **MDX** | JSX | Web/React | Discarded: not readable Markdown for non-programmers |
+
+**Decision**: **DocMark = CommonMark + GFM (tables, strikethrough, task lists) + a subset of
+Pandoc extensions** (attributes `{...}` on headings/images/spans/code, fenced divs `:::`, YAML
+front matter) **+ custom extensions for spreadsheets** (cell metadata) documented in
+`docmark-specification.md`. Additional benefit: a DocMark file is processable by Pandoc
+directly with acceptable degradation, giving free interoperability with the whole Pandoc
+ecosystem (PDF via LaTeX, HTML, EPUB…).
+
+---
+
+## 4. Rust library evaluation
+
+### 4.1 Document read/write
+
+| Crate | Proposed role | Status (2026) | Evaluation notes |
+|---|---|---|---|
+| **`calamine`** | Read `.xls`, `.xlsx`, `.xlsb`, `.ods` (values **and formulas**) | Mature, maintained, widely used | Lazy and fast reading; reads formulas via `worksheet_formula()`. **Does not read styles/number formats in enough detail** → complemented with custom reading of `xl/styles.xml` |
+| **`umya-spreadsheet`** | Read+write `.xlsx` with styles | Maintained | Only crate that both reads AND writes xlsx with styles; parses the whole workbook in memory (cost on large files; `lazy_read` exists). Main candidate for xlsx **writing** |
+| **`rust_xlsxwriter`** | Write `.xlsx` (alternative) | Very maintained (port of XlsxWriter) | Excellent write API with formulas and formats, but write-only and does not allow "edit" — fine because docsai regenerates from IR. Decide vs umya in a Phase 3 spike |
+| **`docx-rs` (bokuweb)** | ~~Read~~ + possible write `.docx` | Most used (1M+ downloads) | **Discarded for reading** after spike R1 (`docs/spikes/R1-docx-strategy.md`, August 2026): handles styles and numbering well, but loses almost the entire image model (wrap, `behindDoc`, crop, flip, rotation, alt, title, hyperlink), footnotes and `w:instr` on simple fields, does not preserve unknown elements for raw-blocks, and *panics* on 23% of 903 measured corrupt inputs. docx reading uses a custom parser on `zip` + `quick-xml`. Still a candidate for the Phase 2 **writer**, an independent decision |
+| **`docx-rust`** | Alternative `.docx` reading | Less activity | More direct XML mapping; keep as reference |
+| **`spreadsheet-ods`** | Read+write `.ods` | Maintained | Covers ODS styles and formulas; avoids writing a custom ODF-spreadsheet writer |
+| **(none)** | `.odt` | — | No mature crate for ODT with styles: **custom parser/writer** on `zip` + `quick-xml` (ODF is regular; bounded effort) |
+| **`cfb`** | OLE2 container for legacy `.doc`/`.xls` | Stable | Base of the degraded `.doc` extractor |
+
+### 4.2 Markdown (inverse path)
+
+| Crate | Role | Notes |
+|---|---|---|
+| **`comrak`** | Markdown parser for the DocMark→IR pipeline | Full CommonMark+GFM, keeps positions, supports front matter, has limited attribute extension; full `{...}` attributes and fenced divs `:::` are processed in a custom pass over its AST (or pre-lexer) |
+| `markdown-rs` / `pulldown-cmark` | Alternatives | pulldown-cmark is faster but event-oriented (awkward for transformation); markdown-rs has a pleasant mdast AST but fewer native extensions |
+
+**Decision**: `comrak` + custom attributes/divs layer. The DocMark **serializer** (IR→MD) is
+hand-written (not delegated to comrak) to control output byte-by-byte and guarantee round-trip
+idempotence.
+
+### 4.3 Infrastructure
+
+| Crate | Role |
+|---|---|
+| `zip` | OOXML/ODF containers |
+| `quick-xml` (+ `serde`) | High-performance XML parsing where format crates fall short |
+| `serde` / `serde_yaml` / `serde_json` | Front matter, `inspect --json`, config |
+| `clap` (derive) | CLI |
+| `rmcp` (official MCP SDK, stdio transport) | MCP server; `#[tool]` macros; implements the 2026-07-28 spec with backward compatibility |
+| ~~`image`~~ | **Not used in Phase 1.** docsai never re-encodes a bitmap; it only needs to name and measure it, which is done by reading the format header (PNG, JPEG, GIF, BMP, TIFF, WebP, EMF, WMF) in `docsai-model::assets`, without a heavy dependency. Will be re-evaluated if some phase truly needs re-encoding |
+| ~~`serde_yaml`~~ | **Not used.** Front matter has a small known schema and the spec requires byte-for-byte determinism, so it is written by hand; the crate is also without active maintenance |
+| `thiserror` / `anyhow` | Errors |
+| `tracing` + `tracing-subscriber` | Logs (always to stderr) |
+| `tokio` | Only in `docsai-mcp` (rmcp requires it); the conversion core is synchronous |
+| ~~`insta`~~ | **Not used.** Golden files are `.expected.dmk.md` beside the corpus, as prescribed by `AGENTS.md` §6: they are reviewed as normal text in the diff and do not depend on a snapshot format |
+| `cargo-fuzz` | Parser fuzzing (Phase 8) |
+| `cargo-dist` | Multiplatform release packaging |
+
+---
+
+## 5. Derived architecture decisions (summary)
+
+1. **Mandatory pivot IR** (`docsai-model`): document tree with two possible roots
+   (`TextDocument`, `Workbook`) — detail in `architecture.md`. N formats → 2N converters
+   instead of N².
+2. **Styles by reference + delta**: the IR stores `style_id` + direct properties, and the full
+   style catalog travels in the front matter. Round-trip thus rebuilds a real `styles.xml` and
+   Markdown stays clean.
+3. **External assets with manifest**: images to `assets/` with deterministic names
+   (content hash) so round-trip does not duplicate media.
+4. **Structured `ConversionReport`**: every conversion returns document + list of typed
+   warnings (unsupported element, degradation, raw-block emitted). The CLI shows it; MCP returns
+   it in the tool response.
+5. **Optional external fallbacks**: LibreOffice headless only for `.doc`, detected at runtime
+   (`--use-loffice=auto|never|require`).
+
+## 6. Main risks and mitigations
+
+| # | Risk | Prob. | Impact | Mitigation |
+|---|---|---|---|---|
+| R1 | OOXML style cascade turns out more expensive than expected and delays Phase 1 | High | High | 1-week spike in Phase 0 with real documents; limit v1 to 4-level resolution without conditional `tblStyle` |
+| R2 | No xlsx crate covers style reading in enough detail | Medium | Medium | Already assumed: complementary custom reading of `xl/styles.xml` with quick-xml (bounded effort, documented format) |
+| R3 | Non-idempotent round-trip due to Markdown ambiguities (escapes, spaces) | Medium | High | Custom serializer with deterministic rules + idempotence test in CI from Phase 2 |
+| R4 | `.doc` without LibreOffice disappoints users | Medium | Low | Clear degraded-mode messages; document in README |
+| R5 | OOXML/OpenFormula formula dialect divergence | High | Medium | v1 keeps original dialect + `formula-dialect` field; automatic translation postponed (Phase 9/backlog) |
+| R6 | Third-party crates abandoned mid-project | Low | Medium | The four critical crates are among the most used in the ecosystem; IR design lets a reader be replaced without touching the rest |
+| R7 | Binary size grows out of control | Low | Low | `cargo bloat` in CI, optional features, LTO in release |
+| R8 | Diversity of image models (DrawingML vs VML vs Escher vs draw:frame) fragments effort | Medium | Medium | Normalized `ImageGeometry` model in the IR defined in Phase 0 (architecture §3.1); VML reading limited to model attributes; Escher only BLIPs on the native `.doc` path |
+
+## 7. Sources consulted
+
+- [Pandoc User's Guide](https://pandoc.org/MANUAL.html) — attribute, div, and front-matter syntax
+- [calamine (GitHub)](https://github.com/tafia/calamine) and [docs.rs/calamine](https://docs.rs/calamine)
+- [umya-spreadsheet (GitHub)](https://github.com/mathnya/umya-spreadsheet) and comparison [calamine vs umya-spreadsheet](https://umaranis.com/2026/05/04/reading-excel-files-in-rust-calamine-vs-umya-spreadsheet/)
+- [docx-rs (crates.io)](https://crates.io/crates/docx-rs) · [docx-rust (crates.io)](https://crates.io/crates/docx-rust) · [rdocx (lib.rs)](https://lib.rs/crates/rdocx)
+- [Official Rust MCP SDK — rmcp](https://github.com/modelcontextprotocol/rust-sdk) and [docs.rs/rmcp](https://docs.rs/rmcp)
+- Converter comparisons: [MarkItDown vs Pandoc](https://www.file2markdown.ai/blog/markitdown-vs-pandoc), [Docling vs MarkItDown](https://www.file2markdown.ai/blog/docling-vs-markitdown), [Real Python on MarkItDown](https://realpython.com/python-markitdown/)
+- ECMA-376 (OOXML), ISO/IEC 26300 (ODF), [MS-DOC]/[MS-XLS] Microsoft Open Specifications
diff --git a/kb/01-phases-0-1-summary.md b/kb/01-phases-0-1-summary.md
new file mode 100644
index 0000000..baa3855
--- /dev/null
+++ b/kb/01-phases-0-1-summary.md
@@ -0,0 +1,112 @@
+# 01 — Summary of phases 0 and 1
+
+## What you can do today
+
+```bash
+docsai convert report.docx -o report.dmk.md   # extracts assets/ next to the .md
+docsai convert report.docx                      # to stdout
+docsai convert report.docx --fidelity plain     # clean CommonMark for LLM/RAG
+docsai convert report.docx -o out.md --json     # conversion report as JSON
+docsai formats                                   # support matrix for this binary
+```
+
+A `.docx` goes in and a DocMark file comes out with:
+
+- **Document properties** (core, app, and custom) in the front matter.
+- Full **style catalog**, with `w:docDefaults` and the `basedOn` chain, without flattening.
+- **Paragraphs and runs**: bold, italic, strikethrough, underline (all seven styles), color,
+  highlight, font, size, sub/superscript, small caps, all caps, hyperlinks, line/page/column
+  breaks, and tabs.
+- **Lists** rebuilt as a tree from flat `(numId, ilvl)` pairs, with their typographic definition
+  in `list-definitions`.
+- **Tables** with `gridSpan` and `vMerge` resolved to `colspan`/`rowspan` and absorbed cells
+  marked; `::: {.table complex=true}` container for what GFM does not allow.
+- **Images** with full geometry: displayed and native size, inline or floating anchor,
+  position base per axis, offsets or symbolic alignment, text wrapping and side, Z-order,
+  rotation, flips, crop, border, alt text, title, internal name, and hyperlink.
+  Both DrawingML and **legacy VML**.
+- **Sections** split at each `sectPr`, with headers and footers by scope (default, first
+  page, even).
+- **Footnotes** inserted at their reference point.
+- **Simple and complex fields**, preserving the original instruction.
+- **Raw-blocks** with the exact bytes of every unrecognized OOXML element.
+
+What you **cannot** do yet: reverse conversion (Phase 2), spreadsheets (Phase 3), ODF
+(Phase 4), `.doc` (Phase 5), and the MCP server (Phase 7).
+
+## Phase 0 — Foundations
+
+| Plan task | Status |
+|---|---|
+| 1. Workspace with the 7 crates | ✅ |
+| 2. `docsai-model` v1 (IR, units, images, `AssetStore`, validator) | ✅ |
+| 3. Risk spike R1 | ✅ [`docs/spikes/R1-docx-strategy.md`](../docs/spikes/R1-docx-strategy.md) |
+| 4. Freeze DocMark spec v1.0 | ✅ annex A resolved, changelog in §10 |
+| 5. Initial corpus | ✅ 14 docx + 6 xlsx generated by `corpus/generate.py` |
+| 6. CI GitHub Actions on 3 OSes | ✅ build, test, corpus up to date, fmt, clippy, rustdoc |
+| 7. CLI skeleton | ✅ surpassed: the CLI already does full `convert` |
+
+**Acceptance criteria**: all four met and verified with tests
+(`cargo test --workspace` green, IR JSON round-trip with proptest, spike documented with
+signed decision, spec with no TODOs).
+
+## Phase 1 — DOCX reading → DocMark
+
+| Plan task | Status |
+|---|---|
+| 1. docx reader (ZIP, `document.xml`, relationships) | ✅ |
+| 2. Styles with reference + delta resolution | ✅ |
+| 3. Paragraphs and runs with all inline formatting from spec §3.2 | ✅ |
+| 4. Lists from `numbering.xml` | ✅ |
+| 5. Tables with spans, widths, and style | ✅ |
+| 6. DrawingML + VML images, with hash-based deduplication | ✅ |
+| 7. Sections, headers/footers, footnotes, fields, properties | ✅ |
+| 8. DocMark serializer with fidelity modes | ✅ |
+| 9. Raw-block + typed warning for the unrecognized | ✅ |
+| 10. Corpus golden tests + 5 anonymized real documents | ⚠️ goldens yes; real documents **pending** |
+
+**Acceptance criteria**, all verified by tests:
+
+- ✅ Corpus goldens pass, including the three image cases with full geometry.
+- ✅ Zero panics on synthetic corrupt corpus: 900+ inputs (truncated and byte-flipped)
+  return `Err` (`crates/docsai-office/tests/robustness.rs`).
+- ✅ 50+ page document in under 1 s with fewer than 10 raw-blocks.
+- ✅ `--fidelity plain` is clean CommonMark, verified by parsing it with comrak.
+
+## Metrics
+
+| | |
+|---|---|
+| Passing tests | 164 |
+| Production code | ~9,500 lines of Rust |
+| Test code | ~1,200 lines in integration files, plus `#[cfg(test)]` modules |
+| Corpus documents | 14 docx + 6 xlsx, with their 14 goldens |
+| Core external dependencies | `serde`, `thiserror`, `quick-xml`, `zip`, `tracing` |
+| `unsafe` | Zero (`#![forbid(unsafe_code)]` in all library crates) |
+
+## Three defects the corpus uncovered
+
+All three were on the fidelity path, and none would have been seen without running real
+documents through the pipeline:
+
+1. **Lossy length formatting.** A Word margin of 1417 twips was written as `2.499cm`
+   and re-reading it produced a different value: it would have shifted margins and images on
+   every round-trip. Now the first unit that represents the length **exactly** is chosen
+   (`px` → `cm` → `pt` → `emu`), and a test verifies it for each case.
+2. **Empty paragraphs disappeared silently.** A blank line does not survive Markdown.
+   In `full` mode they are now written as `[]{.empty}`.
+3. **Hyperlink style emitted twice**, inside and outside the tag.
+
+Additionally, the spike itself uncovered a bug in the corpus generator (`w:drawing` placed
+outside a `w:r`, which is invalid OOXML) before it contaminated the goldens.
+
+## What was left out, and why
+
+| Element | Reason |
+|---|---|
+| **Anonymized real documents** (Phase 1, task 10) | Requires having real documents available. Does not block Phase 2; the synthetic corpus already covers traits one by one |
+| **DrawingML text boxes** (`wps:txbx`) | Travel as raw-block. The `Block::TextBox` type exists in the IR and `::: {.textbox}` is in the spec, but emitting it without the writer that rebuilds it would advance Phase 2 work |
+| **Validation in Word and LibreOffice** | Phase 2 criterion (`.docx` files are not generated yet), and there is no LibreOffice in the environment |
+| **Comments and track changes** | Out of v1 scope per analysis §1.1. Revisions are taken as accepted and the count is reported |
+| **`w:lvlOverride` in lists** | Not modeled in v1; a `Degraded` warning is emitted |
+| **xlsx reader** | Phase 3. The corpus files already exist for then |
diff --git a/kb/01-resumen-fases-0-1.md b/kb/01-resumen-fases-0-1.md
deleted file mode 100644
index bf2d476..0000000
--- a/kb/01-resumen-fases-0-1.md
+++ /dev/null
@@ -1,112 +0,0 @@
-# 01 — Resumen de las fases 0 y 1
-
-## Qué se puede hacer hoy
-
-```bash
-docsai convert informe.docx -o informe.dmk.md   # extrae assets/ junto al .md
-docsai convert informe.docx                      # a stdout
-docsai convert informe.docx --fidelity plain     # CommonMark limpio para LLM/RAG
-docsai convert informe.docx -o out.md --json     # informe de conversión en JSON
-docsai formats                                   # matriz de soporte de este binario
-```
-
-Un `.docx` entra y sale un fichero DocMark con:
-
-- **Propiedades** del documento (core, app y personalizadas) en el front matter.
-- **Catálogo de estilos** completo, con `w:docDefaults` y la cadena `basedOn`, sin aplanar.
-- **Párrafos y runs**: negrita, cursiva, tachado, subrayado (los siete estilos), color,
-  resaltado, fuente, tamaño, sub/superíndice, versalitas, mayúsculas, hipervínculos, saltos de
-  línea, página y columna, y tabuladores.
-- **Listas** reconstruidas en árbol desde los pares planos `(numId, ilvl)`, con su definición
-  tipográfica en `list-definitions`.
-- **Tablas** con `gridSpan` y `vMerge` resueltos a `colspan`/`rowspan` y celdas absorbidas
-  marcadas; contenedor `::: {.table complex=true}` para lo que GFM no admite.
-- **Imágenes** con la geometría entera: tamaño mostrado y nativo, anclaje en línea o flotante,
-  base de posición por eje, offsets o alineación simbólica, ajuste de texto y lado, orden Z,
-  rotación, volteos, recorte, borde, texto alternativo, título, nombre interno e hipervínculo.
-  Tanto DrawingML como **VML heredado**.
-- **Secciones** partidas en cada `sectPr`, con cabeceras y pies por ámbito (defecto, primera
-  página, pares).
-- **Notas al pie** insertadas en el punto de su referencia.
-- **Campos** simples y complejos, conservando la instrucción original.
-- **Raw-blocks** con los bytes exactos de todo elemento OOXML no reconocido.
-
-Lo que **no** se puede hacer: la conversión inversa (Fase 2), hojas de cálculo (Fase 3), ODF
-(Fase 4), `.doc` (Fase 5) y el servidor MCP (Fase 7).
-
-## Fase 0 — Fundamentos
-
-| Tarea del plan | Estado |
-|---|---|
-| 1. Workspace con los 7 crates | ✅ |
-| 2. `docsai-model` v1 (IR, unidades, imágenes, `AssetStore`, validador) | ✅ |
-| 3. Spike de riesgo R1 | ✅ [`docs/spikes/R1-estrategia-docx.md`](../docs/spikes/R1-estrategia-docx.md) |
-| 4. Congelar la spec DocMark v1.0 | ✅ anexo A resuelto, registro de cambios en §10 |
-| 5. Corpus inicial | ✅ 14 docx + 6 xlsx generados por `corpus/generate.py` |
-| 6. CI GitHub Actions en 3 SO | ✅ build, test, corpus al día, fmt, clippy, rustdoc |
-| 7. Esqueleto de CLI | ✅ superado: la CLI ya hace `convert` completo |
-
-**Criterios de aceptación**: los cuatro cumplidos y verificados con tests
-(`cargo test --workspace` verde, round-trip JSON del IR con proptest, spike documentado con
-decisión firmada, spec sin TODO).
-
-## Fase 1 — Lectura DOCX → DocMark
-
-| Tarea del plan | Estado |
-|---|---|
-| 1. Reader docx (ZIP, `document.xml`, relaciones) | ✅ |
-| 2. Estilos con resolución referencia + delta | ✅ |
-| 3. Párrafos y runs con todo el formato inline de la spec §3.2 | ✅ |
-| 4. Listas desde `numbering.xml` | ✅ |
-| 5. Tablas con spans, anchos y estilo | ✅ |
-| 6. Imágenes DrawingML + VML, con deduplicación por hash | ✅ |
-| 7. Secciones, cabeceras/pies, notas al pie, campos, propiedades | ✅ |
-| 8. Serializador DocMark con modos de fidelidad | ✅ |
-| 9. Raw-block + advertencia tipada para lo no reconocido | ✅ |
-| 10. Golden tests del corpus + 5 documentos reales anonimizados | ⚠️ goldens sí; documentos reales **pendientes** |
-
-**Criterios de aceptación**, todos verificados por tests:
-
-- ✅ Los goldens del corpus pasan, incluidos los tres de imágenes con geometría completa.
-- ✅ Cero pánicos con corpus corrupto sintético: 900+ entradas (truncados y volteos de byte)
-  devuelven `Err` (`crates/docsai-office/tests/robustness.rs`).
-- ✅ Documento de 50+ páginas en menos de 1 s con menos de 10 raw-blocks.
-- ✅ `--fidelity plain` es CommonMark limpio, verificado parseándolo con comrak.
-
-## Métricas
-
-| | |
-|---|---|
-| Tests que pasan | 164 |
-| Código de producción | ~9 500 líneas de Rust |
-| Código de test | ~1 200 líneas en ficheros de integración, más los módulos `#[cfg(test)]` |
-| Documentos del corpus | 14 docx + 6 xlsx, con sus 14 goldens |
-| Dependencias externas del núcleo | `serde`, `thiserror`, `quick-xml`, `zip`, `tracing` |
-| `unsafe` | Cero (`#![forbid(unsafe_code)]` en todos los crates de biblioteca) |
-
-## Tres defectos que el corpus destapó
-
-Los tres estaban en el camino de la fidelidad, y ninguno se habría visto sin pasar documentos
-reales por el pipeline:
-
-1. **Formato de longitudes con pérdida.** Un margen de Word de 1417 twips se escribía `2.499cm`
-   y al releerlo daba un valor distinto: habría movido márgenes e imágenes en cada ida y vuelta.
-   Ahora se elige la primera unidad que representa la longitud de forma **exacta**
-   (`px` → `cm` → `pt` → `emu`), y hay un test que lo verifica para cada caso.
-2. **Párrafos vacíos desaparecían en silencio.** Una línea en blanco no sobrevive a Markdown.
-   En modo `full` se escriben ahora como `[]{.empty}`.
-3. **Estilo de hipervínculo emitido dos veces**, dentro y fuera de la etiqueta.
-
-Además, el propio spike destapó un error en el generador del corpus (`w:drawing` colocado fuera
-de un `w:r`, que es OOXML inválido) antes de que contaminara los goldens.
-
-## Qué quedó fuera, y por qué
-
-| Elemento | Motivo |
-|---|---|
-| **Documentos reales anonimizados** (Fase 1, tarea 10) | Requiere disponer de documentos reales. No bloquea la Fase 2; el corpus sintético ya cubre los rasgos uno a uno |
-| **Cuadros de texto DrawingML** (`wps:txbx`) | Viajan como raw-block. El tipo `Block::TextBox` existe en el IR y `::: {.textbox}` está en la spec, pero emitirlo sin el writer que lo reconstruya es adelantar trabajo de la Fase 2 |
-| **Validación en Word y LibreOffice** | Criterio de la Fase 2 (aún no se generan `.docx`), y no hay LibreOffice en el entorno |
-| **Comentarios y control de cambios** | Fuera de alcance de la v1 según el análisis §1.1. Las revisiones se toman como aceptadas y se reporta cuántas |
-| **`w:lvlOverride` en listas** | No modelado en v1; se emite advertencia `Degraded` |
-| **Lector xlsx** | Fase 3. Los ficheros del corpus ya existen para entonces |
diff --git a/kb/02-estructura-proyecto.md b/kb/02-estructura-proyecto.md
deleted file mode 100644
index 1bfc3fa..0000000
--- a/kb/02-estructura-proyecto.md
+++ /dev/null
@@ -1,155 +0,0 @@
-# 02 — Estructura del proyecto
-
-## Árbol
-
-```
-docsai/
-├── Cargo.toml                  # workspace: 7 miembros + dependencias compartidas
-├── .github/workflows/ci.yml    # build/test en 3 SO + fmt/clippy/rustdoc
-├── crates/
-│   ├── docsai-model/           # el IR. Sin I/O, sin dependencias pesadas
-│   ├── docsai-docmark/         # serializador DocMark (el parser es Fase 2)
-│   ├── docsai-office/          # lector .docx (xlsx Fase 3, doc Fase 5)
-│   ├── docsai-odf/             # esqueleto (Fase 4)
-│   ├── docsai-convert/         # orquestación: detección, pipelines, assets
-│   ├── docsai-cli/             # binario `docsai`
-│   └── docsai-mcp/             # esqueleto (Fase 7)
-├── corpus/
-│   ├── generate.py             # genera TODOS los ficheros del corpus
-│   ├── README.md               # qué aísla cada documento
-│   ├── docx/*.docx             # 14 documentos + 14 *.expected.dmk.md (goldens)
-│   └── xlsx/*.xlsx             # 6 libros, para la Fase 3
-├── docs/                       # documentación de diseño (español)
-│   └── spikes/                 # informes de spikes con su decisión
-└── kb/                         # esta base de conocimiento
-```
-
-## Los siete crates
-
-| Crate | Tipo | Líneas | Responsabilidad | Depende de |
-|---|---|---|---|---|
-| `docsai-model` | lib | ~3 500 | El IR y los tipos comunes | *(nada del workspace)* |
-| `docsai-docmark` | lib | ~1 850 | IR ⇄ DocMark | model |
-| `docsai-office` | lib | ~3 500 | Lectores/escritores OOXML y legados | model |
-| `docsai-odf` | lib | 21 | Lectores/escritores ODF | model |
-| `docsai-convert` | lib | ~500 | Detección, pipelines, gestión de assets | los cuatro anteriores |
-| `docsai-cli` | bin | ~200 | El binario `docsai` | convert, model |
-| `docsai-mcp` | lib | 26 | Servidor MCP por stdio | convert |
-
-**Regla de dependencia (`AGENTS.md` §3)**: ningún crate de formato importa a otro crate de
-formato. `docsai-odf` y `docsai-mcp` existen ya, vacíos, precisamente para que el compilador
-haga cumplir esa regla desde el primer día en lugar de descubrirla rota en la Fase 4.
-
-## `docsai-model` — el IR
-
-| Módulo | Contenido |
-|---|---|
-| `units` | `Length` (newtype sobre EMU), `Size`, `Point`, conversiones exactas y el formato de salida |
-| `style` | `StyleCatalog`, `Style`, `FontProps`, `ParaProps`, `DocDefaults` y la resolución de la cascada |
-| `list` | `ListCatalog`, `ListDef`, `ListLevel`, `NumFormat` |
-| `text` | `TextDocument`, `Section`, `PageGeometry`, `Block`, `Inline`, `Paragraph`, `Table`, `RawFragment` |
-| `sheet` | `Workbook`, `Sheet`, `Cell`, `CellRef` (A1), `Formula`, `NumFmt` — poblado en la Fase 3 |
-| `image` | `ImageRef`, `ImageGeometry`, `Anchor` y su cortejo (wrap, crop, flip, bordes) |
-| `assets` | `AssetStore` (trait), `MemoryAssetStore`, hash de contenido, sniffing y dimensiones |
-| `report` | `ConversionReport`, `Warning` tipada, `Severity`, `ConversionStats` |
-| `validate` | Invariantes: anclajes de hoja solo en `Workbook`, filas más anchas que la rejilla, anclajes `two-cell` invertidos |
-
-Tres principios que los tipos codifican, y que conviene no romper:
-
-1. **Estilo = referencia + delta.** Cada campo de `FontProps`/`ParaProps` es `Option`: `None`
-   significa *heredar*, no *desactivado*. `over()` mezcla la cascada; `minus()` calcula el delta
-   que hay que emitir (la «regla de economía» de la spec §3.1).
-2. **Todas las longitudes en EMU.** Un solo entero, sin pérdidas, para OOXML (EMU/twips),
-   ODF (cm/in) y `.doc` (twips).
-3. **El IR no conoce el I/O.** Las imágenes son un `AssetId` detrás de un trait.
-
-## `docsai-office` — el lector docx
-
-| Módulo | Responsabilidad |
-|---|---|
-| `xml` | Árbol XML sobre `quick-xml` con **spans de bytes** por nodo |
-| `package` | ZIP, relaciones OPC, límites anti-bomba, saneado de nombres |
-| `detect` | Detección de formato **por contenido**, no por extensión |
-| `docx/format` | `w:rPr` y `w:pPr` → los tipos delta del IR |
-| `docx/styles` | `styles.xml` → `StyleCatalog`; nivel de encabezado |
-| `docx/numbering` | `numbering.xml` → `ListCatalog` (aplana la doble indirección) |
-| `docx/drawing` | DrawingML y VML → `ImageRef`/`ImageGeometry` |
-| `docx/body` | El recorrido del cuerpo: bloques, inlines, campos, tablas, listas |
-| `docx/mod` | Ensamblaje: propiedades, secciones, cabeceras/pies, notas al pie |
-
-El detalle que lo sostiene todo: **cada nodo del árbol XML recuerda su rango de bytes en el
-origen**. Un elemento no reconocido se conserva citando los bytes originales, no una
-re-serialización, y por eso el raw-block es exacto.
-
-## `docsai-docmark` — el serializador
-
-| Módulo | Responsabilidad |
-|---|---|
-| `escape` | Tabla de escapado fija por contexto (bloque, celda de tabla, etiqueta de enlace) |
-| `attrs` | Bloques `{#id .clase clave="valor"}` con el orden canónico de la spec §8 |
-| `units` | Cómo se escribe una longitud, un porcentaje o un número |
-| `frontmatter` | El YAML, escrito a mano para garantizar determinismo byte a byte |
-| `writer` | El recorrido del IR: bloques, inlines, imágenes, tablas, contenedores |
-
-## Flujo de una conversión
-
-```
-fichero.docx
-    │  docsai-convert::read_document
-    ▼
-detect (por contenido) ──► docsai-office::read_docx
-                                │  Package::open  → partes en memoria, nombres saneados
-                                │  Element::parse → árbol XML con spans
-                                │  styles + numbering + footnotes
-                                │  read_sections → bloques, con DirAssetStore recibiendo medios
-                                ▼
-                          (Document, ConversionReport)
-                                │  docsai_model::validate
-                                ▼
-                       docsai-docmark::serialize
-                                │  front matter + cuerpo, según --fidelity
-                                ▼
-                    fichero.dmk.md  +  assets/img-<hash8>.<ext>
-```
-
-## Dependencias externas
-
-Todo el núcleo se apoya en cinco crates:
-
-| Crate | Para qué | Dónde |
-|---|---|---|
-| `serde` | Serialización del IR | model y derivados |
-| `thiserror` | Errores tipados de biblioteca | model, docmark, office, convert |
-| `quick-xml` | Parsing XML | office |
-| `zip` | Contenedores OOXML | office |
-| `tracing` | Logs, siempre a stderr | office, convert, cli |
-
-Y en los binarios: `clap` (CLI), `anyhow` (errores de binario), `serde_json` (`--json`),
-`tracing-subscriber`. En tests: `proptest` y `comrak`.
-
-Deliberadamente **ausentes**: `docx-rs` (descartado por el spike R1), `image` (basta leer la
-cabecera del formato), `serde_yaml` (el front matter se escribe a mano y el crate no está
-mantenido) e `insta` (los goldens son ficheros de texto revisables). Cada ausencia está
-justificada en [`docs/analisis-tecnico.md`](../docs/analisis-tecnico.md) §4, como exige
-`AGENTS.md` §2.
-
-## Dónde están los tests
-
-| Ubicación | Qué cubre |
-|---|---|
-| Módulos `#[cfg(test)]` de cada fichero | Unidades: conversiones, escapado, cascada de estilos, parsing de fragmentos XML |
-| `crates/docsai-model/tests/json_roundtrip.rs` | Round-trip JSON del IR: documentos a mano con todos los nodos + proptest |
-| `crates/docsai-office/tests/docx_images.rs` | Geometría de imágenes sobre el corpus real |
-| `crates/docsai-office/tests/robustness.rs` | Los 900+ inputs corruptos, path traversal, ZIP sin documento |
-| `crates/docsai-convert/tests/goldens.rs` | Goldens, determinismo, finales de línea, `plain` con comrak, rendimiento |
-
-## Convenciones que conviene respetar
-
-- Nombres de código, comentarios y mensajes de commit en **inglés**; la documentación de `docs/`
-  y `kb/` en **español** (`AGENTS.md` §5).
-- `thiserror` en bibliotecas, `anyhow` sólo en binarios.
-- Los parsers **nunca entran en pánico**: sin `unwrap`, `expect` ni indexación sin comprobar en
-  el camino de lectura.
-- El serializador es **determinista**: mismo IR ⇒ mismos bytes. Cualquier iteración sobre un
-  mapa usa `BTreeMap`, nunca `HashMap`.
-- Rutas con `std::path`, nunca concatenando `/`.
diff --git a/kb/02-project-structure.md b/kb/02-project-structure.md
new file mode 100644
index 0000000..a75b905
--- /dev/null
+++ b/kb/02-project-structure.md
@@ -0,0 +1,155 @@
+# 02 — Project structure
+
+## Tree
+
+```
+docsai/
+├── Cargo.toml                  # workspace: 7 members + shared dependencies
+├── .github/workflows/ci.yml    # build/test on 3 OSes + fmt/clippy/rustdoc
+├── crates/
+│   ├── docsai-model/           # the IR. No I/O, no heavy dependencies
+│   ├── docsai-docmark/         # DocMark serializer + parser (Phase 2)
+│   ├── docsai-office/          # .docx reader (xlsx Phase 3, doc Phase 5)
+│   ├── docsai-odf/             # skeleton (Phase 4)
+│   ├── docsai-convert/         # orchestration: detection, pipelines, assets
+│   ├── docsai-cli/             # `docsai` binary
+│   └── docsai-mcp/             # skeleton (Phase 7)
+├── corpus/
+│   ├── generate.py             # generates ALL corpus files
+│   ├── README.md               # what each document isolates
+│   ├── docx/*.docx             # 14 documents + 14 *.expected.dmk.md (goldens)
+│   └── xlsx/*.xlsx             # 6 workbooks, for Phase 3
+├── docs/                       # design documentation (English)
+│   └── spikes/                 # spike reports with their decision
+└── kb/                         # this knowledge base
+```
+
+## The seven crates
+
+| Crate | Type | Lines | Responsibility | Depends on |
+|---|---|---|---|---|
+| `docsai-model` | lib | ~3,500 | The IR and common types | *(nothing from the workspace)* |
+| `docsai-docmark` | lib | ~1,850 | IR ⇄ DocMark | model |
+| `docsai-office` | lib | ~3,500 | OOXML and legacy readers/writers | model |
+| `docsai-odf` | lib | 21 | ODF readers/writers | model |
+| `docsai-convert` | lib | ~500 | Detection, pipelines, asset management | the four above |
+| `docsai-cli` | bin | ~200 | The `docsai` binary | convert, model |
+| `docsai-mcp` | lib | 26 | MCP server over stdio | convert |
+
+**Dependency rule (`AGENTS.md` §3)**: no format crate imports another format crate.
+`docsai-odf` and `docsai-mcp` already exist, empty, precisely so the compiler enforces that
+rule from day one rather than discovering it broken in Phase 4.
+
+## `docsai-model` — the IR
+
+| Module | Contents |
+|---|---|
+| `units` | `Length` (newtype over EMU), `Size`, `Point`, exact conversions and output formatting |
+| `style` | `StyleCatalog`, `Style`, `FontProps`, `ParaProps`, `DocDefaults` and cascade resolution |
+| `list` | `ListCatalog`, `ListDef`, `ListLevel`, `NumFormat` |
+| `text` | `TextDocument`, `Section`, `PageGeometry`, `Block`, `Inline`, `Paragraph`, `Table`, `RawFragment` |
+| `sheet` | `Workbook`, `Sheet`, `Cell`, `CellRef` (A1), `Formula`, `NumFmt` — populated in Phase 3 |
+| `image` | `ImageRef`, `ImageGeometry`, `Anchor` and related types (wrap, crop, flip, borders) |
+| `assets` | `AssetStore` (trait), `MemoryAssetStore`, content hash, sniffing and dimensions |
+| `report` | `ConversionReport`, typed `Warning`, `Severity`, `ConversionStats` |
+| `validate` | Invariants: sheet anchors only in `Workbook`, rows wider than the grid, inverted `two-cell` anchors |
+
+Three principles encoded in the types, which should not be broken:
+
+1. **Style = reference + delta.** Every field of `FontProps`/`ParaProps` is `Option`: `None`
+   means *inherit*, not *disabled*. `over()` merges the cascade; `minus()` computes the delta
+   that must be emitted (the “economy rule” of spec §3.1).
+2. **All lengths in EMU.** A single integer, lossless, for OOXML (EMU/twips),
+   ODF (cm/in), and `.doc` (twips).
+3. **The IR does not know about I/O.** Images are an `AssetId` behind a trait.
+
+## `docsai-office` — the docx reader
+
+| Module | Responsibility |
+|---|---|
+| `xml` | XML tree over `quick-xml` with **byte spans** per node |
+| `package` | ZIP, OPC relationships, anti-bomb limits, name sanitization |
+| `detect` | Format detection **by content**, not by extension |
+| `docx/format` | `w:rPr` and `w:pPr` → the IR delta types |
+| `docx/styles` | `styles.xml` → `StyleCatalog`; heading level |
+| `docx/numbering` | `numbering.xml` → `ListCatalog` (flattens the double indirection) |
+| `docx/drawing` | DrawingML and VML → `ImageRef`/`ImageGeometry` |
+| `docx/body` | Body traversal: blocks, inlines, fields, tables, lists |
+| `docx/mod` | Assembly: properties, sections, headers/footers, footnotes |
+
+The detail that holds everything together: **every node in the XML tree remembers its byte
+range in the source**. An unrecognized element is preserved by citing the original bytes, not a
+re-serialization, and that is why the raw-block is exact.
+
+## `docsai-docmark` — the serializer
+
+| Module | Responsibility |
+|---|---|
+| `escape` | Fixed escape table by context (block, table cell, link label) |
+| `attrs` | `{#id .class key="value"}` blocks with the canonical order from spec §8 |
+| `units` | How a length, a percentage, or a number is written |
+| `frontmatter` | The YAML, handwritten to guarantee byte-for-byte determinism |
+| `writer` | IR traversal: blocks, inlines, images, tables, containers |
+
+## Conversion flow
+
+```
+file.docx
+    │  docsai-convert::read_document
+    ▼
+detect (by content) ──► docsai-office::read_docx
+                                │  Package::open  → parts in memory, sanitized names
+                                │  Element::parse → XML tree with spans
+                                │  styles + numbering + footnotes
+                                │  read_sections → blocks, with DirAssetStore receiving media
+                                ▼
+                          (Document, ConversionReport)
+                                │  docsai_model::validate
+                                ▼
+                       docsai-docmark::serialize
+                                │  front matter + body, according to --fidelity
+                                ▼
+                    file.dmk.md  +  assets/img-<hash8>.<ext>
+```
+
+## External dependencies
+
+The entire core rests on five crates:
+
+| Crate | Purpose | Where |
+|---|---|---|
+| `serde` | IR serialization | model and derivatives |
+| `thiserror` | Typed library errors | model, docmark, office, convert |
+| `quick-xml` | XML parsing | office |
+| `zip` | OOXML containers | office |
+| `tracing` | Logs, always to stderr | office, convert, cli |
+
+And in the binaries: `clap` (CLI), `anyhow` (binary errors), `serde_json` (`--json`),
+`tracing-subscriber`. In tests: `proptest` and `comrak`.
+
+Deliberately **absent**: `docx-rs` (rejected by spike R1), `image` (reading the format
+header is enough), `serde_yaml` (front matter is handwritten and the crate is unmaintained),
+and `insta` (goldens are reviewable text files). Each absence is justified in
+[`docs/technical-analysis.md`](../docs/technical-analysis.md) §4, as required by
+`AGENTS.md` §2.
+
+## Where the tests live
+
+| Location | What it covers |
+|---|---|
+| `#[cfg(test)]` modules in each file | Units: conversions, escaping, style cascade, XML fragment parsing |
+| `crates/docsai-model/tests/json_roundtrip.rs` | IR JSON round-trip: hand-built documents with all nodes + proptest |
+| `crates/docsai-office/tests/docx_images.rs` | Image geometry over the real corpus |
+| `crates/docsai-office/tests/robustness.rs` | The 900+ corrupt inputs, path traversal, ZIP without document |
+| `crates/docsai-convert/tests/goldens.rs` | Goldens, determinism, line endings, `plain` with comrak, performance |
+
+## Conventions worth respecting
+
+- Code names, comments, commit messages, and **all documentation in `docs/` and `kb/`** must be
+  in **English** (`AGENTS.md` §5).
+- `thiserror` in libraries, `anyhow` only in binaries.
+- Parsers **never panic**: no `unwrap`, `expect`, or unchecked indexing on the
+  read path.
+- The serializer is **deterministic**: same IR ⇒ same bytes. Any iteration over a
+  map uses `BTreeMap`, never `HashMap`.
+- Paths with `std::path`, never concatenating `/`.
diff --git a/kb/03-decisiones-tecnicas.md b/kb/03-decisiones-tecnicas.md
deleted file mode 100644
index cdb730a..0000000
--- a/kb/03-decisiones-tecnicas.md
+++ /dev/null
@@ -1,177 +0,0 @@
-# 03 — Decisiones técnicas
-
-Las decisiones que no se deducen del plan y que un futuro colaborador podría deshacer sin
-querer. Cada una lleva su motivo y su coste.
-
-## 1. Parser docx propio, sin `docx-rs`
-
-**Decisión**: la lectura `.docx` se hace con `zip` + `quick-xml` propios.
-
-**Motivo** (spike R1, medido sobre el corpus, no supuesto):
-
-- `docx-rs` resuelve bien estilos, numeración y cabeceras/pies. Pero pierde **casi todo el modelo
-  de imagen**: ajuste de texto y lado, `behindDoc`, recorte, volteos, texto alternativo, título,
-  nombre del objeto, hipervínculo sobre la imagen y las imágenes enlazadas. La rotación existe
-  como campo pero devuelve `0` para un `rot="2700000"`, y el tipo es `u16`, que no puede
-  representar sesentamilésimas de grado ni valores negativos.
-- Descarta `w:footnoteReference` y el `w:instr` de `w:fldSimple`.
-- El VML (`w:pict`) se colapsa a un nodo genérico sin `r:id`, sin estilo y sin `alt`.
-- No conserva elementos desconocidos, que es justo lo que el raw-block necesita.
-- **204 pánicos de 903 entradas corruptas** (23 %), contra un criterio de aceptación que exige
-  siempre `Err`.
-
-Las imágenes son requisito de primera clase del proyecto y la mitad de los criterios de la
-Fase 1. Lo que quedaba delegable en `docx-rs` era la parte mecánica; el complemento propio
-habría sido el grueso de `document.xml` de todos modos, con dos parsers XML en el binario y dos
-árboles del mismo documento que reconciliar.
-
-**Coste asumido**: más superficie propia que mantener. Se mitiga con el corpus, los goldens y la
-captura genérica de elementos desconocidos, que hace *visible* lo que falta en vez de silencioso.
-
-**Detalle**: `docx-rs` sigue siendo candidato para el **writer** de la Fase 2. Es una decisión
-independiente y aún abierta: escribir es mucho más simple que leer, porque el XML de salida lo
-controlamos nosotros.
-
-## 2. Árbol XML con spans de bytes
-
-**Decisión**: `quick-xml` alimenta un árbol en memoria donde **cada nodo recuerda el rango de
-bytes que ocupa en el origen**.
-
-**Motivo**: un raw-block tiene que conservar los bytes originales. Re-serializar el subárbol
-daría XML equivalente pero no idéntico, y la re-inyección de la Fase 2 dejaría de ser exacta. Con
-el rango basta cortar la cadena de origen. Añadido: un árbol es mucho más revisable que una
-máquina de estados sobre eventos, y las partes OOXML caben en memoria de sobra.
-
-**Coste**: memoria proporcional al tamaño de la parte XML. Aceptable para documentos; habrá que
-revisarlo en la Fase 3 para hojas de 100 k celdas, donde `calamine` ya hace streaming por hoja.
-
-## 3. Coincidencia por nombre local, no por espacio de nombres
-
-**Decisión**: los elementos se buscan por su nombre local (`p`, no `w:p`).
-
-**Motivo**: los prefijos OOXML son convencionales pero no obligatorios, y toda la navegación del
-lector es contextual (hijos de un padre conocido), así que no hay ambigüedad. Un documento que
-renombre sus prefijos se lee igual.
-
-**Excepción**: los atributos con significado distinto según el espacio de nombres —`r:embed` y
-`r:link` junto a un `a:blip`— se buscan por nombre **cualificado** con `attr_qualified`.
-
-## 4. Formato de longitudes: exactitud antes que legibilidad
-
-**Decisión**: al escribir una longitud se elige la **primera unidad que la representa
-exactamente**, en el orden `px` (96 dpi) → `cm` → `pt` → `emu`.
-
-**Motivo**: un margen de Word de 1417 twips no es un número redondo de centímetros. Escribirlo
-`2.499cm` lo mueve 155 EMU en cada ida y vuelta, y esos errores se acumulan. Ahora sale
-`70.85pt`, que es exacto. `emu` es la escotilla final y siempre existe.
-
-**Coste**: alguna longitud se lee peor (`85.05pt` en vez de «unos 3 cm»). Es el precio de que el
-round-trip de la Fase 2 pueda aspirar al 95 % de fidelidad.
-
-## 5. `Document` externamente etiquetado en serde
-
-**Decisión**: `#[serde(rename_all = "kebab-case")]` sin `tag`, a diferencia de `Block` e
-`Inline`, que sí son adyacentemente etiquetados.
-
-**Motivo**: un enum *internamente* etiquetado hace que serde almacene el contenido en un búfer
-`Content` intermedio, y ese búfer **reescribe toda clave de mapa como cadena**. Eso rompe los
-mapas con clave entera de `Workbook` (`cols`, `rows`). Es un fallo que sólo aparece al
-deserializar y con un mensaje poco claro (`invalid type: string "0", expected u32`).
-
-**Relacionado**: `CellRef` implementa `Serialize`/`Deserialize` a mano como su referencia A1
-(`"B2"`), para poder ser clave de mapa y de paso dejar el `inspect --json` legible.
-
-## 6. `serde_json` con la feature `float_roundtrip`
-
-**Decisión**: activada en el workspace.
-
-**Motivo**: sin ella, el parser rápido de coma flotante de `serde_json` puede desplazar un valor
-un ULP. Sobre celdas de hoja de cálculo eso es **corromper datos del usuario en silencio**. Se
-detectó comparando IR antes y después de un round-trip JSON en el test de proptest.
-
-## 7. Hash no criptográfico para los assets
-
-**Decisión**: FNV-1a de 64 bits, mezclando la longitud, renderizado en 16 dígitos hex.
-
-**Motivo**: el id sólo tiene que ser estable y libre de colisiones en la práctica para los medios
-de un documento. Evita meter `sha2` en `docsai-model`, que es el crate que debe permanecer
-ligero. El trait `AssetStore` permite que la capa de conversión sustituya el hash sin tocar el
-modelo.
-
-**Cuándo revisarlo**: si algún día el nombre del asset se usa como frontera de confianza. Hoy no
-lo es.
-
-## 8. Sniffing de imágenes propio, sin el crate `image`
-
-**Decisión**: leer la cabecera de PNG, JPEG, GIF, BMP, TIFF, WebP, EMF y WMF a mano.
-
-**Motivo**: docsai **nunca recodifica** un mapa de bits; sólo necesita nombrarlo (extensión y
-content-type) y medirlo (dimensiones nativas). Eso son unas decenas de líneas contra un árbol de
-dependencias considerable en el binario final.
-
-**Detalle de seguridad**: la extensión sale del **contenido**, nunca del nombre que traiga el
-documento.
-
-## 9. Front matter YAML escrito a mano
-
-**Decisión**: sin librería YAML.
-
-**Motivo**: la spec exige determinismo byte a byte, el esquema es pequeño y conocido, y
-`serde_yaml` está sin mantenimiento activo. Escribirlo a mano da control total sobre el orden de
-las claves y el entrecomillado.
-
-**Coste**: hay que mantener el emisor a mano. Cuando la Fase 2 escriba el parser, ambos lados
-tendrán que moverse juntos; el test de idempotencia lo hará evidente si se desincronizan.
-
-## 10. Golden files como ficheros de texto, no snapshots de `insta`
-
-**Decisión**: `corpus/docx/<nombre>.expected.dmk.md` junto al documento.
-
-**Motivo**: es lo que prescribe `AGENTS.md` §6, y un golden que es DocMark legible se revisa en
-el diff como cualquier otro texto. Un `.snap` de `insta` añade un formato intermedio entre el
-revisor y lo que el programa produce.
-
-Actualizar es deliberado: `DOCSAI_UPDATE_GOLDENS=1 cargo test -p docsai-convert --test goldens`,
-y **se revisa el diff**.
-
-## 11. Corpus generado, no dibujado a mano
-
-**Decisión**: `corpus/generate.py` produce los 20 ficheros; CI comprueba que el árbol está al día.
-
-**Motivo**: el XML de cada documento vive en el generador, donde se revisa; un `.docx` hecho con
-Word es opaco en la revisión. Los paquetes salen con marca de tiempo y orden de miembros fijos,
-así que regenerar da archivos idénticos byte a byte y el repositorio no acumula ruido binario.
-Los medios se sintetizan en Python puro para que funcione igual en las tres plataformas de CI.
-
-**Coste**: son documentos *mínimos*, no documentos de Word reales. Los reales anonimizados siguen
-pendientes (Fase 1, tarea 10). La decisión valió su precio de inmediato: el spike destapó que el
-generador colocaba `w:drawing` fuera de un `w:r`, que es OOXML inválido, antes de que eso
-contaminara ningún golden.
-
-## 12. `w:sdt` se aplana en lugar de conservarse opaco
-
-**Decisión**: un control de contenido emite sus bloques hijos y una advertencia `Degraded`, en
-vez de un raw-block con todo dentro.
-
-**Motivo**: meterlo entero en un raw-block escondería texto perfectamente legible detrás de un
-bloque opaco, y en modo `plain` desaparecería del todo. El texto es lo que el usuario quiere ver.
-
-**Coste**: se pierden las propiedades del control (`w:alias`, binding de datos). Está reportado,
-no es silencioso, y la Fase 2 tendrá que decidir si las necesita.
-
-## 13. La advertencia es parte de la salida, no un adorno
-
-Cada degradación emite una `Warning` **tipada** con severidad. La CLI las cuenta en stderr, las
-detalla con `--verbose` y las serializa con `--json`; el código de salida 1 marca una conversión
-que perdió algo. `--strict` sube el listón para que cuenten también las menores.
-
-Es la regla 3 de `AGENTS.md` hecha código: **nada se degrada en silencio**.
-
-## 14. Límites de seguridad desde el principio
-
-Aunque el endurecimiento es la Fase 8, tres cosas eran demasiado baratas como para posponerlas:
-
-- **Tope de descompresión**: 512 MB por paquete, 128 MB por parte.
-- **Límite de profundidad XML**: 256 niveles.
-- **Saneado de nombres de miembro**: un `word/media/../../evil.png` nunca llega a ser una parte
-  ni un asset. Hay un test dedicado.
diff --git a/kb/03-technical-decisions.md b/kb/03-technical-decisions.md
new file mode 100644
index 0000000..66583ce
--- /dev/null
+++ b/kb/03-technical-decisions.md
@@ -0,0 +1,175 @@
+# 03 — Technical decisions
+
+The decisions that do not follow from the plan alone and that a future collaborator could undo
+unintentionally. Each one carries its rationale and its cost.
+
+## 1. Custom docx parser, without `docx-rs`
+
+**Decision**: `.docx` reading is done with our own `zip` + `quick-xml`.
+
+**Rationale** (spike R1, measured on the corpus, not assumed):
+
+- `docx-rs` handles styles, numbering, and headers/footers well. But it loses **almost the entire
+  image model**: text wrapping and side, `behindDoc`, crop, flips, alt text, title,
+  object name, hyperlink on the image, and linked images. Rotation exists as a field but
+  returns `0` for `rot="2700000"`, and the type is `u16`, which cannot represent sixty-thousandths
+  of a degree or negative values.
+- It drops `w:footnoteReference` and the `w:instr` of `w:fldSimple`.
+- VML (`w:pict`) collapses to a generic node with no `r:id`, no style, and no `alt`.
+- It does not preserve unknown elements, which is exactly what the raw-block needs.
+- **204 panics out of 903 corrupt inputs** (23 %), against an acceptance criterion that requires
+  always `Err`.
+
+Images are a first-class requirement of the project and half of the Phase 1 criteria. What
+remained delegable to `docx-rs` was the mechanical part; a custom complement would have been the
+bulk of `document.xml` anyway, with two XML parsers in the binary and two trees of the same
+document to reconcile.
+
+**Accepted cost**: more custom surface to maintain. Mitigated by the corpus, the goldens, and
+generic capture of unknown elements, which makes what is missing *visible* rather than silent.
+
+**Detail**: `docx-rs` remains a candidate for the Phase 2 **writer**. That is an independent and
+still open decision: writing is much simpler than reading, because we control the output XML.
+
+## 2. XML tree with byte spans
+
+**Decision**: `quick-xml` feeds an in-memory tree where **each node remembers the byte range it
+occupies in the source**.
+
+**Rationale**: a raw-block must preserve the original bytes. Re-serializing the subtree would
+yield equivalent but not identical XML, and Phase 2 re-injection would no longer be exact. With
+the range it is enough to slice the source string. Bonus: a tree is far more reviewable than a
+state machine over events, and OOXML parts fit comfortably in memory.
+
+**Cost**: memory proportional to the size of the XML part. Acceptable for documents; it will need
+review in Phase 3 for sheets with 100k cells, where `calamine` already streams per sheet.
+
+## 3. Match by local name, not by namespace
+
+**Decision**: elements are looked up by their local name (`p`, not `w:p`).
+
+**Rationale**: OOXML prefixes are conventional but not mandatory, and all reader navigation is
+contextual (children of a known parent), so there is no ambiguity. A document that renames its
+prefixes is read the same way.
+
+**Exception**: attributes with different meaning depending on the namespace — `r:embed` and
+`r:link` next to an `a:blip` — are looked up by **qualified** name with `attr_qualified`.
+
+## 4. Length formatting: exactness before readability
+
+**Decision**: when writing a length, choose the **first unit that represents it exactly**, in the
+order `px` (96 dpi) → `cm` → `pt` → `emu`.
+
+**Rationale**: a Word margin of 1417 twips is not a round number of centimeters. Writing it as
+`2.499cm` shifts it by 155 EMU on every round-trip, and those errors accumulate. Now it comes out
+as `70.85pt`, which is exact. `emu` is the final escape hatch and always exists.
+
+**Cost**: some lengths read worse (`85.05pt` instead of “about 3 cm”). That is the price so that
+the Phase 2 round-trip can aim for 95 % fidelity.
+
+## 5. Externally tagged `Document` in serde
+
+**Decision**: `#[serde(rename_all = "kebab-case")]` without `tag`, unlike `Block` and
+`Inline`, which are adjacently tagged.
+
+**Rationale**: an *internally* tagged enum makes serde store the content in an intermediate
+`Content` buffer, and that buffer **rewrites every map key as a string**. That breaks maps with
+integer keys in `Workbook` (`cols`, `rows`). It is a failure that only appears on deserialize and
+with an unclear message (`invalid type: string "0", expected u32`).
+
+**Related**: `CellRef` implements `Serialize`/`Deserialize` by hand as its A1 reference
+(`"B2"`), so it can be a map key and also keep `inspect --json` readable.
+
+## 6. `serde_json` with the `float_roundtrip` feature
+
+**Decision**: enabled in the workspace.
+
+**Rationale**: without it, `serde_json`'s fast floating-point parser can shift a value by one ULP.
+On spreadsheet cells that is **silently corrupting user data**. It was detected by comparing IR
+before and after a JSON round-trip in the proptest test.
+
+## 7. Non-cryptographic hash for assets
+
+**Decision**: 64-bit FNV-1a, mixing in the length, rendered as 16 hex digits.
+
+**Rationale**: the id only needs to be stable and practically collision-free for the media of one
+document. Avoids pulling `sha2` into `docsai-model`, which is the crate that must stay light. The
+`AssetStore` trait lets the conversion layer replace the hash without touching the model.
+
+**When to revisit**: if someday the asset name is used as a trust boundary. Today it is not.
+
+## 8. Custom image sniffing, without the `image` crate
+
+**Decision**: read the header of PNG, JPEG, GIF, BMP, TIFF, WebP, EMF, and WMF by hand.
+
+**Rationale**: docsai **never re-encodes** a bitmap; it only needs to name it (extension and
+content-type) and measure it (native dimensions). That is a few dozen lines against a considerable
+dependency tree in the final binary.
+
+**Security detail**: the extension comes from the **content**, never from the name the document
+carries.
+
+## 9. Handwritten YAML front matter
+
+**Decision**: no YAML library.
+
+**Rationale**: the spec requires byte-for-byte determinism, the schema is small and known, and
+`serde_yaml` has no active maintenance. Writing it by hand gives full control over key order and
+quoting.
+
+**Cost**: the emitter must be maintained by hand. When Phase 2 writes the parser, both sides will
+have to move together; the idempotence test will make it obvious if they drift.
+
+## 10. Golden files as text files, not `insta` snapshots
+
+**Decision**: `corpus/docx/<name>.expected.dmk.md` next to the document.
+
+**Rationale**: that is what `AGENTS.md` §6 prescribes, and a golden that is readable DocMark is
+reviewed in the diff like any other text. An `insta` `.snap` adds an intermediate format between
+the reviewer and what the program produces.
+
+Updating is deliberate: `DOCSAI_UPDATE_GOLDENS=1 cargo test -p docsai-convert --test goldens`,
+and **the diff is reviewed**.
+
+## 11. Generated corpus, not hand-drawn
+
+**Decision**: `corpus/generate.py` produces the 20 files; CI checks that the tree is up to date.
+
+**Rationale**: each document's XML lives in the generator, where it is reviewed; a `.docx` made
+with Word is opaque in review. Packages come out with fixed timestamps and member order, so
+regenerating yields byte-identical files and the repository does not accumulate binary noise.
+Media are synthesized in pure Python so it works the same on all three CI platforms.
+
+**Cost**: these are *minimal* documents, not real Word documents. Anonymized real ones remain
+pending (Phase 1, task 10). The decision paid for itself immediately: the spike uncovered that the
+generator placed `w:drawing` outside a `w:r`, which is invalid OOXML, before that contaminated any
+golden.
+
+## 12. `w:sdt` is flattened instead of kept opaque
+
+**Decision**: a content control emits its child blocks and a `Degraded` warning, instead of a
+raw-block with everything inside.
+
+**Rationale**: putting the whole thing in a raw-block would hide perfectly readable text behind an
+opaque block, and in `plain` mode it would disappear entirely. The text is what the user wants to
+see.
+
+**Cost**: control properties are lost (`w:alias`, data binding). It is reported, not silent, and
+Phase 2 will have to decide whether it needs them.
+
+## 13. The warning is part of the output, not decoration
+
+Every degradation emits a **typed** `Warning` with severity. The CLI counts them on stderr,
+details them with `--verbose`, and serializes them with `--json`; exit code 1 marks a conversion
+that lost something. `--strict` raises the bar so minor ones also count.
+
+It is rule 3 of `AGENTS.md` made code: **nothing is degraded silently**.
+
+## 14. Security limits from the start
+
+Although hardening is Phase 8, three things were too cheap to postpone:
+
+- **Decompression cap**: 512 MB per package, 128 MB per part.
+- **XML depth limit**: 256 levels.
+- **Member name sanitization**: a `word/media/../../evil.png` never becomes a part or an asset.
+  There is a dedicated test.
diff --git a/kb/04-next-phases.md b/kb/04-next-phases.md
new file mode 100644
index 0000000..dbbdc34
--- /dev/null
+++ b/kb/04-next-phases.md
@@ -0,0 +1,166 @@
+# 04 — Considerations for the next phases
+
+What the following phases will already find solved, what awaits them, and the traps that are
+already known.
+
+---
+
+## Phase 2 — DocMark → DOCX writing + round-trip
+
+> **Status: implemented** in-tree (`parse` / `parse_with_base`, `write_docx`,
+> `convert` DocMark↔DOCX, CLI `roundtrip`). Remaining polish is fidelity on
+> complex drawings, full footnote body rewrite, and floating anchors.
+
+## Phase 2 (original plan) — DocMark → DOCX writing + round-trip
+
+This is the immediate phase. It closes the cycle and builds the fidelity infrastructure.
+
+### What is already done for it
+
+| | |
+|---|---|
+| **The spec is frozen** | v1.0, with the changelog in §10. The parser has a fixed contract to work against, not a moving draft |
+| **The serializer is deterministic** | The idempotence test `serialize(parse(md)) == md` already has half the equation guaranteed |
+| **Lengths do not lose precision** | Every written length re-reads exactly. Without this, the fidelity metric would have an artificial floor |
+| **The IR is complete** | `Block::TextBox`, `Workbook`, sheet anchors… already exist, even if the docx reader does not produce all of them |
+| **The invariant validator** | Already invoked on every conversion; the parser inherits that safety net |
+| **Raw-blocks are exact** | They store the original bytes, so `format=ooxml` re-injection is copy and paste |
+| **Goldens are the reference** | 14 documents with their expected DocMark: the parser has 14 known inputs and their expected IR |
+
+### What needs to be built
+
+1. **DocMark parser** (`docsai-docmark`): comrak + custom layer for `{...}` attributes and fenced
+   divs `:::`. Comrak is already in the tree as a test dependency, so evaluation is done.
+2. **docx writer** (`docsai-office`): IR → `document.xml`, `styles.xml`, `numbering.xml`, media and
+   properties.
+3. **`roundtrip` command** with structural diff of the normalized IR and per-category metric.
+4. **Serializer idempotence test** over all goldens.
+5. **Property testing**: random IR → md → IR must be the identity. The arbitrary IR generator
+   **already exists** in `crates/docsai-model/tests/json_roundtrip.rs` and can be reused almost as-is.
+
+### Traps already identified
+
+- **Escaping must be reversible, not merely correct.** `escape()` escapes `\` first, so
+  unescaping is deterministic. The `escaping_is_idempotent_in_shape` test fixes that property; the
+  parser must be its exact inverse.
+- **The three fidelity modes are not symmetric.** Only `full` is reversible. `standard` and
+  `plain` lose information on purpose, and `roundtrip` only makes sense over `full`.
+- **`[]{.empty}`, `[]{.break kind=page}`, and `{.field ...}` are custom syntax** on top of
+  CommonMark: the parser needs them explicitly. They are in the spec §3.1, §3.2, and §10.
+- **A list item never carries two `{...}` blocks.** `list=` goes inside the attribute block of the
+  first item.
+- **The docx writer must put absorbed cells back.** The IR marks `covered=true` and
+  `colspan`/`rowspan` on the cell that opens the area; OOXML expects `w:gridSpan` and `w:vMerge`.
+- **Text boxes are still raw-block.** If Phase 2 wants real `::: {.textbox}`, the reader must be
+  extended first — it is noted in the plan.
+- **Decide whether `docx-rs` works as a writer.** Still open. Spike R1 only closed reading.
+- **Validating in Word and LibreOffice** is an acceptance criterion and there is no LibreOffice in
+  the current CI environment: it must be planned for (manual checklist per release, or headless
+  `soffice` on the Linux runner).
+
+---
+
+## Phase 3 — Spreadsheets (XLSX/XLS)
+
+### What is already done
+
+- **The xlsx corpus exists**: `values-types`, `formulas-basic`, `formulas-shared`,
+  `number-formats`, `merged-cells`, and `images-anchored` (all three anchors). Generated in Phase 0
+  precisely so it would not have to be invented in a hurry.
+- **The `Workbook` side of the IR is defined and tested**: `Sheet`, `Cell`, `CellValue`, `Formula`
+  with its dialect, `NumFmt`, `CellRef` with A1 notation both ways, `ColProps`, `RowProps`,
+  `Pane`, `DefinedName`. All with verified JSON round-trip.
+- **The three sheet anchors** are in the image model and the validator already rejects using them
+  outside a `Workbook`.
+- **`float_roundtrip`** is enabled: numeric values are not corrupted when going through JSON.
+
+### What needs to be decided and built
+
+1. **xlsx writer spike**: `umya-spreadsheet` versus `rust_xlsxwriter`. Criterion: which regenerates
+   styles + `numFmt` from the IR with higher fidelity. Document in `docs/spikes/`.
+2. **Sheet serialization to DocMark** (spec §4): the syntax is specified but **not implemented**.
+   `docsai_docmark::serialize` today returns front matter and an explicit `Degraded` warning for
+   `Document::Workbook`; that is the entry point.
+3. **Reading `xl/drawings/drawing*.xml`** with custom `quick-xml`: neither `calamine` nor `umya`
+   expose full geometry. The `docx/drawing.rs` module is the pattern to follow; the target model
+   is the same.
+
+### Traps already identified
+
+- **Streaming.** The in-memory XML tree is comfortable for documents but the budget for a 100k-cell
+  sheet is < 3 s and < 500 MB. Use `calamine` (lazy per sheet) for values and reserve the custom
+  tree for small parts (`styles.xml`, `drawing*.xml`).
+- **Dates are serial numbers plus format.** The IR stores `CellValue::DateTime` in ISO-8601 so that
+  hand-editing DocMark cannot corrupt them; serial ⇄ ISO conversion both ways is the reader and
+  writer responsibility.
+- **In `two-cell` anchors, `width`/`height` are not serialized** (spec §4.1): size is defined by the
+  grid. The attribute writer already accounts for this.
+- **Formulas keep their dialect**; they are not translated (risk R5). `FormulaDialect` is already
+  in the IR.
+
+---
+
+## Phase 4 — ODF (ODT and ODS)
+
+- `docsai-odf` is a skeleton with the `FORMATS` constant; the dependency rule is already enforced
+  by the compiler.
+- The known hard point is **de-automatizing styles**: ODF `office:automatic-styles` represent
+  direct formatting and must be mapped to IR deltas. The “reference + delta” model is ready to
+  receive them: `FontProps::minus()` is exactly the inverse operation.
+- `detect()` already recognizes ODF by `content.xml` + `mimetype`; it only disambiguates `.odt`
+  from `.ods` by extension, which will need refining by reading the `mimetype`.
+- The image model already has the concepts ODF needs (`as-char`/`char`/`paragraph`/
+  `page` → `Inline`/`Floating`, `fo:clip` → `CropRect`).
+
+---
+
+## Phase 5 — Legacy DOC
+
+- `detect()` already recognizes the OLE2 container and disambiguates `.doc` from `.xls` by name;
+  that remains to be replaced by reading the CFB directory.
+- The two-level strategy from analysis §1.3 still stands: fallback to headless LibreOffice and a
+  degraded native extractor.
+- The `Warning::ImageGeometryDegraded` that the native extractor needs already exists and is
+  already used (for VML), so the pattern is established.
+
+---
+
+## Phases 6 to 9 — Product, MCP, and hardening
+
+- **CLI (Phase 6)**: `convert` and `formats` exist with `--fidelity`, `--assets-dir`, `--json`,
+  `--strict`, `--verbose`, and the exit codes from architecture §5. Still missing: `inspect`,
+  `roundtrip`, `--style-map`, stdin/stdout with `-`, batch processing, and `cargo-dist`.
+- **MCP (Phase 7)**: `docsai-mcp` declares the four tools. The clean-stdout rule is already
+  respected in the CLI (`tracing` always writes to stderr), so the automated test of that guarantee
+  already makes sense.
+- **Hardening (Phase 8)**: part of the work is ahead of schedule — decompression caps, XML depth
+  limit, path sanitization, 900+ corrupt inputs in CI. Still missing: real `cargo-fuzz`, the full
+  adversarial suite, benchmarks with `criterion`, and `cargo audit`/`deny`. The existing corpus
+  serves as a seed for fuzzing.
+
+---
+
+## Known technical debt
+
+None of these block anything, but they are worth noting:
+
+| Item | Where | Note |
+|---|---|---|
+| Anonymized real documents | Phase 1, task 10 | The synthetic corpus covers traits one by one, but not real-world oddities |
+| Text boxes as raw-block | `docx/drawing.rs` | The IR type and spec syntax exist; emit and rebuild are missing |
+| `w:lvlOverride` not modeled | `docx/numbering.rs` | Emits `Warning::Degraded` |
+| Comments ignored | `docx/body.rs` | Out of v1 scope; emits a warning |
+| DrawingML effects | `docx/drawing.rs` | Detected and warned, but not yet dumped to `effects_raw` |
+| In-memory XML tree | `office/xml.rs` | Revisit for large sheets in Phase 3 |
+| FNV hash for assets | `model/assets.rs` | Sufficient today; revisit if the name becomes a trust boundary |
+
+## Rules not to break
+
+1. **Do not advance phases.** The plan order reflects real dependencies.
+2. **Do not change the DocMark spec to make a test pass.** It is frozen at v1.0; any change bumps
+   the front-matter version and documents the migration.
+3. **Nothing is degraded silently.** Every loss is a typed `Warning`.
+4. **Parsers never panic.** There is a test that checks this with 900+ corrupt inputs; keep it
+   passing.
+5. **The serializer is deterministic.** `BTreeMap` always, `HashMap` never, on any path that
+   reaches the output.
diff --git a/kb/04-siguientes-fases.md b/kb/04-siguientes-fases.md
deleted file mode 100644
index f62811b..0000000
--- a/kb/04-siguientes-fases.md
+++ /dev/null
@@ -1,162 +0,0 @@
-# 04 — Consideraciones para las siguientes fases
-
-Lo que las fases siguientes van a encontrarse ya resuelto, lo que les espera, y las trampas que
-ya se conocen.
-
----
-
-## Fase 2 — Escritura DocMark → DOCX + round-trip
-
-Es la fase inmediata. Cierra el ciclo y monta la infraestructura de fidelidad.
-
-### Lo que ya está hecho para ella
-
-| | |
-|---|---|
-| **La spec está congelada** | v1.0, con el registro de cambios en §10. El parser tiene un contrato fijo contra el que trabajar, no un borrador móvil |
-| **El serializador es determinista** | El test de idempotencia `serialize(parse(md)) == md` tiene la mitad de la ecuación ya garantizada |
-| **Las longitudes no pierden** | Toda longitud escrita se relee exacta. Sin esto, la métrica de fidelidad tendría un suelo artificial |
-| **El IR es completo** | `Block::TextBox`, `Workbook`, anclajes de hoja… ya existen, aunque el lector docx no los produzca todos |
-| **El validador de invariantes** | Ya se invoca en cada conversión; el parser hereda esa red |
-| **Los raw-blocks son exactos** | Guardan los bytes originales, así que la re-inyección `format=ooxml` es copiar y pegar |
-| **Los goldens son la referencia** | 14 documentos con su DocMark esperado: el parser tiene 14 entradas conocidas y su IR esperado |
-
-### Lo que hay que construir
-
-1. **Parser DocMark** (`docsai-docmark`): comrak + capa propia de atributos `{...}` y fenced divs
-   `:::`. Comrak ya está en el árbol como dependencia de test, así que la evaluación está hecha.
-2. **Writer docx** (`docsai-office`): IR → `document.xml`, `styles.xml`, `numbering.xml`, medios y
-   propiedades.
-3. **Comando `roundtrip`** con diff estructural del IR normalizado y métrica por categoría.
-4. **Test de idempotencia** del serializador sobre todos los goldens.
-5. **Property testing**: IR aleatorio → md → IR debe ser la identidad. El generador de IRs
-   arbitrarios **ya existe** en `crates/docsai-model/tests/json_roundtrip.rs` y se puede reutilizar
-   casi tal cual.
-
-### Trampas ya identificadas
-
-- **El escapado tiene que ser reversible, no sólo correcto.** `escape()` escapa `\` primero, de
-  modo que desescapar es determinista. El test `escaping_is_idempotent_in_shape` fija esa
-  propiedad; el parser tiene que ser su inverso exacto.
-- **Los tres modos de fidelidad no son simétricos.** Sólo `full` es reversible. `standard` y
-  `plain` pierden a propósito, y el `roundtrip` sólo tiene sentido sobre `full`.
-- **`[]{.empty}`, `[]{.break kind=page}` y `{.field ...}` son sintaxis propia** por encima de
-  CommonMark: el parser los necesita explícitamente. Están en la spec §3.1, §3.2 y §10.
-- **Un ítem de lista nunca lleva dos bloques `{...}`.** `list=` va dentro del bloque de atributos
-  del primer ítem.
-- **El writer docx tiene que volver a poner las celdas absorbidas.** El IR marca `covered=true` y
-  `colspan`/`rowspan` en la celda que abre el área; OOXML espera `w:gridSpan` y `w:vMerge`.
-- **Los cuadros de texto siguen siendo raw-block.** Si la Fase 2 quiere `::: {.textbox}` de
-  verdad, hay que ampliar antes el lector — está anotado en el plan.
-- **Decidir si `docx-rs` sirve como writer.** Sigue abierto. El spike R1 sólo cerró la lectura.
-- **Validar en Word y LibreOffice** es criterio de aceptación y no hay LibreOffice en el entorno
-  de CI actual: hay que preverlo (checklist manual por release, o `soffice` headless en el runner
-  Linux).
-
----
-
-## Fase 3 — Hojas de cálculo (XLSX/XLS)
-
-### Lo que ya está hecho
-
-- **El corpus xlsx existe**: `values-types`, `formulas-basic`, `formulas-shared`,
-  `number-formats`, `merged-cells` e `images-anchored` (los tres anclajes). Generado en la Fase 0
-  precisamente para no tener que inventarlo con prisa.
-- **El lado `Workbook` del IR está definido y probado**: `Sheet`, `Cell`, `CellValue`, `Formula`
-  con su dialecto, `NumFmt`, `CellRef` con notación A1 en ambos sentidos, `ColProps`, `RowProps`,
-  `Pane`, `DefinedName`. Todo con round-trip JSON verificado.
-- **Los tres anclajes de hoja** están en el modelo de imágenes y el validador ya rechaza usarlos
-  fuera de un `Workbook`.
-- **`float_roundtrip`** está activado: los valores numéricos no se corrompen al pasar por JSON.
-
-### Lo que hay que decidir y construir
-
-1. **Spike del writer xlsx**: `umya-spreadsheet` contra `rust_xlsxwriter`. Criterio: cuál
-   regenera con mayor fidelidad estilos + `numFmt` desde el IR. Documentar en `docs/spikes/`.
-2. **Serialización de hojas a DocMark** (spec §4): la sintaxis está especificada pero **no
-   implementada**. `docsai_docmark::serialize` devuelve hoy front matter y una advertencia
-   `Degraded` explícita para `Document::Workbook`; ese es el punto de entrada.
-3. **Lectura de `xl/drawings/drawing*.xml`** propia con `quick-xml`: ni `calamine` ni `umya`
-   exponen la geometría completa. El módulo `docx/drawing.rs` es el patrón a imitar; el modelo de
-   destino es el mismo.
-
-### Trampas ya identificadas
-
-- **Streaming.** El árbol XML en memoria es cómodo para documentos pero el presupuesto de la hoja
-  de 100 k celdas es < 3 s y < 500 MB. Habrá que usar `calamine` (que es perezoso por hoja) para
-  valores y reservar el árbol propio para partes pequeñas (`styles.xml`, `drawing*.xml`).
-- **Las fechas son números de serie más formato.** El IR guarda `CellValue::DateTime` en ISO-8601
-  para que una edición a mano del DocMark no pueda corromperlas; la conversión de ida y vuelta
-  serial ⇄ ISO es responsabilidad del lector y el escritor.
-- **En anclajes `two-cell` no se serializan `width`/`height`** (spec §4.1): el tamaño lo define la
-  rejilla. El escritor de atributos ya lo contempla.
-- **Las fórmulas conservan su dialecto**, no se traducen (riesgo R5). `FormulaDialect` ya está en
-  el IR.
-
----
-
-## Fase 4 — ODF (ODT y ODS)
-
-- `docsai-odf` es un esqueleto con la constante `FORMATS`; la regla de dependencia ya la impone
-  el compilador.
-- El punto duro conocido es la **des-automatización de estilos**: los `office:automatic-styles`
-  de ODF representan formato directo, y hay que mapearlos a deltas del IR. El modelo
-  «referencia + delta» está preparado para recibirlos: `FontProps::minus()` es exactamente la
-  operación inversa.
-- `detect()` ya reconoce ODF por `content.xml` + `mimetype`; sólo desempata `.odt` de `.ods` por
-  extensión, lo que habrá que afinar leyendo el `mimetype`.
-- El modelo de imágenes tiene ya los conceptos que ODF necesita (`as-char`/`char`/`paragraph`/
-  `page` → `Inline`/`Floating`, `fo:clip` → `CropRect`).
-
----
-
-## Fase 5 — DOC legado
-
-- `detect()` ya reconoce el contenedor OLE2 y desempata `.doc` de `.xls` por nombre; queda
-  sustituirlo por lectura del directorio CFB.
-- La estrategia de dos niveles del análisis §1.3 sigue en pie: fallback a LibreOffice headless
-  y extractor nativo degradado.
-- El `Warning::ImageGeometryDegraded` que necesita el extractor nativo ya existe y ya se usa
-  (para VML), así que el patrón está establecido.
-
----
-
-## Fases 6 a 9 — Producto, MCP y endurecimiento
-
-- **CLI (Fase 6)**: `convert` y `formats` existen con `--fidelity`, `--assets-dir`, `--json`,
-  `--strict`, `--verbose` y los códigos de salida de arquitectura §5. Faltan `inspect`,
-  `roundtrip`, `--style-map`, stdin/stdout con `-`, el procesado por lotes y `cargo-dist`.
-- **MCP (Fase 7)**: `docsai-mcp` declara las cuatro tools. La regla de stdout limpio ya se
-  respeta en la CLI (`tracing` escribe siempre a stderr), así que el test automático de esa
-  garantía tiene sentido desde ya.
-- **Endurecimiento (Fase 8)**: parte del trabajo está adelantado —topes de descompresión, límite
-  de profundidad XML, saneado de rutas, 900+ inputs corruptos en CI—. Lo que falta es `cargo-fuzz`
-  de verdad, la suite adversaria completa, los benchmarks con `criterion` y `cargo audit`/`deny`.
-  El corpus existente sirve de semilla para el fuzzing.
-
----
-
-## Deuda técnica conocida
-
-Ninguna de estas cosas bloquea nada, pero conviene tenerlas anotadas:
-
-| Punto | Dónde | Nota |
-|---|---|---|
-| Documentos reales anonimizados | Fase 1, tarea 10 | El corpus sintético cubre los rasgos uno a uno, pero no las rarezas del mundo real |
-| Cuadros de texto como raw-block | `docx/drawing.rs` | El tipo del IR y la sintaxis de la spec existen; falta emitir y reconstruir |
-| `w:lvlOverride` no modelado | `docx/numbering.rs` | Emite `Warning::Degraded` |
-| Comentarios ignorados | `docx/body.rs` | Fuera de alcance v1; emite advertencia |
-| Efectos DrawingML | `docx/drawing.rs` | Se detectan y se avisa, pero aún no se vuelcan a `effects_raw` |
-| Árbol XML en memoria | `office/xml.rs` | Revisar para hojas grandes en la Fase 3 |
-| Hash FNV para assets | `model/assets.rs` | Suficiente hoy; revisar si el nombre pasa a ser frontera de confianza |
-
-## Reglas que no conviene romper
-
-1. **No adelantar fases.** El orden del plan responde a dependencias reales.
-2. **No cambiar la spec DocMark para hacer pasar un test.** Está congelada en v1.0; cualquier
-   cambio sube la versión del front matter y documenta la migración.
-3. **Nada se degrada en silencio.** Toda pérdida es una `Warning` tipada.
-4. **Los parsers nunca entran en pánico.** Hay un test que lo comprueba con 900+ entradas
-   corruptas; que siga pasando.
-5. **El serializador es determinista.** `BTreeMap` siempre, `HashMap` nunca, en cualquier camino
-   que llegue a la salida.
diff --git a/kb/README.md b/kb/README.md
index 956271c..024e9fc 100644
--- a/kb/README.md
+++ b/kb/README.md
@@ -1,37 +1,37 @@
-# Base de conocimiento de `docsai`
+# Knowledge base for `docsai`
 
-Documentación de trabajo sobre **lo que hay construido**, cómo está organizado y qué hay que
-tener en cuenta al abordar las fases siguientes. Complementa —no sustituye— la documentación de
-diseño de [`docs/`](../docs/), que describe el proyecto completo tal como se concibió.
+Working documentation on **what is already built**, how it is organized, and what to keep in
+mind when tackling the next phases. It complements — does not replace — the design documentation
+in [`docs/`](../docs/), which describes the full project as originally conceived.
 
-Diferencia práctica entre ambas carpetas:
+Practical difference between the two folders:
 
-| Carpeta | Responde a |
+| Folder | Answers |
 |---|---|
-| [`docs/`](../docs/) | Qué se quiere construir y por qué: análisis, spec DocMark, arquitectura, plan por fases |
-| `kb/` (esta) | Qué está construido hoy, cómo, y qué se sabe ya sobre lo que viene |
+| [`docs/`](../docs/) | What we want to build and why: analysis, DocMark spec, architecture, phased plan |
+| `kb/` (this one) | What is built today, how, and what is already known about what comes next |
 
-## Índice
+## Index
 
-| Documento | Contenido |
+| Document | Contents |
 |---|---|
-| [01 — Resumen de las fases 0 y 1](01-resumen-fases-0-1.md) | Qué se entregó, criterios de aceptación, qué quedó fuera y por qué |
-| [02 — Estructura del proyecto](02-estructura-proyecto.md) | Crates, módulos, reglas de dependencia y por dónde entra cada cosa |
-| [03 — Decisiones técnicas](03-decisiones-tecnicas.md) | Las decisiones no obvias, con su motivo y su coste |
-| [04 — Consideraciones para las siguientes fases](04-siguientes-fases.md) | Lo que la Fase 2 y posteriores encontrarán ya resuelto, y lo que les espera |
+| [01 — Summary of phases 0 and 1](01-phases-0-1-summary.md) | What was delivered, acceptance criteria, what was left out and why |
+| [02 — Project structure](02-project-structure.md) | Crates, modules, dependency rules, and where each piece enters |
+| [03 — Technical decisions](03-technical-decisions.md) | The non-obvious decisions, with their rationale and cost |
+| [04 — Considerations for the next phases](04-next-phases.md) | What Phase 2 and later will already find solved, and what awaits them |
 
-## Estado en una línea
+## Status in one line
 
-**Fases 0 y 1 cerradas**: `docsai convert x.docx -o x.dmk.md` funciona con estilos, listas,
-tablas, imágenes (geometría completa), cabeceras, pies, notas al pie, campos y propiedades. La
-vuelta (DocMark → `.docx`) es la Fase 2 y no existe todavía.
+**Phases 0 and 1 closed**: `docsai convert x.docx -o x.dmk.md` works with styles, lists,
+tables, images (full geometry), headers, footers, footnotes, fields, and properties. The reverse
+path (DocMark → `.docx`) landed in Phase 2.
 
-## Comprobaciones rápidas
+## Quick checks
 
 ```bash
 cargo test --workspace                                  # 164 tests
 cargo clippy --workspace --all-targets -- -D warnings
 cargo fmt --all -- --check
-python3 corpus/generate.py --check                      # el corpus está al día
-cargo run -p docsai-cli -- formats                      # matriz de soporte real del binario
+python3 corpus/generate.py --check                      # corpus is up to date
+cargo run -p docsai-cli -- formats                      # real support matrix of the binary
 ```