Expand H3 reference-node documentation

H3_LONG_VIDEOS_GUIDE.md

@@ -891,6 +891,77 @@ The node uses reference data in two different ways:
 
 Character refs can now contribute actual image identity when the beat names the character, not just when you explicitly tag the picture slot.
 
+### Character Reference Node: what the fields actually do
+
+`Dumas Character Reference` packages one image plus metadata into one `REFERENCE` socket.
+
+What the long-videos code actually uses:
+
+- `image`: the real reference image H3 sees when that slot is selected for a shot
+- `name`, `character_id`, `alias`: used for character-name matching in beat text
+- `description`: injected as persistent appearance text when that character ref is matched
+- `wardrobe`: injected as persistent wardrobe text when matched, and also used to seed `character_memory` if the long-videos node field is blank
+- `general`: injected as extra character notes when matched
+- `gender`, `age`, `nationality`, `occupation`, `height`, `accent`: turned into one "Character facts" sentence when matched
+
+What this means in practice:
+
+- the image and the text metadata are separate channels
+- a character image can still condition a shot even if its metadata was not injected into the beat text
+- wardrobe from character refs is only promoted into live tracked wardrobe state when `character_memory` is empty
+
+### When character data gets used
+
+There are three different moments:
+
+1. Shot ref routing chooses whether the character image is attached to that beat at all.
+2. Text matching decides whether the character metadata is injected into that beat text.
+3. Chain-state seeding decides whether the character ref wardrobe becomes the starting `character_memory`.
+
+The important detail is that these do not always happen together.
+
+Character image conditioning:
+
+- happens according to `ref_mode`
+- can be forced with `<Picture N>`
+- can also be pulled in by naming the character in the beat
+
+Character text metadata injection:
+
+- happens only when the beat explicitly tags the slot with `<Picture N>`
+- or when the beat mentions the character by `name`, `id`, or `alias`
+
+Character wardrobe seeding:
+
+- happens once at chain setup
+- only if the long-videos `character_memory` field is blank
+- only for character refs that actually contain wardrobe text
+
+### Location Reference Node: what the fields actually do
+
+`Dumas Location Reference` is simpler. It packages one environment image plus environment metadata into one `REFERENCE` socket.
+
+What the long-videos code actually uses:
+
+- `image`: the real location reference image H3 sees when that slot is selected for a shot
+- `description`: injected as location context when that slot is explicitly tagged
+- `general`: injected as location notes when that slot is explicitly tagged
+- `name`, `location_id`, `alias`: used mainly as labels in summaries and injected sentences, not for automatic prose matching
+
+Important difference from character refs:
+
+- location refs are **not** auto-matched from location names in beat prose
+- if you write `in the cafe` and do not tag `<Picture N>`, the location image may still be in the shot because of `ref_mode`, but the location text metadata is not auto-injected just from that name
+
+### When location data gets used
+
+Location node data has two separate paths:
+
+1. The location image can be attached to shots through normal ref routing.
+2. The location text metadata is only injected when you explicitly tag that slot with `<Picture N>`.
+
+So location references are more tag-driven than character references.
+
 Simple usage patterns:
 
 - one character, no special routing: use `auto ref2v`
@@ -904,6 +975,96 @@ What to remember:
 - location refs are often tagged because they are about where the shot happens
 - character refs are often named because they are about who is in the shot
 
+### Scenarios
+
+### Scenario: one hero character, no location ref
+
+Setup:
+
+- `ref_1` = Maya character reference
+- beat text says `Maya crosses the road and looks back`
+- `ref_mode = auto ref2v`
+
+What happens:
+
+- Maya's image is attached to the shot
+- Maya's character metadata is injected because the beat names `Maya`
+- if `character_memory` is blank, Maya's `wardrobe` field also seeds the live wardrobe tracker at chain start
+
+### Scenario: two characters plus one tagged location
+
+Setup:
+
+- `ref_1` = Maya character reference
+- `ref_2` = Jon character reference
+- `ref_3` = warehouse location reference
+- beat says `Maya argues with Jon near the loading bay <Picture 3>`
+
+What happens:
+
+- Maya and Jon can be matched by name, so their character metadata can be injected
+- the warehouse location metadata is injected because `<Picture 3>` tags it
+- the image refs used on the shot still depend on `ref_mode`
+
+Why this pattern works well:
+
+- character refs can be driven by names
+- location refs usually need explicit tags when you want the environment text to be stated clearly
+
+### Scenario: location image works, but location notes do not seem to
+
+Setup:
+
+- `ref_3` = cafe location reference
+- beat says `They sit in the cafe window booth`
+- no `<Picture 3>` tag
+
+What happens:
+
+- with `auto ref2v` or `every shot`, the cafe image may still be conditioning the shot
+- but the location `description` and `general` fields are not auto-injected from the word `cafe`
+
+What to do:
+
+- add `<Picture 3>` on the beat where the location wording matters
+
+### Scenario: character face is partly right, but identity is weak
+
+Setup:
+
+- character refs are connected
+- beat prose uses `she` and `he`, but never names the characters
+- `character_memory` contains clothing and height-like facts
+
+What happens:
+
+- the beat can still pick up some tracked wardrobe/state language
+- but the strongest character-ref match path is weaker because the beat is not naming the people
+- that can produce "same role, wrong face" results
+
+What to do:
+
+- name the characters in the beat, or tag their slots explicitly
+- keep `ref_noise_aug` high
+- use `every shot` when identity matters more than soft continuity
+
+### Scenario: character wardrobe from the ref node does not update later
+
+Setup:
+
+- character ref has wardrobe filled in
+- long-videos `character_memory` is also filled in with different clothing
+
+What happens:
+
+- the long-videos `character_memory` wins as the live starting wardrobe state
+- the wardrobe field inside the character ref is still usable as injected descriptive text when matched, but it does not replace the explicit `character_memory` sheet
+
+What to do:
+
+- put the canonical changing outfit in `character_memory`
+- treat character-ref wardrobe as a fallback/default seed, not the main changing state source
+
 ### If faces drift or people turn into random lookalikes
 
 Check these in this order: