Caret Imagine · backend behavior

Generate the same person twice.

Ask an image model for “my sister at the beach” and you get a stranger — a different stranger every time. Identity is not something a text prompt can carry. The fix is boring and it works: collect real photographs of the people and things you care about, distil each subject into one reference sheet, and pass that sheet to the image model whenever the user names that subject.

Imagine is the Caret surface where this belongs. The keyboard sends a prompt over the /imagine route and expects one image back; everything between those two points is yours. References are entirely a backend behavior — the contract does not change, no new route appears, and a backend without references stays perfectly valid.

What you are building

Two behaviors, and they are separate on purpose.

1 · Collect the source photos

Aim for 8–15 photographs per subject. Fewer than eight and the sheet starts inventing; more than fifteen mostly adds redundancy and cost. Cover this spread:

• Angles. Straight-on front, left three-quarter, right three-quarter, and at least one true profile. The three-quarter and profile shots are what teach the model the shape of a nose, a jaw, a brow — the parts a front photo flattens away.
• Expressions. Neutral, smiling, and serious. A face at rest and a face in motion are different faces; give it both.
• 1–2 full-body shots, standing, whole figure in frame. This is what fixes height, build, and proportion.
• 2–3 different outfits, so the model learns the person rather than the sweater. A set shot in one afternoon produces a reference sheet that can only draw that afternoon.
• Relevant detail shots. Anything a stranger would need pointed out: glasses they always wear, a tattoo, a scar, a distinctive hairline, freckles, a piece of jewellery that is part of the person.

2 · Quality rules for the source photos

The set is the ceiling on everything downstream. Reject:

• Anything soft, blurry, or motion-smeared. Sharp and in focus, always.
• Bad light — harsh shadow across the face, blown-out highlights, heavy backlight, extreme colour casts. Even, natural light wins.
• Sunglasses, masks, hands, hair, or hats covering the face. One or two shots with everyday glasses are useful; a set shot entirely in sunglasses is not.
• Beauty filters, smoothing, heavy retouching, and stylised presets. They teach the model a face that does not exist.
• Group shots and anything with a second face in frame — the model cannot know which person you mean. Crop tightly to one subject per photo.
• Tiny faces. If the head is a small fraction of the frame, there is no detail to work with. Use the highest resolution originals you have, not screenshots or re-compressed copies from a chat thread.

And keep the set from one era. Photographs spanning a decade, a major weight change, or four hairstyles average into someone who is nobody. Pick the current era and stay in it. Vary background and setting across the set, but not the person.

3 · Generate one reference sheet per subject

Feed the whole approved set to your image model and produce a single image: six large panels in a clean grid, one subject, consistent identity across every panel.

Non-negotiable properties of the sheet:

• Large panels. Six panels, not twelve. Each one must carry real facial detail at full resolution — a contact sheet of thumbnails is useless as a reference.
• Plain studio background, neutral light grey or white, the same in every panel, with even, soft, consistent lighting. The background is not the subject and must not be learned as part of it.
• No labels, captions, numbers, watermarks, or text of any kind. Image models read text in a reference image as content and leak it into the pictures you generate later.
• One outfit and one grade. Same clothing, same colour treatment across all six panels, so the only thing the sheet asserts is the subject.

Show the sheet to the user before you save it. If a panel is off — wrong nose in profile, a face that drifts between panels — fix the source set and regenerate. A bad sheet is worse than no sheet, because it is consistently wrong.

4 · Store it under a clear name

One directory per subject, holding the approved sheet, the originals it was built from, and a small metadata record. Any store works — this shape is the point, not the filesystem.

references/
  ada/
    sheet.png          the approved six-panel sheet — the only thing sent to the model
    sources/           the originals, kept so the sheet can be rebuilt
    meta.json

{
  "name": "ada",
  "kind": "person",
  "aliases": ["ada b", "my sister", "my sister ada"],
  "sheet": "sheet.png",
  "source_count": 12,
  "created": "2026-08-18",
  "refreshed": "2026-08-18",
  "consent": "asked and given, 2026-08-17",
  "notes": "round tortoiseshell glasses, always"
}

Names are how the user reaches a reference, so make them unambiguous and predictable: short, lowercase, one subject each. Record the aliases the user actually says out loud — “my sister”, “the dog”, “my green mug” — because that is what will be in the prompt. Refuse a new name that collides with an existing one or with a common noun that will match by accident: a reference named cat will hijack every prompt containing the word cat.

5 · Generation behavior

On each Imagine request, in this order:

