@mcptoolshop/style-dataset-lab 3.0.1 → 3.2.0

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>
 
@@ -56,6 +58,28 @@ sdlab reingest selected --selection selection_2026-04-16_001
 
 That last command is the point. Selected outputs come back through the same review process as everything else. The corpus grows and the rules hold.
 
+## Canon authoring
+
+Before the dataset pipeline runs, the `sdlab canon *` namespace turns your project's canon entity store into the three projections training and production actually consume — and locks the entries that must not drift.
+
+```bash
+# Build three projections from the canon entity store:
+#   dataset.jsonl  → training adapters
+#   prompts/*.j2   → ComfyUI workflow invocation
+#   context/*.md   → Role OS narrative dispatch
+sdlab canon build --project my-project
+
+# Freeze an entry so regeneration can't silently change it
+sdlab canon freeze kael_maren --project my-project --reason "prologue portrait locked"
+
+# Report drift on frozen entries since the last clean build
+sdlab canon drift --project my-project
+```
+
+`canon build` is content-addressable — its output is keyed by a `canon_sha` and cached, so an unchanged canon rebuilds instantly. `canon freeze` witnesses each freeze against a specific build and appends to a `freeze-events.jsonl` audit trail: `frozen` entries refuse regeneration outright, `soft-advisory` entries refuse by default (bypass with `--i-know`). `canon drift` recomputes every watched entry's hash and flags anything that moved since the last clean build.
+
+Full workflow in the handbook: [Canon build](handbook/canon-build/), [Canon freeze](handbook/canon-freeze/), and [Two-LoRA stacking](handbook/two-lora-stacking/).
+
 ## What it produces
 
 Seven dataset artifacts and a full production workbench. Each artifact links to its predecessors so you can trace any training record back to the rule that approved it.
@@ -178,6 +202,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,16 +8,18 @@
 
 <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 arte. Avalie cada imagem com base nessas regras. Envie os resultados como dados de treinamento auditáveis e versionados — e, em seguida, coloque modelos treinados para trabalhar em fluxos de trabalho de produção reais e insira as melhores saídas de volta no seu corpus.
 
-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 Style Dataset Lab conecta o que você escreveu sobre seu estilo artístico ao conjunto de dados do qual você realmente treina, e então fecha o ciclo até a produção. Você define uma constituição — regras de silhueta, restrições de paleta, linguagem dos materiais, qualquer coisa que seja importante para o seu projeto. O pipeline gera candidatos, avalia-os com base nessas regras e empacota o trabalho aprovado 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 estação de trabalho de produção assume o controle: compile resumos de geração a partir da verdade do projeto, execute-os no ComfyUI, critique as saídas, produza em lote folhas de expressão e painéis de ambiente, selecione os melhores resultados e reintroduza-os como novos candidatos. O ciclo se fecha: produzir, selecionar, revisar, fortalecer.
 
-## O processo
+## O pipeline
 
 ```bash
 # Write your canon. Scaffold the project.
@@ -28,59 +30,104 @@ 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
+```
+
+Esse último comando é o ponto crucial. As saídas selecionadas retornam pelo mesmo processo de revisão que tudo o mais. O corpus cresce e as regras permanecem válidas.
+
+## Criação do cânone
+
+Antes que o pipeline do conjunto de dados seja executado, o namespace `sdlab canon *` transforma o repositório de entidades do cânone do seu projeto nas três projeções que o treinamento e a produção realmente usam — e bloqueia as entradas que não devem ser alteradas.
+
+```bash
+# Build three projections from the canon entity store:
+#   dataset.jsonl  → training adapters
+#   prompts/*.j2   → ComfyUI workflow invocation
+#   context/*.md   → Role OS narrative dispatch
+sdlab canon build --project my-project
+
+# Freeze an entry so regeneration can't silently change it
+sdlab canon freeze kael_maren --project my-project --reason "prologue portrait locked"
+
+# Report drift on frozen entries since the last clean build
+sdlab canon drift --project my-project
 ```
 
