Reference Library Organizer

---
name: reference-library-organizer
description: >-
  Understands and organizes a project's references into 01_REFERENCES: EXTERNAL (found films, art, ads, photos, motion refs:
  look only, never shipped), INTERNAL (our own character, location, prop and style references, split into LOCKED vs
  CANDIDATES), PROMPTS (reference prompts with "why it works" notes) and PERSONAL (real people's photos and voice samples:
  never copied or pulled out, only indexed where they already are). Classifies each file from its name, folder, source URL,
  camera metadata and the generation log, then LOOKS at contact sheets to decide what the names cannot tell. Every reference
  gets a stable id (R012), a role line ("look only", "face and outfit only, never its background"), its source and the shots
  that use it, in REFERENCES_INDEX.csv. Also locks a candidate, records usage, and runs a leak check that fails if any
  external or personal reference sits inside a delivery, final output or public repo. Use when the user drops references,
  says "organize the references", "which refs are ours", "what is approved", "sort the moodboard", before building a
  reference set, and before any delivery or public push. Includes scripts/refs.py.
user-invocable: true
---

# Reference Library Organizer

References do different jobs and carry different risks. A film still is there for its light and palette and must never
end up in a deliverable. An approved character sheet is the identity anchor for every later shot. A real person's photo
is private. The library makes that difference visible on disk and in one index.

## The library

```
01_REFERENCES/
  REFERENCES_INDEX.csv     id, origin, class, state, file, original, hash, role, used_in, source_url, author, license, notes
  EXTERNAL/
    FILM/ ART/ ADS/ PHOTO/ MOTION/ OTHER/     R012_FILM_<name>.jpg
  INTERNAL/
    CHARACTERS/{LOCKED,CANDIDATES}/  LOCATIONS/{…}/  PROPS/{…}/  STYLE/{…}/
  PROMPTS/                 R031_PROMPT_<name>.md
  PERSONAL/                empty on purpose: personal files stay where they are, the index points at them
  _sheets/                 contact sheets used to classify by eye
```

| origin | what it is | default role | may leave the project? |
|---|---|---|---|
| EXTERNAL | material we do not own: film stills, artwork, other brands' ads, stock/photo, motion refs | look only: palette, light, composition; never its people, logos or text | never |
| INTERNAL | made by us: character sheets, location plates, room maps, prop sheets, style frames, keyframes | set per file: "face and outfit only", "room layout only"… | yes, LOCKED ones, when the user ships them |
| PROMPTS | prompt texts worth copying, ours or found | pattern to copy, with why it works | ours yes, found ones no |
| PERSONAL | real photos or voice of real people (the user, cast, clients) | identity only; private | never; not even copied inside the project |

## Workflow

1. **Scan** (copies nothing):
   ```
   python3 scripts/refs.py scan --project "<project>" --src "<refs folder>" [--src "<dir>=EXTERNAL/FILM"] [--src "<dir>=INTERNAL/CHARACTERS/LOCKED"]
   ```
   Writes `_refs_plan.csv` with a guess and the reason for each file, plus `_sheets/sheet_NN.jpg` (12 cells, left to
   right, top to bottom) with the matching `sheet_NN.txt` list of ids. Already indexed files (same content) are skipped,
   so re-scans only show what is new.
2. **Look at every sheet** (Read the jpg). The names cannot tell what a picture is; the picture can. For each cell decide:
   - origin: generated by us (INTERNAL) or found (EXTERNAL)? Watermarks, platform UI (arrows, like buttons), poster credits
     and real-camera photos mean EXTERNAL. A real person's own photo means PERSONAL;
   - class: CHARACTERS / LOCATIONS / PROPS / STYLE, or FILM / ART / ADS / PHOTO / MOTION / OTHER;
   - state for INTERNAL: LOCKED only if the user approved it (or it is already used as an identity anchor), else CANDIDATES;
   - a role line for anything that will be attached to a generation.
   Write the decisions into `_refs_plan.csv`. Set `origin` to `SKIP` for junk.
3. **Show the user a short summary** (counts per origin/class, the PERSONAL list, every INTERNAL marked LOCKED) and ask only
   about the doubtful ones. Do not ask about each file.
4. **Apply after a yes:**
   ```
   python3 scripts/refs.py apply --project "<project>"           # copies; --move only on the user's explicit request
   ```
   Undecided rows stay in the plan for the next round.
5. **While producing:**
   - `refs.py use --project P --id R020 --shot S03 --role "face and outfit only"` every time a reference goes into a prompt.
   - `refs.py lock --project P --id R020` when the user approves a candidate. The candidate copy stays; LOCKED gets its own.
   - Attach only LOCKED internal refs as identity/location anchors. Candidates and external refs never anchor identity.
6. **Before any delivery, final export, post or public push:**
   ```
   python3 scripts/refs.py leak --project P --path "<folder about to leave>"
   ```
   FAIL lists every external or personal reference found in that folder by content. Stop and tell the user.

## Rules

- English only: folder names, ids, classes, roles, notes.
- PERSONAL files are never copied, moved, uploaded or put on a contact sheet that leaves the project. They are indexed by
  path where the user keeps them. Sending one to a generator happens only when the user asks for that shot.
- EXTERNAL references keep their source: fill `source_url`, `author`, `license` when known (sidecar .txt/.url next to the
  file is read automatically).
- Never rename or delete the user's original folders. The library is a copy unless the user asks to move.
- A role line is mandatory for every reference that is attached to a generation: it tells the model what to take and what
  to ignore. See `reference-roles-leak-check` and `reference-style-builder`.

## Related skills

`project-scaffold` (creates 01_REFERENCES), `reference-style-builder` (builds the style card and the reference set),
`character-identity-lock-setup`, `detail-reference-intake`, `generation-log` (marks what we generated, which makes it
INTERNAL), `delivery-package` (runs the leak check).