@mcptoolshop/style-dataset-lab 2.0.0 → 2.2.0

package/README.md

@@ -1,3 +1,7 @@
+<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>
@@ -9,148 +13,140 @@
 
 # style-dataset-lab
 
-A canon-bound visual dataset pipeline for directed image production.
+Define visual canon. Curate approved work. Produce versioned datasets. Build training packages. Score outputs against canon. Re-ingest accepted results. Repeat.
 
-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.
+## What this does
 
-## What this is
+Style Dataset Lab is a production pipeline for visual datasets. It takes a project from written canon through curation, dataset packaging, model training preparation, evaluation, and back again as a closed loop.
 
-A **visual canon + dataset pipeline** for teams that care about style consistency, provenance, and reviewable judgment. Every asset carries three things:
+Every asset in the system carries full provenance, canon-bound judgments, and per-dimension quality scores. Nothing is a label without a reason.
+
+```
+canon → curate → bind → snapshot → split → export → train → eval → reingest
+```
 
-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
+## The artifacts
 
-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.
+The pipeline produces seven first-class artifacts. Each is versioned, checksummed, and linked to its predecessors.
+
+| Artifact | What it is |
+|----------|-----------|
+| **Snapshot** | Frozen, fingerprinted record selection. Every inclusion has an explicit reason trace. |
+| **Split** | Leakage-safe train/val/test partition. Subject families never cross split boundaries. |
+| **Export package** | Self-contained dataset: manifest, metadata, images, splits, dataset card, checksums. |
+| **Eval pack** | Canon-aware test tasks: lane coverage, forbidden drift, anchor/gold, subject continuity. |
+| **Training package** | Trainer-ready layout built by adapters. Same truth, different format. |
+| **Eval scorecard** | Per-task pass/fail verdict from scoring generated outputs against eval packs. |
+| **Implementation pack** | Prompt examples, known failures, subject continuity tests, re-ingest guide. |
 
 ## Quick start
 
 ```bash
-# Install the CLI + pipeline
 npm install -g @mcptoolshop/style-dataset-lab
 
-# Scaffold a new project
 sdlab init my-project --domain character-design
-
-# Validate the project structure
 sdlab project doctor --project my-project
 ```
 
-Available domains: `game-art`, `character-design`, `creature-design`, `architecture`, `vehicle-mech`, or `generic`.
+Available domains: `game-art`, `character-design`, `creature-design`, `architecture`, `vehicle-mech`.
 
-## CLI
+## End-to-end example
 
 ```bash
-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
+# 1. Curate and bind records to constitution rules
+sdlab curate <id> approved "Strong silhouette, correct palette"
+sdlab bind --project my-project
+
+# 2. Produce a versioned dataset
+sdlab snapshot create --project my-project
+sdlab split build --project my-project
+sdlab export build --project my-project
+
+# 3. Build a training package
+sdlab training-manifest create --profile character-style-lora
+sdlab training-package build --project my-project
+
+# 4. Evaluate and close the loop
+sdlab eval-pack build --project my-project
+sdlab eval-run create --project my-project
+sdlab eval-run score <id> --outputs results.jsonl
+sdlab reingest generated --source ./outputs --manifest <id>
 ```
 
-All commands accept `--project <name>` (default: `star-freight`).
-
-## Project model
+## Project structure
 
-Each project is a self-contained directory under `projects/` with its own canon, config, and data:
+Each project is self-contained under `projects/<name>/`:
 
 ```
-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)
+project.json            Identity + generation defaults
+constitution.json       Rules 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)
+snapshots/              Frozen dataset snapshots
+splits/                 Train/val/test partitions
+exports/                Versioned export packages
+eval-packs/             Canon-aware eval instruments
+training/
+  profiles/             What kind of model asset to produce
+  manifests/            Frozen training contracts
+  packages/             Trainer-ready layouts
+  eval-runs/            Scored output evaluations
+  implementations/      Usage examples + re-ingest guides
 ```
 
-## Pipeline
+## Key properties
 
-```
-canon  -->  prompts  -->  generate  -->  curate  -->  bind  -->  compare  -->  export
- |            |             |              |           |            |            |
- rules      packs        ComfyUI       judgment    assertions   preferences   dataset
-```
+**Snapshots are frozen.** Once created, a snapshot never silently changes. The config fingerprint (SHA-256 of all project config files) proves reproducibility.
 