-Aquele último comando é crucial. As saídas geradas passam pelo mesmo processo de revisão de tudo o mais. O ciclo se fecha.
+`canon build` é endereçável por conteúdo — sua saída é identificada por um `canon_sha` e armazenada em cache, para que uma reconstrução do cânone inalterado seja feita instantaneamente. `canon freeze` registra cada congelamento em relação a uma construção específica e anexa a um rastreamento de auditoria `freeze-events.jsonl`: as entradas `frozen` rejeitam explicitamente a regeneração, as entradas `soft-advisory` rejeitam por padrão (ignore com `--i-know`). `canon drift` recalcula o hash de cada entrada monitorada e sinaliza qualquer coisa que tenha sido alterada desde a última construção limpa.
+
+Fluxo de trabalho completo no manual: [Canon build](handbook/canon-build/), [Canon freeze](handbook/canon-freeze/) e [Two-LoRA stacking](handbook/two-lora-stacking/).
 
 ## 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 de conjunto de dados e uma estação 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 é |
 |----------|-----------|
-| **Snapshot** | Seleção de registros fixos com impressão digital de configuração. Cada inclusão tem uma razão explícita. |
-| **Split** | Partição de treinamento/validação/teste, onde as famílias de elementos nunca ultrapassam as fronteiras. |
-| **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. |
-| **Training package** | Formato pronto para treinamento através de adaptadores (`diffusers-lora`, `generic-image-caption`). A mesma informação, em formato diferente. |
-| **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. |
+| **Snapshot** | Seleção de registros congelados com impressão digital da configuração. Cada inclusão tem uma razão explícita. |
+| **Split** | Partição de treinamento/validação/teste onde as famílias de assuntos nunca cruzam os limites. |
+| **Export package** | Conjunto de dados autônomo: manifesto, metadados, imagens, divisões, cartão do conjunto de dados, somas de verificação. |
+| **Eval pack** | Tarefas de teste com reconhecimento do cânone: cobertura da faixa, desvio proibido, âncora/ouro, continuidade do assunto. |
+| **Training package** | Layout pronto para o treinador por meio de adaptadores (`diffusers-lora`, `generic-image-caption`). A mesma verdade, formato diferente. |
+| **Eval scorecard** | Resultado de aprovação/reprovação por tarefa a partir da pontuação das saídas geradas em relação aos pacotes de avaliação. |
+| **Implementation pack** | Exemplos de prompts, falhas conhecidas, testes de continuidade e orientação para reintrodução. |
+
+A estação de trabalho de produção adiciona:
+
+| Superfície | O que faz |
+|---------|-------------|
+| **Compiled brief** | Instrução de geração determinística a partir do perfil do fluxo de trabalho + verdade do projeto. |
+| **Run** | Artefato de execução congelado: resumo + sementes + saídas do ComfyUI + manifesto. |
+| **Critique** | Avaliação estruturada multidimensional das saídas da execução em relação ao cânone. |
+| **Batch** | Produção coordenada multislot (folhas de expressão, painéis de ambiente, pacotes de silhueta). |
+| **Selection** | Artefato de decisão criativa: quais saídas foram escolhidas, por quê e de onde vieram. |
+| **Re-ingest** | As saídas selecionadas retornam como registros candidatos com toda a proveniência 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.
+Os dados de treinamento são o artefato de maior impacto em qualquer pipeline de IA visual. Mas, na maioria das vezes, os dados de treinamento são apenas uma pasta de imagens sem histórico, sem rastreamento de julgamento e sem conexão com as regras de estilo que deveriam ser seguidas.
 
-O Style Dataset Lab torna essa conexão explícita. Sua estrutura define as regras. Sua rubrica define as dimensões de avaliação. Seus registros de curadoria documentam a avaliação. Seu cânone vinculante prova a conexão. E seu conjunto de dados carrega tudo isso como uma verdade estruturada, pesquisável e reproduzível.
+O Style Dataset Lab torna a conexão explícita. Sua constituição define as regras. Seu rubrica define as dimensões de pontuação. Seus registros de curadoria registram o julgamento. Sua vinculação do cânone prova a conexão. E seu conjunto de dados carrega tudo isso para frente como uma verdade estruturada, pesquisável e reproduzível.
 
-O resultado prático: quando seu LoRA se desvia, você pode perguntar *por quê*. Quando sua próxima rodada de treinamento precisar de melhores dados, você saberá exatamente quais registros estão próximos do ideal e qual regra específica eles não cumpriram. Quando um novo membro da equipe perguntar qual é a linguagem visual do projeto, a resposta não é um quadro do Figma – é uma estrutura pesquisável com 1.182 exemplos classificados.
+O resultado prático: quando seu LoRA se desvia, você pode perguntar *por quê*. Quando sua próxima rodada de treinamento precisar de melhores dados, você saberá exatamente quais registros estão próximos do ideal e qual regra única eles não cumpriram. Quando um novo membro da equipe perguntar qual é a linguagem visual do projeto, a resposta não será uma placa Figma — será uma constituição pesquisável com 1.182 exemplos graduados.
 
 ## Cinco domínios, regras reais
 
