@mcptoolshop/style-dataset-lab 1.2.0 → 2.0.0

package/README.md

@@ -1,7 +1,3 @@
-<p align="center">
-  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
-</p>
-
 <p align="center">
   <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/style-dataset-lab/readme.png" width="400">
 </p>
@@ -13,163 +9,146 @@
 
 # style-dataset-lab
 
-A production pipeline for visual dataset creation -- from canon rules to structured prompts to ComfyUI generation to curated, canon-bound training data.
+A canon-bound visual dataset pipeline for directed image production.
 
-## What this is
+Define what your project looks like. Generate candidates. Curate against your canon. Bind approved work to constitution rules. Export trustworthy datasets for training, evaluation, and production reuse.
 
-A **pipeline** for building structured visual training datasets. You write style rules (canon), compose prompts, generate with ComfyUI, curate with per-dimension scoring, bind judgments to canon rules, and export in 10 formats via [`@mcptoolshop/repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset).
+## What this is
 
-The pipeline is game-agnostic. Each game gets its own data directory under `games/<name>/`; the 13 scripts and blank templates are shared. Every asset produced carries three things:
+A **visual canon + dataset pipeline** for teams that care about style consistency, provenance, and reviewable judgment. Every asset carries three things:
 
-1. **Image pixels** -- generated by ComfyUI with full provenance (checkpoint, LoRA, seed, sampler, cfg)
-2. **Canon explanation** -- why this is on-style or off-style, grounded in a style constitution
-3. **Quality judgment** -- approved/rejected with per-dimension scores and cited rules
+1. **Provenance** -- full generation history (checkpoint, LoRA, seed, sampler, cfg, timing)
+2. **Canon binding** -- which constitution rules this asset passes, fails, or partially meets
+3. **Quality judgment** -- approved/rejected/borderline with per-dimension scores
 
-## Security model
+The pipeline works for game art, character design, creature design, architecture, vehicle/mech concepts, and any domain where visual production needs to stay on-model.
 
-**Local-only.** style-dataset-lab talks to ComfyUI on `localhost:8188` and never makes external network requests. No telemetry, no analytics, no phoning home. Image generation happens entirely on your GPU. Records and canon data stay on your filesystem.
+## Quick start
 
-## What the npm package ships
+```bash
+# Install the CLI + pipeline
+npm install -g @mcptoolshop/style-dataset-lab
 
-`npm install @mcptoolshop/style-dataset-lab` gives you:
+# Scaffold a new project
+sdlab init my-project --domain character-design
 
-- **13 scripts** -- generate, curate, compare, canon-bind, painterly, identity generation, ControlNet/IP-Adapter generation, bulk curation, migration
-- **Blank templates** -- starter constitution, review rubric, and example prompt pack in `templates/`
+# Validate the project structure
+sdlab project doctor --project my-project
+```
 
-The npm package does **not** include game data. Clone the repo if you want the Star Freight example (1,182 records, 28 prompt waves, 18 visual categories).
+Available domains: `game-art`, `character-design`, `creature-design`, `architecture`, `vehicle-mech`, or `generic`.
 
-## Install
+## CLI
 
 ```bash
-# Get the pipeline scripts + templates
-npm install @mcptoolshop/style-dataset-lab
-
-# Or clone the repo for the Star Freight example data
-git clone https://github.com/mcp-tool-shop-org/style-dataset-lab
-cd style-dataset-lab
-npm install
+sdlab init <name> [--domain <domain>]     # Scaffold a new project
+sdlab project doctor [--project <name>]   # Validate project config
+
+sdlab generate <pack> [--project <name>]  # Generate candidates via ComfyUI
+sdlab generate:identity <packet>          # Named-subject identity images
+sdlab generate:controlnet                 # ControlNet-guided generation
+sdlab generate:ipadapter                  # IP-Adapter reference-guided
+
+sdlab curate <id> <status> <explanation>  # Record review judgment
+sdlab compare <a> <b> <winner> <reason>   # Pairwise A-vs-B comparison
+sdlab bind [--project <name>]             # Bind records to constitution rules
+sdlab painterly [--project <name>]        # Post-processing style pass
 ```
 
-To start a new game from the templates:
-
-```bash
-# Copy templates into your game directory
-mkdir -p games/my-game/{records,comparisons,inputs/prompts,outputs/{candidates,approved,rejected,borderline,painterly},exports}
-cp -r templates/canon games/my-game/canon
-cp templates/inputs/prompts/example-wave.json games/my-game/inputs/prompts/wave1.json
-# Edit the canon and prompts, then generate
-```
+All commands accept `--project <name>` (default: `star-freight`).
 
-## Monorepo structure
+## Project model
 
-The pipeline lives in `scripts/` and `templates/`. Each game lives in `games/<name>/` with its own canon, records, and assets. Scripts accept `--game <name>` (defaults to `star-freight`).
+Each project is a self-contained directory under `projects/` with its own canon, config, and data:
 
 ```
-style-dataset-lab/
-  scripts/                  13 pipeline scripts (generate, curate, compare, etc.)
-  templates/                Blank starting point for new games
-    canon/                  Starter constitution + review rubric
-    inputs/prompts/         Example prompt pack
-  games/
-    star-freight/           Star Freight example (1,182 records, repo-only)
-      canon/                Style constitution, review rubric, species canon
-      records/              Per-asset JSON (provenance + judgment + canon)
-      comparisons/          A-vs-B preference judgments
-      inputs/               Prompt packs, identity packets, references
-      outputs/              Generated images (gitignored)
-      exports/              repo-dataset output (gitignored)
-    <your-game>/            Add more games with the same structure
+projects/
+  my-project/
+    project.json            Project identity + generation defaults
+    constitution.json       Rules array with rationale templates
+    lanes.json              Subject lanes with detection patterns
+    rubric.json             Scoring dimensions + thresholds
+    terminology.json        Group vocabulary + detection order
+    canon/                  Style constitution (markdown)
+    records/                Per-asset JSON (provenance + judgment + canon)
+    inputs/prompts/         Prompt packs (JSON)
+    outputs/                Generated images (gitignored)
+    comparisons/            A-vs-B preference judgments
+    exports/                Training data output (gitignored)
 ```
 
-## Pipeline workflow
+## Pipeline
 
-The full pipeline from canon to training export:
+```
+canon  -->  prompts  -->  generate  -->  curate  -->  bind  -->  compare  -->  export
+ |            |             |              |           |            |            |
+ rules      packs        ComfyUI       judgment    assertions   preferences   dataset
+```
 
-```bash
-# 1. Write your canon -- style constitution + review rubric
-#    (start from templates/ or write from scratch)
+1. **Define canon** -- write your style constitution and review rubric
+2. **Create prompt packs** -- structured subjects with style prefix and variations
+3. **Generate** -- ComfyUI produces candidates with full provenance
+4. **Curate** -- approve/reject with per-dimension scores and failure modes
+5. **Bind** -- link each asset to constitution rules with pass/fail/partial verdicts
+6. **Compare** -- record pairwise preferences for DPO/ranking datasets
+7. **Export** -- produce training data via [`repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset) in 10+ formats
 
-# 2. Create prompt packs in inputs/prompts/
-#    (see templates/inputs/prompts/example-wave.json)
+## Domain templates
 
-# 3. Start ComfyUI and generate candidates
-npm run generate -- --game star-freight inputs/prompts/wave1.json
-npm run generate -- --game star-freight inputs/prompts/wave1.json --dry-run
+Each domain template ships with lane definitions, constitution rules, scoring rubrics, and terminology structures designed for that production context:
 
-# 4. Generate identity-packet characters (named subjects)
-npm run generate:identity -- --game star-freight inputs/identity-packets/wave27a.json
+| Domain | Lanes | Key concerns |
+|--------|-------|-------------|
+| **game-art** | character, environment, prop, UI, ship, interior, equipment | Silhouette at gameplay scale, faction differentiation, wear/aging |
+| **character-design** | portrait, full_body, turnaround, expression_sheet, action_pose | Proportion accuracy, costume logic, personality read, gesture clarity |
+| **creature-design** | concept, orthographic, detail_study, action, scale_reference, habitat | Anatomical plausibility, evolutionary logic, silhouette distinction |
+| **architecture** | exterior, interior, streetscape, structural_detail, ruin, landscape | Structural plausibility, material consistency, perspective, era coherence |
+| **vehicle-mech** | exterior, cockpit, component, schematic, silhouette_sheet, damage_variant | Mechanical logic, functional design language, access points, damage narrative |
 
-# 5. Curate -- approve, reject, or mark borderline
-npm run curate -- --game star-freight <asset_id> approved "explanation"
-npm run curate -- --game star-freight <asset_id> rejected "explanation" --failures "too_clean"
+## The dataset angle
 
-# 6. Generate painterly variants of approved assets
-npm run painterly -- --game star-freight
+The pipeline produces more than organized images. It produces **trustworthy, structured datasets** with:
 
-# 7. Bind canon explanations to curated assets
-npm run canon-bind -- --game star-freight
+- **Full provenance** on every asset (reproducible generations)
+- **Canon-bound judgments** (not just labels -- reasoned verdicts against declared rules)
+- **Pairwise preferences** (for DPO and ranking-based training)
+- **Per-dimension scoring** (fine-grained quality signals, not just pass/fail)
+- **Failure mode tagging** (what specifically went wrong and which rules were violated)
 
-# 8. Record pairwise comparisons
-npm run compare -- --game star-freight <asset_a> <asset_b> a "A has better faction read"
+Export via `repo-dataset` to TRL, LLaVA, Qwen2-VL, JSONL, Parquet, and more.
 
-# 9. Export training data via repo-dataset
-repo-dataset visual generate ./games/star-freight --format trl
-repo-dataset visual inspect ./games/star-freight
-```
+## Star Freight example
 
-## Adding a new game
+Clone the repo for a complete working example: 1,182 records, 28 prompt waves, 5 factions, 7 lanes, 24 constitution rules, and 892 approved assets from a gritty sci-fi RPG.
 
 ```bash
-# Create structure and copy blank templates
-mkdir -p games/my-game/{records,comparisons,inputs/prompts,outputs/{candidates,approved,rejected,borderline,painterly},exports}
-cp -r templates/canon games/my-game/canon
-cp templates/inputs/prompts/example-wave.json games/my-game/inputs/prompts/wave1.json
-
-# Edit your canon/constitution.md and canon/review-rubric.md
-# Edit your prompt pack, then run the pipeline with --game my-game
+git clone https://github.com/mcp-tool-shop-org/style-dataset-lab
+cd style-dataset-lab
+sdlab bind --stats --project star-freight
+sdlab project doctor --project star-freight
 ```
 
-## Per-game directory layout
+## Migrating from v1.x
 
-Each `games/<name>/` directory contains:
+v2.0 renames `games/` to `projects/` and `--game` to `--project`:
 
-```
-canon/                  Style constitution, review rubric, species canon, identity gates
-inputs/
-  prompts/              Prompt packs per wave (JSON: subjects, variations, defaults)
-  references/           IP-Adapter reference images
-  control-guides/       ControlNet guide overlays
-  identity-packets/     Named character identity spines
-outputs/
-  candidates/           Raw generations (gitignored)
-  approved/             Curated approved (gitignored)
-  rejected/             Curated rejected (gitignored)
-  borderline/           Curated borderline (gitignored)
-  painterly/            Painterly-style variants (gitignored)
-records/                Per-asset JSON (provenance + judgment + canon binding)
-comparisons/            A-vs-B preference judgments
-exports/                repo-dataset output (gitignored)
-```
+```bash
+# Rename your data directory
+mv games projects
 
-## Generation setup
-
-```yaml
-checkpoint: dreamshaperXL_v21TurboDPMSDE.safetensors
-lora: classipeintxl_v21.safetensors (weight: 1.0)
-resolution: 1024x1024
-steps: 8
-cfg: 2.0
-sampler: dpmpp_sde
-scheduler: karras
-speed: ~9s per image (RTX 5080)
+# --game still works with a deprecation warning (removed in v3.0)
+sdlab bind --game star-freight   # works, prints warning
+sdlab bind --project star-freight # canonical form
 ```
 
-Additional generation modes: ControlNet (pose/depth-guided), IP-Adapter (reference-driven), and identity packets (named character consistency).
+## Security model
+
+**Local-only.** Talks to ComfyUI on `localhost:8188`. No telemetry, no analytics, no external requests. Images stay on your GPU and filesystem.
 
 ## Requirements
 
 - [ComfyUI](https://github.com/comfyanonymous/ComfyUI) running on localhost:8188
-- DreamShaper XL Turbo checkpoint + ClassipeintXL LoRA
+- SDXL-compatible checkpoint + style LoRA
 - Node.js 20+
 - [`@mcptoolshop/repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset) for training export
 

package/README.pt-BR.md

@@ -13,91 +13,133 @@
 
 # style-dataset-lab
 
-Ferramenta para criação de conjuntos de dados visuais – gera, organiza e exporta dados de treinamento multimodais para o ajuste fino de modelos de linguagem visuais (VLM).
+Uma linha de produção para a criação de conjuntos de dados visuais – desde regras predefinidas até prompts estruturados, passando pela geração no ComfyUI, até dados de treinamento selecionados e vinculados a regras predefinidas.
 
 ## O que é isso
 
-Um conjunto de ferramentas para construir a "verdade visual" que pode ser usada para treinamento. Cada elemento contém três coisas:
+Uma **linha de produção** para a criação de conjuntos de dados visuais estruturados para treinamento. Você define regras de estilo (regras predefinidas), compõe prompts, gera imagens com o ComfyUI, seleciona os resultados com base em critérios específicos, associa as avaliações às regras predefinidas e exporta em 10 formatos através do [`@mcptoolshop/repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset).
+
+A linha de produção é independente de qualquer jogo específico. Cada jogo possui seu próprio diretório de dados em `games/<nome>/`; os 13 scripts e modelos vazios são compartilhados. Cada ativo gerado contém três elementos.
 
 1. **Pixels da imagem** – gerados pelo ComfyUI com total rastreabilidade (checkpoint, LoRA, seed, sampler, cfg).
 2. **Explicação detalhada** – por que este elemento está ou não de acordo com o estilo definido, com base em uma "constituição" de estilo.
 3. **Avaliação de qualidade** – aprovado/rejeitado, com pontuações por dimensão e regras citadas.
 
-A saída é integrada ao [`@mcptoolshop/repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset) para produzir dados de treinamento multimodais em 10 formatos: TRL, LLaVA, Qwen2-VL, Axolotl, LLaMA-Factory, ShareGPT, pares para RLHF, DPO, legendagem e classificação.
-
 ## Modelo de segurança
 
 **Apenas local.** O style-dataset-lab se comunica com o ComfyUI em `localhost:8188` e nunca faz solicitações de rede externas. Sem telemetria, sem análise, sem envio de dados. A geração de imagens ocorre inteiramente na sua GPU. Os registros e os dados de referência permanecem no seu sistema de arquivos.
 
-## Estatísticas do conjunto de dados
+## O que o pacote npm oferece:
+
+`npm install @mcptoolshop/style-dataset-lab` fornece:
 
-| Métrica | Valor |
-|--------|-------|
-| Registros organizados | 1,182 |
-| Total de elementos | 2.571 (893 aprovados, 887 variações com estilo pictórico) |
-| Variações de prompts | 28 |
-| Categorias visuais | 18 (roupas, navios, interiores, equipamentos, ambientes, espécies, estações, sinalização, iluminação, carga, arquitetura, criaturas, superfícies, vida cotidiana, planetas, danos/reparos, biologia alienígena, detalhes realistas) |
-| Comparativos | 6 criados por humanos + 71 criados sinteticamente |
-| Tipos de rejeição distintos | 30+ |
-| Sistema de pacotes de identidade | Personagens nomeados com DNA de facção, patente e referências visuais. |
-| Formatos de exportação | 10 (via @mcptoolshop/repo-dataset) |
+- **13 scripts** – para geração, seleção, comparação, vinculação a regras predefinidas, estilo pictórico, geração de identidade, geração ControlNet/IP-Adapter, seleção em massa, migração.
+- **Modelos vazios** – um modelo inicial, um guia de avaliação e um conjunto de exemplos de prompts, localizados em `templates/`.
+
+O pacote npm **não** inclui dados de jogos. Clone o repositório se você quiser o exemplo do Star Freight (1.182 registros, 28 sequências de prompts, 18 categorias visuais).
 
 ## Instalação
 
 ```bash
-npm install -g @mcptoolshop/style-dataset-lab
+# Get the pipeline scripts + templates
+npm install @mcptoolshop/style-dataset-lab
+
+# Or clone the repo for the Star Freight example data
+git clone https://github.com/mcp-tool-shop-org/style-dataset-lab
+cd style-dataset-lab
+npm install
 ```
 
-Em seguida, clone um projeto ou inicialize um novo espaço de trabalho para conjuntos de dados:
+Para iniciar um novo jogo a partir dos modelos:
 
 ```bash
-git clone https://github.com/mcp-tool-shop-org/style-dataset-lab my-dataset
-cd my-dataset
-npm install
+# Copy templates into your game directory
+mkdir -p games/my-game/{records,comparisons,inputs/prompts,outputs/{candidates,approved,rejected,borderline,painterly},exports}
+cp -r templates/canon games/my-game/canon
+cp templates/inputs/prompts/example-wave.json games/my-game/inputs/prompts/wave1.json
+# Edit the canon and prompts, then generate
+```
+
+## Estrutura do monorepository
+
+A linha de produção está localizada nos diretórios `scripts/` e `templates/`. Cada jogo está em `games/<nome>/`, com suas próprias regras predefinidas, registros e ativos. Os scripts aceitam o argumento `--game <nome>` (o padrão é `star-freight`).
+
+```
+style-dataset-lab/
+  scripts/                  13 pipeline scripts (generate, curate, compare, etc.)
+  templates/                Blank starting point for new games
+    canon/                  Starter constitution + review rubric
+    inputs/prompts/         Example prompt pack
+  games/
+    star-freight/           Star Freight example (1,182 records, repo-only)
+      canon/                Style constitution, review rubric, species canon
+      records/              Per-asset JSON (provenance + judgment + canon)
+      comparisons/          A-vs-B preference judgments
+      inputs/               Prompt packs, identity packets, references
+      outputs/              Generated images (gitignored)
+      exports/              repo-dataset output (gitignored)
+    <your-game>/            Add more games with the same structure
 ```
 
-## Fluxo de trabalho
+## Fluxo de trabalho da linha de produção
+
+A linha de produção completa, desde as regras predefinidas até a exportação para treinamento:
 
 ```bash
-# 1. Start ComfyUI
-# (point it at your checkpoint + LoRA setup)
+# 1. Write your canon -- style constitution + review rubric
+#    (start from templates/ or write from scratch)
 
-# 2. Generate candidates from a prompt pack
-npm run generate -- inputs/prompts/wave1.json
-npm run generate -- inputs/prompts/wave1.json --dry-run
+# 2. Create prompt packs in inputs/prompts/
+#    (see templates/inputs/prompts/example-wave.json)
 
-# 3. Generate identity-packet characters
-npm run generate:identity -- inputs/identity-packets/wave27a-identity-spine.json
+# 3. Start ComfyUI and generate candidates
+npm run generate -- --game star-freight inputs/prompts/wave1.json
+npm run generate -- --game star-freight inputs/prompts/wave1.json --dry-run
 
-# 4. Generate painterly variants of approved assets
-npm run painterly -- <asset_id>
+# 4. Generate identity-packet characters (named subjects)
+npm run generate:identity -- --game star-freight inputs/identity-packets/wave27a.json
 
 # 5. Curate -- approve, reject, or mark borderline
-npm run curate -- <asset_id> approved "explanation" --scores "silhouette:0.9,palette:0.8"
-npm run curate -- <asset_id> rejected "explanation" --failures "too_clean,wrong_material"
+npm run curate -- --game star-freight <asset_id> approved "explanation"
+npm run curate -- --game star-freight <asset_id> rejected "explanation" --failures "too_clean"
+
+# 6. Generate painterly variants of approved assets
+npm run painterly -- --game star-freight
+
+# 7. Bind canon explanations to curated assets
+npm run canon-bind -- --game star-freight
 
-# 6. Bind canon explanations to assets
-npm run canon-bind -- <asset_id>
+# 8. Record pairwise comparisons
+npm run compare -- --game star-freight <asset_a> <asset_b> a "A has better faction read"
 
-# 7. Record pairwise comparisons
-npm run compare -- <asset_a> <asset_b> a "A has better faction read because..."
+# 9. Export training data via repo-dataset
+repo-dataset visual generate ./games/star-freight --format trl
+repo-dataset visual inspect ./games/star-freight
+```
+
+## Adicionando um novo jogo
 
-# 8. Export training data via repo-dataset
-npm run export
-npm run inspect
-npm run validate
+```bash
+# Create structure and copy blank templates
+mkdir -p games/my-game/{records,comparisons,inputs/prompts,outputs/{candidates,approved,rejected,borderline,painterly},exports}
+cp -r templates/canon games/my-game/canon
+cp templates/inputs/prompts/example-wave.json games/my-game/inputs/prompts/wave1.json
+
+# Edit your canon/constitution.md and canon/review-rubric.md
+# Edit your prompt pack, then run the pipeline with --game my-game
 ```
 
-## Estrutura de diretórios
+## Estrutura do diretório por jogo
+
+Cada diretório `games/<nome>/` contém:
 
 ```
-canon/                  Style constitution, review rubric, identity gates, species canon
+canon/                  Style constitution, review rubric, species canon, identity gates
 inputs/
   prompts/              Prompt packs per wave (JSON: subjects, variations, defaults)
   references/           IP-Adapter reference images
-  control/              ControlNet control images
   control-guides/       ControlNet guide overlays
-  identity-packets/     Named character identity spines (faction DNA, rank, visual anchors)
+  identity-packets/     Named character identity spines
 outputs/
   candidates/           Raw generations (gitignored)
   approved/             Curated approved (gitignored)
@@ -107,8 +149,6 @@ outputs/
 records/                Per-asset JSON (provenance + judgment + canon binding)
 comparisons/            A-vs-B preference judgments
 exports/                repo-dataset output (gitignored)
-scripts/                generate, curate, compare, canon-bind, painterly, identity gen
-workflows/              Reusable ComfyUI workflow templates
 ```
 
 ## Configuração de geração