EnragedAntelope · Oct 9, 2026 · Oct 8, 2026 · Oct 8, 2026 · Oct 8, 2026 · Oct 9, 2026
diff --git a/.env.example b/.env.example
@@ -19,7 +19,8 @@ GROQ_API_KEY=
 
 # Built-in SAM3 subject isolation (gated model): accept the license at
 # https://huggingface.co/facebook/sam3 then create a READ token at
-# https://huggingface.co/settings/tokens
+# https://huggingface.co/settings/tokens (HUGGINGFACE_API_KEY in the environment works too, when
+# there is no HF_TOKEN and no `hf auth login`)
 HF_TOKEN=
 
 # --- Optional overrides (defaults shown) ---

diff --git a/AGENTS.md b/AGENTS.md
@@ -6,11 +6,11 @@ Turn a character, style, or concept into a ready-to-train LoRA dataset. One refe
 
 ## Current state
 
-_Last verified: 2026-10-08_
+_Last verified: 2026-10-09_
 
-- **Status:** in active development; main is v0.19.0 (git tag `v0.19.0`). **Every version bump must ship a GitHub Release** or the in-app update check never fires. The project was renamed twice (lora-dataset-studio → lora-distillery → dataset-deviser); older references under the previous names are stale.
-- **Works:** all five stages end to end (preprocess → generate & curate → caption → export → train config); the three dataset types (character, style, concept) with their own shot plans and caption framing; local and cloud paths for every stage; gallery curation with selection carried forward between stages, including shift-click range select; advisory dedupe, quality flags and caption lint; trainer configs for ai-toolkit (incl. SDXL), kohya sd-scripts, musubi-tuner and Fizgig; opt-in private Hugging Face publish. Since 0.15.0: per-image fault isolation in ① (one bad source never ends the batch), a cooperative ⏹ Stop across ①/②/③ with documented resume paths, translated ComfyUI failures (missing node, bad input, unreachable server) and an in-app 🩺 setup check. Since 0.15.1: a ② **shot style** (default = keep the reference's own medium; eight presets + custom text) threaded into both prompt builders, the CLI, ④ metadata and ⑤'s sample prompt, a final-prompt preview, and a prev/next/save-and-next caption editor with the image on screen. Since 0.16.0: **one name box and one trigger box in the header** that ②/③/④/⑤ all read (they used to be per-tab and went stale), ④ stating the pair it stamped, an opt-in ④ **hand-off to [Idiot LoRa Builder](https://github.com/Fablestarexpanse/Idiot-Lora-Builder)** (writes its `.lora-studio/ratings.json` so its grid opens pre-triaged — nothing is launched), a ⑤ advisory when the dataset can't fill the training resolution, every bundled ComfyUI model filename overridable from `.env`, and a `cli build` preflight for the local engine. Since 0.17.0: the local ② engine is **Qwen-Image 2.1** (plain-English prompts shared with Gemini, ~26 s/shot, `LDS_QWEN21_*` filenames) instead of Qwen-Image-Edit 2511 + the Multiple-Angles LoRA, whose graph stays in `studio/comfy_workflows/legacy/`; a dead ComfyUI mid-batch now fails one shot, not the run. Since 0.17.1: the UI port is chosen by `_pick_port` in `app.py` — 7861 if bindable, else an OS-assigned free port (Windows reserves a ~500-port block around 7861), or `LDS_PORT` to pin one. Since 0.17.2: `comfy_api.upload_image` downscales a source over 90 MB before upload (ComfyUI answers 413 above its 100 MB `--max-upload-size`). Since 0.17.3: the cloud image model defaults to **`auto`** (Google shut down the `-preview` ids on 2026-06-25; `resolve_image_model` picks from the cached live list, Nano Banana 2.1 first), Groq captions use `qwen/qwen3.8-27b` (key `groq-qwen`, old key aliased), every API image goes through `config.api_image` (true mime, size cap), musubi commands include the cache steps and the per-architecture network module, ai-toolkit gains Qwen-Image 2.1 and a correct Krea 2 (Raw) preset and keeps every checkpoint, ① applies EXIF rotation, no longer 4x-upscales large JPEGs, and can jump a busy ComfyUI queue like ② (`--front` on `preprocess`/`build`). Since 0.18.0: ⑤ counts **epochs** (one checkpoint and one sample set each) with auto repeats sized to a step target and a live exposure line; every config ships a `validation/` pack (8 fixed prompts at seed 42, `validation.md`, a per-epoch score sheet); **Fizgig** is a ⑤ target (Krea 2 / Qwen Image 2.1 / Klein); ① stamps a `dd_source` provenance PNG chunk so ⑤ names upscaled sources and ④ knows real photos; ④ can hold out N real photos in a `-heldout` sibling as a likeness test. Since 0.18.1: a ⑤ optimizer dropdown, AdamW8bit by default, Prodigy (lr 1.0, its diffusion args) for ai-toolkit/musubi/kohya; Fizgig stays AdamW8bit. Since 0.19.0: ① training copies **keep their background** and the isolated copy goes to `prepped/refs/` for ② only (angle re-isolation is its own ② option, off); a header **identity policy** for characters (Identity only varies outfits and captions clothing; Signature costume keeps the outfit out of captions); four framing tiers in the shot plan and a ② coverage line with a dominance warning; a cut-off-reference warning; ② near-duplicate finder and primary-reference preview, ④ burst grouping; local ② sends several references (`LDS_QWEN21_MAX_REFS`, default 1) at `LDS_QWEN21_RESOLUTION` (1536); Gemini gets a per-shot aspect and a reference cap; an opt-in **anchor shot**; SAM3 load errors name a stale `HF_TOKEN`.
-- **In progress:** a phased LoRA best-practice update. 0.20.0 is next: a ⚡ Quick build tab and `cli build` on shared `pipeline.build_start`/`build_finish`. Nothing from it is half-built on main. The attention-only toggle planned for 0.18.0 was deferred (ARCHITECTURE.md → Future ideas).
+- **Status:** in active development; main is v0.20.0 (git tag `v0.20.0`). **Every version bump must ship a GitHub Release** or the in-app update check never fires. The project was renamed twice (lora-dataset-studio → lora-distillery → dataset-deviser); older references under the previous names are stale.
+- **Works:** all five stages end to end (preprocess → generate & curate → caption → export → train config); the three dataset types (character, style, concept) with their own shot plans and caption framing; local and cloud paths for every stage; gallery curation with selection carried forward between stages, including shift-click range select; advisory dedupe, quality flags and caption lint; trainer configs for ai-toolkit (incl. SDXL), kohya sd-scripts, musubi-tuner and Fizgig; opt-in private Hugging Face publish. Since 0.15.0: per-image fault isolation in ① (one bad source never ends the batch), a cooperative ⏹ Stop across ①/②/③ with documented resume paths, translated ComfyUI failures (missing node, bad input, unreachable server) and an in-app 🩺 setup check. Since 0.15.1: a ② **shot style** (default = keep the reference's own medium; eight presets + custom text) threaded into both prompt builders, the CLI, ④ metadata and ⑤'s sample prompt, a final-prompt preview, and a prev/next/save-and-next caption editor with the image on screen. Since 0.16.0: **one name box and one trigger box in the header** that ②/③/④/⑤ all read (they used to be per-tab and went stale), ④ stating the pair it stamped, an opt-in ④ **hand-off to [Idiot LoRa Builder](https://github.com/Fablestarexpanse/Idiot-Lora-Builder)** (writes its `.lora-studio/ratings.json` so its grid opens pre-triaged — nothing is launched), a ⑤ advisory when the dataset can't fill the training resolution, every bundled ComfyUI model filename overridable from `.env`, and a `cli build` preflight for the local engine. Since 0.17.0: the local ② engine is **Qwen-Image 2.1** (plain-English prompts shared with Gemini, ~26 s/shot, `LDS_QWEN21_*` filenames) instead of Qwen-Image-Edit 2511 + the Multiple-Angles LoRA, whose graph stays in `studio/comfy_workflows/legacy/`; a dead ComfyUI mid-batch now fails one shot, not the run. Since 0.17.1: the UI port is chosen by `_pick_port` in `app.py` — 7861 if bindable, else an OS-assigned free port (Windows reserves a ~500-port block around 7861), or `LDS_PORT` to pin one. Since 0.17.2: `comfy_api.upload_image` downscales a source over 90 MB before upload (ComfyUI answers 413 above its 100 MB `--max-upload-size`). Since 0.17.3: the cloud image model defaults to **`auto`** (Google shut down the `-preview` ids on 2026-06-25; `resolve_image_model` picks from the cached live list, Nano Banana 2.1 first), Groq captions use `qwen/qwen3.8-27b` (key `groq-qwen`, old key aliased), every API image goes through `config.api_image` (true mime, size cap), musubi commands include the cache steps and the per-architecture network module, ai-toolkit gains Qwen-Image 2.1 and a correct Krea 2 (Raw) preset and keeps every checkpoint, ① applies EXIF rotation, no longer 4x-upscales large JPEGs, and can jump a busy ComfyUI queue like ② (`--front` on `preprocess`/`build`). Since 0.18.0: ⑤ counts **epochs** (one checkpoint and one sample set each) with auto repeats sized to a step target and a live exposure line; every config ships a `validation/` pack (8 fixed prompts at seed 42, `validation.md`, a per-epoch score sheet); **Fizgig** is a ⑤ target (Krea 2 / Qwen Image 2.1 / Klein); ① stamps a `dd_source` provenance PNG chunk so ⑤ names upscaled sources and ④ knows real photos; ④ can hold out N real photos in a `-heldout` sibling as a likeness test. Since 0.18.1: a ⑤ optimizer dropdown, AdamW8bit by default, Prodigy (lr 1.0, its diffusion args) for ai-toolkit/musubi/kohya; Fizgig stays AdamW8bit. Since 0.19.0: ① training copies **keep their background** and the isolated copy goes to `prepped/refs/` for ② only (angle re-isolation is its own ② option, off); a header **identity policy** for characters (Identity only varies outfits and captions clothing; Signature costume keeps the outfit out of captions); four framing tiers in the shot plan and a ② coverage line with a dominance warning; a cut-off-reference warning; ② near-duplicate finder and primary-reference preview, ④ burst grouping; local ② sends several references (`LDS_QWEN21_MAX_REFS`, default 1) at `LDS_QWEN21_RESOLUTION` (1536); Gemini gets a per-shot aspect and a reference cap; an opt-in **anchor shot**; SAM3 load errors name a stale `HF_TOKEN`. Since 0.20.0: a **⚡ Quick build** tab (first tab: drop images, name, Cloud or Local, trainer; Build runs ①→②, untick, Finish runs ③→④→⑤) and `cli build` share `pipeline.build_start`/`build_finish`, and `cli build` writes ⑤ configs with `--trainer/--model`; a failed isolation keeps the photo and gives ② the whole image; builtin SAM3 retries `person` on real photos; a ComfyUI job's timeout no longer runs while it waits in the queue; `HUGGINGFACE_API_KEY` stands in when there is neither an `HF_TOKEN` nor an `hf auth login`; a caption that opens with the name in another case (`Ann` for trigger `ann`) now opens with the trigger's exact casing; `cli build` and Quick build Finish show ⑤'s undersized/upscaled warnings.
+- **In progress:** nothing half-built on main. The phased LoRA best-practice update (0.17.3–0.20.0) is complete; the optional local face model (drift flag, verified coverage) awaits a go-ahead. The attention-only toggle planned for 0.18.0 was deferred (ARCHITECTURE.md → Future ideas).
 - **Known gaps / next steps:** Auto's model order (`IMAGE_MODEL_PREFERENCE`, Nano Banana 2.1 then Pro) rests on one A/B subject — see ARCHITECTURE.md; the local defaults (one reference, 1536, anchor off) likewise rest on one A/B subject. Otherwise pick up from `docs/ARCHITECTURE.md` → "Future ideas" / "Deferred", and read its *Maintainer principles* before changing anything; `gradio` is pinned `<6` because of a real stuck-loading-overlay regression — unpinning needs that verified fixed upstream; training is never launched for you and is not planned to be; the default export `output_root` writes into the repo root, so a smoke-test export leaves an untracked dataset folder to delete before committing.
 - **Deep docs:** `docs/ARCHITECTURE.md` (module map, stage and backend detail, gotchas, backlog — the deep reference), `docs/comfyui-setup.md`. Worklogs under `docs/` are gitignored and local-only by design.
 
@@ -28,7 +28,7 @@ _Last verified: 2026-10-08_
 
 | File / Directory | Purpose |
 |------------------|---------|
-| `app.py` | Gradio UI — thin wiring over stage functions (5 tabs) |
+| `app.py` | Gradio UI — thin wiring over stage functions (⚡ Quick build + 5 stage tabs) |
 | `cli.py` | Typer CLI — one subcommand per stage + `build`, `doctor`, `keys`, `custom-endpoint` |
 | `setup.bat` / `setup.sh` | One-time install: Python gate, venv, GPU/CPU torch, requirements, ONNX, keys, doctor |
 | `start.bat` / `start.sh` | Launch the UI |

diff --git a/README.md b/README.md
@@ -39,7 +39,17 @@ ai-toolkit, kohya, musubi or Fizgig, and a validation pack for picking the best
 
 **① Preprocess → ② Generate & curate → ③ Caption → ④ Export → ⑤ Train config**
 
-Run them in order (each step auto-fills the next) or jump straight to the one you need.
+New to this? Use the **⚡ Quick build** tab: drop your images, type a name at the top, pick Cloud
+or Local and a trainer, press **Build**. Untick any shot that looks wrong and press **Finish**: you
+get the captioned dataset, the trainer config with its run command, and the validation pack.
+Name anything the subject is holding (*"cup, plate"*) so it isn't redrawn in every shot. If a
+shadow or object crosses the face in your best photo, pick Cloud: Local tends to copy it into
+the generated shots, Cloud draws a clean face. Photos
+① had to enlarge a lot start unticked (they still guide generation). The trigger is made from
+the name if you leave it blank.
+
+The numbered tabs run the same steps one at a time, with every option. Run them in order (each
+step auto-fills the next) or jump straight to the one you need.
 
 | Stage | Local | Cloud |
 |---|---|---|
@@ -257,6 +267,8 @@ python cli.py generate ./prepped/refs --name "Sy Snootles" --engine comfyui
 python cli.py generate ./prepped/refs --name "Sy Snootles" --identity costume  # outfit is the character
 python cli.py generate ./prepped/refs --name "Sy Snootles" --shot-style anime  # keep an illustrated look
 python cli.py generate ./prepped/refs --name "brass compass" --dataset-type concept  # 18-shot object set
+python cli.py build ./photos --name "Ann Lee" --trigger annlee --exclude-prompt "cup" \
+  --trainer ai-toolkit --model krea                                       # everything, plus ⑤
 python cli.py caption ./folder --trigger sysnootles                       # prose sidecars
 python cli.py caption ./folder --trigger sysnootles --caption-style tags  # Danbooru tags
 python cli.py caption ./folder --trigger mystyle --dataset-type style     # style-framed
@@ -278,7 +290,7 @@ Set or change any of them with `python cli.py keys` — they live only in a giti
 
 - **Gemini** — image generation and/or captioning: <https://aistudio.google.com/apikey>
 - **Groq** — free-tier captioning: <https://console.groq.com/keys>
-- **Hugging Face** (`HF_TOKEN`) — two uses:
+- **Hugging Face** (`HF_TOKEN`, or `HUGGINGFACE_API_KEY` in the environment when you have no `hf auth login`) — two uses:
   - **Built-in SAM3 isolation.** `facebook/sam3` is **gated**: accept the licence on the
     [model page](https://huggingface.co/facebook/sam3), wait for approval, then add a **read**
     token. Weights (~3.4 GB) download once.