-Não são modelos genéricos. Cada domínio é fornecido com regras de estrutura de produção, definições de categorias, rubricas de avaliação e vocabulário específico.
+Não são apenas modelos de exemplo. Cada domínio é fornecido com regras de constituição de nível de produção, definições de faixa, rubricas de pontuação e vocabulário de grupo.
 
-| Domínio | Aspectos | O que é avaliado. |
+| Domínio | Faixas | O que é avaliado |
 |--------|-------|-----------------|
-| **game-art** | personagem, ambiente, acessório, interface do usuário, nave, interior, equipamento | Silhueta em escala de jogabilidade, identificação de facção, desgaste e envelhecimento. |
-| **character-design** | retrato, corpo inteiro, vista de 360 graus, folha de expressões, pose de ação | Proporções, lógica de figurino, personalidade, clareza de gestos. |
-| **creature-design** | conceito, ortográfico, estudo de detalhes, ação, referência de escala, habitat | Anatomia, lógica evolutiva, distinção de silhueta. |
-| **architecture** | exterior, interior, paisagem urbana, detalhe estrutural, ruína, paisagem | Estrutura, consistência de materiais, perspectiva, coerência de é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. |
+| **game-art** | personagem, ambiente, adereço, interface do usuário, nave, interior, equipamento | Silhueta na escala de jogabilidade, leitura da facção, desgaste e envelhecimento |
+| **character-design** | retrato, corpo inteiro, rotação, folha de expressão, pose de ação | Proporções, lógica do traje, personalidade, clareza dos gestos |
+| **creature-design** | conceito, ortográfico, estudo de detalhes, ação, referência de escala, habitat | Anatomia, lógica evolutiva, distinção da silhueta |
+| **architecture** | exterior, interior, paisagem urbana, detalhe estrutural, ruína, paisagem | Estrutura, consistência do material, perspectiva, coerência de época |
+| **vehicle-mech** | exterior, cabine, componente, esquema, folha de silhueta, variante de dano | Lógica mecânica, linguagem de design, pontos de acesso, narrativa de danos |
 
 ## Estrutura do projeto
 
-Cada projeto é autônomo. Cinco arquivos de configuração JSON definem as regras; o resto é apenas dados.
+Cada projeto é autocontido. Cinco arquivos de configuração JSON definem as regras; tudo o mais são dados.
 
 ```
 projects/my-project/
@@ -94,21 +141,27 @@ 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
+## Propriedades de confiança
 
-Essas propriedades não são apenas desejáveis; elas são aplicadas.
+Estas não são apenas aspirações. Elas são aplicadas.
 
-- **Os snapshots são imutáveis.** A impressão digital de configuração (SHA-256) prova que nada foi alterado.
-- **As divisões evitam vazamentos.** As famílias de elementos (por identidade, linhagem ou sufixo de ID) nunca ultrapassam as fronteiras das partições.
-- **Os manifestos são contratos fixos.** Hash de exportação + impressão digital de configuração. Se algo mudar, crie um novo.
-- **Os adaptadores não podem alterar a verdade.** Formato diferente, mesmos registros. Sem adições, sem remoções, sem reclassificações.
-- **As saídas geradas são submetidas à revisão.** Sem atalhos. Curadoria e vinculação como tudo o mais.
+- **Os snapshots são imutáveis.** A impressão digital da configuração (SHA-256) prova que nada foi alterado.
+- **As divisões evitam vazamentos.** As famílias de objetos (por identidade, linhagem ou sufixo de ID) nunca cruzam os limites das partições.
+- **Os manifestos são contratos congelados.** Hash de exportação + impressão digital da configuração. Se algo mudar, crie um novo.
+- **Os adaptadores não podem alterar a verdade.** Layout diferente, mesmos registros. Sem adições, sem remoções, sem reclassificações.
+- **As saídas geradas retornam através da revisão.** Sem atalhos. Curadoria e vinculação como tudo o mais.
 
 ## Star Freight
 
-O repositório inclui um exemplo completo e funcional: 1.182 registros, 5 facções, 7 caminhos, 24 regras constitucionais, 892 ativos aprovados e 2 perfis de treinamento. Um cânone visual de RPG de ficção científica, totalmente organizado.
+O repositório inclui um exemplo completo e funcional: 1.182 registros, 5 facções, 7 rotas, 24 regras de constituição, 892 ativos aprovados, 2 perfis de treinamento. Um cânone visual de RPG de ficção científica sombrio, totalmente selecionado.
 
 ```bash
 git clone https://github.com/mcp-tool-shop-org/style-dataset-lab
