@mcptoolshop/style-dataset-lab 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -2,23 +2,97 @@
 
 All notable changes to this project will be documented in this file.
 
-## [2.6.0] - 2026-07-01
+## [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)
+
+- **Four Laws enforcement** (`lib/snapshot.js`, `lib/split.js`, `lib/export.js`):
+  - Export now inherits `snapshot.config_fingerprint` instead of recomputing; throws `FINGERPRINT_DRIFT` on mismatch (Law 4).
+  - Deterministic majority-lane per family with lexicographic tie-break, recorded in `audit.family_lane_decisions` (Law 3).
+  - Unassigned-family fallback now throws instead of silently landing in train.
+  - `existsSync` guards across snapshot/split/export/eval/training-manifest/training-package/impl-pack prevent ID collisions from overwriting frozen artifacts (Law 1).
+  - `included.jsonl` entries now carry `rules_checked`, `profile_id`, and `config_fingerprint` for explainable inclusion (Law 2).
+- **Security hardening**: path-traversal rejection on `record.asset_path` and all user-supplied `--source`/`--guide`/`--anchor`/`--ref`/`--outputs`/`--prompt-file`/`--packet-file`/`--domain` flags; URL validation on ComfyUI endpoints; safe filename regex at selection boundaries.
+- **CLI structured errors**: ~25 scripts converted from raw `throw new Error` to `inputError`/`runtimeError` so exit codes are correct (1 = user error, 2 = runtime).
+- **Pipeline correctness**: brief fingerprint uses recursive `canonicalize()` — deterministic across nested key reordering; override precedence fixed (`||` → `??` so legit zero/empty overrides are preserved); negative-prompt dedup switched from substring to token-exact match; adapter output filenames keyed by `record.id` to prevent basename collisions silently dropping records.
+- **Re-ingest**: now actually copies images to `outputs/candidates/` instead of writing records that point at missing files.
+- **Curate ordering**: `curate.js` moves image first, then updates record; bulk-curate trio gained `--dry-run` and standard error handling.
+
+### Added — Dogfood swarm humanization pass (Stage B/C)
+
+- **ComfyUI progress**: `submitAndWait` emits heartbeats every 15 s (queued → generating → completed); bails fast on `execution_error` or unknown status shapes instead of timing out silently.
+- **Atomic manifest writes**: run/batch manifests use temp-file + rename; `checkpointRunManifest` saves progress after every slot so a crash no longer orphans GPU work.
+- **`schema_version` enforcement**: every manifest (`snapshot`, `split`, `export`, `eval-pack`, `eval-run`, `training-manifest`, `training-package`, `implementation-pack`) now stamps `schema_version: '2.2.0'` with warn-on-mismatch loaders.
+- **Export truthfulness**: tracks `expected`/`actual`/`failed` counts with per-record reasons and stderr warnings (no more silent-skip under `catch {}`).
+- **Snapshot resilience**: malformed record JSON lands in `errors[]` instead of aborting the snapshot.
+- **Split audit**: `deviation_from_target` per lane + `overall_deviation_score` in audit output.
+- **Eval scorecards**: `sample_record_ids` up to 5 per failure bucket so operators can investigate.
+- **CLI help**: `sdlab <cmd> --help` now works for 15 top commands via `HELP_TEXT` registry.
+- **Did-you-mean**: hand-rolled Levenshtein suggestion for typo'd commands and flags.
+- **`--project` fallback**: loud 2-line stderr warning when falling back to `star-freight` (silence with `SDLAB_QUIET_FALLBACK=1`).
+- **Signal handling**: `SIGINT` (130), `SIGTERM` (143), `uncaughtException`, `unhandledRejection` handlers at `main()` so Ctrl+C surfaces a clean message.
+- **ETA**: generate and batch-generate print ETA every 5 items with rolling averages.
+- **`result()`/`success()` helpers**: artifact paths always print regardless of `--quiet`.
+- **`sdlab init`**: scaffolded projects now get a `README.md` with quick commands, layout, and TODO sections.
+- **Per-domain example waves**: all 5 domain templates ship `inputs/prompts/example-wave.json` with subjects matching their lane `id_patterns`.
+- **Troubleshooting section**: README covers ComfyUI connection failure, missing weights, doctor errors, `--project` fallback, and bug reporting.
+- **Install as primary CTA**: landing page leads with a copy-to-clipboard install command; `og:image`/`twitter:card` meta added via `SiteLayout`.
 
