Rework the README as a showcase, and put SWAP in the changelog

The page opened with ten version blockquotes -- roughly 145 lines of patch
notes, back to 0.4.1 -- before it said what the pack does. Somebody arriving
from the registry read four months of small updates first.

**The changelog is now one section at the bottom**, five short paragraphs
instead of ten quoted blocks, with the detail left in CHANGELOG.md where it
belongs. Above it, the page leads: what it gives you, install, the one law,
WRITE, SWAP, the tester's study, then the join and the tone anchor, and only
then a **Reference** section holding the shot-plan schema, directives,
register, media, cache, instruments, defaults, nodes and limits.

New sections:

- **SWAP.** It shipped in this release with no user-facing documentation
anywhere -- not in the README, and not one mention in CHANGELOG.md. Both
now carry the four modes and, more importantly, the two usage rules that
cost renders to establish: do not describe the clip on MEDIA before a swap
(that caption reaches the encoder as what `<Video 1>` IS, and naming a
person asks for the person being replaced), and drop the clip to about
0.3 MP, because a clip's decode area is its token count and its token
count is its influence.
- **Tested in public**, with @urlilgoddess 's scorecard and her
background-detail frames, published with her consent. Her ten-run nine-hop
study is why three of this release's behaviours exist, and her framing --
relay convergence with no content anchor -- explains why the scale knobs
did nothing better than ours did. The section also says plainly what she
could not fix and this release does not claim to: texture still ratchets,
3-5 hops is still the honest limit.
- **Credits**, naming @urlilgoddess , @frankyi and @Sean3884 of the Sulphur
discord alongside rkfg and Motion-Context.

CHANGELOG.md gains SWAP in all three of its lists -- the feature, what a GPU
confirmed, and what it has not. The wardrobe plate and the picture
background go in the unverified list: they could not have rendered before
the fix two commits ago, and that fix is covered offline, not on a GPU.

Both tester images are LFS-tracked (`docs/img/*.png`), so their URLs use
media.githubusercontent.com; the page has no raw.githubusercontent link.
Every image it references exists, every internal anchor resolves, and
nothing links to a README anchor that this rewrite removed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RVz8qNGn2NhrP3KG2Lh5yT

CHANGELOG.md

@@ -37,6 +37,38 @@ four new behaviours.
   for the register default (unscheduled stills on chain starts, off
   continuations). `[]` is none. A filled list is those tags only, in that
   order. Unknown tags fail on the queue.
+- **SWAP**, a fifth tab. A one-hop identity swap from a reference clip: the
+  clip supplies the motion and the scene, a still from the REFERENCES rail
+  supplies the person. **Write** drafts it, **Accept** writes exactly one
+  shot plus the clip's description and never touches `ref_plan` -- your
+  register is not rewritten. Contributed by @frankyi, then rebuilt from its
+  own prose rather than merged.
+
+  Four named modes, because at cfg 1.0 there is no negative branch and a
+  mode that merely *omits* the swap line does not keep the clip's person --
+  the identity photograph is in front of the encoder either way and governs
+  the subject anyway. Each mode says positively what stays:
+  `replace_person` (face, build, hairstyle and wardrobe),
+  `head_swap` (face, hair and skin tone; the body, posture, hands and every
+  garment stay with the clip), `face_only` (features only), and
+  `keep_person` (swaps nobody -- the clip is a scene and motion plate, and
+  the identity picker greys out). The taxonomy follows PromptMasterLD's edit
+  laws; the prose is written fresh for H3 beats.
+
+  Alongside them: **background** from the clip, from a `@tag` picture, or
+  free; and an optional **wardrobe plate**, a `@tag` whose garment is *worn*
+  -- draping on the body in frame and creasing where it bends -- rather than
+  pasted.
+
+  **Two things to get right, both of which cost renders to find out.** Do
+  not run MEDIA's describe on the clip before a swap: that caption reaches
+  the encoder as what `<Video 1>` *is*, and a caption naming a person asks
+  for the person you are replacing. Four consecutive "head swap doesn't
+  work" reports traced to that, a missing frame sequence and a weak
+  citation -- no broken code among them. SWAP now warns when a caption names
+  somebody. And drop the clip to about 0.3 MP: a reference clip's decode
+  area is its token count, and its token count is its influence, so a
+  full-size plate out-argues a single photograph.
 
 ### Already on the 1.2 tree, now in the release
 
@@ -80,6 +112,9 @@ take it; a third-party node that assumes fp32 has not been tested against it.
 - `last_frame_guide` turns the restart jump into a match cut, and `still`
   fights an authored framing as described above.
 - fp16 survives delivery.
+- SWAP `head_swap` on a 0.3 MP clip with no clip caption: the head is
+  replaced, the body and its motion stay with the clip, and no colour or
+  hair from the plate bleeds through.
 
 ### Still not verified
 
@@ -89,6 +124,10 @@ take it; a third-party node that assumes fp32 has not been tested against it.
 - Anything longer than 4 hops at 8 s. The texture ratchet is unchanged and
   3-5 hops is still the honest limit.
 - Three reference clips or three voices at once, on a card.
+- SWAP's wardrobe plate and picture background. Both were cited-but-not-
+  scheduled until the fix in this release and could never have rendered;
+  the fix is covered offline, not on a GPU. `face_only` and `keep_person`
+  have not been run either.
 
 Saved 1.1 workflows load. New widgets were appended, not inserted, and no
 existing default changed.

README.md

@@ -13,7 +13,9 @@ tags:
 
 # Hand Tie Clips
 
