@mcptoolshop/style-dataset-lab 3.0.1 → 3.1.0

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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,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.
 
 ---
 

package/README.hi.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>
 
-अपनी दृश्य दिशानिर्देशों को लिखें। कला उत्पन्न करें। प्रत्येक छवि का मूल्यांकन उन दिशानिर्देशों के आधार पर करें। परिणामों को संस्करणों के साथ, ऑडिट करने योग्य प्रशिक्षण डेटा के रूप में प्रस्तुत करें।
+अपने दृश्य नियमों को लिखें। कला उत्पन्न करें। प्रत्येक छवि का मूल्यांकन उन नियमों के आधार पर करें। परिणामों को संस्करणित और ऑडिट योग्य प्रशिक्षण डेटा के रूप में प्रस्तुत करें। फिर, प्रशिक्षित मॉडलों को वास्तविक उत्पादन प्रक्रियाओं में उपयोग करें और सर्वोत्तम परिणामों को वापस अपने डेटासेट में शामिल करें।
 
 स्टाइल डेटासेट लैब आपके कलात्मक शैली के बारे में आपने जो कुछ भी लिखा है, उसे उस डेटासेट से जोड़ता है जिससे आप वास्तव में प्रशिक्षण लेते हैं। आप एक "संविधान" परिभाषित करते हैं - जैसे कि आकार के नियम, रंग पैलेट की सीमाएं, सामग्री का विवरण, या जो भी आपके प्रोजेक्ट के लिए महत्वपूर्ण है। यह प्रणाली संभावित विकल्पों को उत्पन्न करती है, उन्हें आपके द्वारा परिभाषित नियमों के आधार पर मूल्यांकन करती है, और स्वीकृत कार्यों को ऐसे डेटासेट में व्यवस्थित करती है जो पुन: प्रयोज्य हों, जहां प्रत्येक प्रविष्टि यह बताती है कि उसे क्यों शामिल किया गया है।
 
-यह प्रक्रिया एक चक्र की तरह चलती है: एक मॉडल को प्रशिक्षित करें, नए आउटपुट उत्पन्न करें, उन्हें एक ही मानदंड के आधार पर मूल्यांकित करें, और जो आउटपुट मानदंडों को पूरा करते हैं, उन्हें वापस डेटासेट में शामिल करें। इस तरह, डेटासेट का आकार बढ़ता रहता है और नियम बने रहते हैं।
+फिर उत्पादन कार्यक्षेत्र (प्रोडक्शन वर्कबेंच) सक्रिय होता है: यह प्रोजेक्ट की वास्तविकताओं से संकलित किए गए विवरणों को लेता है, उन्हें कॉमफीयूआई (ComfyUI) के माध्यम से संसाधित करता है, परिणामों की समीक्षा करता है, बड़ी संख्या में एक्सप्रेशन शीट और वातावरण संबंधी चित्र बनाता है, सर्वोत्तम परिणामों का चयन करता है, और उन्हें नए विकल्पों के रूप में फिर से उपयोग करता है। यह प्रक्रिया एक चक्र में चलती रहती है: उत्पादन, चयन, समीक्षा, और सुधार।
 
 ## पाइपलाइन।
 
