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.
The brand object lives in the workspace shared/brands/ tier (.ralphy/workspaces/<ws>/shared/brands/<slug>.json) and carries the logo, palette, tone, and optional default persona. Reference it on any project create:
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.
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.
Attach a persona to a project at create time, or pass --persona <slug> on a template use call:
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”.
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 for the per-modality model picks.
The reference-required gate
This is AGENTS invariant #3. 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 "<reason>" 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 <project-id> [--text "<brief>"], which runs an offline classifier (no LLM cost) over the scenario and brief.
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 "<reason>" on the failing call:
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 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:
This appends to user-assets.jsonl — append-only, never overwrites, like every other log under .ralphy/workspaces/default/projects/<id>/logs/ (AGENTS invariant #13).
Editing a brand or persona
The standard CRUD verbs work on brand and persona just like every other resource:
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.