-One node. Write a shot plan, drop in your reference stills, queue.
+**Multi-hop MiniMax H3 video from one node.** Write a shot plan, drop in your
+reference stills, queue. The pack's whole job is the *join* — the place where
+one generation ends and the next begins.
 
 ![Six consecutive frames across a join](https://media.githubusercontent.com/media/dntpi/ComfyUI-Hand-Tie-Clips/main/docs/img/seam-frames.png)
 
@@ -21,225 +23,78 @@ One node. Write a shot plan, drop in your reference stills, queue.
 is the last frame the first generation produced and the next is the first frame
 of a second, separate generation. The pack exists so that you cannot tell which.*
 
-> **Renamed 2026-08-29.** This pack was `ComfyUI-H3-Ref-Chain`. The nodes now
-> live under the **Hand Tie Clips** category and register as `HandTieClips`,
-> `HTCChainPreview`, `HTCToneCompensate` and `HTCContinuityState`. The old ids
-> are still registered as deprecated aliases, so **every workflow saved before
-> the rename keeps loading** — they are just hidden from node search. Nothing
-> needs migrating.
-
-> **2.0.0 — 2026-09-05.** Full release. One continuous take every hop can
-> lip-sync to (`master_audio_file`, empty = off). An opt-in last-frame
-> AddGuide (`last_frame_guide`) pins `start_image` at a hop's last pixel;
-> default `off`, recommended `before_restart` (only the hop before an
-> `anchor: restart`, so the cut meets on one image). `still` plants it on
-> every hop and fights an authored `framing`. `anchor: "restart"` is a
-> chain start and now writes its full length instead of dropping 0.9 s of
-> new content. A shot can name which stills ride it (`refs`); omitted is
-> the register default, `[]` is none. `tone_anchor_ref=still` holds the
-> photograph rather than hop 1, which already missed it. Three
-> reference-clip slots, three voice slots, `pin_mech`, and a hop cache
-> that no longer pickles. New widgets were appended, so saved 1.1 graphs
-> keep their values. What a GPU has not confirmed yet is named in
-> [`CHANGELOG.md`](CHANGELOG.md).
-
-> **0.4.1 — 2026-08-30.** The 0.4.0 feature set was built without a browser or a
-> GPU and verified offline only. It has now been run in ComfyUI, and two things
-> were broken: the five new dials were never added to the run panel's widget list
-> (they worked, but rendered as raw dials on the node body), and a dry run
-> returned a 1×1 placeholder image that **libx264 cannot encode** — so every dry
-> run wired to `SaveVideo`, which is what the Starter ships, died in
-> `avcodec_open2`. Both fixed. The Starter now also ships the seam report wired.
-> Measurements are in [`docs/DEVLOG.md`](docs/DEVLOG.md) section 21.
-
-> **0.4.4 — 2026-08-30.** Two local models were given `prompt_pack/SYSTEM_PROMPT.md`
-> and the same scene, and both made the same two mistakes — so both were the
-> prompt's fault, not theirs. The register example had no place tag in it, so
-> each model invented its own convention (`kitchen_plate`) while leaving
-> `@kitchen` in the beat, and the run stopped on an unknown reference. One model
-> also wrote `"name": "@cook_face"` into `subjects`, which parsed, rendered, and
-> quietly put a literal at-sign in front of the text encoder on every
-> continuation hop. The prompt now shows a place tag on both sides of the round
-> trip and says the two spellings are one string; `refs.py` now rejects an
-> `@tag` in `name`, `locked` or `context` instead of encoding it. The RUN panel
-> also has its tooltips back — it read them from `widget.options`, where this
-> frontend does not keep them. Section 22 of the devlog has the A/B.
-
-> **0.4.5 — 2026-08-30.** The hop cache no longer needs `ffmpeg` on PATH. It
-> used to shell out to an ffmpeg binary to write its lossless FFV1, so the
-> feature that makes a tone A/B cost 14 seconds instead of 164 raised a
-> `RuntimeError` for anyone who did not happen to have ffmpeg installed —
-> which ComfyUI itself never requires. It now encodes in process through PyAV,
-> which ComfyUI already depends on. **The format is unchanged** (ffv1 /
-> `rgb48le` / level 3), verified bit-exact in both directions, so caches
-> written by the old path still read and a resumed chain still matches an
-> uninterrupted one. This also clears the Comfy registry's security scan, which
-> flags any spawn of an external command from a custom node regardless of how
-> it is invoked. Section 23 of the devlog.
-
-> **1.0.0 — 2026-09-02.** First full release. The headline is **WRITE**: a plan
-> writer on the node itself, pointed at any OpenAI-compatible server, that fills
-> the script and the reference rows together and sends your reference pictures
-> with the request. Around it, the parts that make a written plan survive
-> contact with the model — the schema the server is handed now *requires* both
-> documents, so a reply carrying only half of one stopped being a silent
-> failure; the reference rail owns each picture's pixel budget, which a plan
-> used to reset to full and quietly triple the load against a fixed canvas; and
-> the writer is told the hop length, so beats are sized to the clip instead of
-> to a guess. Three plan lints were measured against real renders and found to
-> be warning about correct work — a restated framing read as a cut, a
-> single-room chain read as an abandoned location — and were narrowed. Rule 3
-> of the prompt pack grew the case that cost the most renders: a hop that
-> speaks *later* has opening seconds with a picture and no sound assigned, and
-> the model fills them with dialogue nobody wrote. Ending the previous hop
-> quiet buys a quiet pin, not a quiet opening. Sections 31 and 32 of the devlog
-> have the measurements.
-
-> **1.1.1 — 2026-09-05.** Fixes a crash on hop 1 for anyone whose ComfyUI
-> orders `MiniMaxH3ReferenceToVideo`'s parameters differently from the build
-> this was written against — reported as `got multiple values for argument
-> 'ref_image_size'`, with nothing sampled and nothing written. The pack was
-> passing Core's first seven arguments positionally; it now passes every
-> argument by name at all three Core call sites, so a reordering upstream
-> cannot rebind anything. If a future Core changes the parameter *names*, the
-> pack now says which node, which arguments it passed and which the installed
-> Core takes, instead of raising a bare `TypeError`. No behaviour changes.
->
-> **1.1.0 — 2026-09-03.** The panel is a 4:3 box with tabs instead of one long
-> scrolling column, and RUN stays pinned at the bottom. The **WRITE** draft is
-> readable — it used to clip every beat at 110 characters and throw away the
-> duration, seed, directives and per-shot references before rendering, so what
-> you were asked to Accept was a row of sentences ending in an ellipsis — and it
-> now survives leaving the tab or reloading the page. Shot cards carry `⏵` and
-> `lock` buttons driving `render_from` / `render_through`, the new one being the
-> other end of a range `render_through` has had since 0.4: everything before the
-> start is replayed from the hop cache rather than re-rendered.
->
-> The bug worth upgrading for: **a reference pinned to any hop but the first
-> tended to be rendered as the shot.** `retention_analysis:` — the text that
-> tells the encoder what a picture is *for* — was emitted on hop 1 only, so a
-> still scheduled onto hop 3 arrived uncited; and the identity lock never read
-> `retention`, so a wardrobe plate carrying a subject was announced as *"the
-> only identity … that face, bone structure, and hairstyle match the photograph
-> exactly"* about a photograph of an apron, while the closer simultaneously said
-> clothing follows the live frame. Both fixed. The reference *clip* had the same
-> gap — it went in as `<Video 1>` with nothing naming it — and now has a
-> description field.
->
-> Output size is computed rather than tabulated: eleven aspect ratios from 21:9
-> to 9:21 across five short-edge tiers, every one on H3's 32 px grid and under
-> its 768×1344 cap. H3 is a 768-short-edge model, so **the top rung is 768p and
-> 16:9 there is 1344×768** — the size MiniMax states as native, and the same
-> number core's own `adapt_canvas` produces. The hop cache invalidates once
-> because of it. Saved 1.0.x workflows keep the
-> exact pixels they were built with. And changing a reference picture now
-> re-renders only the hops that picture rides, instead of the whole chain.
-
-> **1.0.1 — 2026-09-02.** Three fixes, all found by the first people to use
-> 1.0.0. The **WRITE** panel never saved your model on a fresh install: with
-> nothing stored, no entry in the dropdown was ever *selected* and the browser
-> simply displayed the first one, so the panel showed a model the backend had
-> never been told about. That one empty string produced every symptom — WRITE
-> answering *no model is selected*, Just-In-Time loading never firing because
-> nothing was ever asked of the server, and Free VRAM working anyway, which
-> made it stranger still. Underneath it, a failed write of `htc_llm.json` was
-> swallowed and reported as success, so a pack folder the ComfyUI account
-> cannot write to — a system-wide install, a container — gave the same
-> complaint from a different cause with the evidence in a console nobody
-> reads; it now says so. And writing a plan no longer spends attempts on
-> filenames: your photographs are named by the camera, a model that has just
-> looked at one renames it after the tag you gave it, and the node rejected the
-> whole plan over a value the rail was already holding. Worse, a filename
-> complaint is not a prose gap, so it suppressed the repair that actually works
-> for a full round. Sections 34 and 35 of the devlog.
-
-**Writing for it:** [PROMPTING.md](PROMPTING.md) is the authoring guide — the rules that come from what this model actually does, not from taste. The node's **WRITE** bar hands the whole job to a local model: describe the scene in a sentence and it fills the script and the reference rows for you. [prompt_pack/](prompt_pack/) is the same writer as a copy-paste prompt, for when you would rather work in a chat window.
-
-Each hop is native **MiniMax H3 Reference-to-Video**. Hops after the first are guided by the **previous hop's sampler AV latent** via `ComfyUI-H3-Motion-Context` when that pack is installed (22 picture frames + 24-frame end-aligned audio). Stock `MiniMaxH3AddGuide` is the fallback when Motion-Context is missing or the previous hop was a pixel cache hit. Voice rides every hop under `hop_script=verbatim`; under `next` — which a shot plan forces, so it is the default path whenever you use SHOTS — the voice is a hop 1 reference only, and the console says `voice ref stays off this continue` when it drops. Identity stills ride hop 1; later hops use the pin for wardrobe and room unless a ref lists those hops in `shots`. A 5 s hop drops the airlock on a continuous join — validate seams at 8 s or 15 s.
-
-This is not the seamless-chain pack. No airlock script, no Motion-Context, no interior patch.
-
-## What v1.0 changed
-
-The prompt is no longer a wall of `---`-delimited text, and the MODEL wire is no longer four extra nodes.
+Each hop is native **MiniMax H3 Reference-to-Video**. Hops after the first are
+guided by the previous hop's sampler AV latent through
+[ComfyUI-H3-Motion-Context](https://github.com/NikoDemon80/ComfyUI-H3-Motion-Context)
+when it is installed; stock `MiniMaxH3AddGuide` is the fallback, and the console
+says which one each hop took.
+
+---
+
+## What it gives you
 
 | | |
 |---|---|
-| **`shot_plan`** | The script, as JSON. One shot per hop — **the shot count is the hop count**, so `chains` can no longer disagree with it. |
-| **`directives`** | `join` / `camera` / `framing` / `pace` / `tail` per shot, compiled to vetted prose. Improving a phrase improves every plan you have ever written. |
-| **`ref_plan`** | Stable `@tags` for reference stills, grouped into subjects, each naming a picture file. Removing one can no longer silently renumber `<Picture N>`. |
-| **`cache_hops`** | Lossless per-hop cache. Re-roll one shot, resume after a crash, and hold roughly one hop in RAM instead of the whole clip. Edit hop 5 of 8 and only 5-8 re-render. [How to use it](PROMPTING.md#re-rolling-one-hop). |
-| **`WRITE`** | A plan writer on the node. Point it at any OpenAI-compatible server — LM Studio, llama-server — describe the scene in plain language, and it fills the script and the reference rows, reading the pictures you have already dropped in. Server settings stay on your machine, never in the workflow. |
-| **the editor** | Cards on the node, not JSON in a textarea. Hover any directive to read the exact sentence it puts in the prompt, or hit **Templates** for a ready-made pattern. |
+| **One node, five tabs** | SCRIPT, REFS, MEDIA, WRITE and SWAP on the node body. No `Load Image` chains, no JSON in a textarea. |
+| **A shot plan** | One card per hop — the shot count *is* the hop count. Beat, duration, seed, and five directive axes compiled to vetted prose. |
+| **A reference register** | Stable `@tags` for your stills, grouped per subject, each with a retention rule and its own pixel budget. Pulling one out of the middle no longer renumbers `<Picture N>`. |
+| **WRITE** | A plan writer on the node. Point it at any OpenAI-compatible server, describe the scene in a sentence, and it fills the script *and* the reference rows — reading the pictures you already dropped in. |
+| **SWAP** | One-hop identity swap from a reference clip. Four named modes, so what *stays* with the clip is stated rather than left to omission. |
+| **A lossless hop cache** | Re-roll shot 5 of 8 and only 5–8 re-render. Resume after a crash. Hold about one hop in RAM instead of the whole film. |
+| **A lip-sync lock** | `master_audio_file` — one continuous take every hop locks to, delivered as a passthrough. |
+| **Instruments** | Dry run, contact sheet, seam report and a live preview panel, so you can find the hop that broke without scrubbing the file. |
 
-Simple mode keeps the old one-prompt workflow; the speed stack (LoRAs, AdaLN fix, low-VRAM, SLA) stays as four ordinary nodes on the MODEL wire, where you can see it.
+---
 
 ## Install
 
-### Clone it (recommended)
-
 From your `ComfyUI/custom_nodes/` folder:
 
 ```
-cd ComfyUI/custom_nodes
 git clone https://github.com/dntpi/ComfyUI-Hand-Tie-Clips.git
 ```
 
-Or from HuggingFace, if that is where you found it -- the two are mirrors of the same repository and either is fine:
+Or from the HuggingFace mirror, which is the same repository:
 
 ```
 git clone https://huggingface.co/sandpies/ComfyUI-Hand-Tie-Clips
 ```
 
-Cloning creates the folder at the right depth for you, which is the mistake the zip route invites. **Updating later is then one command** from inside the pack folder:
-
-```
-git pull
-```
-
-followed by a restart of ComfyUI. No re-downloading, and you can see exactly what changed with `git log`.
-
-### Or unzip it
-
-Unzip the folder into `ComfyUI/custom_nodes/`, so that it lands as:
-
-```
-ComfyUI/custom_nodes/ComfyUI-Hand-Tie-Clips/
-    __init__.py
-    h3_ref_chain.py
-    js/
-    workflows/
-```
-
-One folder level too deep (`custom_nodes/ComfyUI-Hand-Tie-Clips/ComfyUI-Hand-Tie-Clips/`) is the usual mistake, and the pack simply will not appear.
-
-### Either way
+Cloning puts the folder at the right depth, which is the mistake the zip route
+invites — one level too deep
+(`custom_nodes/ComfyUI-Hand-Tie-Clips/ComfyUI-Hand-Tie-Clips/`) and the pack
+simply will not appear. Updating later is `git pull` and a restart.
 
-No dependencies to install. Everything it imports -- `torch`, `numpy`, `PIL`, `av`, `aiohttp` -- already ships with ComfyUI, which is why `dependencies` in `pyproject.toml` is empty.
+**No dependencies to install.** Everything it imports — `torch`, `numpy`,
+`PIL`, `av`, `aiohttp` — already ships with ComfyUI, which is why
+`dependencies` in `pyproject.toml` is empty.
 
-Then:
-
-1. **Restart ComfyUI.** Python changed.
-2. **Hard-refresh the browser** (Ctrl+Shift+R / Cmd+Shift+R). The editor is served from `/extensions/ComfyUI-Hand-Tie-Clips/`, and a stale cache is the single most common reason the node mounts with no UI on a fresh install.
+Then **restart ComfyUI** (Python changed) and **hard-refresh the browser**
+(Ctrl+Shift+R). The editor is served from
+`/extensions/ComfyUI-Hand-Tie-Clips/`, and a stale cache is the single most
+common reason the node mounts with no UI on a fresh install.
 
 It is installed correctly when all three are true:
 
 - the startup log carries a line beginning `[HandTieClips]`
 - the browser console says `[HandTieClips] editor ui v2.0.0 loaded`
-- node search shows a **Hand Tie Clips** category with five nodes, each listed once
-
-Workflows saved before the 2026-08-29 rename keep loading: the old ids are still registered as deprecated aliases. Nothing needs migrating.
+- node search shows a **Hand Tie Clips** category with five nodes, each once
 
-The two example graphs are in `workflows/` inside the pack folder -- open them with the **Workflow > Open** menu, or copy them into `ComfyUI/user/default/workflows/` to have them in the sidebar. Start with `HandTieClips_Starter.json`; it ships with no references on purpose, so it runs before you have supplied any pictures.
+Workflows saved before the 2026-08-29 rename keep loading — the old ids are
+registered as deprecated aliases. Nothing needs migrating.
 
 ## Needs
 
 - ComfyUI new enough to include **Add Guide for MiniMax H3** (`MiniMaxH3AddGuide`)
 - A **ref2va** (or hybrid ref2va) checkpoint — fl2va has no reference rows
 - Video VAE + audio VAE + MiniMax text encoder
-- **Optional but recommended:** [ComfyUI-H3-Motion-Context](https://github.com/NikoDemon80/ComfyUI-H3-Motion-Context). Hops after the first are guided by the previous hop's sampler AV latent through it. Without it the node falls back to stock `MiniMaxH3AddGuide`, which still works and still chains -- it is a different join, so a seam you are comparing against someone else's render may not be the same code path. The node detects it at runtime and prints which one it took.
+- **Recommended:** [ComfyUI-H3-Motion-Context](https://github.com/NikoDemon80/ComfyUI-H3-Motion-Context)
+  for the latent join. Without it the node falls back to `MiniMaxH3AddGuide`,
+  which still works and still chains — it is a different join, so a seam you
+  are comparing against someone else's render may not be the same code path.
 
-The two shipped workflows wire the **turbo stack** this node is actually run with, because an example without it is not the graph anyone uses:
+The two shipped workflows wire the **turbo stack** this node is actually run
+with, because an example without it is not the graph anyone uses:
 
 ```
 UNETLoader -> LoRA Loader Stack -> H3 AdaLN LoRA Fix -> MiniMax H3 Low VRAM
@@ -251,11 +106,23 @@ UNETLoader -> LoRA Loader Stack -> H3 AdaLN LoRA Fix -> MiniMax H3 Low VRAM
 | [ComfyUI-PlagueKind-Nodes](https://github.com/PlagueKind/ComfyUI-PlagueKind-Nodes) | LoRA Loader Stack, H3 AdaLN LoRA Fix, H3 SLA Attention |
 | [ComfyUI-KJNodes](https://github.com/kijai/ComfyUI-KJNodes) | MiniMax H3 Low VRAM Attention (experimental), Model Preview Override |
 
-On disk as well: the **turbo LoRA** named in the loader stack, and `taeh3.safetensors` for the live preview (or set `tiny_vae` to `none`).
+**CLIP reaches the node from the LoRA loader, not from the encoder** — that is
+what makes the text half of every LoRA land. Do not rewire it back.
+
+None of it is required by the node itself. Missing a pack, its nodes load as
+red boxes: delete them, wire the loader straight into `model` and the encoder
+into `clip`, and raise `steps` from 7 to around 20.
+
+Both shipped workflows are saved pointing at the exact quantised files they
+were rendered with. These are **not** the only builds that work — any ref2va or
+hybrid ref2va set will do. Repoint the loaders at what you have; a loader
+showing an empty or red filename is naming a file you do not have, not a broken
+workflow.
 
-Both shipped workflows are saved pointing at the exact files they were rendered with. These are quantised builds and are **not** the only ones that work -- any ref2va or hybrid ref2va set will do. Repoint the loaders at what you have; a loader showing an empty or red filename is naming a file you do not have, not a broken workflow.
+<details>
+<summary>The exact files the examples name</summary>
 
-| loader | file the example names |
+| loader | file |
 |---|---|
 | `UNETLoader` | `minimax_h3_hybrid_fl2va_ref2va_b30-49-int8.safetensors` |
 | `CLIPLoader` | `qwen3vl_32b_minimax_h3_int8_convrot.safetensors` |
@@ -264,467 +131,548 @@ Both shipped workflows are saved pointing at the exact files they were rendered
 | LoRA Loader Stack | `minimax_h3_ref2v_turbo_4step_v0.1_comfyui_bf16.safetensors` |
 | `tiny_vae` | `taeh3.safetensors` (or `none`) |
 
-**CLIP reaches the node from the LoRA loader, not from the encoder** — that is what makes the text half of every LoRA land. Do not rewire it back.
-
-None of it is required by the node itself. Missing a pack, its nodes load as red boxes: delete them, wire the loader straight into `model` and the encoder into `clip`, and raise `steps` from 7 to around 20.
-
-## Use
-
-1. Restart ComfyUI and load **`workflows/HandTieClips_Starter.json`** — two hops, no references, runs as soon as the loaders are pointed at your files. It carries a six-card **READ ME** board on its own canvas, to the left of the loaders: the three laws, the directive table, the reference rules and the failure table, where you need them rather than in another file. `workflows/HandTieClips_Showcase.json` is the six-hop version and needs three pictures of your own. Both carry the turbo stack listed above.
-2. Point the loaders at your ref2va DiT, encoder, and both VAEs
-3. Add a row per identity still in the **REFERENCES** rail, then **drop a picture onto its thumbnail** (or click to browse, or pick one already uploaded). Give it a `@tag` and group photos of the same person under one subject number. There are no `Load Image` nodes to wire — files land in `ComfyUI/input/h3_refs`.
-4. In **SHOTS**, write one card per hop. Shot 1 is the whole opening; every later card is only the new beat.
-5. Optional: a `voice_file`, a `start_image_file`, a look `reference_video_file` — all picked in the **MEDIA** strip, all files under `input/h3_refs`
-6. Queue, and wire the **`info`** output to a Preview Text node — it prints the fully assembled prompt for every hop
-
-![The editor's four tabs, with SCRIPT open on a ten-shot plan](https://media.githubusercontent.com/media/dntpi/ComfyUI-Hand-Tie-Clips/main/docs/img/editor-tabs.png)
-
-*Four tabs -- SCRIPT, REFS, MEDIA, WRITE -- each with its count, and RUN pinned below them. SCRIPT is one card per hop: the beat, its duration, and its own join, camera, framing, pace and tail, with `lock` and the range button on the card header.*
-
-Keep later-hop beats on **what happens next**. Do not re-describe the face; the photos, the register and the pin already carry it.
-
-Two modes:
-
-- **Simple** — one prompt box and a hop count, the way it always worked. Later hops advance the same action rather than replaying the opening.
-- **Shots** — one card per hop with directives. Switching from Simple carries your prompt over and splits it on `---`.
-
-Only one of them is on screen at a time, so there is never a text box quietly doing nothing.
-
-Under the script sits **RUN**, collapsed, holding everything that is not per-shot: output size and length, sampling, the join and pin controls (`pin_mech`, `last_frame_guide`, tone), and the hop cache. Its title line summarises the run — `1344x768 · 10s ×3 · 14 steps res_multistep · cache off` — so you can read the setup without opening it. In Shots mode `chains` and `hop_script` are not offered there, because the shot list already decides both. `last_frame_guide` ships `off`; reach for `before_restart` when the plan has a restart, and leave `still` alone unless no shot authors a framing (see [Last-frame guide](#last-frame-guide)).
-
-**`tone_compensate`** lives in that panel's *join & pin* group. The H3 denoiser biases each hop's tone, so a chain gets steadily brighter; this measures the bias on the overlap each hop regenerated and undoes it, correcting each hop against the previous **corrected** one so the whole chain lands on hop 1's tone. `frame_shift` is the mode to reach for: all three modes remove the drift equally well (within 0.4/255 of each other), but `gain_bias` and `lut` pair pixels between a frame and its *regeneration*, which fits a slope that is not really there and flattens contrast a little more with every hop. `frame_shift` uses frame averages only, so it can shift but never distort. **Measured on a 3-hop render: chain drift 5.6/255 without it, 0.3/255 with it.** Worth turning on for anything past two hops. It ships off because enabling it also clamps the master to 0..1, and because the correction grows with hop count — by hop 10 it is subtracting ~23/255 and will start crushing blacks. Switching modes never invalidates the hop cache, so it is free to A/B. Do **not** judge it by whether the seams flatten to zero: real scene brightness changes across a cut should survive, and they do.
-
-## Shot plan
+</details>
 
-The cards write this; you rarely see it. It is under **JSON** on the node if you want to copy a plan between workflows.
-
-```json
-{
-  "shots": [
-    {
-      "beat": "The cook stands at the counter, looks up, and speaks one short line.",
-      "directives": {"camera": "hold", "framing": "medium", "pace": "steady", "tail": "ongoing"}
-    },
-    {
-      "beat": "The cook sets the knife down and turns toward the window, still talking.",
-      "directives": {"join": "continuous", "camera": "push_in", "framing": "close"}
-    }
-  ]
-}
-```
-
-Shot 1 is the whole opening. Every later shot is **only the new beat** — the node supplies the identity lock, the live-frame citation and the join itself.
-
-Fields, all optional except `beat`:
-
-| | |
-|---|---|
-| `beat` | What happens this hop. |
-| `directives` | The five axes below. |
-| `prose` | Free text appended verbatim, for anything the vocabulary lacks. |
-| `seed`, `steps`, `duration` | Per-shot overrides. `duration` takes the same labels as the widget (`"8 s"`). |
-| `locked` | Reuse this shot's cached render even when its inputs changed -- freeze a take you like while you rewrite the hops around it. Needs `cache_hops=on`, and give the shot an `id`. Not to be confused with `subjects.N.locked`, which is identity text. |
-| `tone` | `"free"` skips the chain-wide tone pull once; `"rebase"` also moves the anchor onto this hop. Omit it unless a scene is deliberately darker or brighter from here. |
-| `anchor` | `"restart"` makes this hop a chain start: the start image is frame 0, nothing is relayed. It is a **cut**, so it belongs where a cut is motivated — a pause, a change of thought, a new beat — not on a hop interval. Pair with `join: hard_cut` or `match_cut`; `continuous` is refused. Name the room in the beat: a pin-less hop has nothing else telling it where it is. Never on shot 1. Needs a start image. |
-| `refs` | Which register stills ride this hop, as tags. Omit for the register default. `[]` is none. A list is those tags only, in that order. |
-| `id` | Stable name, used as the cache pointer. Generated if absent. |
-
-### Hops of different lengths
-
-`duration` is per shot, and everything downstream sizes itself around it — the master buffer, the reference-video decode and the per-hop cache key all read the real lengths:
-
-```json
-{
-  "shots": [
-    {"beat": "She slams the drawer shut.",            "duration": "5 s",  "directives": {"join": "hard_cut", "pace": "urgent"}},
-    {"beat": "She crosses to the window, still talking.", "duration": "15 s", "directives": {"join": "continuous", "camera": "push_in"}},
-    {"beat": "She stops and looks back."}
-  ]
-}
-```
-
-The third shot has no `duration`, so it takes the widget's. Labels are the widget's too — `5 s`, `7 s`, `8 s`, `10 s`, `15 s`. That set is fixed, not arbitrary: every value has to land on H3's frame grid (`n % 17 == 5` at 24 fps), so there is no `6.5 s`. Editing one shot's length invalidates that hop and the hops after it, and nothing before it.
-
-**Short hops cut, long hops flow.** Overlap is chain-wide — 0.9 s by default — so a 5 s hop asking for `join: continuous` spends a fifth of itself on the airlock, and the node prints a note saying so. That constraint matches how you would edit anyway: quick beats take a cut, flowing takes want length.
-
-### Directives
-
-| axis | options |
-|---|---|
-| `join` | `continuous`, `match_cut`, `hard_cut` — ignored on shot 1, which has nothing to join to |
-| `camera` | `hold`, `pan_follow`, `push_in`, `pull_back`, `orbit`, `handheld` |
-| `framing` | `keep`, `wide`, `medium`, `close` |
-| `pace` | `slow`, `steady`, `brisk` |
-| `tail` | `ongoing` (default), `settle`, `hold` |
-
-An unset axis emits nothing rather than asserting a default, so it costs no tokens.
-
-**Everything is phrased affirmatively, on purpose.** Sampling runs at cfg 1.0 with no negative branch, so every concept named is additive — "no cut" puts the word `cut` in front of the encoder. If you add prose of your own, say what the shot *is* doing.
-
-`join=continuous` together with a framing change and a held camera will warn: with the camera still, the only way to reach a new framing is a cut, so the two are asking for opposite things. Use `push_in` / `pull_back` / `pan_follow` to earn the framing on the move, or `framing: keep`.
-
-A camera move that points the opposite way from the framing (`push_in` with `wide`, `pull_back` with `close`) warns too -- those are physically contradictory whatever the join.
-
-When `join=continuous` and the camera *is* moving, the framing sentence is compiled as a **landing** ("The move settles into a close shot...") rather than as the shot's opening state, so it does not fight the pin that still holds the previous framing.
+---
 
-## Writing beats
+## Start here
+
+1. Load **`workflows/HandTieClips_Starter.json`** — two hops, no references,
+   runs as soon as the loaders point at your files. It carries a **READ ME**
+   board on its own canvas, to the left of the loaders: the laws, the directive
+   table, the reference rules and the failure table, where you need them rather
+   than in another file.
+2. Point the loaders at your ref2va DiT, encoder, and both VAEs.
+3. In **REFS**, add a row per identity still and **drop a picture onto its
+   thumbnail**. Give it a `@tag`; group photos of the same person under one
+   subject number. Files land in `ComfyUI/input/h3_refs` — there is nothing to
+   wire.
+4. In **SCRIPT**, write one card per hop. Shot 1 is the whole opening; every
+   later card is **only the new beat**.
+5. Optional: a first frame, up to three reference clips, up to three voices, a
+   music bed, a master audio take — all in **MEDIA**.
+6. Queue. Wire **`info`** to a Preview Text node to read the fully assembled
+   prompt for every hop.
+
+`workflows/HandTieClips_Showcase.json` is the six-hop version and needs three
+pictures of your own. Both carry the turbo stack above.
+
+![The editor's tabs, with SCRIPT open on a ten-shot plan](https://media.githubusercontent.com/media/dntpi/ComfyUI-Hand-Tie-Clips/main/docs/img/editor-tabs.png)
+
+*Each tab carries its count, and RUN stays pinned below them. SCRIPT is one
+card per hop: the beat, its duration, and its own join, camera, framing, pace
+and tail, with `lock` and the range button on the card header.*
+
+Under the script sits **RUN**, collapsed, holding everything that is not
+per-shot: output size and length, sampling, the join and pin controls
+(`pin_mech`, `last_frame_guide`, tone), and the hop cache. Its title line
+summarises the run — `1344x768 · 10s ×3 · 14 steps res_multistep · cache off` —
+so you can read the setup without opening it.
+
+Two script modes: **Simple** (one prompt box and a hop count, the way it always
+worked) and **Shots** (one card per hop with directives; switching from Simple
+carries your prompt over and splits it on `---`). Only one is on screen at a
+time, so no text box is ever quietly doing nothing.
+
+Keep later-hop beats on **what happens next**. Do not re-describe the face; the
+photos, the register and the pin already carry it.
 
-> The full authoring guide, including how to have a model write plans for you, is **[PROMPTING.md](PROMPTING.md)**. What follows is the short version.
+---
 
-Sampling runs at cfg 1.0 with no negative branch, so **the prompt is additive:
-anything you name is added, and nothing can be removed by mentioning it.** Three
-rules follow, each confirmed against renders rather than reasoned from the code.
+## The one law
 
-**Point the action line at the reference you want used.** Describing a reference
-in the register is not enough -- the beat is what drives the frame. Write the tag
-into the action:
-
-```
-The cook stands at the counter in @kitchen, looks up from the chopping board,
-and speaks one short line to someone off-frame.
-```
-
-`@kitchen` resolves to the right `<Picture N>` on every hop it is active, so
-rewiring references never breaks the text. Phrase it as a place that is depicted,
-not as a container to be placed inside -- otherwise you can get a literal
-composite of the photograph.
+Sampling runs at **cfg 1.0 with no negative branch**, so the prompt is purely
+additive: **anything you name is added, and nothing can be removed by
+mentioning it.** Almost every rule in this pack is a consequence, and each of
+the rules below was confirmed against renders rather than reasoned from code.
 
 **Never name the thing you want to end.** `The cook stops talking` keeps her
-talking. Describe the state you want as a pose plus a sound:
+talking. Write the state you want as a pose plus a sound:
 
-```
-The cook leans back against the counter with her lips closed, and lets her eyes
-move slowly across the room. The kitchen is quiet apart from the hum of the
-refrigerator and faint street noise through the window.
-```
+> The cook leans back against the counter with her lips closed, and lets her
+> eyes move slowly across the room. The kitchen is quiet apart from the hum of
+> the refrigerator.
 
-H3 generates audio for the whole hop no matter what, so silence must be written
-as a sound -- room tone, a fridge, traffic. Written as an absence, you get speech.
+H3 generates audio for the whole hop no matter what, so silence has to be
+written as a sound. Written as an absence, you get speech. The ban is on the
+idea, not on a word list: *fades, subsides, dies down* all name an ending as
+surely as *stops* does.
 
-**Put a state change at the end of the previous shot.** Every hop after the first
-opens by holding the frames it was handed, and the audio pin carries the tail of
-the previous hop across the join. If shot 2 ends mid-sentence, no wording in shot
-3 will make it start quiet. Finish the line where it actually finishes:
+**Point the action line at the reference you want used.** Describing a
+reference in the register is not enough — the beat is what drives the frame.
+Write the tag into the action: `The cook stands at the counter in @kitchen,
+looks up…`. Phrase a place as depicted, not as a container to be placed inside,
+or you can get a literal composite of the photograph.
 
-```
-shot 2: The cook sets the knife down, turns toward the window, and finishes her
-        last word as she looks out.
-shot 3: The cook leans back against the counter with her lips closed...
-```
+**Put a state change at the end of the previous shot.** Every hop after the
+first opens by holding the frames it was handed, and the audio pin carries the
+previous hop's tail across the join. If shot 2 ends mid-sentence, no wording in
+shot 3 will make it start quiet — arrive there before the previous shot ends.
+
+**Pick ambience that is narrowband and specific.** "faint street noise through
+the window" is broadband and renders as a five-second hiss; "the low hum of the
+refrigerator" does not.
 
-To be silent, still, or somewhere else in a shot, arrive there before the
-previous shot ends.
+**Set `tail` on your last shot.** Left on `ongoing`, the model is told action is
+still underway at the final frame and will invent something to satisfy it — a
+stray gesture, or a stray line of dialogue in the closing second.
 
-**Pick ambience that is narrowband and specific.** After the first shot, official
-soundscape fields are stripped and ambience is plain prose, so the exact words
-matter. "faint street noise through the window" is broadband and renders as a
-five-second hiss; "the low hum of the refrigerator" does not. If a continuous bed
-still misbehaves, name a single discrete event instead -- "a single click from the
-refrigerator, then stillness".
+> The full authoring guide is **[PROMPTING.md](PROMPTING.md)**. Its rules come
+> from what this model actually does, not from taste. `prompt_pack/` is the
+> same writer as a copy-paste prompt, for when you would rather work in a chat
+> window.
 
-**Set `tail` on your last shot.** `settle` and `hold` change the final sentence of
-the prompt, which governs the terminal state of the clip. Left on `ongoing`, the
-model is told action is still underway at the final frame and will invent
-something to satisfy it -- on a last shot that means a stray gesture or a stray
-line of dialogue in the closing second.
+---
 
 ## Let a model write the plan
 
-Open **WRITE** on the node, point it at any OpenAI-compatible server, say what
-you want in one sentence, and press **Write plan**. It fills the SCRIPT cards
-and the REFERENCES rows together — and the pictures already on those rows go
-with the request, so the model describes what it is actually looking at rather
-than guessing from a filename.
+Open **WRITE**, point it at any OpenAI-compatible server, say what you want in
+one sentence, and press **Write plan**. It fills the SCRIPT cards and the
+REFERENCES rows together — and the pictures already on those rows go with the
+request, so the model describes what it is actually looking at rather than
+guessing from a filename.
 
 ![The WRITE bar](https://media.githubusercontent.com/media/dntpi/ComfyUI-Hand-Tie-Clips/main/docs/img/write-panel.png)
 
-- **Context 32768.** The system prompt alone is ~6,000 tokens, the reply another
-  1,000–2,000, and every reference picture costs ~260 on top.
+- **Context 32768.** The system prompt alone is ~6,000 tokens, the reply
+  another 1,000–2,000, and every reference picture costs ~260 on top.
 - **Reasoning off.** Thinking tokens come out of the same budget; a reply that
   stops before the JSON closes is the tell.
 - **Temperature 0.3.** Higher and the JSON grows trailing commas and smart quotes.
 
-Server settings are saved on this machine only — they are not part of the
-workflow, so a shared `.json` never points at your server.
+Server settings are saved on this machine only — a shared `.json` never points
+at your server.
 
 **Treat what comes back as a strong draft, not a finished plan.** It gets the
 structure right — hop count, join types, which reference rides which hop, a
-sound bed on every quiet hop — and that is the part that is tedious by hand.
-Two things are worth reading every time: each reference's `desc`, which can be
-confidently wrong about its own photograph, and the spoken words in every beat.
-The node lints both and prints what it finds before you render.
+sound bed on every quiet hop — which is the part that is tedious by hand. Read
+two things every time: each reference's `desc`, which can be confidently wrong
+about its own photograph, and the spoken words in every beat. The node lints
+both and prints what it finds before you render.
 
-`prompt_pack/` is the same writer as a copy-paste prompt for a chat window.
+---
 
-## Reference media: three clips, three voices
+## SWAP
 
-H3 takes **9 reference pictures, 3 reference videos and 3 standalone reference
-audios**. Pictures go through the REFS rail (see below). The clips and voices
-are in **MEDIA**, one slot each until 1.2:
+A **one-hop identity swap** from a reference clip: the clip supplies the motion
+and the scene, a still from your rail supplies the person. Trim the clip in
+MEDIA, pick an identity, press **Write**, then **Accept** — which writes exactly
+one shot and the clip's description, and never touches `ref_plan`. Your
+register is not rewritten.
 
-| slot | cited as | notes |
-|---|---|---|
-| `reference clip` 1-3 | `<Video 1..3>` | motion/look plates the whole chain reads |
-| `voice` 1-3 | `<Audio 1..3>` | timbre references for hop 1 |
+Four modes, because at cfg 1.0 **a mode that merely omits the swap line does
+not keep the clip's person** — the identity still is in front of the encoder
+either way and governs the subject anyway. Each mode states positively what
+stays:
 
-**Numbering is dense.** Fill slots 1 and 3 and you get `<Video 1>` and
-`<Video 2>` — there is no gap. That means **clearing a slot renumbers the ones
-after it**, so a beat that names an ordinal will cite a different clip. Refer to
-media by what it is, not by its number, unless you are sure the slots above it
-are filled.
+| mode | what the photograph contributes |
+|---|---|
+| `replace_person` | Face, build, hairstyle **and** wardrobe. |
+| `head_swap` | Face, hair and skin tone. The body stays with the clip: build, posture, hands and every garment. |
+| `face_only` | Facial features only. Hair, ears, expression, build and clothes stay with the clip. |
+| `keep_person` | Nobody is swapped; the clip is a scene and motion plate. The identity picker greys out. |
+
+Alongside them: **background** (from the clip / from a picture `@tag` / free)
+and an optional **wardrobe plate** — a `@tag` whose garment is *worn*, draping
+on the body in frame and creasing where it bends, not pasted.
+
+**Two things to get right, both of which cost renders to find out:**
+
+- **Do not run MEDIA's describe on the clip before a swap.** That caption
+  reaches the encoder as what `<Video 1>` *is*, and — being additive — a
+  caption naming a person asks for the person you are about to replace. Four
+  consecutive "head swap doesn't work" reports came down to that, a missing
+  frame sequence and a weak citation; none of them was broken code. SWAP now
+  warns when a caption names somebody.
+- **Drop the clip to ~0.3 MP.** A reference clip's decode area is its token
+  count, and its token count is its influence. A full-size plate out-argues a
+  single photograph.
 
-**Reference clips now carry their own sound.** Each clip's audio track is
-decoded and handed to the model alongside its picture. Before 1.2 a reference
-clip arrived silent even when the file had sound. A clip with no usable audio
-track just passes silent and says so in the log.
+---
 
-**Trim them.** Every reference audio is attended on every step of every hop, and
-H3 encodes the whole file. With one voice the trim window was an optimisation;
-with three it is not. Slots 2 and 3 share slot 1's `reference video size`, which
-is a decode budget rather than a creative setting.
+## Tested in public
 
-## Reference register
+Before 2.0 shipped, a tester ran **ten controlled nine-hop chains** — 65 s each,
+one variable per run, same model, LoRA, references, locked audio and seed — and
+measured them end to end with her own instruments rather than by eye. The
+results below are hers, used with permission.
 
-```json
-{
-  "refs": [
-    {"tag": "hero_face",   "file": "cook_face.jpg",   "subject": 1, "retention": "fully_preserved"},
-    {"tag": "hero_outfit", "file": "cook_apron.jpg",  "subject": 1, "retention": "partially_copy"},
-    {"tag": "kitchen",     "file": "kitchen_wide.jpg", "retention": "reference", "mp": 0.3}
-  ],
-  "subjects": {
-    "1": {"name": "the cook", "locked": "the same face, the same short dark hair"}
-  }
-}
-```
+![Scorecard across the ten runs](https://media.githubusercontent.com/media/dntpi/ComfyUI-Hand-Tie-Clips/main/docs/img/tester-scorecard.png)
 
-`file` is a picture in `ComfyUI/input/h3_refs`, set by the rail. `tag` is what you write in your beats — `@hero_face` — and the node resolves it to the right `<Picture N>` **per hop**, so pulling a still out of the middle no longer breaks every later reference.
+Her headline: **`anchor: "restart"` won.** It is the only run type whose last
+ten seconds is still on the reference still's side of its own hop 1 — colour,
+texture, background and framing all hold. The cost is that a restart is a hard
+cut. Second best was a small `pin_noise`, one run each way. **Nothing else moved
+the needle** — not `pin_renorm=band`, not reference protection, not a different
+DiT, not `ref_image_size=match`, not a fresh seed — and the plain control was
+the worst of the ten.
 
-`subject` groups pictures per person. This matters: declaring every picture as a photo of `<Subject 1>` makes the model render the *average* of two different people.
+![Background detail across hops](https://media.githubusercontent.com/media/dntpi/ComfyUI-Hand-Tie-Clips/main/docs/img/tester-background-drift.png)
 
-`retention` says how much of a picture carries over — `fully_preserved` (face and bone structure exactly), `partially_copy` (the garment and its cut), `reference` (layout, surfaces and light, i.e. a place). Refs with a subject default to `fully_preserved`; everything else defaults to `reference`.
+Her diagnosis is sharper than ours was: **relay convergence with no content
+anchor.** Each hop inherits its predecessor's end state and nothing pulls it
+back toward the reference. It also explains why the scale knobs did nothing —
+the pin's *statistics* never drifted (sigma stayed within ±6% across nine hops)
+while the picture lost a fifth of its chroma and doubled its background edges.
+The drift is in the latent's **content**, not its scale, and `pin_renorm` and
+`pin_noise` only rescale.
 
-`mp` caps one picture's pixel budget in megapixels. It is a **token dial, not a quality one**: H3 turns every reference into `latent_h × latent_w` entries — pixel area ÷ 256 — and attends over all of them on every step of every hop, so a location plate costing what a face costs is waste. A 0.3 MP place plate is ~1,170 tokens; a 2 MP portrait is ~7,800. Absent (or `0`) means no cap. The rail offers 0.3–2.0; `ref_plan` accepts up to 16.
+Three things in 2.0 come straight from that study:
 
-> **The dial is inert at the default.** On `ref_image_size=match` every reference is first scaled down to the output's pixel area, and `mp` only ever caps *further* — so at 768p (~1.03 MP) the 1.5 and 2.0 settings change nothing. The real per-reference resolution control is `ref_image_size=max` **plus** `mp`, never `mp` on its own.
+- **Restart hops write their full length.** They used to drop 0.9 s of new
+  content as though they were continuations.
+- **`last_frame_guide=before_restart`**, so both sides of a restart cut meet on
+  the same photograph and it reads as a match cut rather than a jump.
+- **`tone_anchor_ref=still`.** The anchor used to hold hop 1, on the reasoning
+  that hop 1 is the one tone in the chain nothing has drifted into yet. Her
+  measurements say that is false — hop 1 is the *first casualty*, already short
+  of the still before any relay has happened:
 
-Add `"shots": [1, 2]` to a ref to keep it out of the hops it does not belong in. On a continuation chain (`hop_script=next` / a shot plan), omitting `shots` means **hop 1 only** — right for a place plate, which beats the pin if it rides a hop set somewhere else. **Put face plates on every hop:** a hop with no face reference comes back a different person and no later hop recovers.
+| | reference still | hop 1 |
+|---|---|---|
+| chroma | 33.6 | 30 |
+| b\* (warmth) | 26.6 | 22 |
+| fine detail | 1.00 | 0.72–0.99 |
 
-## Hop cache
+A chain anchored on hop 1 converges on a target that already fell short.
 
-`cache_hops=on` writes every rendered hop to ComfyUI's temp dir as lossless FFV1 video plus a float32 `.npy` waveform, evicting least-recently-used above `cache_budget_gb`. The key is chained and includes the model fingerprint and, per hop, which pin mechanism was used -- a hop pinned by the AddGuide fallback is not the same render as one pinned by Motion-Context.
+**What her study could not fix, this release does not claim to fix.** Texture
+still ratchets on long chains, and 3–5 hops is still the honest limit.
 
-The key **chains** — each hop's key includes the previous hop's — because hops are causally dependent. So:
+---
 
-- edit shot 3 and re-queue → shots 1 and 2 load from cache, only 3 renders;
-- edit shot 1 → all three re-render, which is correct, not a bug;
-- change resolution, sampler, the checkpoint, a LoRA, or an attention setting → the whole chain re-renders;
-- change `pin_to_qwen` or `overlap` → only hops 2+ re-render, because neither can reach hop 1. A restart hop is a start, so overlap does not reach it either;
-- set `last_frame_guide=still` or set `master_audio_file` → every hop re-renders (both reach hop 1). `before_restart` only moves the hop that actually gets the guide; empty / `off` do not move existing keys;
-- change a reference picture → only the hops that picture rides re-render. Swapping the file behind `@outfit` when it rides hop 5 leaves hops 1-4 on cache. Before 1.1 this invalidated everything.
+## Holding a chain together
 
-That last one is worth knowing about. The node cannot read the settings on your LoRA and attention nodes, so instead it fingerprints what they *did* to the model — which weight keys were patched, at what strengths, and the attention overrides — plus the base model itself: its class, its dtype and its parameter count. Change a LoRA strength, or load the int8 build where you had the bf16 one, and the cache correctly invalidates. Nodes that configure themselves by closure or by object are read the same way, so changing a setting on one moves the key rather than only installing it. Two remaining gaps: two different LoRAs touching exactly the same keys at exactly the same strengths, and two different builds of the same architecture at the same dtype and parameter count.
+### The join
 
-Set `locked: true` on a shot to pin it to its last render regardless.
+`pin_mech` chooses it. `auto` (default) is Motion-Context when the pack is
+installed, the overlap has a matching `context_length`, and the previous hop
+left a sampler latent; AddGuide pixels otherwise. Forcing `motion_context` or
+`addguide` does **not** fall back — it fails with the reason, because a lever
+that silently becomes the other setting cannot be compared against it.
+`motion_context` is a latent join with no decode/re-encode; `addguide`
+re-encodes decoded pixels, which is itself a VAE round trip. Switching
+re-renders hops 2+ and leaves hop 1 on disk. A restart hop pins nothing.
 
-## Reading a plan before you render it
+<details>
+<summary>Three more pin dials, all defaulting to their pre-existing behaviour</summary>
 
-`dry_run=on` compiles every hop's prompt and stops. No model, no sampler,
-seconds instead of minutes. The compiled text comes out on `info`; the same
-thing comes out on `contact_sheet` as a page you can read at a glance.
+| widget | default | what it does |
+|---|---|---|
+| `audio_pin_frames` | `24` | Audio context handed to the pin, in frames; 24 is one second on the model's 40 Hz grid. Longer costs conditioning rows but **no delivered frames**, so it is the cheap lever on speech that breaks across a join — try `96` (4 s) for continuous dialogue. |
+| `pin_renorm` | `off` | Rescales each pinned latent back toward the first pinned hop's, against the texture ratchet — measured at +4.2% mid-band per join, flat inside each hop. Both modes are scalar rescales, so neither moves structure or can blur detail, and video and audio are corrected separately. **`band`** matches the high-band fraction, which is the statistic the ratchet actually moves: a 12.74% drift went to −0.04%. **`sigma`** is the original lever, kept for old workflows and measurably the wrong statistic — total sigma *falls* across a chain whose picture is baking, so it corrects the wrong way. Use `band` for 3+ hops. |
+| `pin_noise` | `0.0` | Mixes seeded noise into the pin — the other half of the same fix. Small values only; measured gains reverse above `0.10`, which is where the range stops. |
 
-This is the only way to see what the text encoder will actually receive. The
-directive layer, the continuation scaffolding, the identity lock and the
-`<Picture N>` citations are all assembled at render time, so until now the first
-sight of the real prompt was in the log of a render you had already paid for.
+`pin_to_qwen` separately shows the incoming state to the *text* encoder: `off`,
+`last frame` (default — the previous hop's last frame becomes `<Picture 1>`, and
+identity stills shift to Picture 2+), `pin clip` (overlap frames as an extra
+`<Video>` at ~2 fps, no soundtrack), or `both`. `@tags` in beats resolve per
+hop, so stills shifting never breaks prose; a literal `<Picture N>` in a hop 2+
+beat would.
 
-![`lock` and the range button on the shot cards](https://media.githubusercontent.com/media/dntpi/ComfyUI-Hand-Tie-Clips/main/docs/img/shot-lock-range.png)
+</details>
 
-*`lock` freezes a take you like; the `⏵` beside it sets the render range to that shot alone.*
+### Brightness drift — two different problems
 
-`render_through=N` stops after N hops. With `cache_hops=on` the hops you already
-rendered stay on disk, so 3 → 5 → 8 builds a chain up in stages and only ever
-renders the new hops. The plan is not truncated: shot 4 still knows it is shot
-4, keeps its own seed, and keys the same way it will in the full run.
+**The step at a join** is the denoiser's tone bias on a fresh generation.
+`tone_compensate=frame_shift` measures it on the overlap the hop regenerated and
+cancels it, which is why the seams in a corrected chain read as invisible.
+Measured on a 3-hop render: chain drift 5.6/255 without it, 0.3/255 with it.
+All three modes remove the drift equally well, but `gain_bias` and `lut` pair
+pixels between a frame and its *regeneration*, fitting a slope that is not
+really there; `frame_shift` uses frame averages only, so it can shift but never
+distort.
 
-`quality=draft` forces the 448p tier and 6 steps — enough to read blocking, camera and
-whether a join lands. Resolution and steps are both in the cache key, so a draft
-never overwrites the final it stands in for; the two simply cost two entries.
+**The slide across a whole chain** is different. Each hop also darkens across
+its *own* frames, hands that darker tail to the next hop, and the next hop
+starts from there. Seam correction cannot see this — every individual join is
+exact while the film gets steadily dimmer. An 8×15 s chain slid from luma 46 to
+11 across hops 2–6 with every seam already corrected.
+
+`tone_compensate=anchor` is frame_shift **plus** a pull back toward a target,
+matched in **Lab** — L\*, a\*, b\* and L\* spread — because chroma loss is the
+largest measured drift and a per-channel RGB mean cannot restore it.
+`tone_anchor_ref` picks the target: `hop1` (default) or **`still`**, which holds
+the photograph and is the only setting that ever closes the 33.6-against-30 gap
+above. `still` needs `start_image_file`, and under the Motion-Context join the
+correction still only reaches the delivered frames, not the next hop's pin —
+`pin_mech=addguide` is what closes that loop.
+
+Two things keep the pull from causing the problem it is fixing: it **ramps in**
+across the first two seconds of each hop, so frame 0 still matches the previous
+hop's last frame exactly and the seam stays as clean as frame_shift left it;
+and it is **capped** per hop (`tone_anchor`, default 0.35 ≈ a third of the gap),
+so a long slide is corrected over several hops instead of one hop snapping back
+and pumping.
 
-Treat it as a **fidelity** lever rather than a speed one. Measured at ~42 s/hop
-against ~45 s/hop at 7 steps: if you already render at 448p and 6–8 steps —
-the regime this pack targets — draft saves almost nothing, and `dry_run` is the
-fast button. Draft earns its place when your final is genuinely heavier, 768p
-at 14 steps.
+![Seam report chart](https://media.githubusercontent.com/media/dntpi/ComfyUI-Hand-Tie-Clips/main/docs/img/seam-report.png)
 
-## Contact sheet
+| `tone_anchor` | drift across the chain | worst seam |
+|---|---|---|
+| off | 13.5/255 | 2.1/255 |
+| 0.15 | 7.4 | 1.3 |
+| 0.35 | 5.1 | 1.9 |
+| 0.60 | 2.9 | 2.6 |
 
-`contact_sheet=on` adds an image on the fourth output: one row per hop, that
-hop's first and last **delivered** frame side by side, its beat, its directives,
-and what actually happened to it — seed, steps, whether it came from cache, what
-the tone correction did. Wire it to a Save Image.
+Both columns are **H3 Seam Report's own numbers**, so what you measure matches
+what this table says. Drift falls evenly — 45%, 62%, 78% of the uncorrected
+slide. The seam does not: `0.15` pulls it *tighter* than the uncorrected chain
+and it grows from there. Hop 1 is byte-identical in all four. **0.35 is the
+default and stays** — it halves the drift while every seam still reads as
+marginal or better. Set `tone_anchor` to 0 for plain frame_shift.
+
+A scene that is *meant* to get darker looks exactly like drift from the inside,
+so a shot can opt out: `"tone": "free"` skips the pull for that hop,
+`"tone": "rebase"` also moves the anchor onto it — which is how a scene that is
+genuinely darker from here on stops being fought for the rest of the film.
+
+### Restarts, and the last-frame guide
+
+`anchor: "restart"` on a shot makes that hop a chain start — the start image is
+frame 0 and nothing is relayed. It is **a cut**, so it belongs where a cut is
+motivated: a pause, a change of thought, a new beat, not on a hop interval.
+Pair it with `join: hard_cut` or `match_cut`; `continuous` is refused. Name the
+room in the beat, because a pin-less hop has nothing else telling it where it
+is. Never on shot 1, and it needs a start image.
 
-![Contact sheet](https://media.githubusercontent.com/media/dntpi/ComfyUI-Hand-Tie-Clips/main/docs/img/contact-sheet-vlog.png)
+`last_frame_guide` plants `start_image` at a hop's last **pixel** frame
+(AddGuide `frame_idx=-1`, not latent T-1). It does not become the next hop's
+frame 0. Needs a start image. Ships `off`.
 
-On a chain of any length this is the fastest way to find the hop that broke. The
-one hard cut in the 114-second reference chain sat in a plan that passed every
-automated check; it is obvious in one row of a contact sheet and invisible in a
-progress bar.
+**Reach for `before_restart`.** It guides only a hop whose *next* shot is a
+restart, so both sides of the cut meet on one image — hop 3 used to end tight
+and smiling, hop 4 open wide and neutral; with the guide, hop 3 *arrives* at the
+still's framing. Measured: the four hop endings of a 4-hop chain converge to
+3.8/255 of each other against 39.1/255 unguided, while mid-hop frames stay as
+varied as ever (65.8 against 61.1). Two people watched it in motion and could
+not see the convergence.
+
+**`still` is the "I know what I am doing" setting.** It plants the photograph on
+every hop, unconditionally, which overrides an authored `framing` at every hop
+ending — a shot set `framing: close` plays close for six seconds and then snaps
+to the still's wider framing in about 0.6 s, and the next hop pushes back in. A
+user watching this described it, unprompted, as *"the camera kept cutting in and
+out."* Frame-by-frame from that run, hop 3, `framing: close`:
 
-## Brightness drift, and the two things that fix it
+    1.58s close   3.67s close   4.92s close   5.96s close-ish   6.58s WIDE   7.04s WIDE
 
-These are different problems and they need different settings.
+Safe when no shot authors a framing; visibly wrong when they do.
 
-**The step at a join** is the denoiser's tone bias on a fresh generation.
-`tone_compensate=frame_shift` measures it on the overlap the hop regenerated and
-cancels it, which is why the seams in a corrected chain read as invisible.
+---
 
-**The slide across a whole chain** is different. Each hop also darkens across
-its *own* frames, hands that darker tail to the next hop, and the next hop
-starts from there. Seam correction cannot see this — every individual join is
-exact while the film gets steadily dimmer. The 8×15 s reference chain slid from
-luma 46 to 11 across hops 2–6 with every seam already corrected.
+## Reference
 
-`tone_compensate=anchor` is frame_shift plus a pull back toward a target.
-`tone_anchor_ref` chooses which.
+### Shot plan
 
-**`hop1` (default) holds whatever hop 1 rendered.** That was the original
-reasoning: hop 1 is the one tone in the chain nothing has drifted into yet. An
-outside ten-run 9-hop study measured that this is false. Before any relay has
-happened:
+The cards write this; you rarely see it. It is under **JSON** on the node if you
+want to copy a plan between workflows.
 
-| | reference still | hop 1 |
-|---|---|---|
-| chroma | 33.6 | 30 |
-| b* (warmth) | 26.6 | 22 |
-| fine detail | 1.00 | 0.72–0.99 |
+```json
+{
+  "shots": [
+    {
+      "beat": "The cook stands at the counter, looks up, and speaks one short line.",
+      "directives": {"camera": "hold", "framing": "medium", "pace": "steady", "tail": "ongoing"}
+    },
+    {
+      "beat": "The cook sets the knife down and turns toward the window, still talking.",
+      "directives": {"join": "continuous", "camera": "push_in", "framing": "close"}
+    }
+  ]
+}
+```
 
-Hop 1 is not the reference — it is the **first casualty**. A chain anchored on
-it converges on a target that already fell short.
+Shot 1 is the whole opening. Every later shot is **only the new beat** — the
+node supplies the identity lock, the live-frame citation and the join itself.
+Fields, all optional except `beat`:
 
-**Reach for `still` when you want the chain to hold the photograph**, not hop
-1's already-short copy. It uses `start_image` instead, which does not drift,
-and it pulls hop 1 itself — the only way that 33.6-against-30 gap ever closes.
+| | |
+|---|---|
+| `beat` | What happens this hop. |
+| `directives` | The five axes below. |
+| `prose` | Free text appended verbatim, for anything the vocabulary lacks. |
+| `seed`, `steps`, `duration` | Per-shot overrides. `duration` takes the widget's labels (`"8 s"`). |
+| `refs` | Which register stills ride this hop, as tags. Omit for the register default; `[]` is none; a list is those tags only, in that order. Unknown tags fail on the queue. |
+| `anchor` | `"restart"` makes this hop a chain start. See above. |
+| `tone` | `"free"` skips the chain-wide tone pull once; `"rebase"` also moves the anchor. |
+| `locked` | Reuse this shot's cached render even when its inputs changed. Needs `cache_hops=on` and a stable `id`. Not to be confused with `subjects.N.locked`, which is identity text. |
+| `id` | Stable name, used as the cache pointer. Generated if absent. |
 
-Costs: needs `start_image_file` (the queue refuses otherwise). Under the
-Motion-Context join the correction still only reaches the delivered frames,
-not the next hop's pin — `pin_mech=addguide` is what closes that loop.
+**Hops can differ in length.** `duration` is per shot and everything downstream
+sizes itself around it. Labels are the widget's — `5 s`, `7 s`, `8 s`, `10 s`,
+`15 s` — and that set is fixed, not arbitrary: every value has to land on H3's
+frame grid (`n % 17 == 5` at 24 fps), so there is no `6.5 s`. Editing one shot's
+length invalidates that hop and the hops after it, and nothing before it.
 
-Two things keep the pull from causing the problem it is fixing:
+**Short hops cut, long hops flow.** Overlap is chain-wide — 0.9 s by default —
+so a 5 s hop asking for `join: continuous` spends a fifth of itself on the
+airlock, and the node prints a note saying so.
 
-- the pull **ramps in** across the first two seconds of each hop, so frame 0
-  still matches the previous hop's last frame exactly and the seam stays as
-  clean as frame_shift left it;
-- it is **capped** per hop (`tone_anchor`, default 0.35 = about a third of the
-  gap), so a long slide is corrected over several hops instead of one hop
-  snapping back and pumping.
+### Directives
 
-A scene that is *meant* to get darker looks exactly like drift from the
-inside, so a shot can opt out:
+| axis | options |
+|---|---|
+| `join` | `continuous`, `match_cut`, `hard_cut` — ignored on shot 1, which has nothing to join to |
+| `camera` | `hold`, `pan_follow`, `push_in`, `pull_back`, `orbit`, `handheld` |
+| `framing` | `keep`, `wide`, `medium`, `close` |
+| `pace` | `slow`, `steady`, `brisk` |
+| `tail` | `ongoing` (default), `settle`, `hold` |
+
+An unset axis emits nothing rather than asserting a default, so it costs no
+tokens. Everything is phrased affirmatively, for the reason in
+[The one law](#the-one-law).
+
+`join=continuous` with a framing change and a held camera warns: with the camera
+still, the only way to reach a new framing is a cut. Earn it on the move, or use
+`framing: keep`. A camera move pointing the opposite way from the framing
+(`push_in` with `wide`, `pull_back` with `close`) warns too. When `continuous`
+and the camera *is* moving, the framing sentence compiles as a **landing** —
+"The move settles into a close shot…" — so it does not fight the pin that still
+holds the previous framing.
+
+### Reference register
 
 ```json
-{ "beat": "She steps down into the cellar.", "tone": "rebase" }
+{
+  "refs": [
+    {"tag": "hero_face",   "file": "cook_face.jpg",   "subject": 1, "retention": "fully_preserved"},
+    {"tag": "hero_outfit", "file": "cook_apron.jpg",  "subject": 1, "retention": "partially_copy"},
+    {"tag": "kitchen",     "file": "kitchen_wide.jpg", "retention": "reference", "mp": 0.3}
+  ],
+  "subjects": {
+    "1": {"name": "the cook", "locked": "the same face, the same short dark hair"}
+  }
+}
 ```
 
-`"tone": "free"` skips the pull for that hop only. `"tone": "rebase"` also moves
-the anchor onto that hop, which is how a scene that is genuinely darker from
-here on stops being fought for the rest of the film.
+`file` is a picture in `ComfyUI/input/h3_refs`, set by the rail. `tag` is what
+you write in beats, and the node resolves it to the right `<Picture N>` **per
+hop**, so pulling a still out of the middle no longer breaks every later
+reference.
 
-Set `tone_anchor` to 0 to get plain frame_shift back.
+`subject` groups pictures per person. **This matters:** declaring every picture
+as a photo of `<Subject 1>` makes the model render the *average* of two
+different people.
 
-**Measured** on three hops from one seed and one cache — the hop store writes
-before the tone stage runs, so flipping the mode re-grades the same renders and
-only the correction differs:
+`retention` says how much of a picture carries over — `fully_preserved` (face
+and bone structure exactly), `partially_copy` (the garment and its cut),
+`reference` (layout, surfaces and light, i.e. a place). Refs with a subject
+default to `fully_preserved`; everything else defaults to `reference`.
 
-| `tone_anchor` | drift across the chain | worst seam |
-|---|---|---|
-| off | 13.5/255 | 2.1/255 |
-| 0.15 | 7.4 | 1.3 |
-| 0.35 | 5.1 | 1.9 |
-| 0.60 | 2.9 | 2.6 |
+`mp` caps one picture's pixel budget in megapixels. It is a **token dial, not a
+quality one**: H3 turns every reference into pixel area ÷ 256 entries and
+attends over all of them on every step of every hop, so a location plate costing
+what a face costs is waste. A 0.3 MP place plate is ~1,170 tokens; a 2 MP
+portrait is ~7,800.
 
-Both columns are **H3 Seam Report's own numbers**, so what you measure matches
-what this table says.
+> **The dial is inert at the default.** On `ref_image_size=match` every
+> reference is first scaled down to the output's pixel area, and `mp` only ever
+> caps *further* — so at 768p (~1.03 MP) the 1.5 and 2.0 settings change
+> nothing. The real per-reference resolution control is `ref_image_size=max`
+> **plus** `mp`, never `mp` on its own.
 
-![Seam report chart](https://media.githubusercontent.com/media/dntpi/ComfyUI-Hand-Tie-Clips/main/docs/img/seam-report.png)
+Add `"shots": [1, 2]` to a ref to keep it out of the hops it does not belong in.
+On a continuation chain, omitting `shots` means **hop 1 only** — right for a
+place plate, which beats the pin if it rides a hop set somewhere else. **Put
+face plates on every hop:** a hop with no face reference comes back a different
+person and no later hop recovers. A shot's own `refs` overrides all of this for
+that one hop.
 
-Drift falls evenly — 45%, 62%, 78% of the uncorrected slide. The seam does not:
-`0.15` pulls it *tighter* than the uncorrected chain, and it grows from there at
-roughly 0.6/255 per step of strength. Hop 1 is byte-identical in all four.
-**0.35 is the default and stays** — it halves the drift while every seam still
-reads as marginal or better.
+### Reference media: three clips, three voices
 
-One caveat the numbers cannot capture: a scene that brightens *for a reason* —
-walking toward a window — is indistinguishable from drift from the inside, and
-anchor will flatten it. That is what the per-shot `tone` field is for.
+H3 takes 9 reference pictures, 3 reference videos and 3 standalone reference
+audios. Pictures go through REFS; the clips and voices are in **MEDIA**.
 
-## The MODEL wire
+| slot | cited as | notes |
+|---|---|---|
+| `reference clip` 1–3 | `<Video 1..3>` | motion/look plates the whole chain reads |
+| `voice` 1–3 | `<Audio 1..3>` | timbre references for hop 1 |
 
-Four ordinary nodes, in this order:
+**Numbering is dense.** Fill slots 1 and 3 and you get `<Video 1>` and
+`<Video 2>` — there is no gap, so **clearing a slot renumbers the ones after
+it**. Refer to media by what it is, not by its number.
 
-    UNETLoader → LoRA stack (mode=minimax) → H3 AdaLN Fix → MiniMax Low VRAM Attention → H3 SLA Attention → H3 Ref2VA Chain
+Reference clips carry their own sound: each clip's audio track is decoded and
+handed to the model alongside its picture. A clip with no usable audio track
+passes silent and says so in the log.
 
-**Take CLIP from the LoRA loader's second output**, not straight from the encoder, or the text-side keys H3 LoRAs carry are silently dropped.
+**Trim them.** Every reference audio is attended on every step of every hop, and
+H3 encodes the whole file, so a three-minute take is a large invisible tax on a
+clip that only needed four seconds. Slots 2 and 3 share slot 1's `reference
+video size`, which is a decode budget rather than a creative setting — and, as
+[SWAP](#swap) found the hard way, an influence dial.
 
-They briefly lived inside this node as a `model_patches` JSON widget. That made the graph shorter and the node harder to read, so it was reverted — these belong where you can see them.
+![The MEDIA tab with a reference clip loaded](https://media.githubusercontent.com/media/dntpi/ComfyUI-Hand-Tie-Clips/main/docs/img/reference-clip.png)
 
-## Pinning the previous hop
+*A reference clip with its in/out scrubber, the description that tells the
+encoder what the clip is **for**, and `video input size`.*
 
-`pin_mech` chooses the join. `auto` (default) is Motion-Context when the pack
-is installed, the overlap has a matching `context_length`, and the previous hop
-left a sampler latent; AddGuide pixels otherwise. Forcing `motion_context` or
-`addguide` does not fall back — it fails with the reason, because a lever that
-silently becomes the other setting cannot be compared against it.
-`motion_context` is a latent join, no decode/re-encode. `addguide` re-encodes
-decoded pixels, which is itself a VAE round trip. Switching re-renders hops 2+
-and leaves hop 1 on disk. A restart hop pins nothing.
+`master_audio_file` is the odd one out: one continuous take every hop lip-syncs
+to, delivered as a passthrough with no VAE round trip. Empty is off and leaves
+generated voice as before. The beat still needs the words in `<d>[English]
+…</d>` — the lock supplies the timing, not the script — and a take shorter than
+the chain is refused on the queue rather than discovered as a mute final hop.
 
-Three more widgets tune the pin, all defaulting to their pre-existing behaviour:
+An end of `0` on any scrubber means *to the end of the file*, so a longer
+replacement still plays out rather than being cropped to the old one.
 
-| widget | default | what it does |
-|---|---|---|
-| `audio_pin_frames` | `24` | Audio context handed to the pin, in frames. 24 is one second on the model's 40 Hz grid. Longer audio context costs conditioning rows but **no delivered frames**, so it is the cheap lever on speech that breaks across a join — try `96` (4 s) for continuous dialogue. |
-| `pin_renorm` | `off` | Rescales each pinned latent back toward the first pinned hop's, to fight the texture ratchet — measured at +4.2% mid-band per join, flat inside each hop. Both modes are scalar rescales, so neither moves structure or can blur detail, and video and audio are corrected separately because their statistics drift independently. **`band`** matches the high-band fraction, which is the statistic the ratchet actually moves — a 12.74% band drift went to −0.04% under it. **`sigma`** matches total spread: it is the original lever, kept for old workflows (saved as `on` before 0.5) and measurably the wrong statistic — total sigma *falls* across a chain whose picture is baking, so it corrects the wrong way and left that same 12.74% drift unchanged. Use `band` for 3+ hops. |
-| `pin_noise` | `0.0` | Mixes seeded noise into the pin — the other half of the same fix. Small values only; measured gains reverse above `0.10`, which is why the range stops there. |
+### Hop cache
 
-The DiT pin is the previous hop’s **sampler latent** through Motion-Context when present (no decode/re-encode; audio window ends at the join). AddGuide on decoded frames is the fallback. `pin_to_qwen` still shows the incoming state to the text encoder:
+`cache_hops=on` writes every rendered hop to ComfyUI's temp dir as lossless FFV1
+video plus a float32 `.npy` waveform, evicting least-recently-used above
+`cache_budget_gb`. The key **chains** — each hop's key includes the previous
+hop's — because hops are causally dependent. So:
 
-| | |
-|---|---|
-| `off` | Pin stays DiT-only. |
-| `last frame` (default) | Previous hop's last frame is `<Picture 1>`. Identity stills that still ride this hop shift to Picture 2+. |
-| `pin clip` | Overlap frames become an extra `<Video>` at ~2 fps. No soundtrack on it, so `voice` stays `<Audio 1>`. |
-| `both` | Last frame + pin clip. |
+- edit shot 3 and re-queue → shots 1 and 2 load from cache, only 3 renders;
+- edit shot 1 → all three re-render, which is correct, not a bug;
+- change resolution, sampler, the checkpoint, a LoRA, or an attention setting →
+  the whole chain re-renders;
+- change `pin_to_qwen` or `overlap` → only hops 2+ re-render, because neither
+  can reach hop 1. A restart hop is a start, so overlap does not reach it either;
+- set `last_frame_guide=still` or `master_audio_file` → every hop re-renders
+  (both reach hop 1). `before_restart` only moves the hop that gets the guide;
+- change a reference picture → only the hops that picture rides re-render.
+
+That last one is worth knowing about. The node cannot read the settings on your
+LoRA and attention nodes, so it fingerprints what they *did* to the model —
+which weight keys were patched, at what strengths, and the attention overrides —
+plus the base model's class, dtype and parameter count. Two remaining gaps: two
+different LoRAs touching exactly the same keys at exactly the same strengths,
+and two different builds of the same architecture at the same dtype and
+parameter count.
 
-`@tags` in beats resolve per hop, so stills shifting to Picture 2+ does not break prose. Literal `<Picture N>` in hop 2+ beats would.
+Set `locked: true` on a shot to pin it to its last render regardless.
 
-## Last-frame guide
+### Reading a plan before you render it
 
-`last_frame_guide` plants `start_image` at a hop's last **pixel** frame
-(AddGuide `frame_idx=-1`, not latent T-1). It does not become the next hop's
-frame 0. Needs a start image. Ships `off`.
+`dry_run=on` compiles every hop's prompt and stops. No model, no sampler,
+seconds instead of minutes. The compiled text comes out on `info`, and as a
+readable page on `contact_sheet`. This is the only way to see what the text
+encoder will actually receive — the directive layer, the continuation
+scaffolding, the identity lock and the `<Picture N>` citations are all assembled
+at render time.
 
-**Reach for `before_restart`.** It guides only a hop whose *next* shot is
-`anchor=restart`. That restart opens on the same photograph, so both sides of
-the cut meet on one image and it reads as a match cut rather than a jump —
-hop 3 used to end tight and smiling, hop 4 open wide and neutral; with the
-guide, hop 3 *arrives* at the still's framing. Measured: the four hop endings
-of a 4-hop chain converge to 3.8/255 of each other against 39.1/255 unguided,
-while mid-hop frames stay as varied as ever (65.8 against 61.1). Two people
-watched it in motion and could not see the convergence.
-
-**`still` is the "I know what I am doing" setting.** It plants the photograph
-on every hop, unconditionally. A shot authored `framing: close` plays as a
-close-up for six seconds and then snaps to the still's wider framing in about
-0.6 s at its ending. Then the next hop pushes back in. Then snaps again. A
-user watching this described it, unprompted, as "the camera kept cutting in
-and out." Frame-by-frame from that run, hop 3, `framing: close`:
+![`lock` and the range button on the shot cards](https://media.githubusercontent.com/media/dntpi/ComfyUI-Hand-Tie-Clips/main/docs/img/shot-lock-range.png)
 
-    1.58s close   3.67s close   4.92s close   5.96s close-ish   6.58s WIDE   7.04s WIDE
+`render_through=N` stops after N hops; with `cache_hops=on`, 3 → 5 → 8 builds a
+chain up in stages and only ever renders the new hops. The plan is not
+truncated: shot 4 still knows it is shot 4 and keys the same way it will in the
+full run.
 
-Safe when no shot authors a framing; visibly wrong when they do.
+`quality=draft` forces the 448p tier and 6 steps. Treat it as a **fidelity**
+lever rather than a speed one — measured at ~42 s/hop against ~45 s/hop at 7
+steps, so if you already render at 448p and 6–8 steps it saves almost nothing
+and `dry_run` is the fast button. Draft earns its place when your final is
+genuinely heavier, 768p at 14 steps.
+
+`contact_sheet=on` adds an image on the fourth output: one row per hop, that
+hop's first and last **delivered** frame side by side, its beat, its directives,
+and what actually happened to it. On a chain of any length this is the fastest
+way to find the hop that broke.
+
+![Contact sheet](https://media.githubusercontent.com/media/dntpi/ComfyUI-Hand-Tie-Clips/main/docs/img/contact-sheet-vlog.png)
 
-## Defaults
+### Defaults
 
 | | |
 |---|---|
@@ -738,60 +686,134 @@ Safe when no shot authors a framing; visibly wrong when they do.
 | cache budget | 20 GB |
 | tone_compensate | off (both shipped workflows set `frame_shift`) |
 | tone_anchor | 0.35, used only by `tone_compensate=anchor` |
-| tone_anchor_ref | `hop1` (holds hop 1's already-short copy). `still` holds the photograph; needs a start image |
+| tone_anchor_ref | `hop1`. `still` holds the photograph; needs a start image |
 | pin_mech | `auto` |
 | last_frame_guide | `off`. Recommended `before_restart` when the plan has a restart |
-| master_audio_file | empty (generated voice). A set file is the lip-sync lock |
+| master_audio_file | empty (generated voice) |
 | quality | final |
 
-Three shots at 10 s with a 0.9 s overlap is about 28 s of master after the overlap is dropped.
+Three shots at 10 s with a 0.9 s overlap is about 28 s of master.
+
+### Nodes
+
+**H3 Ref2VA Chain** — `images`, `audio`, `info`, `contact_sheet` out. Wire
+`CreateVideo` + `SaveVideo` as in the example workflow, `info` to a Preview Text
+node, and `contact_sheet` to a Save Image.
+
+**H3 Chain Preview** — a passthrough panel for the IMAGE (and optionally AUDIO)
+wire, placed between the chain and `CreateVideo`. Images and audio come out
+unchanged, so adding or removing it changes no pixels. It shows the live sample,
+the seam, a chain-wide progress bar, cache hit / seed / steps per hop, **which
+pin mechanism each hop actually used**, and end-of-run A/V drift.
+
+**H3 Tone Compensate** — `images` out. **For hand-built chains only.** It cannot
+fix `H3 Ref2VA Chain`'s output: that node joins its hops internally and drops
+each hop's first `overlap` frames at the seam, so the regenerated copies this
+needs are already gone. Use the chain node's `tone_compensate` widget instead.
+
+**H3 Seam Report** — `report` (STRING) + `chart` (IMAGE). **Ships wired on the
+Starter canvas.** Wire the chain's `info` into it as well as `images`: with a
+restart in the chain the hop lengths are no longer uniform, and the `hops` /
+`overlap` widgets cannot describe that. It measures the brightness step at every
+join, says whether each is invisible / marginal / visible, and totals the
+chain's cumulative drift. A single reading includes whatever the scene did
+across the cut, so treat one number as an upper bound.
+
+**H3 Continuity State** — `continuity_state` (STRING) out. **Setting only**:
+`setting_locked` / `setting_context` / `setting_mutable`. Characters belong in
+`ref_plan`.
+
+### Limits
+
+- **Texture still ratchets on long chains.** Stay around **3–5 hops** until that
+  is handled. Nine-hop chains have been measured; they converge.
+- A workflow saved before 2026-08-28 loses its reference pictures. The old
+  `ref_image_N` sockets carried tensors, so there is no filename to recover.
+  The rail names each affected ref and asks you to pick its picture.
+- The reference `desc` and subject `locked` text go to the encoder verbatim,
+  every hop. A detail that is not in the photograph is **asked for**, not
+  ignored. Describe what you actually wired.
+- `HTCContinuityState` is setting only; the `characters_*` fields were removed
+  because filling in both injected identity text twice.
+- Each join hard-cuts video but crossfades audio ~40 ms, so A/V drifts ~40 ms
+  per hop.
+- A 22-frame pin clip is ~2 Qwen frames at 2 fps. It is a live-state hint, not a
+  full previous-clip watch.
+- A longer overlap does not fix continuity — it can pin whatever content happens
+  to be in that longer tail.
+- A 5 s hop drops the airlock on a continuous join; validate seams at 8 s or 15 s.
 
-## Voice, music and trims
-
-The **MEDIA** strip takes a first frame, up to three look reference clips, up
-to three voice references, a music bed, and an optional **master audio** take
-every hop lip-syncs to — all files under `input/h3_refs`, all picked in the
-panel, none of them a `Load Image` node you have to wire. Empty master audio
-is off and leaves generated voice as before.
-
-![The MEDIA tab with a reference clip loaded](https://media.githubusercontent.com/media/dntpi/ComfyUI-Hand-Tie-Clips/main/docs/img/reference-clip.png)
-
-*A reference clip with its in/out scrubber, the description that tells the encoder what the clip is **for**, and `video input size` -- which decodes the plate straight to the size you pick instead of loading it at source resolution first.*
-
-Each audio slot has a scrubber with an in/out window, and it is worth using.
-H3 encodes the **whole** voice file into the conditioning with no cap, and every
-latent frame of it is attended over on every step of every hop — so a
-three-minute take is a large invisible tax on a clip that only needed four
-seconds. The soundtrack window is cut from the track first, then `music_fit`
-loops or trims that to the chain, which is what stops a mastered track always
-starting the chain on its intro.
-
-An end of `0` always means *to the end of the file*, so a longer replacement
-file still plays out rather than being silently cropped to the old one.
-
-## Limits
-
-- **A workflow saved before 2026-08-28 loses its reference pictures.** The old `ref_image_N` sockets carried tensors, so there is no filename to recover. The rail names each affected ref and asks you to pick its picture; nothing else about the plan is lost.
-- Shot-level `refs` is a choice, default omitted. A ref still activates itself through its own `shots` list; the shot field overrides that list for one hop, including the empty list (no stills). Unknown tags fail on the queue.
-- The reference `desc` and subject `locked` text go to the encoder verbatim, every hop. At cfg 1.0 there is no negative branch, so a detail that is not in the photograph is **asked for**, not ignored. Describe what you actually wired.
-- `HTCContinuityState` is **setting only**. Characters live in the reference register; the node's `characters_*` fields were removed because filling in both injected identity text twice.
-- Each join hard-cuts video but crossfades audio ~40 ms, so A/V drifts ~40 ms per hop.
-- Texture still ratchets on long chains. Stay around 3–5 hops until that is handled.
-- A 22-frame pin clip is ~2 Qwen frames at 2 fps. It is a live-state hint, not a full previous-clip watch.
-- A longer overlap does not fix continuity — it can pin whatever content happens to be in that longer tail.
-
-## Nodes
-
-**H3 Ref2VA Chain** — `images`, `audio`, `info`, `contact_sheet` out. Wire `CreateVideo` + `SaveVideo` as in the example workflow, `info` to a Preview Text node, and `contact_sheet` to a Save Image.
-
-**H3 Chain Preview** — a passthrough panel for the IMAGE (and optionally AUDIO) wire, placed **between the chain and `CreateVideo`**. Images and audio come out unchanged, so adding or removing it changes no pixels. It shows the live sample, the seam (the previous hop's last frame beside this hop's first), a chain-wide progress bar, cache hit / seed / steps per hop, **which pin mechanism each hop actually used** — a latent Motion-Context pin or the AddGuide pixel fallback — and end-of-run A/V drift. Drag the grip to resize the stats panel; double-click it to reset.
+---
 
-**H3 Tone Compensate** — `images` out. Corrects a generated segment's tone against the previous one, estimated on the overlap they share. **For hand-built chains only.** It cannot fix `H3 Ref2VA Chain`'s output: that node joins its hops internally and drops each hop's first `overlap` frames at the seam, so the regenerated copies this needs are already gone by the time images leave it. Use the chain node's `tone_compensate` widget instead. Estimator ported from [rkfg/ComfyUI-MiniMaxH3-ToneCompensate](https://github.com/rkfg/ComfyUI-MiniMaxH3-ToneCompensate) (MIT).
+## Credits
+
+From the **Sulphur** Discord:
+
+- **@urlilgoddess** — the ten-run degradation study this release is built on,
+  run and measured with her own instruments, and the sample frames in
+  [Tested in public](#tested-in-public). Three of 2.0's behaviours exist because
+  she measured that the reasoning behind the old ones was wrong.
+- **@frankyi** — contributed the SWAP tab, which ships in 2.0 rebuilt from its
+  own design rather than merged as-is.
+- **@Sean3884** — author of **PromptMasterLD**, which this pack has borrowed
+  from twice: its `song_lock` shaped `audio_lock.py`, and its edit laws shaped
+  SWAP's four modes. Technique, not code — the distinctions and the discipline
+  of stating an exclusion affirmatively, with the prose written fresh here.
+
+Also: the tone estimator is ported from
+[rkfg/ComfyUI-MiniMaxH3-ToneCompensate](https://github.com/rkfg/ComfyUI-MiniMaxH3-ToneCompensate)
+(MIT, as is this pack), and the latent join comes from
+[ComfyUI-H3-Motion-Context](https://github.com/NikoDemon80/ComfyUI-H3-Motion-Context).
+The turbo stack in the shipped workflows is
+[PlagueKind](https://github.com/PlagueKind/ComfyUI-PlagueKind-Nodes) and
+[KJNodes](https://github.com/kijai/ComfyUI-KJNodes).
 
-**H3 Seam Report** — `report` (STRING) + `chart` (IMAGE). **Ships wired on the Starter canvas.** Set `hops` to your shot count: it derives hop length from frames, hops and overlap, so a wrong `hops` does not error — it returns a plausible length and puts every seam where no join exists. Wire the chain's `images` into it and it measures the brightness step at every join, says whether each is invisible / marginal / visible, and totals the chain's cumulative drift. A single reading includes whatever the scene did across the cut — the frames either side are ~0.9 s apart in scene time — so treat one number as an upper bound; to isolate the seam itself, render twice from the same seed and cache changing only `tone_compensate`, and compare.
+## Docs
 
-**H3 Continuity State** — `continuity_state` (STRING) out. **Setting only**: `setting_locked` / `setting_context` / `setting_mutable`. Characters belong in `ref_plan`.
+[`CHANGELOG.md`](CHANGELOG.md) is what 2.0.0 contains, written for users.
+[`PROMPTING.md`](PROMPTING.md) is the authoring guide. [`CLAUDE.md`](CLAUDE.md)
+is the current map of the pack if you are changing it, and `docs/DEVLOG.md` is
+the engineering log. `docs/HANDOVER_*.md`, root `HANDOVER.md` and `BETA_NOTES.md`
+are historical session notes — do not take them as the state of this release.
 
-## Docs
+---
 
-[`CHANGELOG.md`](CHANGELOG.md) is what 2.0.0 contains, written for users. [`CLAUDE.md`](CLAUDE.md) is the current map of the pack if you are changing it. `docs/DEVLOG.md` is the engineering log. `docs/HANDOVER_*.md`, root `HANDOVER.md`, and `BETA_NOTES.md` are historical session notes — do not take them as the state of this release.
+## Changelog
+
+Full notes in [`CHANGELOG.md`](CHANGELOG.md).
+
+**2.0.0** — 2026-09-05. Full release. `master_audio_file`, one continuous take
+every hop lip-syncs to. `last_frame_guide` (`before_restart` recommended).
+`anchor: "restart"` as a real chain start, now writing its full length. `refs`
+on a shot. The **SWAP** tab. Three reference-clip and three voice slots. A Lab
+tone anchor with `tone_anchor_ref=still`. `pin_mech`. A hop cache that no longer
+pickles, and an fp16 master buffer that halves the largest allocation in the
+pack. New widgets were appended, so saved 1.1 graphs keep their values — but a
+1.1 *hop cache* is fully invalidated on purpose, because the model fingerprint
+now identifies the base checkpoint.
+
+**1.1.x** — 2026-09-03/05. Tabbed editor with RUN pinned at the bottom.
+`render_from` / `render_through` as a range. `retention_analysis` on every hop a
+still rides, which fixes a reference pinned to any hop but the first being
+rendered *as* the shot. Computed canvas — eleven aspect ratios on H3's 32 px
+grid, so 16:9 at the top rung is 1344×768. Per-hop reference keys, so changing
+one picture re-renders only the hops it rides. 1.1.1 passes every Core argument
+by name, fixing `got multiple values for argument 'ref_image_size'` on builds
+that order MiniMax H3's parameters differently.
+
+**1.0.x** — 2026-09-02. First full release: the **WRITE** panel, the required
+two-document schema, the reference rail owning each picture's pixel budget, and
+the writer being told the hop length. Three plan lints were measured against
+real renders, found to be warning about correct work, and narrowed. Patch
+releases fixed the "no model is selected" bug on a fresh install and cleared
+registry-scanner findings.
+
+**0.4.x** — 2026-08-30. The five new dials reached the run panel; a dry run
+stopped returning a 1×1 placeholder that libx264 cannot encode. The prompt pack
+learned to show a place tag on both sides of its round trip. The hop cache
+stopped shelling out to `ffmpeg` and encodes FFV1 in process through PyAV —
+same format, bit-exact, and no external command for the registry scanner to flag.
+
+**Renamed 2026-08-29** from `ComfyUI-H3-Ref-Chain`. The old node ids are still
+registered as deprecated aliases, so every workflow saved before the rename
+keeps loading. Nothing needs migrating.