@@ -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
 ```
 
-"वह अंतिम आदेश महत्वपूर्ण है। उत्पन्न होने वाले परिणाम भी उसी समीक्षा प्रक्रिया से गुजरते हैं, जैसे कि बाकी सब कुछ। इस प्रकार, एक चक्र पूरा होता है।"
+"वह अंतिम आदेश महत्वपूर्ण है। चुने गए आउटपुट भी बाकी सब कुछ की तरह ही, उसी समीक्षा प्रक्रिया से गुजरते हैं। डेटा संग्रह लगातार बढ़ रहा है और नियम अभी भी लागू हैं।"
 
 ## यह क्या उत्पादित करता है।
 
-सात संस्करणों वाले, चेकसम से सत्यापित दस्तावेज़। प्रत्येक दस्तावेज़ अपने पूर्ववर्ती संस्करणों से जुड़ा हुआ है, जिससे आप किसी भी प्रशिक्षण रिकॉर्ड को उस नियम तक वापस खोज सकते हैं जिसने उसे स्वीकृत किया था।
+सात डेटासेट संबंधी अभिलेखागार (आर्टिफैक्ट) और एक पूर्ण उत्पादन कार्यक्षेत्र उपलब्ध हैं। प्रत्येक अभिलेखागार अपने पूर्ववर्ती अभिलेखागार से जुड़ा हुआ है, जिससे आप किसी भी प्रशिक्षण रिकॉर्ड को उस नियम तक वापस खोज सकते हैं जिसने उसे स्वीकृत किया था।
 
 | पुरातत्विक वस्तु। | यह क्या है। |
 |----------|-----------|
@@ -58,6 +72,17 @@ sdlab reingest generated --source ./outputs --manifest <id>
 | **Eval scorecard** | प्रत्येक कार्य के लिए, स्कोरिंग के आधार पर उत्पन्न परिणामों की तुलना मूल्यांकन पैकों से की जाती है, और यह निर्धारित किया जाता है कि परिणाम पास हुआ है या फेल। |
 | **Implementation pack** | त्वरित उदाहरण, ज्ञात विफलताएं, निरंतरता परीक्षण, और पुनः उपयोग के लिए मार्गदर्शन। |
 
+उत्पादन कार्यक्षेत्र में निम्नलिखित विशेषताएं शामिल हैं:
+
+| सतह। | यह क्या करता है। |
+|---------|-------------|
+| **Compiled brief** | कार्यप्रवाह प्रोफाइल और परियोजना की वास्तविक जानकारी के आधार पर, एक निश्चित (निर्धारित) पीढ़ी निर्देश। |
+| **Run** | फ्रीज किए गए निष्पादन कलाकृतियाँ: संक्षिप्त विवरण + बीज (seeds) + कॉमफीयूआई (ComfyUI) के आउटपुट + मैनिफेस्ट (manifest)। |
+| **Critique** | "रन आउटपुट का मानकीकृत, बहु-आयामी मूल्यांकन, जो कि एक स्थापित मानक के आधार पर किया जाता है।" |
+| **Batch** | समन्वित, बहु-स्लॉट उत्पादन (एक्सप्रेशन शीट, पर्यावरण संबंधी बोर्ड, सिल्हूट पैक)। |
+| **Selection** | रचनात्मक निर्णय का दस्तावेज़: किन परिणामों का चयन किया गया, क्यों किया गया, और वे कहाँ से प्राप्त हुए। |
+| **Re-ingest** | चयनित परिणाम "उम्मीदवार रिकॉर्ड" के रूप में वापस आते हैं, जिनमें पूरी जानकारी शामिल होती है कि वे कैसे उत्पन्न हुए। |
+
 ## यह क्यों मौजूद है?
 
 प्रशिक्षण डेटा किसी भी विज़ुअल एआई प्रणाली में सबसे महत्वपूर्ण घटक होता है। लेकिन अधिकांश प्रशिक्षण डेटा छवियों का एक संग्रह होता है, जिसमें कोई पृष्ठभूमि जानकारी, कोई मूल्यांकन प्रक्रिया, और उन शैलीगत नियमों से कोई संबंध नहीं होता जिनका पालन करने की अपेक्षा की जाती थी।
@@ -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
 ```
 
 ## ट्रस्ट की संपत्ति।