@@ -118,9 +171,9 @@ sdlab snapshot create --project star-freight   # 839 eligible records
 sdlab split build --project star-freight       # zero subject leakage
 ```
 
-## Formatos compatíveis
+## Formatos downstream
 
-O projeto `sdlab` é o proprietário do conjunto de dados. A conversão de formatos é gerenciada pelo [`repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset): TRL, LLaVA, Qwen2-VL, JSONL, Parquet e outros. O `repo-dataset` é responsável pela renderização; ele nunca decide a inclusão de dados.
+`sdlab` é o proprietário do conjunto de dados. A conversão de formato é tratada por [`repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset): TRL, LLaVA, Qwen2-VL, JSONL, Parquet e muito mais. `repo-dataset` renderiza; nunca decide a inclusão.
 
 ## Instalação
 
@@ -128,11 +181,71 @@ O projeto `sdlab` é o proprietário do conjunto de dados. A conversão de forma
 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.
+Requer Node.js 20+ e [ComfyUI](https://github.com/comfyanonymous/ComfyUI) no localhost:8188 para geração.
+
+### Experimente sem o ComfyUI
+
+Você pode explorar toda a funcionalidade não relacionada à geração — inspeção, curadoria, snapshot, divisão, exportação — usando o projeto Star Freight incluído, sem instalar o ComfyUI ou baixar quaisquer pesos 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 configuração de projeto (constituição, rotas, rubrica, terminologia) e relata a elegibilidade sem tocar na GPU. Qualquer comando que altere o estado gerado aceita `--dry-run` para visualizar o efeito primeiro.
+
+Se você esquecer `--project`, a CLI voltará ao primeiro projeto que encontrar em `projects/` e imprimirá um aviso — passe `--project` explicitamente para silenciá-lo.
+
+### Retomando uma execução interrompida
+
+Execuções de geração longas podem ser retomadas sem refazer o trabalho 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 grava sua entrada de manifesto atomicamente ao terminar — uma falha no meio da 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 `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 de fluxo de trabalho especifica um arquivo de modelo que não está na pasta `models/checkpoints/` ou `models/loras/` do ComfyUI. Abra `projects/<project>/workflows/profiles/<profile>.json`, localize o campo `checkpoint` ou `lora` e, ou baixe o peso referenciado ou substitua-o por um que você já tenha. Execute novamente `sdlab project doctor --project <project>` para confirmar a correção.
+
+**Erros de `sdlab project doctor`**
+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 o arquivo e o campo com problemas.
+- `E_RECORD_DRIFT` — a impressão digital da configuração de um registro não corresponde mais à sua fonte. Reavalie ou redefina conforme sugerido no aviso.
+
+**`No --project specified, falling back to <name>`**
+Um aviso leve. Passe `--project <name>` explicitamente para selecionar o projeto correto e silenciar o aviso.
+
+**Problemas de VRAM / "Painterly" (estilo pictórico) / falta de memória**
+Consulte `docs/internal/HANDOFF.md` para obter as notas sobre o ajuste do ruído no estilo pictórico. Em resumo: diminua a intensidade do ruído, reduza o tamanho do lote ou altere para um checkpoint menor em seu perfil de fluxo de trabalho.
+
+**Relatando bugs**
+Crie uma solicitação em https://github.com/mcp-tool-shop-org/style-dataset-lab/issues com sua versão do sdlab (`sdlab --version`), versão do Node (`node -v`), o comando completo e a saída de erro estruturada. Um modelo de relatório de bug preenche os campos automaticamente.
 
 ## 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.
+Apenas local. Sem telemetria, sem análises, sem solicitações externas. As imagens permanecem em sua GPU e sistema de arquivos.
 
 ## Licença
 
@@ -140,4 +253,4 @@ MIT
 
 ---
 
-Criado por <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a
+Criado por <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>

package/README.zh.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,55 +30,100 @@ 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
 ```
 
-那个最后的命令至关重要。生成的输出会经过与所有其他内容相同的审查流程。循环闭合。
+最后一条命令就是关键。选定的输出会通过与所有其他内容相同的审核流程进行评估。语料库不断增长，规则始终有效。
+
+## 规范创作
+
+在数据集流水线运行之前，“sdlab canon *”命名空间会将你项目的规范实体存储转换为实际用于训练和生产的三个投影——并锁定那些不应发生变化的项目。
+
+```bash
+# Build three projections from the canon entity store:
+#   dataset.jsonl  → training adapters
+#   prompts/*.j2   → ComfyUI workflow invocation
+#   context/*.md   → Role OS narrative dispatch
+sdlab canon build --project my-project
+
+# Freeze an entry so regeneration can't silently change it
+sdlab canon freeze kael_maren --project my-project --reason "prologue portrait locked"
+
+# Report drift on frozen entries since the last clean build
+sdlab canon drift --project my-project
+```
 
-## 它产生的内容
+“canon build”（构建规范）是基于内容的——其输出由 `canon_sha` 标识，并进行缓存，因此未更改的规范可以立即重建。“canon freeze”（冻结规范）会针对特定的构建记录每次冻结操作，并将结果附加到 `freeze-events.jsonl` 审计跟踪中：`frozen`（已冻结）条目直接拒绝重新生成，`soft-advisory`（软提示）条目默认拒绝（通过 `--i-know` 参数可以绕过）。“canon drift”（规范漂移）会重新计算每个受监控条目的哈希值，并标记自上次干净构建以来发生变化的任何内容。
 
-七个版本控制的、具有校验和的成果。每个成果都链接到其前身，因此您可以追溯任何训练记录，了解它是根据哪个规则被批准的。
+完整的流程在手册中：[构建规范](handbook/canon-build/)、[冻结规范](handbook/canon-freeze/)和[双 LoRA 堆叠](handbook/two-lora-stacking/)。
 
-| 成果 | 它的定义 |
+## 它产生的结果
+
+七个数据集工件和一个完整的生产工作台。每个工件都链接到其前身，因此你可以追溯任何训练记录到批准它的规则。
+
+| 工件 | 它是什么 |
 |----------|-----------|
-| **Snapshot** | 带有配置指纹的冻结记录选择。每个包含项都有明确的理由。 |
-| **Split** | 训练/验证/测试数据集，其中主题类别之间绝不交叉。 |
-| **Export package** | 自包含的数据集：清单、元数据、图像、数据集划分、数据集描述、校验和。 |
-| **Eval pack** | 与规范相关的测试任务：覆盖范围、避免偏差、锚定/黄金标准、主题连续性。 |
-| **Training package** | 通过适配器（`diffusers-lora`、`generic-image-caption`）提供可供训练器使用的布局。相同的真理，不同的格式。 |
-| **Eval scorecard** | 每个任务的通过/失败结果，基于生成的输出与评估包的比较。 |
-| **Implementation pack** | 提示示例、已知的失败案例、连续性测试以及重新导入指南。 |
+| **Snapshot** | 带有配置指纹的冻结记录选择。每条包含的内容都有明确的原因。 |
+| **Split** | 训练/验证/测试分区，其中主题系列不会跨越边界。 |
+| **Export package** | 独立的数据集：清单、元数据、图像、分割、数据集卡、校验和。 |
+| **Eval pack** | 考虑规范的测试任务：车道覆盖率、禁止漂移、锚点/黄金标准、主题连续性。 |
+| **Training package** | 通过适配器（`diffusers-lora`、`generic-image-caption`）实现的，可用于训练器的布局。相同的真实数据，不同的格式。 |
+| **Eval scorecard** | 根据评估包对生成的输出进行评分后的每个任务的通过/失败结果。 |
+| **Implementation pack** | 提示示例、已知错误、连续性测试和重新导入指南。 |
+
+生产工作台添加的内容：
 
-## 存在的理由
+| 表面 | 它做什么 |
+|---------|-------------|
+| **Compiled brief** | 从工作流程配置文件 + 项目真实数据中生成确定性的生成指令。 |
+| **Run** | 冻结的执行工件：简报 + 种子 + ComfyUI 输出 + 清单。 |
+| **Critique** | 对运行输出相对于规范进行结构化的多维评估。 |
+| **Batch** | 协调的多插槽生产（表情图、环境板、轮廓包）。 |
+| **Selection** | 创意决策工件：选择了哪些输出，原因是什么，以及它们的来源是什么。 |
+| **Re-ingest** | 选定的输出作为带有完整生成溯源的候选记录返回。 |
 
-训练数据是任何视觉人工智能流水线中最具价值的资源。但大多数训练数据只是一个包含图像的文件夹，没有任何历史记录、评估记录，以及与它应该遵循的风格规则的联系。
+## 为什么这个工具存在
 
-Style Dataset Lab 明确地建立了这种联系。您的规范定义了规则。您的评分标准定义了评分维度。您的筛选记录记录了评估结果。您的规范证明了这种联系。您的数据集将所有这些信息以结构化、可查询、可重复的方式传递下去。
+训练数据是任何视觉 AI 流水线中最重要的工件。但是，大多数训练数据只是一个包含图像的文件夹，没有历史记录、没有判断轨迹，也没有与它应该遵循的风格规则的联系。
 
-实际结果：当您的 LoRA 出现偏差时，您可以询问*原因*。当您的下一个训练轮需要更好的数据时，您清楚地知道哪些记录是接近理想的，以及它们违反了哪个规则。当新团队成员询问项目的视觉语言是什么时，答案不是一个 Figma 板，而是一份包含 1182 个已评分示例的可搜索规范。
+“风格数据集实验室”使这种联系变得明确。你的规范定义了规则。你的评分标准定义了评分维度。你的策划记录了判断结果。你的规范绑定证明了这种联系。并且你的数据集将所有这些内容作为结构化、可查询、可重现的真实数据进行传递。
+
+实际效果：当你的 LoRA 发生漂移时，你可以询问*原因*。当你的下一个训练轮次需要更好的数据时，你确切地知道哪些记录是接近成功的，以及它们未能满足哪个单一规则。当新的团队成员询问项目的视觉语言是什么时，答案不是 Figma 板——而是一个可搜索的规范，其中包含 1,182 个经过评分的示例。
 
 ## 五个领域，真实的规则
 
-不是占位符模板。每个领域都包含生产级别的规范规则、定义、评分标准和词汇表。
+不是占位符模板。每个领域都提供生产级别的规范规则、车道定义、评分标准和组词汇。
 
-| 领域 | 定义 | 评估内容 |
+| 领域 | 车道 | 要评估的内容 |
 |--------|-------|-----------------|
-| **game-art** | 角色、环境、道具、UI、飞船、内部、设备 | 游戏场景中的轮廓、派系特征、磨损和老化 |
-| **character-design** | 人像、全身照、旋转视图、表情图、动作姿势 | 比例、服装逻辑、个性、姿势清晰度 |
-| **creature-design** | 概念图、正交视图、细节研究、动作、比例参考、栖息地 | 解剖结构、进化逻辑、轮廓区分 |
-| **architecture** | 外部、内部、街道景观、结构细节、废墟、景观 | 结构、材质一致性、透视、时代一致性 |
-| **vehicle-mech** | 外部、驾驶舱、组件、示意图、轮廓图、损坏变体 | 机械逻辑、设计语言、访问点、损坏叙述 |
+| **game-art** | 角色、环境、道具、UI、飞船、内部、设备 | 在游戏规模下的轮廓、派系特征、磨损和老化 |
+| **character-design** | 肖像、全身、旋转图、表情图、动作姿势 | 比例、服装逻辑、个性、手势清晰度 |
+| **creature-design** | 概念、正交视图、细节研究、动作、比例参考、栖息地 | 解剖结构、进化逻辑、轮廓区分 |
+| **architecture** | 外部、内部、街景、结构细节、废墟、景观 | 结构、材质一致性、透视、时代连贯性 |
+| **vehicle-mech** | 外部、驾驶舱、组件、示意图、轮廓图、损坏变体 | 机械逻辑、设计语言、访问点、损坏叙事 |
 
 ## 项目结构
 
@@ -94,21 +141,27 @@ 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
 ```
 
 ## 信任属性
 
-这些不是理想化的目标，而是强制执行的。
+这些不是理想化的，而是强制执行的。
 
-- **快照是不可变的。** 配置文件指纹（SHA-256）可以证明没有发生任何更改。
-- **分片可以防止数据泄露。** 按照身份、血统或 ID 后缀划分的主体类别永远不会跨越分区边界。
-- **清单是冻结的合同。** 导出哈希值 + 配置文件指纹。如果任何内容发生更改，请创建一个新的清单。
-- **适配器不能修改原始数据。** 不同的布局，相同的记录。不允许添加、删除或重新分类。
-- **生成的输出需要经过审核才能重新使用。** 不允许绕过。像其他内容一样，进行筛选和绑定。
+- **快照是不可变的。** 配置指纹（SHA-256）证明没有任何更改。
+- **分割可防止数据泄露。** 主题组（按身份、谱系或 ID 后缀划分）绝不会跨越分区边界。
+- **清单是固定的协议。** 导出哈希 + 配置指纹。如果发生任何更改，请创建一个新的。
+- **适配器不能改变真相。** 不同的布局，相同的记录。没有添加、删除或重新分类。
+- **生成的输出通过审核后重新进入。** 没有绕过机制。像其他所有内容一样进行整理和绑定。
 
-## Star Freight
+## 星际货运
 
-该仓库包含一个完整的示例：1182 条记录，5 个派系，7 条路线，24 条宪法规则，892 个已批准的资源，2 个训练配置文件。这是一个充满科幻感的角色扮演游戏视觉素材库，经过完整的筛选。
+该仓库包含一个完整的示例：1,182 条记录、5 个派系、7 条路线、24 条宪法规则、892 个已批准的资产、2 个训练配置文件。这是一个充满细节的科幻 RPG 视觉规范，经过全面整理。
 
 ```bash
 git clone https://github.com/mcp-tool-shop-org/style-dataset-lab
@@ -120,7 +173,7 @@ sdlab split build --project star-freight       # zero subject leakage
 
 ## 下游格式
 
-`sdlab` 拥有数据集。格式转换由 [`repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset) 处理：支持 TRL、LLaVA、Qwen2-VL、JSONL、Parquet 等格式。`repo-dataset` 用于渲染，但不决定数据的包含与否。
+`sdlab` 拥有数据集。格式转换由 [`repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset) 处理：TRL、LLaVA、Qwen2-VL、JSONL、Parquet 等。`repo-dataset` 进行渲染；它不会决定是否包含。
 
 ## 安装
 
@@ -128,11 +181,71 @@ sdlab split build --project star-freight       # zero subject leakage
 npm install -g @mcptoolshop/style-dataset-lab
 ```
 
-需要 Node.js 20+ 以及安装在本地主机 8188 端口上的 [ComfyUI](https://github.com/comfyanonymous/ComfyUI) 才能进行生成。
+需要 Node.js 20+ 和本地主机上的 [ComfyUI](https://github.com/comfyanonymous/ComfyUI)，地址为：8188，用于生成。
+
+### 不使用 ComfyUI 进行尝试
+
+您可以使用捆绑的“星际货运”项目来探索完整的非生成表面——检查、整理、快照、分割、导出——而无需安装 ComfyUI 或下载任何 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` 会验证每个项目的配置（宪法、路线、评分标准、术语），并在不触及 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
+```
+
+这两个命令都有效，因为每个插槽都会在其完成后以原子方式写入其清单条目——在运行过程中发生崩溃绝不会破坏部分状态。
+
+## 故障排除
+
+常见的失败模式和解决方法：
+
+**任何 `sdlab generate` / `sdlab run generate` / `sdlab batch generate` 命令中出现 `ECONNREFUSED 127.0.0.1:8188`**
+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`——五个 JSON 配置文件中的一个未能通过模式验证。`hint` 字段指定了错误的 文件和字段。
+- `E_RECORD_DRIFT`——某个记录的配置指纹不再与其来源匹配。如提示所述，重新整理或重新绑定。
+
+**`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 版本 (`sdlab --version`)、Node 版本 (`node -v`)、完整的命令以及结构化的错误输出。一个错误报告模板会预填充这些字段。
 
 ## 安全性
 
-仅在本地运行。没有遥测数据，没有分析，没有外部请求。图像保留在您的 GPU 和文件系统中。
+仅限本地使用。没有遥测、分析或外部请求。图像保留在您的 GPU 和文件系统中。
 
 ## 许可证
 
@@ -140,4 +253,4 @@ MIT
 
 ---
 
-由 <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a> 构建。
+由 <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a> 构建