-### Added
+### Changed
+
+- Moved `HANDOFF.md`, `WAVE_PLAN.md`, `WAVE27A_SESSION_STATE.md` to `docs/internal/` with a README explaining the archive.
+- `lib/deprecation.js`: `--game` deprecation target bumped from "v3.0" (lying, package is 3.0) to "v4.0".
+- Handbook `reference.md` and `architecture.md` rewritten against the v3.0 CLI surface (`--project`, `projects/<name>/`); `--game` demoted to a Legacy section.
+- One-off Star Freight wave-curate scripts excluded from the npm tarball via `files`-field negations (137 → 135 files, 179.3 → 173.9 kB).
+
+### Infrastructure
+
+- **Test suite**: 0 → 98 tests across 12 files (`tests/lib-pipeline/`, `tests/lib-dataset/`, `tests/cli-scripts/`).
+- **CI**: added `pull_request` trigger; `publish.yml` now runs `npm ci` + `npm run verify` + `npm test` + tag-vs-version guard before `npm publish`; `permissions: contents: read` and `persist-credentials: false` across all workflows; npm cache on every `setup-node`.
+- **`package-lock.json`** regenerated from stale v2.2.1 to v3.0.1.
+- **Governance**: added `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `.github/ISSUE_TEMPLATE/{bug_report,feature_request}.md`, `.github/PULL_REQUEST_TEMPLATE.md`.
+- **Dependabot**: groups restricted to `minor`/`patch` so breaking majors get individual PRs.
 
-- **Batch production modes (Phase 4D)** — coordinated multi-slot generation with reviewable sheet output
-  - `sdlab batch generate --mode <id>` — execute a batch production mode (expression sheets, environment boards, etc.)
-  - `sdlab batch show [batch-id]` — list all batches or show batch details
-  - `sdlab batch sheet <batch-id>` — re-render batch sheet from saved manifest
-  - `--dry-run` flag prepares batch directory and briefs without submitting to ComfyUI
-- **Batch modes** (`lib/batch-modes.js`) — load, validate, and list batch mode definitions from `workflows/batch-modes/`
-- **Batch compiler** (`lib/batch-compiler.js`) — expand one batch mode into multiple slot briefs with controlled per-slot deltas
-- **Batch runs** (`lib/batch-runs.js`) — batch directory creation (`batch_YYYY-MM-DD_NNN`), coordinated slot execution, manifest save/load
-- **Batch sheet renderer** (`lib/batch-sheet-render.js`) — HTML review surfaces with CSS grid layout, dark theme, zero dependencies
-- **4 starter batch modes** for Star Freight: expression-sheet, environment-board, silhouette-pack, continuity-variants
-- **JSON schemas** for batch mode definitions and batch manifests (`schemas/`)
-- Doctor validates batch mode definitions (batch_type, subject_mode, slot uniqueness, layout, workflow references)
-- Init scaffolds `workflows/batch-modes/` and `batches/` directories
 ## [3.0.0] - 2026-04-16
 
 ### Added
@@ -55,6 +129,25 @@ All notable changes to this project will be documented in this file.
 - **Handbook** updated: index shows production loop diagram, new [Production Loop](handbook/production-loop/) page with complete end-to-end walkthrough
 - **Package metadata** updated: description, keywords (`generation-workflow`, `batch-production`, `reintegration`), version badge
 - Version bumped to **v3.0.0** — the repo is now a full production workbench, not just a dataset preparation system
+
+## [2.6.0] - 2026-04-16
+
+### Added
+
+- **Batch production modes (Phase 4D)** — coordinated multi-slot generation with reviewable sheet output
+  - `sdlab batch generate --mode <id>` — execute a batch production mode (expression sheets, environment boards, etc.)
+  - `sdlab batch show [batch-id]` — list all batches or show batch details
+  - `sdlab batch sheet <batch-id>` — re-render batch sheet from saved manifest
+  - `--dry-run` flag prepares batch directory and briefs without submitting to ComfyUI
+- **Batch modes** (`lib/batch-modes.js`) — load, validate, and list batch mode definitions from `workflows/batch-modes/`
+- **Batch compiler** (`lib/batch-compiler.js`) — expand one batch mode into multiple slot briefs with controlled per-slot deltas
+- **Batch runs** (`lib/batch-runs.js`) — batch directory creation (`batch_YYYY-MM-DD_NNN`), coordinated slot execution, manifest save/load
+- **Batch sheet renderer** (`lib/batch-sheet-render.js`) — HTML review surfaces with CSS grid layout, dark theme, zero dependencies
+- **4 starter batch modes** for Star Freight: expression-sheet, environment-board, silhouette-pack, continuity-variants
+- **JSON schemas** for batch mode definitions and batch manifests (`schemas/`)
+- Doctor validates batch mode definitions (batch_type, subject_mode, slot uniqueness, layout, workflow references)
+- Init scaffolds `workflows/batch-modes/` and `batches/` directories
+
 ## [2.5.0] - 2026-04-16
 
 ### Added

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,9 @@
+# Code of Conduct
+
+This project follows the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+In short: be respectful, assume good faith, and focus discussion on the technical work. Harassment, personal attacks, and discrimination are not tolerated.
+
+## Reporting
+
+Report concerns by emailing `64996768+mcp-tool-shop@users.noreply.github.com`. Reports are handled confidentially. The full Contributor Covenant enforcement ladder applies (correction → warning → temporary ban → permanent ban).

package/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing to style-dataset-lab
+
+Thanks for your interest. This repo is the canon-aware dataset pipeline for visual AI projects — it prioritizes determinism, auditability, and a single source of truth per project. Contributions that reinforce those properties are welcome.
+
+## Dev setup
+
+```bash
+git clone https://github.com/mcp-tool-shop-org/style-dataset-lab
+cd style-dataset-lab
+npm install        # zero runtime deps; installs dev-only tooling
+npm test           # runs the full node --test suite
+npm run verify     # sanity smoke: help output + project doctor on star-freight
+```
+
+Requires Node.js 20+. ComfyUI is only needed for changes that touch the generation path (`lib/comfyui.js`, `scripts/generate.js`, `scripts/run-generate.js`). Doctrine, snapshot, split, export, and curation paths can all be exercised without a GPU — see the "Try it without ComfyUI" section of the README.
+
+## Coding style
+
+- **ESM only.** Every file uses `import` / `export`. No CommonJS.
+- **No TypeScript.** Plain JavaScript. Types live in JSDoc when they help.
+- **Built-in test runner.** Tests use `node --test` from Node 20+ — no Jest, Vitest, Mocha.
+- **No runtime dependencies.** `package.json` intentionally has zero `dependencies`. Dev-only tooling goes in `devDependencies`; a new runtime dep requires a very good reason.
+- **Structured errors.** Errors follow the Structured Error Shape — `code`, `message`, `hint`, optional `cause`, optional `retryable`. See `lib/errors.js` (or equivalent) for helpers.
+- **Canon is truth.** Never hand-edit generated artifacts (snapshots, splits, exports, runs, critiques, selections). Edit the upstream config or record and re-run.
+
+## Testing
+
+Every change ships with tests. For bug fixes, add a regression test that would have failed before the fix.
+
+```bash
+# Run the full suite
+npm test
+
+# Run a single file
+node --test tests/path/to/file.test.js
+```
+
+CI runs the same suite on Node 20 and Node 22 (see `.github/workflows/ci.yml`).
+
+## PR checklist
+
+Before opening a PR:
+
+- [ ] `npm test` passes locally
+- [ ] `npm run verify` passes locally
+- [ ] New features have test coverage
+- [ ] `CHANGELOG.md` has an entry under `## [Unreleased]`
+- [ ] If you touched `package.json`, you regenerated `package-lock.json` (`npm install --package-lock-only`)
+- [ ] If you added or changed a config file schema, `schemas/` is updated too
+- [ ] Commit message explains *why*, not just *what*
+
+## Shipcheck
+
+Every release passes `npx @mcptoolshop/shipcheck audit` with all hard gates (A–D) green. Before we publish, we also re-read `SHIP_GATE.md` against the current repo state. If your change affects security posture, error handling, operator docs, or shipping hygiene, update `SHIP_GATE.md` in the same PR.
+
+See the [shipcheck docs](https://github.com/mcp-tool-shop-org/shipcheck) for the full quality-gate definition.
+
+## Reporting bugs
+
+File an issue using the bug-report template at https://github.com/mcp-tool-shop-org/style-dataset-lab/issues/new/choose. Minimum repro info:
+
+- `sdlab --version`
+- `node --version`
+- ComfyUI version (if relevant)
+- Project name and relevant config file excerpt
+- `sdlab project doctor --project <name>` output
+- The failing command and full structured error output
+
+## Code of conduct
+
+Be decent. See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) — we use the Contributor Covenant.

