@mcptoolshop/style-dataset-lab 3.0.1 → 3.1.0

package/README.it.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>
 
-Scrivete le vostre regole visive. Generate opere d'arte. Valutate ogni immagine in base a tali regole. Distribuite i risultati come dati di addestramento versionati e verificabili.
+Definisci le tue regole visive. Genera immagini. Valuta ogni immagine in base a quelle regole. Invia i risultati come dati di addestramento versionati e verificabili, quindi metti in funzione i modelli addestrati nei flussi di lavoro di produzione reali e reinserisci i risultati migliori nel tuo database.
 
 Style Dataset Lab collega le caratteristiche del vostro stile artistico definite in precedenza al set di dati utilizzato per l'addestramento. Definite una "costituzione" che includa regole sulla silhouette, vincoli di palette, linguaggio dei materiali, o qualsiasi altro aspetto rilevante per il vostro progetto. Il sistema genera candidati, li valuta in base a tali regole e confeziona le opere approvate in set di dati riproducibili, in cui ogni elemento spiega perché è stato incluso.
 
-Il ciclo si chiude: addestrate un modello, generate nuovi risultati, valutateli in base agli stessi criteri e reinserite ciò che supera i test. Il set di dati cresce e le regole rimangono valide.
+Successivamente, entra in gioco l'ambiente di lavoro di produzione: compila le istruzioni di generazione a partire dalle informazioni del progetto, eseguile tramite ComfyUI, valuta i risultati, genera in batch fogli di espressioni e schemi ambientali, seleziona i risultati migliori e reinseriscili come nuovi candidati. Il ciclo si chiude: genera, seleziona, valuta, migliora.
 
 ## La 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
 ```
 
-L'ultimo comando è fondamentale. I risultati generati vengono sottoposti allo stesso processo di revisione di tutto il resto. Il ciclo si chiude.
+Quest'ultimo comando è fondamentale. I risultati selezionati vengono sottoposti allo stesso processo di valutazione di tutto il resto. Il database cresce e le regole rimangono valide.
 
 ## Cosa produce
 
-Sette artefatti versionati e con checksum. Ognuno è collegato ai suoi predecessori, in modo da poter risalire a qualsiasi record di addestramento alla regola che lo ha approvato.
+Sono disponibili sette elementi del database e un intero ambiente di lavoro di produzione. Ogni elemento è collegato ai suoi predecessori, in modo da poter risalire a qualsiasi record di addestramento alla regola che lo ha approvato.
 
 | Artefatto. | Cos'è. |
 |----------|-----------|
@@ -58,6 +72,17 @@ Sette artefatti versionati e con checksum. Ognuno è collegato ai suoi predecess
 | **Eval scorecard** | Valutazione di superamento/non superamento per ogni compito, in base alla valutazione dei risultati generati rispetto ai set di valutazione. |
 | **Implementation pack** | Esempi di prompt, errori noti, test di continuità e indicazioni per il reinserimento. |
 
+L'ambiente di lavoro di produzione offre:
+
+| Superficie di interazione | Cosa fa |
+|---------|-------------|
+| **Compiled brief** | Generazione deterministica a partire dal profilo del flusso di lavoro e dalle informazioni del progetto. |
+| **Run** | Artefatto di esecuzione stabile: istruzioni + seed + output di ComfyUI + manifest. |
+| **Critique** | Valutazione strutturata e multidimensionale dei risultati rispetto al modello di riferimento. |
+| **Batch** | Produzione coordinata su più canali (fogli di espressioni, schemi ambientali, pacchetti di silhouette). |
+| **Selection** | Artefatto delle decisioni creative: quali output sono stati scelti, perché e da dove provengono. |
+| **Re-ingest** | Gli output selezionati vengono restituiti come record candidati con la completa provenienza della generazione. |
+
 ## Perché esiste
 
 I dati di addestramento sono l'elemento più importante in qualsiasi pipeline di intelligenza artificiale visiva. Tuttavia, la maggior parte dei dati di addestramento è costituita da una cartella di immagini senza una cronologia, senza una traccia di valutazione e senza un collegamento alle regole di stile che avrebbero dovuto seguire.
@@ -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
 ```
 
 ## Principi fondamentali
