@mcptoolshop/style-dataset-lab 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.2.0] - 2026-04-14
+
+- Added `templates/` with blank constitution, review rubric, and example prompt pack
+- npm package now ships scripts + templates only (zero game data)
+- Fixed game data leak in v1.0.0/v1.1.0 npm packages (games/ was included in tarball)
+- All docs reframed around the pipeline (canon, prompts, generate, curate, bind, compare, export)
+- README, handbook, and landing page updated for v1.2.0
+
 ## [1.1.0] - 2026-04-14
 
 - Monorepo restructure: each game lives in `games/<name>/` with isolated canon, records, and assets

package/README.md

@@ -13,105 +13,106 @@
 
 # style-dataset-lab
 
-Visual dataset factory -- generate, curate, and export multimodal training data for VLM fine-tuning.
+A production pipeline for visual dataset creation -- from canon rules to structured prompts to ComfyUI generation to curated, canon-bound training data.
 
 ## What this is
 
-A **monorepo** toolkit for building **trainable visual truth** across multiple games. Each game gets its own data directory; scripts are shared. Every asset carries three things:
+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).
+
+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:
 
 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
 
-The output feeds into [`@mcptoolshop/repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset) to produce multimodal training data in 10 formats: TRL, LLaVA, Qwen2-VL, Axolotl, LLaMA-Factory, ShareGPT, RLHF pairs, DPO, captioning, and classification.
-
 ## Security 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.
 
-## Dataset stats (Star Freight)
+## What the npm package ships
+
+`npm install @mcptoolshop/style-dataset-lab` gives you:
 
-The included `games/star-freight/` dataset ships with the repo as a working example:
+- **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/`
 
-| Metric | Value |
-|--------|-------|
-| Curated records | 1,182 |
-| Total assets | 2,571 (893 approved, 887 painterly variants) |
-| Prompt waves | 28 |
-| Visual categories | 18 (costumes, ships, interiors, equipment, environments, species, stations, signage, lighting, cargo, architecture, creatures, surfaces, daily life, planetary, damage/repair, alien biology, lived-in details) |
-| Pairwise comparisons | 6 human + 71 synthetic |
-| Distinct rejection types | 30+ |
-| Identity packet system | Named characters with faction DNA, rank, and visual anchors |
-| Export formats | 10 (via @mcptoolshop/repo-dataset) |
+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).
 
 ## Install
 
 ```bash
-# Install scripts globally (optional)
-npm install -g @mcptoolshop/style-dataset-lab
+# Get the pipeline scripts + templates
+npm install @mcptoolshop/style-dataset-lab
 
-# Clone the repo (includes star-freight game data)
+# 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
 ```
 
-To start a new game, create its directory structure:
+To start a new game from the templates:
 
 ```bash
-mkdir -p games/my-game/{canon,records,comparisons,inputs/prompts,outputs/{candidates,approved,rejected},exports}
+# 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
 ```
 
-Or use the existing `games/star-freight/` data to explore the workflow immediately.
-
 ## Monorepo structure
 
-Each game lives in `games/<name>/` with its own canon, records, and assets. Scripts are shared and accept `--game <name>` (defaults to `star-freight`).
+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`).
 
 ```
 style-dataset-lab/
-  scripts/                  Shared tooling (generate, curate, compare, etc.)
+  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 universe data
+    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)
-    fractured-road/         (add your next game here)
-      canon/
-      records/
-      ...
+    <your-game>/            Add more games with the same structure
 ```
 
-## Workflow
+## Pipeline workflow
+
+The full pipeline from canon to training export:
 
 ```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. Create prompt packs in inputs/prompts/
+#    (see templates/inputs/prompts/example-wave.json)
 
-# 2. Generate candidates from a prompt pack
+# 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
 
-# 3. Generate identity-packet characters
+# 4. Generate identity-packet characters (named subjects)
 npm run generate:identity -- --game star-freight inputs/identity-packets/wave27a.json
 
-# 4. Generate painterly variants of approved assets
-npm run painterly -- --game star-freight
-
 # 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"
 
-# 6. Bind canon explanations to assets
+# 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
 
-# 7. Record pairwise comparisons
+# 8. Record pairwise comparisons
 npm run compare -- --game star-freight <asset_a> <asset_b> a "A has better faction read"
 
-# 8. Export training data via repo-dataset
+# 9. Export training data via repo-dataset
 repo-dataset visual generate ./games/star-freight --format trl
 repo-dataset visual inspect ./games/star-freight
 ```
@@ -119,10 +120,13 @@ repo-dataset visual inspect ./games/star-freight
 ## Adding a new game
 
 ```bash