package/README.es.md

@@ -8,14 +8,16 @@
 
 <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.
+Escriba sus reglas visuales. Genere arte. Evalúe cada imagen según esas reglas. Envíe los resultados como datos de entrenamiento versionados y auditables, y luego ponga los modelos entrenados en funcionamiento en flujos de trabajo de producción reales y retroalimente los mejores resultados a su 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ó.
 
-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: compile las instrucciones de generación a partir de la "verdad" del proyecto, ejecútelas a través de ComfyUI, evalúe los resultados, genere en masa hojas de expresión y paneles de entorno, seleccione los mejores resultados y reincorpórelos como nuevos candidatos. El ciclo se cierra: producir, seleccionar, revisar, fortalecer.
 
 ## El proceso
 
@@ -28,25 +30,37 @@ 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.
+Esa última instrucción es clave. Los resultados seleccionados vuelven a pasar por el mismo proceso de revisión que todo lo demás. El corpus crece y las reglas se mantienen.
 
 ## Lo que produce
 
-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ó.
+Siete artefactos de conjunto de datos y un entorno de trabajo de producción completo. Cada artefacto está vinculado a sus predecesores, por lo que puede rastrear cualquier registro de entrenamiento hasta la regla que lo aprobó.
 
 | Artefacto. | Qué es. |
 |----------|-----------|