@@ -130,6 +161,66 @@ npm install -g @mcptoolshop/style-dataset-lab
 
 Richiede Node.js 20+ e [ComfyUI](https://github.com/comfyanonymous/ComfyUI) installato localmente all'indirizzo localhost:8188 per la generazione.
 
+### Prova senza ComfyUI
+
+È possibile esplorare l'intera interfaccia di interazione, escluse le funzioni di generazione, tramite l'ispezione, la curatela, lo snapshot, la suddivisione e l'esportazione, utilizzando il progetto Star Freight incluso, senza installare ComfyUI o scaricare alcun file 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
+```
+
+Il comando `sdlab project doctor` convalida la configurazione di ogni progetto (costituzione, percorsi, rubriche, terminologia) e segnala l'idoneità senza utilizzare la GPU. Qualsiasi comando che modifichi lo stato generato accetta l'opzione `--dry-run` per visualizzare l'effetto prima di applicarlo.
+
+Se si dimentica `--project`, la CLI passa al primo progetto trovato nella cartella `projects/` e visualizza un avviso; per disattivare l'avviso, è necessario specificare esplicitamente `--project`.
+
+### Riprendere un'esecuzione interrotta
+
+È possibile riprendere le lunghe esecuzioni di generazione senza dover ripetere il lavoro già completato:
+
+```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
+```
+
+Entrambi i comandi funzionano perché ogni sezione scrive il proprio file manifest in modo atomico al termine dell'esecuzione; un arresto anomalo durante l'esecuzione non corrompe lo stato parziale.
+
+## Risoluzione dei problemi
+
+Modalità di errore comuni e soluzioni:
+
+**`ECONNREFUSED 127.0.0.1:8188` in qualsiasi comando `sdlab generate` / `sdlab run generate` / `sdlab batch generate`**
+ComfyUI non è in esecuzione. Avvia ComfyUI (`python main.py --listen 127.0.0.1 --port 8188`) e verifica con `curl http://127.0.0.1:8188/system_stats`. Per puntare a un host/porta diverso, imposta `COMFY_URL=http://host:port`.
+
+**`missing checkpoint` / `LoRA weight not found`**
+Il profilo del flusso di lavoro indica un file modello che non si trova nelle cartelle `models/checkpoints/` o `models/loras/` di ComfyUI. Apri `projects/<project>/workflows/profiles/<profile>.json`, individua il campo `checkpoint` o `lora` e scarica il file corrispondente oppure sostituiscilo con uno che hai già. Esegui nuovamente `sdlab project doctor --project <project>` per confermare la correzione.
+
+**Errori di `sdlab project doctor`**
+Doctor restituisce codici di errore strutturati. Alcuni esempi comuni:
+- `E_PROJECT_NOT_FOUND` — la directory del progetto non esiste nella cartella `projects/`. Verifica l'ortografia.
+- `E_CONFIG_INVALID` — uno dei cinque file di configurazione JSON non ha superato la convalida dello schema. Il campo `hint` indica il file e il campo errati.
+- `E_RECORD_DRIFT` — l'impronta digitale della configurazione di un record non corrisponde più alla sua origine. Ricurata o ricollega come suggerito nell'hint.
+
+**`Nessun progetto specificato, si utilizza il valore predefinito <name>`**
+Un avviso di lieve entità. Utilizzare l'opzione `--project <name>` per specificare esplicitamente il progetto desiderato e silenziare l'avviso.
+
+**Problemi relativi alla memoria della VRAM (painterly)**
+Consultare il file `docs/internal/HANDOFF.md` per le note sulla regolazione del denoising "painterly". In breve: ridurre l'intensità del denoising, diminuire la dimensione del batch o utilizzare un checkpoint più piccolo nel profilo di lavoro.
+
+**Segnalazione di bug**
+Aprire una segnalazione all'indirizzo https://github.com/mcp-tool-shop-org/style-dataset-lab/issues, includendo la versione di sdlab (`sdlab --version`), la versione di Node (`node -v`), il comando completo e l'output dettagliato dell'errore. Un modello per la segnalazione di bug precompila i campi.
+
 ## Sicurezza
 
 Funziona solo localmente. Nessuna telemetria, nessuna analisi, nessuna richiesta esterna. Le immagini rimangono sulla GPU e sul filesystem locale.

package/README.ja.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>
 
-視覚的なルールを定義してください。それに基づいて画像を生成し、生成されたすべての画像をそのルールに照らし合わせて評価します。そして、バージョン管理された、監査可能なトレーニングデータとして結果を配布します。
+視覚的なルールを定義します。画像生成を行い、生成された画像を定義したルールに基づいて評価します。評価結果をバージョン管理された、監査可能な学習データとして出力し、その学習データを用いて訓練したモデルを実際の運用環境で活用します。そして、最も優れた結果を学習データに再投入します。
 
 Style Dataset Labは、お客様が記述されたアートスタイルに関する情報と、実際に学習に使用するデータセットを連携させます。お客様は、シルエットのルール、カラーパレットの制限、素材に関する記述など、プロジェクトにとって重要な要素を定義します。このシステムは、定義されたルールに基づいて候補を生成し、それらを評価し、承認された作品を再現可能なデータセットにまとめます。このデータセットでは、各レコードが、なぜその作品が選択されたのかを説明しています。
 
-このプロセスはループを形成します。モデルを訓練し、新しい出力を生成し、それらを同じ基準で評価し、評価基準を満たしたものをデータセットに再取り込みます。データセットは徐々に成長し、そのルールは維持されます。
+次に、本番環境用のワークベンチが稼働します。プロジェクトの要件に基づいて生成指示を作成し、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
 ```
 
-最後のコマンドが重要な点です。生成された出力も、他のものと同様に、同じ審査プロセスを経ます。これにより、一連の作業が完了し、サイクルが閉じます。
+この最後のコマンドが重要です。選択された出力は、他のすべてのデータと同様に、同じ評価プロセスを経ます。学習データが蓄積され、ルールが維持されます。
 
 ## それが生成するものは何か
 
-バージョン管理された7つのデータセットがあり、それぞれにチェックサムが付与されています。各データセットは、その前のバージョンとリンクされており、これにより、どのトレーニング記録も、それを承認したルールまで遡って追跡することができます。
+7種類のデータセットファイルと、完全な本番環境用ワークベンチが含まれています。各ファイルは、以前のファイルとリンクされており、どの学習記録も、それを承認したルールまで遡ることができます。
 
 | 成果物 | 内容 |
 |----------|-----------|
@@ -58,6 +72,17 @@ sdlab reingest generated --source ./outputs --manifest <id>
 | **Eval scorecard** | 各タスクごとに、評価データセットと照合して生成された結果に基づいて、合格/不合格を判定します。 |
 | **Implementation pack** | プロンプトの例、既知の問題点、動作確認テスト、および再取り込みに関する手順。 |
 
+本番環境用ワークベンチには、以下が含まれます。
+
+| 機能 | 概要 |
+|---------|-------------|
+| **Compiled brief** | ワークフロープロファイルとプロジェクト要件に基づいて、決定論的な画像生成を行います。 |
+| **Run** | 生成結果の記録：指示、シード値、ComfyUIの出力、マニフェストファイル。 |
+| **Critique** | 生成結果を基準と比較し、多角的な評価を行います。 |
+| **Batch** | 表現シート、環境ボード、シルエットパックなど、複数の要素をまとめて生成します。 |
+| **Selection** | 選択された出力について、なぜ選択されたのか、どこから来たのかといった情報を記録します。 |
+| **Re-ingest** | 選択された出力は、生成元の情報を含む候補レコードとして登録されます。 |
+
 ## なぜこれが存在するのか
 
 トレーニングデータは、あらゆる画像認識AIのパイプラインにおいて、最も重要な要素です。しかし、多くのトレーニングデータは、履歴や判断の記録が一切なく、また、本来従うべきスタイルルールとの関連性も欠けている、単なる画像ファイル群に過ぎません。
@@ -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,73 @@ npm install -g @mcptoolshop/style-dataset-lab
 
 生成には、Node.js 20以降のバージョンと、ローカルホストの8188番ポートで動作している [ComfyUI](https://github.com/comfyanonymous/ComfyUI) が必要です。
 
+### ComfyUIなしで試す
+
+ComfyUIをインストールしたり、SDXLのモデルファイルをダウンロードしたりせずに、検査、キュレーション、スナップショット、分割、エクスポートなど、すべての機能を「Star Freight」プロジェクトを通じて利用できます。
+
+```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`コマンドは、すべてのプロジェクト設定（構成、ルール、評価基準、用語集）を検証し、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://host:port`を設定します。
+
+**`missing checkpoint` / `LoRA weight not found`が発生した場合**
+ワークフロープロファイルで指定されているモデルファイルが、ComfyUIの`models/checkpoints/`または`models/loras/`フォルダに存在しません。`projects/<project>/workflows/profiles/<profile>.json`を開き、`checkpoint`または`lora`の項目を探し、指定されたモデルファイルをダウンロードするか、代わりに既存のファイルを使用してください。修正後、`sdlab project doctor --project <project>`を再実行して確認します。
+
+**`sdlab project doctor`でエラーが発生した場合**
+Doctorは、構造化されたエラーコードを返します。一般的なエラーは以下の通りです。
+- `E_PROJECT_NOT_FOUND`：プロジェクトディレクトリが`projects/`ディレクトリに存在しません。スペルを確認してください。
+- `E_CONFIG_INVALID`：5つのJSON設定ファイルのいずれかが、スキーマ検証に失敗しました。`hint`の項目には、問題のあるファイルとフィールドの名前が表示されます。
+- `E_RECORD_DRIFT`：レコードの設定フィンガープリントが、元のデータと一致しなくなりました。`hint`に示されているように、再キュレーションまたは再バインドを行ってください。
+
+**`No --project specified, falling back to <name>`という警告が表示された場合**
+これは、警告です。正しいプロジェクトを選択し、警告を抑制するには、`--project <name>`オプションを明示的に指定してください。
+
+**ペインタリー処理 / VRAMのメモリ不足に関する問題**
+ペインタリー処理の調整に関する詳細は、`docs/internal/HANDOFF.md` を参照してください。簡単に言うと、ノイズ除去の強度を下げたり、バッチサイズを小さくしたり、ワークフロープロファイルでより小さいチェックポイントを使用するように変更してください。
+
+**バグの報告**
+バグを発見した場合は、https://github.com/mcp-tool-shop-org/style-dataset-lab/issues に、`sdlab --version` で確認できるsdlabのバージョン、`node -v` で確認できるNodeのバージョン、実行したコマンド全体、および構造化されたエラー出力を添えて報告してください。バグレポートのテンプレートには、必要な項目が事前に入力されています。
+
 ## セキュリティ
 
 ローカル環境でのみ動作します。テレメトリー、分析、外部へのリクエストは一切ありません。画像はすべて、あなたのGPUとファイルシステム内に保存されます。
 
 ## ライセンス
 
-MIT
+MITライセンス
 
 ---
 

package/README.md

@@ -8,6 +8,8 @@
 
 <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>
 
@@ -178,6 +180,22 @@ sdlab snapshot create --dry-run --project star-freight
 
 If you forget `--project`, the CLI falls back to the first project it finds under `projects/` and prints a warning — pass `--project` explicitly to silence it.
 
+### Resuming an interrupted run
+
+Long generation runs can be resumed without redoing completed work:
+
+```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
+```
+
+Both commands work because every slot writes its manifest entry atomically as it finishes — a crash mid-run never corrupts the partial state.
+
 ## Troubleshooting
 
 Common failure modes and fixes:

package/README.pt-BR.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>
 
-Escreva suas regras visuais. Gere imagens. Avalie cada imagem com base nessas regras. Envie os resultados como dados de treinamento versionados e auditáveis.
+Escreva suas regras visuais. Gere imagens. Avalie cada imagem com base nessas regras. Envie os resultados como dados de treinamento versionados e auditáveis, e então coloque os modelos treinados em operação em fluxos de trabalho de produção reais, e alimente os melhores resultados de volta para o seu conjunto de dados.
 
 O Style Dataset Lab conecta o que você escreveu sobre o estilo da sua arte ao conjunto de dados que você realmente usa para treinamento. Você define uma estrutura – regras de silhueta, restrições de paleta, linguagem de materiais, o que for importante para o seu projeto. O processo gera candidatos, os avalia com base nessas regras e organiza as obras aprovadas em conjuntos de dados reproduzíveis, onde cada registro explica por que foi incluído.
 
-O ciclo se fecha: treine um modelo, gere novas saídas, avalie-as com base nos mesmos critérios e reintroduza o que for aprovado. O conjunto de dados cresce e as regras permanecem válidas.
+Em seguida, a área de trabalho de produção assume o controle: compile as instruções de geração a partir da "verdade" do projeto, execute-as no ComfyUI, critique os resultados, produza em lote planilhas de expressões e painéis de ambiente, selecione os melhores resultados e reintroduza-os como novos candidatos. O ciclo se fecha: produza, selecione, revise, fortaleça.
 
 ## O processo
 
@@ -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
 ```
 
-Aquele último comando é crucial. As saídas geradas passam pelo mesmo processo de revisão de tudo o mais. O ciclo se fecha.
+Essa última instrução é o ponto crucial. Os resultados selecionados passam pelo mesmo processo de revisão que tudo o mais. O conjunto de dados cresce e as regras permanecem válidas.
 
 ## O que ele produz
 
-Sete artefatos versionados e com checksum. Cada um está vinculado aos seus predecessores, para que você possa rastrear qualquer registro de treinamento até a regra que o aprovou.
+Sete artefatos do conjunto de dados e uma área de trabalho de produção completa. Cada artefato está vinculado aos seus predecessores, para que você possa rastrear qualquer registro de treinamento até a regra que o aprovou.
 
 | Artefato | O que é |
 |----------|-----------|
@@ -58,6 +72,17 @@ Sete artefatos versionados e com checksum. Cada um está vinculado aos seus pred
 | **Eval scorecard** | Avaliação de aprovação/reprovação para cada tarefa, com base na avaliação das saídas geradas. |
 | **Implementation pack** | Exemplos de prompts, falhas conhecidas, testes de continuidade e diretrizes para reintrodução. |
 
+A área de trabalho de produção adiciona:
+
+| Interface | O que ela faz |
+|---------|-------------|
+| **Compiled brief** | Geração determinística a partir do perfil do fluxo de trabalho + "verdade" do projeto. |
+| **Run** | Artefato de execução congelado: instrução + sementes + resultados do ComfyUI + manifesto. |
+| **Critique** | Avaliação estruturada e multidimensional dos resultados em relação ao padrão. |
+| **Batch** | Produção coordenada em vários canais (planilhas de expressões, painéis de ambiente, pacotes de silhuetas). |
+| **Selection** | Artefato de decisão criativa: quais resultados foram escolhidos, por quê e de onde vieram. |
+| **Re-ingest** | Os resultados selecionados são retornados como registros candidatos com total rastreabilidade da geração. |
+
 ## Por que isso existe
 
 Os dados de treinamento são o recurso mais valioso em qualquer pipeline de IA visual. No entanto, a maioria dos dados de treinamento é apenas uma pasta de imagens sem histórico, sem rastreamento de avaliação e sem conexão com as regras de estilo que deveria 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
 ```
 
 ## Propriedades de confiabilidade
@@ -130,6 +161,66 @@ npm install -g @mcptoolshop/style-dataset-lab
 
 Requer Node.js 20 ou superior e o [ComfyUI](https://github.com/comfyanonymous/ComfyUI) instalado localmente no endereço localhost:8188 para a geração.
 
+### Experimente sem o ComfyUI
+
+Você pode explorar toda a interface de geração — inspeção, curadoria, instantâneo, divisão, exportação — usando o projeto Star Freight incluso, sem instalar o ComfyUI ou baixar nenhum arquivo de peso do 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
+```
+
+O comando `sdlab project doctor` valida todas as configurações do projeto (constituição, caminhos, critérios, terminologia) e informa a elegibilidade sem acessar a GPU. Qualquer comando que modifique o estado gerado aceita a opção `--dry-run` para visualizar o efeito primeiro.
+
+Se você esquecer `--project`, a interface de linha de comando (CLI) volta para o primeiro projeto que encontra em `projects/` e exibe um aviso — use `--project` explicitamente para silenciá-lo.
+
+### Retomando uma execução interrompida
+
+Execuções longas de geração podem ser retomadas sem a necessidade de refazer o trabalho já concluído:
+
+```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 os comandos funcionam porque cada slot escreve sua entrada de manifesto de forma atômica ao finalizar — um erro durante a execução nunca corrompe o estado parcial.
+
+## Solução de problemas
+
+Modos de falha comuns e soluções:
+
+**`ECONNREFUSED 127.0.0.1:8188` em qualquer comando `sdlab generate` / `sdlab run generate` / `sdlab batch generate`**
+O ComfyUI não está em execução. Inicie o ComfyUI (`python main.py --listen 127.0.0.1 --port 8188`) e confirme com `curl http://127.0.0.1:8188/system_stats`. Para apontar para um host/porta diferente, defina `COMFY_URL=http://host:port`.
+
+**`missing checkpoint` / `LoRA weight not found`**
+O perfil do seu fluxo de trabalho nomeia um arquivo de modelo que não está na pasta `models/checkpoints/` ou `models/loras/` do ComfyUI. Abra `projects/<projeto>/workflows/profiles/<perfil>.json`, localize o campo `checkpoint` ou `lora` e, em seguida, baixe o arquivo de peso referenciado ou substitua-o por um que você já tenha. Execute novamente `sdlab project doctor --project <projeto>` para confirmar a correção.
+
+**Erros do `sdlab project doctor`**
+O Doctor retorna códigos de erro estruturados. Alguns comuns:
+- `E_PROJECT_NOT_FOUND` — o diretório do projeto não existe em `projects/`. Verifique a ortografia.
+- `E_CONFIG_INVALID` — um dos cinco arquivos de configuração JSON falhou na validação do esquema. O campo `hint` indica qual arquivo e campo estão incorretos.
+- `E_RECORD_DRIFT` — a impressão digital de configuração de um registro não corresponde mais à sua origem. Reavalie ou redefina conforme sugerido na dica.
+
+**`No --project specified, falling back to <name>`**
+Um aviso leve. Use `--project <nome>` explicitamente para selecionar o projeto correto e silenciar o aviso.
+
+**Problemas relacionados à renderização / Falta de memória na VRAM**
+Consulte o arquivo `docs/internal/HANDOFF.md` para obter informações sobre o ajuste fino da remoção de ruído (denoise). Em resumo: diminua a intensidade da remoção de ruído, reduza o tamanho do lote ou utilize um modelo (checkpoint) menor no seu perfil de trabalho.
+
+**Relatando erros**
+Registre um problema em https://github.com/mcp-tool-shop-org/style-dataset-lab/issues, incluindo a versão do sdlab (`sdlab --version`), a versão do Node (`node -v`), o comando completo e a saída de erro formatada. Um modelo de relatório de erro preenche automaticamente os campos.
+
 ## Segurança
 
 Funciona apenas localmente. Não há coleta de dados de uso, análises ou requisições externas. As imagens permanecem na sua GPU e no seu sistema de arquivos.