-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
+**Splits prevent leakage.** Records sharing a subject family (by identity name, lineage chain, or ID suffix) always land in the same partition. Lane balance is maintained across train/val/test.
+
+**Manifests are immutable contracts.** A training manifest captures the exact export, split, profile, and config fingerprint. If anything changes, a new manifest is required.
+
+**Adapters never mutate truth.** Trainer-specific adapters (`generic-image-caption`, `diffusers-lora`) transform layout but cannot add, remove, or reclassify records.
+
+**Generated outputs re-enter through review.** Re-ingested work gets a new record with full provenance and must be curated and canon-bound like everything else. No bypass.
 
 ## Domain templates
 
-Each domain template ships with lane definitions, constitution rules, scoring rubrics, and terminology structures designed for that production context:
+Five starter templates with real production rules, lane definitions, and scoring rubrics:
 
 | 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 |
+| **game-art** | character, environment, prop, UI, ship, interior, equipment | Silhouette at gameplay scale, faction read, wear/aging |
+| **character-design** | portrait, full_body, turnaround, expression_sheet, action_pose | Proportions, costume logic, personality, gesture |
+| **creature-design** | concept, orthographic, detail_study, action, scale_reference, habitat | Anatomy, evolutionary logic, silhouette distinction |
+| **architecture** | exterior, interior, streetscape, structural_detail, ruin, landscape | Structure, material consistency, perspective, era |
+| **vehicle-mech** | exterior, cockpit, component, schematic, silhouette_sheet, damage_variant | Mechanical logic, design language, access points |
 
-## The dataset angle
+## Downstream formats
 
-The pipeline produces more than organized images. It produces **trustworthy, structured datasets** with:
+`sdlab` defines and owns the dataset. Downstream format conversion is handled by [`repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset): TRL, LLaVA, Qwen2-VL, JSONL, Parquet, and more. `repo-dataset` renders formats; it never decides inclusion.
 
-- **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)
+## Star Freight
 
-Export via `repo-dataset` to TRL, LLaVA, Qwen2-VL, JSONL, Parquet, and more.
-
-## Star Freight example
-
-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.
+Clone the repo for a complete working example: 1,182 records, 5 factions, 7 lanes, 24 constitution rules, 2 training profiles.
 
 ```bash
 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
+sdlab snapshot create --project star-freight
+sdlab split build --project star-freight
+sdlab training-manifest create --profile character-style-lora --project star-freight
 ```
 
-## Migrating from v1.x
-
-v2.0 renames `games/` to `projects/` and `--game` to `--project`:
-
-```bash
-# Rename your data directory
-mv games projects
-
-# --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
-```
-
-## Security model
+## Security
 
-**Local-only.** Talks to ComfyUI on `localhost:8188`. No telemetry, no analytics, no external requests. Images stay on your GPU and filesystem.
+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
 - SDXL-compatible checkpoint + style LoRA
 - Node.js 20+
-- [`@mcptoolshop/repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset) for training export
 
 ## License
 

package/README.pt-BR.md

@@ -13,158 +13,187 @@
 
 # style-dataset-lab
 
-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.
+Transforme trabalhos visuais aprovados em conjuntos de dados versionados, com revisões, divisões, pacotes de exportação e pacotes de avaliação.
 
 ## O que é isso
 
-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).
+Um **pipeline de produção de conjuntos de dados e de referências visuais**. Defina a aparência do seu projeto. Crie conjuntos de dados de acordo com as regras estabelecidas. Produza pacotes de dados reproduzíveis com divisões seguras contra vazamento de informações. Gere pacotes de avaliação para a verificação futura do modelo.
 
-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.
+O pipeline produz quatro artefatos:
 
-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.
+| Artefato | O que é |
+|----------|-----------|
+| **Snapshot** | Seleção de registros elegíveis, com informações detalhadas e rastreáveis. Cada inclusão tem uma justificativa explícita. |
+| **Split** | Partição de treinamento/validação/teste segura contra vazamento de informações. Registros que compartilham a mesma família de sujeitos sempre ficam na mesma divisão. |
+| **Export package** | Conjunto de dados autônomo: manifesto, metadados, imagens, divisões, descrição do conjunto de dados e checksums. |
+| **Eval pack** | Tarefas de verificação compatíveis com as referências: cobertura de aspectos, prevenção de desvios indesejados, pontos de referência/referências, continuidade do sujeito. |
 
-## 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.
-
-## O que o pacote npm oferece:
-
-`npm install @mcptoolshop/style-dataset-lab` fornece:
+Cada ativo no pipeline contém três elementos:
 