@@ -58,6 +72,17 @@ Siete artefactos versionados y con sumas de verificación. Cada uno tiene un enl
 | **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. |
 
+El entorno de trabajo de producción agrega:
+
+| Superficie | Qué hace |
+|---------|-------------|
+| **Compiled brief** | Generación determinista a partir de la instrucción del perfil de flujo de trabajo + la "verdad" del proyecto. |
+| **Run** | Artefacto de ejecución congelado: instrucción + semillas + resultados de ComfyUI + manifiesto. |
+| **Critique** | Evaluación estructurada y multidimensional de los resultados de la ejecución en comparación con el canon. |
+| **Batch** | Producción coordinada de múltiples elementos (hojas de expresión, paneles de entorno, paquetes de siluetas). |
+| **Selection** | Artefacto de decisión creativa: qué resultados se eligieron, por qué y de dónde provienen. |
+| **Re-ingest** | Los resultados seleccionados se devuelven como registros de candidatos con un historial completo de generación. |
+
 ## Por qué existe
 
 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.
@@ -94,6 +119,12 @@ 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
@@ -130,6 +161,66 @@ 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ébelo sin ComfyUI
+
+Puede explorar toda la superficie de no 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, canales, 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 olvida `--project`, la CLI recurre al primer proyecto que encuentra en `projects/` e imprime una advertencia; use `--project` explícitamente para silenciarla.
+
+### Reanudación de una ejecución interrumpida
+
+Las largas ejecuciones de generación se pueden reanudar sin tener que volver a realizar 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 de forma atómica al finalizar; un fallo durante 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. Inicie ComfyUI (`python main.py --listen 127.0.0.1 --port 8188`) y confirme con `curl http://127.0.0.1:8188/system_stats`. Para apuntar a un host/puerto diferente, establezca `COMFY_URL=http://host:port`.
+
+**`missing checkpoint` / `LoRA weight not found`**
+Su perfil de flujo de trabajo nombra un archivo de modelo que no está en la carpeta `models/checkpoints/` o `models/loras/` de ComfyUI. Abra `projects/<project>/workflows/profiles/<profile>.json`, localice el campo `checkpoint` o `lora` y, ya sea descargue el peso referenciado o reemplácelo por uno que ya tenga. Vuelva a ejecutar `sdlab project doctor --project <project>` para confirmar la solución.
+
+**`sdlab project doctor` errores**
+Doctor devuelve códigos de error estructurados. Algunos comunes:
+- `E_PROJECT_NOT_FOUND` — el directorio del proyecto no existe en `projects/`. Verifique la ortografía.
+- `E_CONFIG_INVALID` — uno de los cinco archivos de configuración JSON no pasó 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. Re-curate o re-asocie según lo sugerido en la pista.
+
+**`No se especificó --project, se utiliza el valor predeterminado <name>`**
+Una advertencia leve. Utilice `--project <name>` explícitamente para seleccionar el proyecto correcto y eliminar la advertencia.
+
+**Problemas de memoria de VRAM relacionados con el estilo "painterly"**
+Consulte el archivo `docs/internal/HANDOFF.md` para obtener información sobre la configuración del estilo "painterly". En resumen: reduzca la intensidad del desenfoque, disminuya el tamaño del lote o cambie a un modelo más pequeño en su perfil de trabajo.
+
+**Informar de errores**
+Registre un problema en https://github.com/mcp-tool-shop-org/style-dataset-lab/issues, incluyendo la versión de sdlab (`sdlab --version`), la versión de Node (`node -v`), el comando completo y la salida de error estructurada. Una plantilla para la presentación de informes de errores precompleta 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.