1. Scan the prompt for saved names and aliases. Case-insensitive, whole words only, longest match first so “my sister ada” does not resolve twice.
2. No match → no reference. Generate exactly what was asked for, with no reference image attached. This is the common case and it must stay fast and unsurprising.
3. Match → attach that subject’s sheet as an image reference to the model call, alongside the user’s prompt.
4. Several matches → attach each sheet if your model accepts multiple reference images. If it accepts one, ask the user which subject leads rather than silently picking.
5. Say what you used. Report the applied references back to the user — in the response text, a log line, or both. A reference that is applied invisibly is indistinguishable from a model that has started hallucinating someone the user knows.

Two prompt-craft rules once a sheet is attached. Refer to the subject by role — “the person in the reference image” — rather than re-describing their face in words; a text description of a face competes with the reference and the model splits the difference. And keep the rest of the prompt about the scene: pose, setting, light, style. The sheet handles identity, the prompt handles everything else.

prompt:     "the person in the reference image, sitting on a harbour wall
             at golden hour, 35mm, shallow depth of field"
references: [references/ada/sheet.png]
applied:    ada

If a subject is named but no sheet exists yet, do not improvise one mid-generation. Generate without it and tell the user the reference is missing, or offer to run setup — that is a deliberate, consented step, not something to do while they wait for a picture.

6 · Pets, objects, and places

The workflow is identical for anything you need to draw repeatably; only the six panels change.

• Pets. Front, both three-quarters, profile, a natural standing pose, and full body. Detail shots of markings, a torn ear, a collar. Coat patterns are the identity here — get them sharp.
• Objects. Front, back, both sides, top, and one detail shot of whatever makes this one yours: a chip in the glaze, a logo, a strap wear pattern. Include a scale cue if size matters.
• Places and rooms. Wide shot from each corner plus the details that define it. Expect less fidelity than faces or objects; rooms drift more, and it is honest to say so.

Naming, resolution, and “only when named” are exactly the same. Consent is the part that does not apply — a mug cannot object to being drawn.

7 · Consent, access, and privacy

A reference library is a folder of biometric-grade portraits of people who are not in the room when the images get generated. Treat it that way.

• Ask first. Store a person’s reference only with that person’s agreement — for friends, family, and colleagues alike, not just public figures. Record when consent was given, and honour a withdrawal by deleting the sheet, the sources, and the metadata together.
• Children are a higher bar. A parent’s consent, a narrow purpose, and a short retention window — or skip it.
• One owner per library. References belong to the person who created them. Do not share a library across users, do not let one user resolve another user’s names, and scope every lookup to the calling identity. On a multi-user backend this is an access-control boundary, not a convention.
• Least exposure at rest. Keep the library outside your source repository and out of backups that travel further than the subjects agreed to. Restrict file permissions to the service account that serves Imagine. Never log the images or their contents.
• Deletion has to be one step. “Forget Ada” must remove the sheet, every source photo, the metadata, and any cached model input — not just unlink the name.

Reference uploads and model inputs must be handled according to the privacy controls of the product you are building — the same rules that govern any other user content it processes. Be concrete with the user about where the sheet goes: if your image model is a remote API, that person’s face leaves the machine on every single generation that names them, and the provider’s retention terms apply to it. A local image model keeps it on your hardware. Either is a legitimate choice; making it without telling the user is not.

8 · Keep the sheets fresh

A reference sheet is a snapshot with an expiry date. New haircut, new glasses, a beard, weight change, a child who grows visibly in six months — the sheet keeps confidently producing last year’s person.

• Re-shoot when the user says results have started looking wrong, and on a schedule for anyone whose appearance moves quickly.
• Refresh from a new set of photographs. Do not regenerate from the old sheet — copies of copies drift, and the drift compounds silently.
• Keep the previous sheet until the replacement is approved, then delete it. Two live sheets for one subject means two different people.
• Store refreshed alongside created, and surface the age of a sheet when the user asks what is in the library.

Done when

• A named subject can be added end to end: photos in, sheet out, user approves, name stored.
• The same name, prompted three times in different scenes, produces three images of recognisably the same subject.
• A prompt that names nothing produces zero reference attachments — verify this one deliberately, it is the rule most easily broken by a helpful default.
• Every generation reports which references it applied.
• Deleting a subject leaves nothing behind on disk.

The contract side of Imagine — the finalizer fields, aspect ratio, quality, idempotent replay, how to return the bytes — is on the protocol page. If you have not built a backend yet, build one against that page first; references are something you add to a backend that already works.