@mcptoolshop/style-dataset-lab 3.0.1 → 3.2.0

package/CHANGELOG.md

@@ -2,6 +2,83 @@
 
 All notable changes to this project will be documented in this file.
 
+## Unreleased
+
+## [3.2.0] - 2026-07-06
+
+The **canon authoring** release. A new `sdlab canon *` namespace turns a project's canon entity store into the projections training actually consumes, and wraps a witness-backed freeze spine around entries that must not drift — plus first-class Flux and Qwen-Image training paths.
+
+### Added
+
+- **Canon authoring namespace (`sdlab canon *`)** — the headline of this release:
+  - **`sdlab canon build`** (#16) — builds three canonical projections from a project's canon entity store: `dataset.jsonl` (for training adapters), `prompts/<id>.j2` (Jinja2 templates for ComfyUI invocation), and `context/<id>.md` (narrative blocks for Role OS dispatch). Output keyed by `<canon_sha>` with a content-addressable cache under `canon-build/.cache/`. Flags: `--full`, `--no-cache`, `--dry-run`, `--only <ids>`, `--json`, `--quiet`.
+  - **`sdlab canon freeze` / `unfreeze` / `freeze-status`** (#17) — witness-chain freeze tooling. `freeze` stamps a freeze block on an entry (witnessed against a canon-build output via `locked_at_build`), writing both the entry frontmatter and an append-only `canon-build/freeze-events.jsonl`. Statuses: `frozen` (regen refused; unfreeze ceremony required) and `soft-advisory` (refused by default, bypassable with `--i-know`). `--reason` is required on freeze/unfreeze — the audit record depends on it. `freeze-status` is a read-only glance at an entry's state.
+  - **`sdlab canon drift`** (#19) — for every frozen / on-canon-change entry, recomputes the watch-field hash and compares against the hash stamped in the latest canon-build manifest; reports drifted entries and overrides since a given build.
+- **Canon schema system** (#18) — Star Freight Grounded canon shipped as worked example data (28 entities across 5 entry schemas), demonstrating the entity format `canon build` consumes.
+- **`flux-natural-language` caption strategy** (#11) — natural-language captions for Flux.1-dev LoRA training, alongside the existing SDXL trigger-word strategy.
+- **Two-LoRA stack training contract** (#15) — threads the `is_style_lora` boolean through profiles and adapters (world/style LoRAs → `true`, per-character subject LoRAs → `false`), driving trainer regularization for the two-LoRA stacking pattern.
+- **Flux training targets** — Flux-target training profiles (#12) and Flux-target ComfyUI workflow profiles (#13) for Star Freight, plus the **`ai-toolkit` adapter** for Flux LoRA training (#14): emits `dataset/<partition>/<record_id>.{png,txt}` + `metadata/<partition>.jsonl` + an `ai-toolkit-config.yaml` that Ostris [ai-toolkit](https://github.com/ostris/ai-toolkit) consumes directly. Flux-only — rejects non-Flux profiles with `ADAPTER_TARGET_FAMILY_MISMATCH`; emits `is_style` from the profile's `is_style_lora`. Registered in `ADAPTER_REGISTRY` beside `generic-image-caption` and `diffusers-lora`.
+- **Qwen-Image native generation** (#24) — native non-anime Qwen-Image generation path with a `gpu_model` override.
+- **Qwen DiT LoRA chain** (#25) — DiT LoRA chaining in both Qwen runners, with tallow-fen style-LoRA dataset wiring.
+
+### Fixed
+
+- **Caption prompt bleed** (#9) — routed captions through the shared research-backed builder so prompt fragments no longer bleed across records.
+- **Freeze witness-chain drift** (#19) — the drift CLI reads `.watch_hash` from the rich freeze stamp, and `freeze-status` surfaces resolved `watch_fields`.
+
+### Changed
+
+- Training adapter registry now exposes three adapters — `generic-image-caption`, `diffusers-lora`, `ai-toolkit`; the handbook reference and README document the `ai-toolkit` Flux-only precondition.
+- `projects/`: rustline and tallow-fen production style datasets added as worked examples (repo-clone content; not shipped in the npm package).
+
+### Dependencies
+
+- **`yaml@^2.8.3`** added as a runtime dependency for the ai-toolkit YAML config (#14), kept current in the range (#23). CI: `actions/checkout` 6→7 (#30), `codecov/codecov-action` 5→7 (#31).
+
+### Tests & coverage
+
+- **368 tests, 0 failing.** Coverage: statements **60.36%** / branches **75.5%** / functions **68.35%**.
+
+## [3.1.0] - 2026-04-22
+
+### Added — `--resume` for `generate` and `batch generate`
+
+- **`sdlab generate --resume`** — skip subjects whose record JSON and output PNG are already on disk. Seeds remain stable: skipped slots still advance the seed counter so resumed runs are bit-identical to a fresh run that reaches the same point. Final summary now reports `(N errors, M resumed)`.
+- **`sdlab batch generate --resume <batch_id>`** — re-runs only failed/missing slots in an existing batch, keeps the same `batch_id`, and inherits `mode_id`/`subject_id`/`theme`/`asset_ref` from the prior manifest. Surfaces "(C/T slots already complete)" in the header. Throws `BATCH_NOT_FOUND` for a bad id and `BATCH_NO_PROGRESS` for pre-checkpoint manifests that can't be partially resumed.
+- **Manifest format:** `slots[].status` is now persisted (`'ok'` or `'error'`) so resume can distinguish failures from successes. Older manifests fall back to "selected_output truthy = success" for compatibility.
+- New helpers: `buildCompletedSlotMap()`, `openBatchDirForResume()` in `lib/batch-runs.js`.
+- 7 new tests in `tests/lib-pipeline/batch-resume.test.js`.
+
+### Fixed — Deterministic SaveImage node selection (PB-003)
+
+- **`lib/comfyui-output.js`** (new): `pickOutputImage(outputs, { preferNodeId })` selects the canonical SaveImage output deterministically. Previously, `comfyui-runner.js` and `generate.js` used `Object.values(outputs)` and broke on the first node with images — first-wins ordering depends on ComfyUI's execution scheduler, not the workflow graph.
+- **Selection precedence:** explicit `preferNodeId` (from the workflow builder's `saveNodeId` or a brief's `expected_outputs.save_node_id`) → highest numeric node id (typical "final save" convention) → first iteration entry (only for non-numeric ids).
+- `lib/adapters/comfyui-runner.js` and `scripts/generate.js` both updated to thread `saveNodeId` through to the picker.
+- Run output records now include `comfy_node_id` so the chosen save node is auditable from the manifest.
+- 9 new tests in `tests/lib-pipeline/comfyui-output.test.js`.
+
+### Added — CI coverage reporting
+
+- **`c8`** added as a `devDependency`; new `npm run coverage` script runs the full test suite under c8 with text + lcov + text-summary reporters (covering `lib/**/*.js`).
+- **CI**: Node 22 matrix entry now runs `npm run coverage` and uploads `coverage/lcov.info` to Codecov via `codecov/codecov-action@v5` (`continue-on-error: true` so a Codecov outage never blocks the PR).
+- **README**: CI and Codecov badges added beside the npm/license badges.
+- **`.gitignore`**: `coverage/` and `.nyc_output/` excluded.
+- Baseline coverage at this commit: **statements 40.6% / branches 70.7% / functions 54.0%** — meaningful coverage on `lib/snapshot.js`, `lib/split.js`, `lib/log.js`, `lib/args.js`, `lib/runtime-runs.js`; adapters and selection layers still uncovered (deferred to future passes).
+
+### Fixed — Mobile nav on landing + handbook (SB-SDL-007)
+
+- **`site/src/layouts/SiteLayout.astro`**: header was `hidden md:flex` for both the link nav and the npm/GitHub buttons, leaving phones with the brand mark and nothing else. Added a hamburger toggle (`md:hidden`) that opens a drawer containing all the same links plus npm/GitHub. Implemented as a `<details>`/`<summary>` so it works without any JavaScript or framework dependency.
+- The desktop nav and the GitHub button still render unchanged at `md:` and up.
+
+### Changed — Training adapter registry (DB-007)
+
+- **`lib/training-adapters.js`** (new): explicit `ADAPTER_REGISTRY` with `loadAdapter()`, `listAdapters()`, `isRegisteredAdapter()`. Replaces the hand-maintained adapter list embedded in a `lib/training-packages.js` error string.
+- **`lib/training-packages.js`**: dropped its private `loadAdapter()`; now imports from the registry. Unknown adapters throw `ADAPTER_NOT_REGISTERED` (input error, exit 1) with the available-adapter list always in sync. Registered-but-missing modules throw `ADAPTER_MODULE_LOAD_FAILED` (distinct from a typo).
+- **`lib/training-profiles.js`**: `validateProfile()` now rejects profiles whose `adapter_targets[]` cite an unregistered adapter — surfaces typos at profile load time instead of at package-build time.
+- 8 new tests in `tests/lib-pipeline/training-adapters.test.js`.
+
+To add a new adapter (e.g. `kohya-lora`, `onedtrainer`): write `lib/adapters/<id>.js` exporting `buildPackage(opts)` and add a one-line entry to `ADAPTER_REGISTRY`. The error message, profile validation, and (eventually) CLI completion all pick it up automatically.
+
 ## [3.0.1] - 2026-04-21
 
 ### Fixed — Dogfood swarm health pass (Stage A: bugs & security)

package/README.es.md

@@ -8,16 +8,18 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@mcptoolshop/style-dataset-lab"><img src="https://img.shields.io/npm/v/@mcptoolshop/style-dataset-lab" alt="npm"></a>
+  <a href="https://github.com/mcp-tool-shop-org/style-dataset-lab/actions/workflows/ci.yml"><img src="https://github.com/mcp-tool-shop-org/style-dataset-lab/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://codecov.io/gh/mcp-tool-shop-org/style-dataset-lab"><img src="https://codecov.io/gh/mcp-tool-shop-org/style-dataset-lab/branch/main/graph/badge.svg" alt="codecov"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
 </p>
 
-Escriba sus reglas visuales. Genere arte. Evalúe cada imagen según esas reglas. Entregue los resultados como datos de entrenamiento versionados y auditables.
+Escribe tus reglas visuales. Genera arte. Evalúa cada imagen según esas reglas. Entrega los resultados como datos de entrenamiento auditables y versionados, y luego utiliza los modelos entrenados en flujos de trabajo de producción reales, e introduce las mejores salidas nuevamente en tu corpus.
 
-Style Dataset Lab conecta lo que ha escrito sobre su estilo artístico con el conjunto de datos con el que realmente entrena. Usted define una constitución: reglas de silueta, restricciones de paleta, lenguaje de materiales, cualquier cosa que sea importante para su proyecto. El proceso genera candidatos, los evalúa según esas reglas y empaqueta el trabajo aprobado en conjuntos de datos reproducibles donde cada registro explica por qué se incluyó.
+Style Dataset Lab conecta lo que has definido sobre tu estilo artístico con el conjunto de datos del cual realmente estás entrenando, y luego cierra el ciclo a lo largo de todo el proceso de producción. Defines una constitución: reglas de silueta, restricciones de paleta, lenguaje de materiales, o cualquier cosa que sea importante para tu proyecto. El flujo de trabajo genera candidatos, los evalúa según esas reglas y empaqueta el trabajo aprobado en conjuntos de datos reproducibles donde cada registro explica por qué se incluyó.
 
-El ciclo se cierra: entrena un modelo, genera nuevas salidas, evalúalas según el mismo criterio y vuelve a incluir lo que cumple los requisitos. El conjunto de datos crece y las reglas se mantienen.
+Luego, el entorno de trabajo de producción toma el control: compila resúmenes de generación a partir de la información del proyecto, ejecútalos a través de ComfyUI, evalúa las salidas, produce en lote hojas de expresión y paneles de entorno, selecciona los mejores resultados y vuelve a introducirlos como nuevos candidatos. El ciclo se cierra: producir, seleccionar, revisar, mejorar.
 
-## El proceso
+## El flujo de trabajo
 
 ```bash
 # Write your canon. Scaffold the project.
@@ -28,59 +30,104 @@ sdlab generate inputs/prompts/wave1.json --project my-project
 sdlab curate <id> approved "Strong silhouette, correct faction palette"
 
 # Bind approved work to constitution rules
-sdlab bind --project my-project
+# (`sdlab bind` is a shorter alias for `canon-bind`)
+sdlab canon-bind --project my-project
 
 # Freeze a versioned dataset
 sdlab snapshot create --project my-project
 sdlab split build
 sdlab export build
 
-# Build a training package and close the loop
+# Build a training package
 sdlab training-manifest create --profile character-style-lora
 sdlab training-package build
-sdlab eval-run create && sdlab eval-run score <id> --outputs results.jsonl
-sdlab reingest generated --source ./outputs --manifest <id>
+
+# Compile a production brief and run it
+sdlab brief compile --workflow character-portrait-set --subject kael_maren
+sdlab run generate --brief brief_2026-04-16_001
+
+# Critique, refine, batch-produce
+sdlab critique --run run_2026-04-16_001
+sdlab refine --run run_2026-04-16_001 --pick 001.png
+sdlab batch generate --mode expression-sheet --subject kael_maren
+
+# Select the best outputs and bring them back
+sdlab select --run run_2026-04-16_001 --approve 001.png,003.png
+sdlab reingest selected --selection selection_2026-04-16_001
 ```
 
-Esa última instrucción es clave. Las salidas generadas vuelven a pasar por el mismo proceso de revisión que todo lo demás. El ciclo se cierra.
+Ese último comando es el punto clave. Las salidas seleccionadas vuelven a pasar por el mismo proceso de revisión que todo lo demás. El corpus crece y las reglas se mantienen.
+
+## Creación del canon
+
+Antes de que se ejecute el flujo de trabajo del conjunto de datos, el espacio de nombres `sdlab canon *` convierte el almacén de entidades del canon de tu proyecto en los tres proyecciones que realmente utiliza el entrenamiento y la producción, y bloquea las entradas que no deben modificarse.
+
+```bash
+# Build three projections from the canon entity store:
+#   dataset.jsonl  → training adapters
+#   prompts/*.j2   → ComfyUI workflow invocation
+#   context/*.md   → Role OS narrative dispatch
+sdlab canon build --project my-project
+
+# Freeze an entry so regeneration can't silently change it
+sdlab canon freeze kael_maren --project my-project --reason "prologue portrait locked"
+
+# Report drift on frozen entries since the last clean build
+sdlab canon drift --project my-project
+```
 
-## Lo que produce
+`canon build` es direccionable por contenido: su salida se identifica mediante un `canon_sha` y se almacena en caché, de modo que una reconstrucción del canon sin cambios se realiza instantáneamente. `canon freeze` registra cada congelación frente a una compilación específica y la agrega a un registro de auditoría `freeze-events.jsonl`: las entradas `frozen` rechazan explícitamente la regeneración, las entradas `soft-advisory` la rechazan por defecto (se puede omitir con `--i-know`). `canon drift` vuelve a calcular el hash de cada entrada observada y marca cualquier cosa que haya cambiado desde la última compilación limpia.
 
-Siete artefactos versionados y con sumas de verificación. Cada uno tiene un enlace a sus predecesores para que pueda rastrear cualquier registro de entrenamiento hasta la regla que lo aprobó.
+Flujo de trabajo completo en el manual: [Canon build](handbook/canon-build/), [Canon freeze](handbook/canon-freeze/) y [Two-LoRA stacking](handbook/two-lora-stacking/).
 
-| Artefacto. | Qué es. |
+## Qué produce
+
+Siete artefactos del conjunto de datos y un entorno de trabajo de producción completo. Cada artefacto se vincula a sus predecesores para que puedas rastrear cualquier registro de entrenamiento hasta la regla que lo aprobó.
+
+| Artefacto | Qué es |
 |----------|-----------|
-| **Snapshot** | Selección de registros congelada con huella de configuración. Cada inclusión tiene una razón explícita. |
-| **Split** | Partición de entrenamiento/validación/prueba donde las familias de sujetos nunca cruzan límites. |
-| **Export package** | Conjunto de datos autocontenido: manifiesto, metadatos, imágenes, divisiones, tarjeta del conjunto de datos, sumas de verificación. |
-| **Eval pack** | Tareas de prueba conscientes del criterio: cobertura de áreas, desviación prohibida, referencia/oro, continuidad del sujeto. |
-| **Training package** | Diseño listo para el entrenamiento a través de adaptadores (`diffusers-lora`, `generic-image-caption`). La misma información, en un formato diferente. |
-| **Eval scorecard** | Resultado de aprobación/reprobación por tarea, según la evaluación de las salidas generadas. |
-| **Implementation pack** | Ejemplos de indicaciones, fallos conocidos, pruebas de continuidad y guías para la inclusión. |
+| **Snapshot** | Selección de registros congelados con huella digital de configuración. Cada inclusión tiene una razón explícita. |
+| **Split** | Partición de entrenamiento/validación/prueba donde las familias de sujetos nunca cruzan los límites. |
+| **Export package** | Conjunto de datos autónomo: manifiesto, metadatos, imágenes, divisiones, tarjeta del conjunto de datos, sumas de comprobación. |
+| **Eval pack** | Tareas de prueba con conocimiento del canon: cobertura de carriles, desviación prohibida, ancla/oro, continuidad del sujeto. |
+| **Training package** | Diseño listo para el entrenamiento a través de adaptadores (`diffusers-lora`, `generic-image-caption`). La misma información, diferente formato. |
+| **Eval scorecard** | Aprobación/rechazo por tarea basada en la evaluación de las salidas generadas con respecto a los paquetes de evaluación. |
+| **Implementation pack** | Ejemplos de indicaciones, fallas conocidas, pruebas de continuidad y orientación para volver a introducir datos. |
+
+El entorno de trabajo de producción agrega:
 
-## Por qué existe
+| Superficie | Qué hace |
+|---------|-------------|
+| **Compiled brief** | Instrucción de generación determinista a partir del perfil del flujo de trabajo + la información del proyecto. |
+| **Run** | Artefacto de ejecución congelado: resumen + semillas + salidas de ComfyUI + manifiesto. |
+| **Critique** | Evaluación estructurada multidimensional de las salidas de ejecución con respecto al canon. |
+| **Batch** | Producción coordinada en múltiples ranuras (hojas de expresión, paneles de entorno, paquetes de silueta). |
+| **Selection** | Artefacto de decisión creativa: qué salidas se eligieron, por qué y de dónde provienen. |
+| **Re-ingest** | Las salidas seleccionadas se devuelven como registros candidatos con el origen completo de la generación. |
 
-Los datos de entrenamiento son el activo más valioso en cualquier canal de IA visual. Pero la mayoría de los datos de entrenamiento son una carpeta de imágenes sin historial, sin rastro de evaluación y sin conexión con las reglas de estilo que se suponía que debían seguir.
+## Por qué existe esto
 
-Style Dataset Lab hace que esa conexión sea explícita. Su constitución define las reglas. Su rúbrica define las dimensiones de la evaluación. Sus registros de curación registran la evaluación. Su canon vinculante prueba la conexión. Y su conjunto de datos transmite todo eso como una verdad estructurada, consultable y reproducible.
+Los datos de entrenamiento son el artefacto más importante en cualquier flujo de trabajo de IA visual. Pero la mayoría de los datos de entrenamiento son una carpeta de imágenes sin historial, sin rastro de evaluación y sin conexión con las reglas de estilo que se suponía que debían seguir.
 
-El resultado práctico: cuando su LoRA se desvía, puede preguntar *por qué*. Cuando su próxima ronda de entrenamiento necesita mejores datos, sabe exactamente qué registros están cerca de cumplir los requisitos y qué regla específica no cumplieron. Cuando un nuevo miembro del equipo pregunta cuál es el lenguaje visual del proyecto, la respuesta no es una pizarra de Figma, sino una constitución con 1182 ejemplos clasificados y que se puede buscar.
+Style Dataset Lab hace que la conexión sea explícita. Tu constitución define las reglas. Tu rúbrica define las dimensiones de puntuación. Tus registros de curación registran el juicio. El enlace del canon prueba la conexión. Y tu conjunto de datos lleva todo eso adelante como información estructurada, consultable y reproducible.
+
+El resultado práctico: cuando tu LoRA se desvía, puedes preguntar *por qué*. Cuando tu próxima ronda de entrenamiento necesita mejores datos, sabes exactamente qué registros son casi correctos y cuál es la única regla que no cumplieron. Cuando un nuevo miembro del equipo pregunta cuál es el lenguaje visual del proyecto, la respuesta no es un panel de Figma, sino una constitución consultable con 1182 ejemplos calificados.
 
 ## Cinco dominios, reglas reales
 
-No son plantillas genéricas. Cada dominio viene con reglas de constitución de calidad de producción, definiciones de áreas, rúbricas de evaluación y vocabulario específico.
+No son plantillas genéricas. Cada dominio se entrega con reglas de constitución de grado de producción, definiciones de carriles, rúbricas de puntuación y vocabulario de grupo.
 
-| Dominio. | Áreas. | Qué se evalúa. |
+| Dominio | Carriles | Qué se evalúa |
 |--------|-------|-----------------|
-| **game-art** | personaje, entorno, accesorio, interfaz de usuario, nave, interior, equipo. | Silueta a escala de juego, identificación de facción, desgaste y envejecimiento. |
-| **character-design** | retrato, cuerpo entero, vista de 360 grados, hoja de expresiones, pose de acción. | Proporciones, lógica del atuendo, personalidad, claridad del gesto. |
-| **creature-design** | concepto, ortográfico, estudio de detalles, acción, referencia de escala, hábitat. | Anatomía, lógica evolutiva, distinción de silueta. |
-| **architecture** | exterior, interior, paisaje urbano, detalle estructural, ruina, paisaje. | Estructura, consistencia de materiales, perspectiva, coherencia de la época. |
-| **vehicle-mech** | exterior, cabina, componente, esquema, hoja de silueta, variante de daño. | Lógica mecánica, lenguaje de diseño, puntos de acceso, narrativa de daño. |
+| **game-art** | personaje, entorno, accesorio, interfaz de usuario, nave, interior, equipo | Silueta a escala de juego, identificación de facción, desgaste y envejecimiento |
+| **character-design** | retrato, cuerpo completo, rotación, hoja de expresión, pose de acción | Proporciones, lógica del disfraz, personalidad, claridad del gesto |
+| **creature-design** | concepto, ortográfico, estudio de detalles, acción, referencia de escala, hábitat | Anatomía, lógica evolutiva, distinción de la silueta |
+| **architecture** | exterior, interior, paisaje urbano, detalle estructural, ruina, paisaje | Estructura, consistencia del material, perspectiva, coherencia de la época |
+| **vehicle-mech** | exterior, cabina, componente, esquema, hoja de silueta, variante de daño | Lógica mecánica, lenguaje de diseño, puntos de acceso, narrativa de daños |
 
 ## Estructura del proyecto
 
-Cada proyecto es independiente. Cinco archivos de configuración JSON definen las reglas; todo lo demás es datos.
+Cada proyecto es independiente. Cinco archivos de configuración JSON definen las reglas; todo lo demás son datos.
 
 ```
 projects/my-project/
@@ -94,21 +141,27 @@ projects/my-project/
   splits/                Train/val/test partitions
   exports/               Versioned export packages
   training/              Profiles, manifests, packages, eval runs, implementations
+  workflows/             Workflow profiles + batch mode definitions
+  briefs/                Compiled generation briefs
+  runs/                  Execution artifacts (brief + outputs + manifest)
+  batches/               Coordinated multi-slot productions
+  selections/            Chosen outputs with reasons and provenance
+  inbox/generated/       Re-ingested images awaiting review
 ```
 
 ## Propiedades de confianza
 
-Estas no son meras aspiraciones. Se aplican de forma obligatoria.
+Estas no son aspiracionales. Se aplican rigurosamente.
 
 - **Las instantáneas son inmutables.** La huella digital de la configuración (SHA-256) demuestra que nada ha cambiado.
-- **Las divisiones evitan fugas de información.** Las familias de sujetos (por identidad, linaje o sufijo de ID) nunca cruzan los límites de la partición.
-- **Los manifiestos son contratos inalterables.** Exporta el hash + la huella digital de la configuración. Si algo cambia, crea uno nuevo.
-- **Los adaptadores no pueden modificar la información.** Diferente diseño, mismos registros. No hay adiciones, ni eliminaciones, ni reclasificaciones.
-- **Las salidas generadas se revisan antes de ser utilizadas.** No hay excepciones. Se curan y se vinculan como todo lo demás.
+- **Las divisiones evitan fugas.** Las familias de sujetos (por identidad, linaje o sufijo de ID) nunca cruzan los límites de las particiones.
+- **Los manifiestos son contratos congelados.** Hash de exportación + huella digital de la configuración. Si algo cambia, cree uno nuevo.
+- **Los adaptadores no pueden modificar la verdad.** Diseño diferente, mismos registros. Sin adiciones, sin eliminaciones, sin reclasificaciones.
+- **Las salidas generadas vuelven a entrar mediante revisión.** No hay atajos. Curar y vincular como todo lo demás.
 
 ## Star Freight
 
-El repositorio incluye un ejemplo de funcionamiento completo: 1182 registros, 5 facciones, 7 rutas, 24 reglas constitucionales, 892 activos aprobados, 2 perfiles de entrenamiento. Un canon visual de un RPG de ciencia ficción realista, completamente curado.
+El repositorio incluye un ejemplo completo y funcional: 1.182 registros, 5 facciones, 7 rutas, 24 reglas de constitución, 892 activos aprobados, 2 perfiles de entrenamiento. Un canon visual de ciencia ficción con toques ásperos, totalmente curado.
 
 ```bash
 git clone https://github.com/mcp-tool-shop-org/style-dataset-lab
@@ -118,9 +171,9 @@ sdlab snapshot create --project star-freight   # 839 eligible records
 sdlab split build --project star-freight       # zero subject leakage
 ```
 
-## Formatos de salida
+## Formatos posteriores
 
-`sdlab` es el propietario del conjunto de datos. La conversión de formatos la gestiona [`repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset): TRL, LLaVA, Qwen2-VL, JSONL, Parquet, y más. `repo-dataset` se encarga de la renderización; nunca decide qué incluir.
+`sdlab` es el propietario del conjunto de datos. La conversión de formato la gestiona [`repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset): TRL, LLaVA, Qwen2-VL, JSONL, Parquet y más. `repo-dataset` renderiza; nunca decide qué incluir.
 
 ## Instalación
 
@@ -130,9 +183,69 @@ npm install -g @mcptoolshop/style-dataset-lab
 
 Requiere Node.js 20+ y [ComfyUI](https://github.com/comfyanonymous/ComfyUI) en localhost:8188 para la generación.
 
+### Pruébalo sin ComfyUI
+
+Puedes explorar toda la funcionalidad que no implica la generación (inspección, curación, instantánea, división, exportación) utilizando el proyecto Star Freight incluido sin instalar ComfyUI ni descargar ningún peso de SDXL.
+
+```bash
+# Scaffold a fresh project (no ComfyUI needed)
+sdlab init test --domain game-art
+
+# Run the canonical health check (no ComfyUI needed)
+sdlab project doctor --project test
+
+# Dry-run a snapshot against the bundled Star Freight corpus
+sdlab snapshot create --dry-run --project star-freight
+```
+
+`sdlab project doctor` valida cada configuración del proyecto (constitución, rutas, rúbrica, terminología) e informa sobre la elegibilidad sin tocar la GPU. Cualquier comando que modifique el estado generado acepta `--dry-run` para previsualizar el efecto primero.
+
+Si olvidas `--project`, la CLI recurre al primer proyecto que encuentra en `projects/` e imprime una advertencia; pasa `--project` explícitamente para silenciarla.
+
+### Reanudando una ejecución interrumpida
+
+Las ejecuciones de generación largas se pueden reanudar sin rehacer el trabajo completado:
+
+```bash
+# Skip subjects whose record + image are already on disk.
+# Seeds are preserved — resumed runs are bit-identical to fresh ones.
+sdlab generate inputs/prompts/wave1.json --project my-project --resume
+
+# Re-run only failed/missing slots in an existing batch.
+# Inherits mode/subject/theme from the prior manifest.
+sdlab batch generate --resume batch_2026-04-22_001 --project my-project
+```
+
+Ambos comandos funcionan porque cada ranura escribe su entrada de manifiesto atómicamente al finalizar; un fallo a mitad de la ejecución nunca corrompe el estado parcial.
+
+## Solución de problemas
+
+Modos de fallo comunes y soluciones:
+
+**`ECONNREFUSED 127.0.0.1:8188` en cualquier `sdlab generate` / `sdlab run generate` / `sdlab batch generate`**
+ComfyUI no se está ejecutando. Inicia ComfyUI (`python main.py --listen 127.0.0.1 --port 8188`) y confirma con `curl http://127.0.0.1:8188/system_stats`. Para apuntar a un host/puerto diferente, establece `COMFY_URL=http://host:port`.
+
+**`missing checkpoint` / `LoRA weight not found`**
+El perfil de flujo de trabajo especifica un archivo de modelo que no está en la carpeta `models/checkpoints/` o `models/loras/` de ComfyUI. Abre `projects/<project>/workflows/profiles/<profile>.json`, localiza el campo `checkpoint` o `lora` y, ya sea descarga el peso referenciado o cámbialo por uno que ya tengas. Vuelve a ejecutar `sdlab project doctor --project <project>` para confirmar la solución.
+
+**Errores de `sdlab project doctor`**
+Doctor devuelve códigos de error estructurados. Algunos comunes:
+- `E_PROJECT_NOT_FOUND`: el directorio del proyecto no existe en `projects/`. Verifica la ortografía.
+- `E_CONFIG_INVALID`: uno de los cinco archivos de configuración JSON falló la validación del esquema. El campo `hint` indica el archivo y el campo incorrectos.
+- `E_RECORD_DRIFT`: la huella digital de la configuración de un registro ya no coincide con su origen. Vuelve a curar o vuelve a vincular según lo que sugiera la pista.
+
+**`No --project specified, falling back to <name>`**
+Una advertencia leve. Pasa `--project <name>` explícitamente para seleccionar el proyecto correcto y silenciar la advertencia.
+
+**Problemas de memoria VRAM / "Painterly"**
+Consulta `docs/internal/HANDOFF.md` para obtener las notas sobre el ajuste del ruido "painterly". En resumen: reduce la intensidad del ruido, disminuye el tamaño del lote o cambia a un punto de control más pequeño en tu perfil de flujo de trabajo.
+
+**Informar errores**
+Crea un problema en https://github.com/mcp-tool-shop-org/style-dataset-lab/issues con tu versión de sdlab (`sdlab --version`), la versión de Node (`node -v`), el comando completo y la salida de error estructurada. Una plantilla de informe de errores rellena previamente los campos.
+
 ## Seguridad
 
-Solo funciona localmente. No hay telemetría, ni análisis, ni solicitudes externas. Las imágenes permanecen en tu GPU y sistema de archivos.
+Solo local. Sin telemetría, sin análisis, sin solicitudes externas. Las imágenes permanecen en tu GPU y sistema de archivos.
 
 ## Licencia
 
@@ -140,4 +253,4 @@ MIT
 
 ---
 
-Creado por <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a
+Creado por <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>