package/README.fr.md

@@ -8,14 +8,16 @@
 
 <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>
 
-Définissez vos règles visuelles. Générez des œuvres. Évaluez chaque image en fonction de ces règles. Livrez les résultats sous forme de données d'entraînement versionnées et auditables.
+Définissez vos règles visuelles. Générez des images. Évaluez chaque image par rapport à ces règles. Envoyez les résultats sous forme de données d'entraînement versionnées et auditables, puis mettez les modèles entraînés en œuvre dans des flux de travail de production réels et réinjectez les meilleurs résultats dans votre corpus.
 
 Style Dataset Lab relie les éléments que vous avez écrits concernant votre style artistique à l'ensemble de données sur lequel vous entraînez réellement votre modèle. Vous définissez une constitution : règles de silhouette, contraintes de palette, langage des matériaux, tout ce qui est important pour votre projet. Le pipeline génère des candidats, les évalue en fonction de ces règles, et regroupe les œuvres approuvées dans des ensembles de données reproductibles où chaque enregistrement explique pourquoi il a été inclus.
 
-La boucle se referme : entraînez un modèle, générez de nouvelles sorties, évaluez-les en fonction des mêmes critères, réintégrez ce qui est validé. L'ensemble de données grandit et les règles restent valables.
+Ensuite, le poste de travail de production prend le relais : compilez les instructions de génération à partir des informations du projet, exécutez-les via ComfyUI, critiquez les résultats, produisez en lot des feuilles d'expressions et des planches d'environnement, sélectionnez les meilleurs résultats et réintégrez-les en tant que nouveaux candidats. Le cycle se referme : production, sélection, révision, amélioration.
 
 ## Le pipeline
 
@@ -28,25 +30,37 @@ 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
 ```
 
-Cette dernière commande est essentielle. Les sorties générées passent par le même processus de révision que tout le reste. La boucle se referme.
+Cette dernière commande est essentielle. Les résultats sélectionnés sont réexaminés selon le même processus que tous les autres éléments. Le corpus s'enrichit et les règles restent valables.
 
 ## Ce qu'il produit
 
-Sept artefacts versionnés et vérifiés par checksum. Chacun est lié à ses prédécesseurs, ce qui vous permet de retracer tout enregistrement d'entraînement jusqu'à la règle qui l'a approuvé.
+Sept artefacts de jeu de données et un poste de travail de production complet. Chaque artefact est lié à ses prédécesseurs, ce qui vous permet de retracer tout enregistrement d'entraînement jusqu'à la règle qui l'a approuvé.
 
 | Élément | Description |
 |----------|-----------|
@@ -58,6 +72,17 @@ Sept artefacts versionnés et vérifiés par checksum. Chacun est lié à ses pr
 | **Eval scorecard** | Indicateur de réussite/échec par tâche, basé sur l'évaluation des sorties générées par rapport aux ensembles d'évaluation. |
 | **Implementation pack** | Exemples de prompts, échecs connus, tests de continuité et instructions de réintégration. |
 
+Le poste de travail de production ajoute :
+
+| Surface | Ce que cela fait |
+|---------|-------------|
+| **Compiled brief** | Génération déterministe à partir du profil de flux de travail + des informations du projet. |
+| **Run** | Artefact d'exécution figé : instruction + graines + résultats ComfyUI + manifeste. |
+| **Critique** | Évaluation structurée et multidimensionnelle des résultats par rapport à la référence. |
+| **Batch** | Production coordonnée en plusieurs flux (feuilles d'expressions, planches d'environnement, ensembles de silhouettes). |
+| **Selection** | Artefact de décision créative : quels résultats ont été choisis, pourquoi et d'où ils proviennent. |
+| **Re-ingest** | Les résultats sélectionnés sont renvoyés en tant qu'enregistrements candidats avec une traçabilité complète de la génération. |
+
 ## Pourquoi cela existe
 
 Les données d'entraînement sont l'élément le plus important dans tout pipeline d'IA visuelle. Mais la plupart des données d'entraînement ne sont qu'un dossier d'images sans historique, sans trace de jugement et sans lien avec les règles de style qu'elles étaient censées suivre.
@@ -94,6 +119,12 @@ 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
 ```
 
 ## Propriétés de confiance