-- **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/`.
+1. **Rastreabilidade** -- histórico completo de geração (checkpoint, LoRA, seed, sampler, cfg, tempo de execução)
+2. **Conformidade com as referências** -- quais regras de estilo este ativo cumpre, não cumpre ou cumpre parcialmente
+3. **Avaliação de qualidade** -- aprovado/rejeitado/limítrofe, com pontuações por dimensão
 
-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).
+Funciona para arte de jogos, design de personagens, design de criaturas, arquitetura, conceitos de veículos/máquinas, e qualquer área onde a produção visual precisa seguir um padrão.
 
-## Instalação
+## Como começar
 
 ```bash
-# Get the pipeline scripts + templates
-npm install @mcptoolshop/style-dataset-lab
+# Install the CLI + pipeline
+npm install -g @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
+# Scaffold a new project
+sdlab init my-project --domain character-design
+
+# Validate the project structure
+sdlab project doctor --project my-project
 ```
 
-Para iniciar um novo jogo a partir dos modelos:
+Domínios disponíveis: `game-art`, `character-design`, `creature-design`, `architecture`, `vehicle-mech` ou `generic`.
+
+## Interface de linha de comando (CLI)
 
 ```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
+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
+
+sdlab snapshot create [--profile <name>]  # Create frozen dataset snapshot
+sdlab snapshot list                       # List all snapshots
+sdlab snapshot diff <a> <b>               # Compare two snapshots
+sdlab eligibility audit                   # Audit record training eligibility
+sdlab split build [--snapshot <id>]       # Build train/val/test split
+sdlab split audit <id>                    # Audit split for leakage + balance
+sdlab card generate                       # Generate dataset card (md + JSON)
+sdlab export build [--snapshot <id>]      # Build versioned export package
+sdlab eval-pack build                     # Build canon-aware eval pack
 ```
 
-## Estrutura do monorepository
+Todos os comandos aceitam `--project <nome>` (padrão: `star-freight`).
+
+## Modelo do projeto
 
-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`).
+Cada projeto é um diretório autônomo dentro de `projects/`, com suas próprias referências, configuração e dados:
 
 ```
-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
+    snapshots/              Frozen dataset snapshots
+    splits/                 Train/val/test partitions
+    exports/                Versioned export packages
+    eval-packs/             Canon-aware eval instruments
 ```
 
-## Fluxo de trabalho da linha de produção
+## Pipeline
 
-A linha de produção completa, desde as regras predefinidas até a exportação para treinamento:
-
-```bash
-# 1. Write your canon -- style constitution + review rubric
-#    (start from templates/ or write from scratch)
+```
+canon → generate → curate → bind → snapshot → split → export → eval
+  |        |          |        |        |         |        |       |
+rules   ComfyUI   judgment  rules   frozen    subject  package  verify
+                                    selection isolation
+```
 
-# 2. Create prompt packs in inputs/prompts/
-#    (see templates/inputs/prompts/example-wave.json)
+1. **Definir referências** -- escreva sua constituição de estilo e guia de revisão
+2. **Gerar** -- o ComfyUI produz candidatos com rastreabilidade completa
+3. **Curadoria** -- aprovar/rejeitar com pontuações por dimensão e modos de falha
+4. **Associar** -- vincular cada ativo às regras de estilo, com veredictos de aprovação/rejeição/parcial
+5. **Captura de instantâneo** -- congelar os registros elegíveis em uma seleção determinística e identificada
+6. **Dividir** -- particionar em treinamento/validação/teste, com isolamento do sujeito e equilíbrio de aspectos
+7. **Exportar** -- criar um pacote autônomo com manifesto, metadados, imagens e checksums
+8. **Avaliar** -- gerar instrumentos de teste compatíveis com as referências para a verificação do modelo
 
-# 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
+A conversão de formato para outros sistemas (TRL, LLaVA, Parquet, etc.) é gerenciada por [`repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset). O `sdlab` define a "verdade" do conjunto de dados; o `repo-dataset` a transforma em formatos especializados.
 
-# 4. Generate identity-packet characters (named subjects)
-npm run generate:identity -- --game star-freight inputs/identity-packets/wave27a.json
+## Modelos de domínio
 
-# 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"
+Cada modelo de domínio é fornecido com definições de aspectos, regras de estilo, guias de pontuação e estruturas de terminologia projetadas para aquele contexto de produção:
 
