> ## Documentation Index > Fetch the complete documentation index at: https://ralphy.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Brands, personas, and refs > When to lock identity. How to attach brands, personas, and reference images, and when the ref gate refuses to budge. The three entities on this page exist for one reason: keeping identity stable across scenes and across projects. A brand carries the logo, palette, and tone across every video you make for one client. A persona is the recurring on-screen character — the founder, the spokesperson, the cartoon mascot — whose face needs to match between scene-01 and scene-04. A reference is the locked image Ralphy passes as `--ref` on every generate call so the model can't drift away from "this exact bottle / this exact face / this exact room". Get the identity pattern right and you stop fighting model drift; get it wrong and every regen invents a different couch. ## Brands — for multi-project consistency A brand is the entity you reuse across projects. Create one when you'll be making more than one video for the same client or product line. ```bash theme={"dark"} ralphy brand create \ --name "Cinnamon Cold Brew" \ --slug cinnamon-cold-brew \ --palette "#7c3a0f,#fff4d6,#1a1a1a" \ --tone "warm, conversational, autumn-cozy" ``` The brand object lives in the workspace `shared/brands/` tier (`.ralphy/workspaces//shared/brands/.json`) and carries the logo, palette, tone, and optional default persona. Reference it on any project create: ```bash theme={"dark"} ralphy project create --name "Syrup launch hero" --brand cinnamon-cold-brew --id syrup-001 ``` Downstream prompts pick up the brand's palette and tone automatically. You don't have to retype "warm, autumn-cozy" into every prompt. ## Personas — for recurring characters A persona is the on-screen human (or cartoon, or AI avatar) that has to look the same in every scene. Create one when more than one scene shows the same character, or when you'll reuse the character across projects. ```bash theme={"dark"} ralphy persona create \ --name "Anna the barista" \ --slug anna-barista \ --archetype "creator-friend" \ --voice-id elevenlabs-voice-xyz \ --master-shot shared/personas/anna-barista/master.png ``` The `master-shot` is the canonical reference image — the locked face Ralphy passes as `--ref` on every scene gen so identity doesn't drift between scene-01 and scene-04. The eight named archetypes live in [`docs/creative-library/personas/ARCHETYPES.md`](https://github.com/alecs5am/ralphy/blob/main/docs/creative-library/personas/ARCHETYPES.md). Attach a persona to a project at create time, or pass `--persona ` on a `template use` call: ```bash theme={"dark"} ralphy template use ugc-selfie-product-review \ --project syrup-001 \ --persona anna-barista ``` ## References — the per-call lock A reference is a single image (or multiple) you pass to a `generate` call with `--ref`. Ralphy converts a local path to a `data:` URI automatically; a URL passes through. Two patterns matter: **The master-shot pattern.** Lock the product and the persona as standalone images first, then pass them as `--ref` on every scene gen. This is the single highest-leverage technique in the art-director playbook — multi-scene projects without master refs spend real money on "they keep sitting on different couches" or "the bottle label changed shape between scenes". ```bash theme={"dark"} # 1. Generate the product master shot once. ralphy generate image \ --project syrup-001 \ --slot product-master \ --prompt "750ml amber syrup bottle, kraft label, cinnamon-stick illustration, studio lighting, 1:1" # 2. Lock the persona master shot. ralphy generate image \ --project syrup-001 \ --slot persona-master \ --prompt "Anna the barista, 30s, warm smile, kitchen lighting" \ --ref shared/personas/anna-barista/master.png # 3. Every downstream scene passes BOTH as --ref. ralphy generate image \ --project syrup-001 \ --slot scene-02-bg \ --prompt "Anna pours syrup into iced coffee, kitchen counter, autumn morning light" \ --ref .ralphy/workspaces/default/projects/syrup-001/assets/product-master.png \ --ref .ralphy/workspaces/default/projects/syrup-001/assets/persona-master.png ``` **Multi-ref.** Most image models accept multiple `--ref` flags. `gemini-3-pro-image-preview` is the default and the canonical multi-ref model — it holds face / wardrobe / product identity across 2-3 refs and tolerates ≥4 concurrent calls. Switch to `gpt-5.4-image-2` only when label typography on a hero product shot must read crisp (it caps at 1 concurrent). See [Generating assets](/working/generating-assets) for the per-modality model picks. ## The reference-required gate This is [AGENTS invariant #3](https://github.com/alecs5am/ralphy/blob/main/AGENTS.md). Read it once and the rest of this section makes sense. The gate fires for **named real entities the model cannot fabricate** — and only those: * A specific person ("Elon Musk", "Cristiano Ronaldo", your own face). * A recognizable brand product ("Coca-Cola can", "iPhone 16", "Old Spice bottle"). * A recognizable IP ("Mickey Mouse", "Pikachu", "Iron Man"). When the gate fires and no reference is attached, Ralphy refuses to generate. You get a concrete ask: either attach a reference image, or pass `--no-ref-consent ""` on the specific failing call. The gate does **not** fire for generic product or lifestyle work. "My coffee shop's new pastry", "a no-name workout app", "a barista named Anna" — these proceed without a ref because there's no real-world identity for the model to fabricate. The CLI floor is `ralphy ref check [--text ""]`, which runs an offline classifier (no LLM cost) over the scenario and brief. ```bash theme={"dark"} ralphy ref check syrup-001 # → { "needs_reference": false, "reasons": [], "entities": [] } ``` ```bash theme={"dark"} ralphy ref check oldspice-relaunch-001 # → { "needs_reference": true, "reasons": ["named-brand-product"], "entities": ["Old Spice"] } ``` ## The `--no-ref-consent` override When the gate fires but you genuinely want to proceed without a reference — maybe you're sketching a comp, maybe the model handles the entity well enough for your purposes, maybe you'll attach the ref later — pass `--no-ref-consent ""` on the failing call: ```bash theme={"dark"} ralphy generate image \ --project oldspice-relaunch-001 \ --slot scene-01-bg \ --prompt "Old Spice deodorant on bathroom counter, morning light" \ --no-ref-consent "comp pass — will lock the real bottle ref before final" ``` The string after `--no-ref-consent` is mandatory and must be non-empty. The CLI appends a `stage: "no-ref-consent"` entry to `user-prompts.jsonl` for that project so the next session — and your future self — can see you deliberately accepted the quality hit. See [Generation log](/concepts/generation-log) for the JSONL contract. `--no-ref-consent` is per-call. It does not propagate to the next `generate` invocation. If you want to skip the gate on three calls, pass the flag three times — that's a deliberate friction point so you can't accidentally turn the gate off for an entire batch. ## Attaching refs after the fact If you attached refs late and want them logged for the gen-log trail, use `ralphy project log-asset`: ```bash theme={"dark"} ralphy project log-asset syrup-001 \ --kind ref-url \ --source https://example.com/canonical-bottle.png \ --purpose product-ref \ --note "official packshot from the client" ``` This appends to `user-assets.jsonl` — append-only, never overwrites, like every other log under `.ralphy/workspaces/default/projects//logs/` ([AGENTS invariant #13](https://github.com/alecs5am/ralphy/blob/main/AGENTS.md)). ## Editing a brand or persona The standard CRUD verbs work on brand and persona just like every other resource: ```bash theme={"dark"} ralphy brand list -p ralphy brand show cinnamon-cold-brew -p ralphy brand update cinnamon-cold-brew --tone "warm, conversational, with a wink" ralphy persona update anna-barista --master-shot path/to/new-master.png ``` Updates are write-in-place on the brand or persona record itself. They do **not** touch projects that already reference the brand or persona — your existing renders stay as they were. If you want the new tone reflected in `syrup-001`, you have to regenerate the affected slots; Ralphy never silently re-renders past work. ## Related * [References concept](/concepts/references) — what the gate classifier checks * [Brands and personas concept](/concepts/brands-personas) — the data model * [Generating assets](/working/generating-assets) — where `--ref` is passed * [Generation log](/concepts/generation-log) — how `--no-ref-consent` is recorded * [`AGENTS.md`](https://github.com/alecs5am/ralphy/blob/main/AGENTS.md) — invariant #3, the gate * [`art-director/ref-photo-policy.md`](https://github.com/alecs5am/ralphy/blob/main/docs/playbooks/art-director/ref-photo-policy.md) — the playbook for ref policy