@@ -130,13 +161,73 @@ npm install -g @mcptoolshop/style-dataset-lab
 
 Nécessite Node.js 20+ et [ComfyUI](https://github.com/comfyanonymous/ComfyUI) installé localement sur le port 8188 pour la génération.
 
+### Essayez-le sans ComfyUI
+
+Vous pouvez explorer toute la surface de non-génération (inspection, curation, instantané, division, exportation) à l'aide du projet Star Freight intégré, sans installer ComfyUI ni télécharger de poids 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` valide chaque configuration de projet (constitution, voies, grille, terminologie) et signale l'éligibilité sans toucher au GPU. Toute commande qui modifie l'état généré accepte l'option `--dry-run` pour prévisualiser l'effet au préalable.
+
+Si vous oubliez `--project`, l'interface de ligne de commande revient au premier projet qu'elle trouve dans le répertoire `projects/` et affiche un avertissement. Utilisez explicitement l'option `--project` pour le supprimer.
+
+### Reprise d'une exécution interrompue
+
+Les longues exécutions peuvent être reprises sans avoir à refaire le travail déjà effectué :
+
+```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
+```
+
+Les deux commandes fonctionnent car chaque emplacement écrit son entrée de manifeste de manière atomique lorsqu'il termine son travail. Ainsi, un crash pendant l'exécution n'endommage jamais l'état partiel.
+
+## Dépannage
+
+Modes de défaillance courants et solutions :
+
+**`ECONNREFUSED 127.0.0.1:8188` pour toute commande `sdlab generate` / `sdlab run generate` / `sdlab batch generate`**
+ComfyUI n'est pas en cours d'exécution. Démarrez ComfyUI (`python main.py --listen 127.0.0.1 --port 8188`) et vérifiez avec `curl http://127.0.0.1:8188/system_stats`. Pour pointer vers un autre hôte/port, définissez `COMFY_URL=http://host:port`.
+
+**`missing checkpoint` / `LoRA weight not found`**
+Votre profil de flux de travail fait référence à un fichier de modèle qui ne se trouve pas dans les dossiers `models/checkpoints/` ou `models/loras/` de ComfyUI. Ouvrez `projects/<project>/workflows/profiles/<profile>.json`, localisez le champ `checkpoint` ou `lora` et téléchargez le fichier de poids référencé ou remplacez-le par un fichier que vous avez déjà. Relancez `sdlab project doctor --project <project>` pour confirmer la correction.
+
+**`sdlab project doctor` errors**
+Doctor renvoie des codes d'erreur structurés. Les plus courants sont :
+- `E_PROJECT_NOT_FOUND` — le répertoire du projet n'existe pas sous `projects/`. Vérifiez l'orthographe.
+- `E_CONFIG_INVALID` — l'un des cinq fichiers de configuration JSON n'a pas réussi la validation du schéma. Le champ `hint` indique le fichier et le champ concernés.
+- `E_RECORD_DRIFT` — l'empreinte de configuration d'un enregistrement ne correspond plus à sa source. Réexaminez-le ou réassociez-le comme suggéré dans l'invite.
+
+**`No --project specified, falling back to <name>`**
+Un avertissement mineur. Utilisez explicitement l'option `--project <name>` pour sélectionner le projet approprié et supprimer l'avertissement.
+
+**Problèmes liés au rendu / erreurs de mémoire insuffisante (VRAM)**
+Consultez le fichier `docs/internal/HANDOFF.md` pour les notes de configuration du rendu. En résumé : réduisez l'intensité du débruitage, diminuez la taille des lots ou utilisez un modèle plus petit dans votre profil de flux de travail.
+
+**Signalement de bogues**
+Signalez un problème sur https://github.com/mcp-tool-shop-org/style-dataset-lab/issues en indiquant votre version de sdlab (`sdlab --version`), la version de Node.js (`node -v`), la commande complète et la sortie d'erreur structurée. Un modèle de rapport de bogue préremplit les champs.
+
 ## Sécurité
 
 Utilisation locale uniquement. Aucune télémétrie, aucune analyse, aucune requête externe. Les images restent sur votre GPU et votre système de fichiers.
 
 ## Licence
 
-MIT
+Licence MIT.
 
 ---