-# 6. Generate painterly variants of approved assets
-npm run painterly -- --game star-freight
+| Domínio | Aspectos | Principais preocupações |
+|--------|-------|-------------|
+| **game-art** | personagem, ambiente, acessório, interface do usuário, nave, interior, equipamento | Silhueta na escala do jogo, diferenciação de facções, desgaste/envelhecimento |
+| **character-design** | retrato, corpo inteiro, vista de 360 graus, folha de expressões, pose de ação | Precisão das proporções, lógica do figurino, leitura da personalidade, clareza dos gestos |
+| **creature-design** | conceito, ortográfico, estudo de detalhes, ação, referência de escala, habitat | Plausibilidade anatômica, lógica evolutiva, distinção de silhuetas |
+| **architecture** | exterior, interior, paisagem urbana, detalhe estrutural, ruína, paisagem | Plausibilidade estrutural, consistência dos materiais, perspectiva, coerência da época |
+| **vehicle-mech** | exterior, cockpit, componente, esquema, folha de silhuetas, variação de dano | Lógica mecânica, linguagem de design funcional, pontos de acesso, descrição de danos. |
 
-# 7. Bind canon explanations to curated assets
-npm run canon-bind -- --game star-freight
+## Produção do conjunto de dados
 
-# 8. Record pairwise comparisons
-npm run compare -- --game star-freight <asset_a> <asset_b> a "A has better faction read"
+A estrutura completa do conjunto de dados: instantâneo, divisão, exportação, avaliação.
 
-# 9. Export training data via repo-dataset
-repo-dataset visual generate ./games/star-freight --format trl
-repo-dataset visual inspect ./games/star-freight
+```
+snapshot  -->  split  -->  export  -->  eval-pack
+   |            |            |             |
+  frozen     subject      package       canon-aware
+  selection  isolation    (manifest,    test instruments
+             + lane       metadata,     (4 task types)
+             balance      images,
+                          checksums,
+                          card)
 ```
 
-## Adicionando um novo jogo
+**Instantâneos** congelam uma seleção determinística de registros elegíveis. Cada inclusão tem um registro de motivo. As "impressões digitais" de configuração garantem a reprodutibilidade.
+
+**Divisões** atribuem registros às partições de treinamento/validação/teste, com isolamento de sujeitos (nenhuma família de sujeitos aparece em várias divisões) e distribuição equilibrada por "faixa". Um gerador de números pseudoaleatórios (PRNG) com semente garante resultados idênticos a partir da mesma semente.
+
+Os **pacotes de exportação** são autônomos: manifesto, metadata.jsonl, imagens (com links simbólicos ou cópias), divisões, cartão do conjunto de dados (Markdown + JSON) e somas de verificação no formato BSD. Tudo o que é necessário para reconstruir o conjunto de dados do zero.
+
+Os **pacotes de avaliação** são instrumentos de teste que levam em consideração o contexto e possuem quatro tipos de tarefas: cobertura de "faixas", desvio proibido, âncora/referência e continuidade do sujeito. Eles comprovam que a estrutura do conjunto de dados está sendo usada para futuras avaliações de modelos, e não apenas para descartar arquivos.
+
+Exportação para formatos compatíveis através de [`repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset) (TRL, LLaVA, Qwen2-VL, JSONL, Parquet, e mais). `repo-dataset` gerencia a conversão de formatos; `sdlab` detém a "verdade" do conjunto de dados.
+
+## Exemplo do Star Freight
+
+Clone o repositório para um exemplo completo e funcional: 1.182 registros, 28 "ondas" de prompts, 5 facções, 7 "faixas", 24 regras constitucionais e 892 ativos aprovados de um RPG de ficção científica.
 
 ```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
+git clone https://github.com/mcp-tool-shop-org/style-dataset-lab
+cd style-dataset-lab
+
+# Validate the project
+sdlab project doctor --project star-freight
 
-# Edit your canon/constitution.md and canon/review-rubric.md
-# Edit your prompt pack, then run the pipeline with --game my-game
+# Run the full dataset spine
+sdlab snapshot create --project star-freight    # 839 eligible records
+sdlab split build --project star-freight        # ~80/10/10, zero leakage
+sdlab export build --project star-freight       # package with checksums
+sdlab eval-pack build --project star-freight    # 78 eval records
 ```
 
-## Estrutura do diretório por jogo
+## Migrando da versão v1.x
 
-Cada diretório `games/<nome>/` contém:
+A versão 2.0 renomeia `games/` para `projects/` e `--game` para `--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
 
-## Configuração de geração
-
-```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
 ```
 
-Modos de geração adicionais: ControlNet (guiado por pose/profundidade), IP-Adapter (guiado por referência) e pacotes de identidade (consistência de personagens nomeados).
+## Modelo de segurança
+
+**Apenas local.** Comunica-se com o ComfyUI em `localhost:8188`. Sem telemetria, sem análises, sem requisições externas. As imagens permanecem na sua GPU e sistema de arquivos.
 
 ## Requisitos