@@ -130,13 +161,75 @@ npm install -g @mcptoolshop/style-dataset-lab
 
 इसके लिए Node.js 20+ और [ComfyUI](https://github.com/comfyanonymous/ComfyUI) की आवश्यकता है, जो localhost:8188 पर चल रहा होना चाहिए, ताकि सामग्री उत्पन्न की जा सके।
 
+### इसे बिना ComfyUI के आज़माएं।
+
+आप "स्टार फ्रेट" नामक प्रोजेक्ट का उपयोग करके, बिना किसी भी अतिरिक्त सॉफ़्टवेयर को स्थापित किए या किसी भी एसडीएक्सएल फ़ाइल को डाउनलोड किए, "नॉन-जेनरेशन" (गैर-उत्पादन) की सभी सुविधाओं का पता लगा सकते हैं, जैसे कि निरीक्षण, चयन, स्नैपशॉट, विभाजन और निर्यात।
+
+```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 प्रोजेक्ट डॉक्टर` प्रत्येक प्रोजेक्ट कॉन्फ़िगरेशन (संरचना, चरण, मूल्यांकन मानदंड, शब्दावली) की जांच करता है और बिना ग्राफिक्स प्रोसेसिंग यूनिट (GPU) का उपयोग किए, परियोजना की पात्रता की रिपोर्ट देता है। कोई भी कमांड जो उत्पन्न डेटा को बदलता है, `--dry-run` विकल्प के साथ उपयोग किया जा सकता है ताकि पहले उसके प्रभाव को देखा जा सके।
+
+यदि आप `--project` विकल्प को भूल जाते हैं, तो कमांड-लाइन इंटरफेस (CLI) `projects/` फ़ोल्डर के अंतर्गत पाए जाने वाले पहले प्रोजेक्ट का उपयोग करेगा और एक चेतावनी प्रदर्शित करेगा। इस चेतावनी को बंद करने के लिए, `--project` विकल्प को स्पष्ट रूप से निर्दिष्ट करें।
+
+### अवरुद्ध प्रक्रिया को फिर से शुरू करना
+
+लंबे समय तक चलने वाली प्रक्रियाओं को फिर से शुरू किया जा सकता है बिना पहले से किए गए काम को दोहराए:
+
+```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
+```
+
+दोनों कमांड काम करते हैं क्योंकि प्रत्येक स्लॉट अपनी मैनिफेस्ट प्रविष्टि को पूरा होने पर एक साथ लिखता है - प्रक्रिया के बीच में होने वाली किसी भी खराबी से आंशिक स्थिति दूषित नहीं होती है।
+
+## समस्या निवारण।
+
+सामान्य खराबी के प्रकार और उनके समाधान:
+
+`ECONNREFUSED 127.0.0.1:8188` - यह त्रुटि `sdlab generate`, `sdlab run generate` या `sdlab batch generate` कमांड चलाने के दौरान आ सकती है।
+
+ComfyUI चल नहीं रहा है। ComfyUI को शुरू करें (`python main.py --listen 127.0.0.1 --port 8188`) और `curl http://127.0.0.1:8188/system_stats` कमांड से इसकी पुष्टि करें। यदि आप किसी अन्य होस्ट/पोर्ट का उपयोग करना चाहते हैं, तो `COMFY_URL=http://होस्ट:पोर्ट` सेट करें।
+
+**`चेकपॉइंट गुम है` / `LoRA फ़ाइल नहीं मिली`**
+
+आपके वर्कफ़्लो प्रोफाइल में एक मॉडल फ़ाइल का नाम दिया गया है जो ComfyUI के `models/checkpoints/` या `models/loras/` फ़ोल्डर में मौजूद नहीं है। `projects/<प्रोजेक्ट>/workflows/profiles/<प्रोफाइल>.json` फ़ाइल खोलें, `checkpoint` या `lora` फ़ील्ड ढूंढें, और या तो संदर्भित फ़ाइल को डाउनलोड करें या उसे उस फ़ाइल से बदल दें जो आपके पास पहले से है। सुधार की पुष्टि करने के लिए `sdlab project doctor --project <प्रोजेक्ट>` कमांड को फिर से चलाएं।
+
+**`sdlab प्रोजेक्ट डॉक्टर` त्रुटियां**
+डॉक्टर संरचित त्रुटि कोड लौटाता है। कुछ सामान्य त्रुटियां:
+- `E_PROJECT_NOT_FOUND` — "projects/" फ़ोल्डर के अंतर्गत प्रोजेक्ट डायरेक्टरी मौजूद नहीं है। वर्तनी की जांच करें।
+- `E_CONFIG_INVALID` — पांच JSON कॉन्फ़िगरेशन फ़ाइलों में से किसी एक में स्कीमा सत्यापन विफल हो गया है। "hint" फ़ील्ड में उस गलत फ़ाइल और फ़ील्ड का नाम दिया गया है।
+- `E_RECORD_DRIFT` — किसी रिकॉर्ड के कॉन्फ़िगरेशन फ़िंगरप्रिंट अब उसके स्रोत से मेल नहीं खाते हैं। "hint" में दिए गए सुझाव के अनुसार, इसे फिर से व्यवस्थित करें या फिर से जोड़ें।
+
+**`कोई प्रोजेक्ट निर्दिष्ट नहीं है, इसलिए डिफ़ॉल्ट रूप से <नाम> का उपयोग किया जा रहा है`**
+यह एक चेतावनी संदेश है। सही प्रोजेक्ट का चयन करने और इस चेतावनी को बंद करने के लिए `--project <नाम>` विकल्प का स्पष्ट रूप से उपयोग करें।
+
+**पेंटरली / वीआरएएम (VRAM) मेमोरी से बाहर होने की समस्याएँ**
+"पेंटरली" डीनोइजिंग (denoise) के ट्यूनिंग नोट्स के लिए, `docs/internal/HANDOFF.md` देखें। संक्षेप में: डीनोइजिंग की शक्ति को कम करें, बैच का आकार घटाएं, या अपने वर्कफ़्लो प्रोफाइल में छोटे चेकपॉइंट का उपयोग करें।
+
+**बग की रिपोर्ट करना**
+https://github.com/mcp-tool-shop-org/style-dataset-lab/issues पर एक मुद्दा दर्ज करें, जिसमें आपके sdlab संस्करण (`sdlab --version`), नोड संस्करण (`node -v`), पूरा कमांड और संरचित त्रुटि आउटपुट शामिल हों। एक बग रिपोर्ट टेम्पलेट स्वचालित रूप से फ़ील्ड को भर देगा।
+
 ## सुरक्षा
 
 यह केवल स्थानीय रूप से काम करता है। इसमें कोई टेलीमेट्री, कोई विश्लेषण और कोई बाहरी अनुरोध शामिल नहीं हैं। छवियां आपके GPU और फ़ाइल सिस्टम पर ही रहती हैं।
 
 ## लाइसेंस
 
-MIT
+एमआईटी (MIT)
 
 ---