-mkdir -p games/my-game/{canon,records,comparisons,inputs/prompts,outputs/{candidates,approved,rejected},exports}
-# Write your canon/constitution.md and canon/review-rubric.md
-# Create prompt packs in inputs/prompts/
-# Then generate, curate, and export as above with --game my-game
+# 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
 ```
 
 ## Per-game directory layout

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mcptoolshop/style-dataset-lab",
-  "version": "1.1.0",
-  "description": "Visual dataset factory — generate, curate, and export multimodal training data for VLM fine-tuning",
+  "version": "1.2.0",
+  "description": "Visual dataset pipeline — canon to prompts to ComfyUI generation to curated, canon-bound training data",
   "type": "module",
   "scripts": {
     "generate": "node scripts/generate.js",
@@ -15,9 +15,7 @@
   },
   "files": [
     "scripts/",
-    "games/*/canon/",
-    "games/*/inputs/",
-    "package.json",
+    "templates/",
     "README.md",
     "LICENSE",
     "SECURITY.md",

package/templates/canon/constitution.md

@@ -0,0 +1,44 @@
+# Style Constitution
+
+> Define the visual rules that every generated asset must follow.
+> Each rule gets an ID, category, and description. The curation scripts score assets against these rules.
+
+## Core Rules
+
+### Silhouette & Shape Language
+
+- **SIL-01**: [Describe the silhouette requirements — what shapes define your style?]
+- **SIL-02**: [Describe faction/character shape differentiation]
+
+### Color & Palette
+
+- **COL-01**: [Describe the color rules — palette constraints, faction colors, mood]
+- **COL-02**: [Describe what colors are forbidden and why]
+
+### Material & Texture
+
+- **MAT-01**: [Describe material rules — worn vs clean, organic vs synthetic]
+- **MAT-02**: [Describe texture expectations — grit level, surface detail]
+
+### Composition & Framing
+
+- **CMP-01**: [Describe framing rules — camera angle, subject placement]
+
+### Mood & Atmosphere
+
+- **MOD-01**: [Describe the emotional tone — tense, serene, chaotic]
+
+## Scoring Dimensions
+
+Assets are scored 0.0–1.0 on each dimension during curation:
+
+| Dimension | What it measures |
+|-----------|-----------------|
+| silhouette | Shape language clarity and faction read |
+| palette | Color accuracy and mood alignment |
+| material | Surface texture and wear level |
+| composition | Framing and visual hierarchy |
+| mood | Emotional tone match |
+| detail | Level of meaningful detail |
+| consistency | Coherence with existing approved assets |
+| originality | Avoids generic/stock-art patterns |

package/templates/canon/review-rubric.md

@@ -0,0 +1,30 @@
+# Review Rubric
+
+## Quick Decision Tree
+
+1. Does the image pass the **style test**? (Would it look at home next to approved assets?)
+   - No → REJECT with cited rule violations
+2. Does it pass **all constitution rules** at ≥0.6 score?
+   - No → Check if fixable with img2img → BORDERLINE or REJECT
+3. Does it add **new signal** the dataset doesn't have?
+   - Yes → APPROVE
+   - No (duplicate composition/subject) → REJECT as redundant
+
+## Approval Criteria
+
+- All scoring dimensions ≥ 0.6
+- No critical rule violations
+- Adds value to the dataset (new subject, angle, or variation)
+
+## Rejection Criteria
+
+- Any scoring dimension < 0.4
+- Violates a core constitution rule
+- Too similar to existing approved assets
+- Generic/stock-art quality (no distinctive style)
+
+## Borderline Criteria
+
+- One or two dimensions between 0.4–0.6
+- Fixable with img2img post-processing
+- Strong composition but weak on style details

package/templates/inputs/prompts/example-wave.json

@@ -0,0 +1,27 @@
+{
+  "wave": "wave1",
+  "description": "First generation wave — core subjects for your visual style",
+  "defaults": {
+    "checkpoint": "dreamshaperXL_v21TurboDPMSDE.safetensors",
+    "lora": { "name": "classipeintxl_v21.safetensors", "weight": 1.0 },
+    "width": 1024,
+    "height": 1024,
+    "steps": 8,
+    "cfg": 2.0,
+    "sampler": "dpmpp_sde",
+    "scheduler": "karras",
+    "negative": "photorealistic, photograph, 3d render, smooth CG, sharp photo detail"
+  },
+  "subjects": [
+    {
+      "id": "subject_a",
+      "variations": 2,
+      "prompt": "oil painting, visible brushstrokes, [DESCRIBE YOUR SUBJECT HERE], painterly concept art, canvas grain"
+    },
+    {
+      "id": "subject_b",
+      "variations": 2,
+      "prompt": "oil painting, visible brushstrokes, [DESCRIBE YOUR SUBJECT HERE], painterly concept art, canvas grain"
+    }
+  ]
+}