scenri 0.6.1 → 0.6.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.6.2](https://github.com/tonygorb/Scenri/compare/v0.6.1...v0.6.2) (2026-08-28)
+
+
+### Bug Fixes
+
+* a custom scene keeps the figure and treatment its references show ([667cede](https://github.com/tonygorb/Scenri/commit/667cedeb4ebac53bf3d7c5cbcf0f8f80745c7431))
+* a custom scene keeps the figure and treatment its references show ([b6532c9](https://github.com/tonygorb/Scenri/commit/b6532c9b47c404243a3ad0994bda4dd634e109e7))
+
 ## [0.6.1](https://github.com/tonygorb/Scenri/compare/v0.6.0...v0.6.1) (2026-08-26)
 
 

package/dist/serve.js

@@ -1286,7 +1286,13 @@ var REFERENCE_ROLE_DIRECTIVE = {
   product: "the exact product \u2014 preserve its label, shape, colors and design faithfully; do not redesign it",
   character: "the exact person \u2014 match their face, facial structure, skin, hair and build exactly; their clothing, pose and background are capture context, not styling to reproduce",
   brand: "the brand's own mark \u2014 if the direction calls for the mark to appear, reproduce it exactly as drawn, same colours, letterforms and proportions; otherwise take only its colour and treatment, and never its subject, geometry or composition",
-  scene: "a reference for the environment and light only \u2014 take no subject, product or person from it",
+  // Only a figure-led scene attaches one of these now, so this says what that
+  // case actually needs. It used to read "environment and light only - take no
+  // subject or person from it", which handed the model a photograph of a face
+  // treatment and told it to ignore the treatment. A hand-attached reference
+  // says "match ... treatment" and works; this now says the same thing, with the
+  // identity carve-out a scene needs and a lone reference does not.
+  scene: "a reference for this world and for the treatment applied to the figure in it \u2014 match the environment, the light, and the material, density, scale, finish and spread of that treatment, including which parts of the form it covers and how far it reaches; take no identity from the person in it, and no product or brand",
   composition: "a reference for framing, camera angle and pose only \u2014 take no subject, color, material or branding from it",
   style: "a reference for overall treatment and mood only \u2014 take no composition, subject or product detail from it",
   reference: "a reference to match in composition, lighting and treatment"
@@ -2241,10 +2247,10 @@ function presenterBody(req, refCount) {
   return `These are photographs of one person, supplied by the person casting them.${same}${ask} Write a casting sheet: what a photographer would need in order to recognise this person again in a different shot. Do not name, identify, or guess who this person is, and do not use any proper name anywhere in your answer. Describe the person, not the photograph: their build, face and hair belong to them, but the background, crop, pose, clothing and lighting of these pictures belong to a shoot and must be left out. ${OUT_FILE} must be a JSON object with exactly these keys: "promptName": a short noun phrase a generator can be handed, such as "a woman in her early thirties with dark shoulder-length waves"; "presentation": either "woman" or "man"; "descriptor": a three-beat casting caption joined by " \xB7 ", such as "Warm editorial \xB7 dark waves \xB7 composed"; "ageRange": an approximate range such as "early 30s"; "hair": colour, length, texture and how it is worn; "identityNotes": one paragraph naming the two or three features that must survive every generation, drawn from face shape, eyes, nose, mouth, jaw, skin, distinctive marks, and build where it is visible; "negativeConstraints": an array of short refusals for the drift these photographs invite, such as "no youth-smoothing that erases the natural lines"; "suitableCategories": the industries this person would be cast for.${categories} "coverage": an array of at most two short sentences naming a view that is missing and would make this person more consistent, such as "A three-quarter photo would pin the cheekbones down." Use an empty array when the coverage is already good.`;
 }
 function sceneBody(req) {
-  const ask = req.instruction ? ` What the person wants from it: ${req.instruction}.` : "";
+  const ask = req.instruction ? ` The person who chose these references says what matters in them: ${req.instruction}. Treat that as the deciding word: whatever it calls essential IS essential even if only one reference shows it, and whatever it tells you to ignore stays out even if every reference contains it.` : "";
   const collections = req.vocabulary?.collections?.length ? ` Choose "collections" only from this list: ${req.vocabulary.collections.join(", ")}.` : "";
   const verticals = req.vocabulary?.verticals?.length ? ` Choose "verticals" only from this list: ${req.vocabulary.verticals.join(", ")}.` : "";
-  return `These are references for a place, not a picture to copy.${ask} Extract the reusable visual world behind them: environment, architecture, surfaces and materials, the character of the light, atmosphere, palette, depth, and the photographic language. Never name or describe a brand, a logo, a product, or a person. If a reference contains a bottle, a garment, a model or a mark, that thing is a visitor, not part of the world: leave it out completely, because something else will be staged here later. Describe where a photograph happens, not what is standing in it. Use no placeholders of any kind. ${OUT_FILE} must be a JSON object with exactly these keys: "name": two or three words a person would call this place, such as "Wet Basalt Shore"; "promptName": the same place named for a generator, at most six words; "lighting": a short phrase naming the light, such as "Low directional sunset, long shadows across wet stone"; "description": one sentence a person reads on a card; "subject": "product" if this world suits a staged object, "person" if it suits someone photographed in it, "either" when it truly suits both; "prompt": three or four sentences describing the set itself, in the present tense, naming nothing that is staged in it; "camera": the camera tendency of this world in a short phrase, or an empty string when it has none; "keywords": five to ten single words someone might search for; "collections": one or two themed groupings;${collections} "verticals": the industries this world flatters.${verticals}`;
+  return `These are references for a place, not a picture to copy.${ask} Extract the reusable visual world behind them: environment, architecture, surfaces and materials, the character of the light, atmosphere, palette, depth, and the photographic language. Name materials rather than colours - travertine, cracked clay, waxed canvas, brushed steel, raw concrete - and say how the space layers from foreground through middle ground to background. Say so when a surface is reflective or transmissive: a mirror, a wet floor, chrome, glass, still water. Those govern how everything in the frame is lit, and they are the first thing lost to a generic description. Treat signage and lettering as typographic texture belonging to the environment: say that it is there and what it is made of, and never transcribe the words or name the brand. What you leave out is identity, not presence. Never name or describe a brand, a logo, a product model or a wordmark, and do not use any proper name anywhere in your answer. A person in a reference is recorded only as a figure: their scale in the frame, their distance, their posture, the kind of act the space is arranged around, and how a body catches this light. Never their face, hair, age, wardrobe, or anything that would identify them, and never as a particular person - "a figure at the water's edge", never "a woman in a red coat". A figure is not always something standing in a world. Sometimes the figure IS the world: a close portrait whose entire art direction is what has been done to the person - a face covered in stickers, painted skin, a veil, a mask, fabric wrapped over the head, a body reduced to a silhouette. When that is what the reference is, the treatment is the single most important thing to record, not a detail to drop along with the identity. Record what was done; never who it was done to. Only a living person counts as a figure. A mannequin, a statue, a face on a poster, a billboard or a screen, a reflection with nobody outside it, or a cast shadow is a thing in the environment: describe it in the set, not as a figure. Where several people appear, only the one the composition is built around is the figure; the rest are crowd, and belong in the set with everything else. A product, garment or mark staged in a reference is a visitor: leave the object itself out, but keep what it tells you about the place - the surface it sat on, the scale it implies, how densely the space is dressed. Where several references are attached, the world is what they share; whatever appears in only one of them is a visitor. Use no placeholders of any kind. ${OUT_FILE} must be a JSON object with exactly these keys: "name": two or three words a person would call this place, such as "Wet Basalt Shore"; "promptName": the same place named for a generator, at most six words; "lighting": a short phrase naming the light, such as "Low directional sunset, long shadows across wet stone"; "description": one sentence a person reads on a card; "subject": "product" if this world suits a staged object, "person" if it suits someone photographed in it, "either" when it truly suits both; "prompt": four or five sentences describing the set itself, in the present tense, naming nothing branded and nobody identifiable. Ambient human presence belongs here, written the way the rest of the set is written - a figure far off in the frame, worn seats, a table dressed for two; "figure": when this concept depends on a person being in it, one short phrase for the role they play - their framing, their scale, and what they are doing - such as "someone is seated at the stone ledge, mid-ground, at human scale" or "one person at close portrait range, squared to camera, filling the frame". A portrait counts. If the reference is built around a person and would stop being this concept without one, that is a figure, however much of the frame they occupy. Use an empty string only when the concept genuinely survives with nobody in it, or when the people present are passers-by rather than the point - describe those in "prompt" with the rest of the set instead. This is a different question from "subject": "subject" is who this world flatters, "figure" is whether the concept needs a body at all; "figureTreatment": what has been done TO that figure, when something has - one short phrase, such as "the face entirely covered in overlapping printed stickers" or "the head and shoulders wrapped in translucent fabric". Describe the treatment, what it is made of, and the character of any printing on it - the kind of label or product it imitates, its typographic style, illustration and colour - because that graphic character is usually the point. Say what kind of thing the printing is without naming a real company from the references. Be specific to what is actually in front of you rather than to the general idea: how much of the surface is covered and how much is left bare, the material and finish - glossy vinyl, matte paper, foil, fabric - the size of the pieces, and - separately from how many there are - how far they reach across the form and which parts they land on, since a treatment can be sparse and still cover the whole face. If the references disagree about how heavy it is, give the range rather than picking one. Use an empty string when nothing has been done to them. Leave it empty too when "figure" is empty; "camera": the camera tendency of this world in a short phrase - height, distance, lens feel, depth of field - or an empty string when it has none. Camera belongs here and never in "prompt"; "keywords": five to ten single words someone might search for; "coverage": an array of at most two short sentences naming what another reference would buy, such as "A wider frame would pin down how the room is laid out." Say so here if these references look like different places, or if they are mostly a person or a packshot with too little environment to build a world from. Use an empty array when they are good; "collections": one or two themed groupings;${collections} "verticals": the industries this world flatters.${verticals}`;
 }
 function parseDraft(req, raw) {
   const text = raw.trim().replace(/^```(?:json)?\s*/i, "").replace(/```$/, "").trim();
@@ -2298,6 +2304,8 @@ function parseScene(req, o) {
   }
   if (problems.length) return { ok: false, problems };
   const camera = cap(str(o.camera), 200);
+  const figure = oneLine(o.figure, 120);
+  const figureTreatment = figure ? oneLine(o.figureTreatment, 160) : "";
   return {
     ok: true,
     draft: {
@@ -2310,11 +2318,19 @@ function parseScene(req, o) {
       verticals: pick(o.verticals, req.vocabulary?.verticals, 4),
       keywords: list(o.keywords, 10, 40),
       prompt: cap(prompt, 2e3),
-      camera: camera || void 0
+      camera: camera || void 0,
+      figure: figure || void 0,
+      figureTreatment: figureTreatment || void 0,
+      coverage: list(o.coverage, 2, 160)
     }
   };
 }
 var str = (v) => typeof v === "string" ? v.trim() : "";
+function oneLine(v, max) {
+  const one = str(v).replace(/\s+/g, " ");
+  if (!one || /\{[^}]*\}/.test(one)) return "";
+  return cap(one, max);
+}
 var cap = (v, max) => v.length > max ? v.slice(0, max).trim() : v;
 function list(v, max, each) {
   if (!Array.isArray(v)) return [];
@@ -3071,6 +3087,28 @@ function shotSpecifiesCamera(text) {
     text
   );
 }
+function sceneFigureDirectives(opts) {
+  const figure = opts.figure.trim().replace(/[.\s]+$/, "");
+  if (!figure) return [];
+  const treatment = (opts.treatment ?? "").trim().replace(/[.\s]+$/, "");
+  const out = [];
+  if (opts.hasPerson) {
+    out.push(
+      `This world is built around one figure: ${figure}. The attached presenter is that figure. Any person the scene direction describes IS the presenter and never a second person, and their identity comes from their own attached photograph alone, never from anything the scene direction says about a body.`
+    );
+  } else {
+    out.push(
+      `This world is built around one figure: ${figure}. Someone fills that role in the frame, and they are nobody in particular: an anonymous person invented for this photograph only, with no recognisable identity to preserve and nothing about them carried anywhere else. Show them unless the direction above asks for no people.`
+    );
+  }
+  if (treatment) {
+    const who = opts.hasPerson ? "The face and body underneath are still exactly theirs - same structure, same proportions, same build - and any earlier instruction that their features must survive unchanged is a rule about who they are, which this does not alter. " : "";
+    out.push(
+      `The art direction of this world is what has been done to that figure: ${treatment}. Render it as a real physical treatment, following the shape of the face and body it sits on rather than floating in the frame. Spread it across the whole form the way the reference does, reaching every part it covers there - brow, forehead, nose, both cheeks, jaw - instead of massing it in one area and leaving the rest untouched. Reaching wide is not the same as covering more: keep the number of pieces and the bare surface between them exactly as the description says, so a sparse treatment stays sparse while still touching every part of the form. Each piece sits on the plane beneath it, curving and catching light with the surface it is stuck to. ${who}The figure is bodily present and in shot: where the treatment covers or hides them, that is the photograph working as intended and never a reason to leave them out, crop them away, or reduce them to a shadow. If no person appears in this shot, the treatment does not go with them: it is what this world looks like, so it applies to whatever the frame does hold - the product, the surfaces, the set - as real pieces resting on those things. Applied on top, never redesigning them: the product keeps the exact form, colour, material and its own printed label that its reference shows, with the treatment sitting over it. Where the treatment carries printing, render it as genuinely designed print: real letterforms, readable words, numerals, illustration and colour, at the quality of commercial label artwork. Invent the companies - every name, logotype and piece of packaging artwork must be plausible but fictional, resembling no existing brand. That includes near-misses: do not borrow, extend or re-spell a name that appears in any attached reference, and use ordinary words for the produce itself rather than any company that sells it.`
+    );
+  }
+  return out;
+}
 function sceneGuardDirectives(opts) {
   const out = [];
   if (opts.hasProduct) {
@@ -3113,6 +3151,7 @@ function markLabel(brand, logo) {
 // src/brief.ts
 var PRODUCT_REF_MAX = 3;
 var CHARACTER_REF_MAX = 2;
+var SCENE_REF_MAX = 1;
 var FORMATS = [
   { id: "square", label: "Square 1:1", w: 1024, h: 1024 },
   { id: "story", label: "Story 9:16", w: 1080, h: 1920 },
@@ -3289,6 +3328,14 @@ function compileBrief(brief, ctx) {
         }
         inlineTemplates.push(t);
         append(composePrompt(t, { fields: brief.templateFields ?? {}, notes: "" }));
+        if (ctx.mode !== "edit" && t.figure) {
+          for (const r of (t.refs ?? []).slice(0, SCENE_REF_MAX)) {
+            const h = assetHash(r?.file);
+            if (h && ctx.images.has(h)) {
+              attachments.push({ role: "scene", id: t.id, label: t.name, hash: h, essential: false });
+            }
+          }
+        }
         break;
       }
       case "format": {
@@ -3347,6 +3394,7 @@ function compileBrief(brief, ctx) {
     // attached one is deliberate.
     "Any earlier instruction that bans props, hands, people, or a presenter from the frame is a solo-packshot rule for this product and does not apply to this shot: the attached presenter is deliberate and must appear as directed."
   ] : [];
+  const figureDirectives = scene?.figure ? sceneFigureDirectives({ figure: scene.figure, treatment: scene.figureTreatment, hasPerson }) : [];
   const closeUpDirectives = hasPerson && /\bclose[- ]?up\b|\bmacro\b|\bzoom(?:ed)?\b|\bDOF\b|\bdepth of field\b/i.test(sentence) ? [
     "The tight framing includes the presenter: keep at least their hand in genuine contact with the product, and as much more of them as the crop allows. A close-up is never a reason to leave the person out of the photograph."
   ] : [];
@@ -3364,6 +3412,7 @@ function compileBrief(brief, ctx) {
     ...productDirectives,
     ...personDirectives,
     ...pairDirectives,
+    ...figureDirectives,
     ...closeUpDirectives,
     ...otherDirectives,
     ...cameraDirectives,
@@ -3375,8 +3424,8 @@ function compileBrief(brief, ctx) {
   if (allDirectives.length) prompt = `${prompt}${prompt.endsWith(".") ? "" : "."} ${dedupe(allDirectives).join(" ")}`;
   const max = ctx.engineCaps.maxReferenceImages;
   const { kept, dropped } = allocateAttachments(attachments, max);
-  if (dropped.length) {
-    const names = [...new Set(dropped.map((d) => d.label))];
+  if (dropped.some((d) => d.role !== "scene")) {
+    const names = [...new Set(dropped.filter((d) => d.role !== "scene").map((d) => d.label))];
     warnings.push(
       `${ctx.engineCaps.displayName} reads ${max} reference image${max === 1 ? "" : "s"}, so ${names.join(
         " and "
@@ -3888,6 +3937,20 @@ var brand_schema_default = {
             type: "string",
             description: "What the user asked for in their own words when this scene was built. Kept so a later refinement has the original intent."
           },
+          figure: {
+            type: "string",
+            not: {
+              pattern: "\\{[^}]*\\}"
+            },
+            description: 'The figure this concept depends on, when it depends on one: "one person at close portrait range, squared to camera, filling the frame". A role, never a person - it names the part a body plays in this world, never whose body. Absent means the concept survives with nobody in it; passing human presence belongs in prompt with the rest of the set. A brief binds this to an attached presenter, so a world built around a body and a real presenter never compile as two people.'
+          },
+          figureTreatment: {
+            type: "string",
+            not: {
+              pattern: "\\{[^}]*\\}"
+            },
+            description: "What has been applied to that figure, when something has: stickers over the face, paint, a veil, fabric, reduction to a silhouette. This is art direction, not identity - the scene owns the treatment and the presenter owns the face underneath it, and nothing here is ever written back to a presenter. Names the material and its form, never the words or artwork printed on it. Meaningless without figure."
+          },
           refs: {
             type: "array",
             items: {
@@ -3900,7 +3963,7 @@ var brand_schema_default = {
                 }
               }
             },
-            description: "The user's inspiration images. Display only: a scene contributes text to a generation, never pixels, so these are never sent to a generator as references."
+            description: "The user's inspiration images. Used to read this scene into words, to draw its preview card, and - only when the scene is built around a figure - one of them is attached to a shot as environment reference. That exception exists because a dense figure treatment cannot survive being described in words. Where it applies, the reference is marked as scene context: the environment and treatment are taken from it, the people, products and marks in it are not."
           },
           preview: {
             $ref: "#/$defs/assetRef",
@@ -5484,8 +5547,13 @@ function sceneRecordFrom(input, base) {
   if (camera) scene.camera = camera;
   const keywords = has("keywords") ? strList(input.keywords, 12, 40) : base?.keywords;
   if (keywords?.length) scene.keywords = keywords;
-  const instruction = has("instruction") ? str3(input.instruction, 400) : base?.instruction;
+  const written = has("instruction") ? str3(input.instruction, 400) : "";
+  const instruction = written || base?.instruction;
   if (instruction) scene.instruction = instruction;
+  const figure = has("figure") ? str3(input.figure, 120).replace(/\s+/g, " ") : base?.figure;
+  if (figure && !/\{[^}]*\}/.test(figure)) scene.figure = figure;
+  const treatment = has("figureTreatment") ? str3(input.figureTreatment, 160).replace(/\s+/g, " ") : base?.figureTreatment;
+  if (scene.figure && treatment && !/\{[^}]*\}/.test(treatment)) scene.figureTreatment = treatment;
   if (refs?.length) scene.refs = refs;
   if (previewRef) scene.preview = previewRef;
   return { ok: true, scene };
@@ -5527,7 +5595,7 @@ function presenterRecordFrom(input, base) {
   return { ok: true, presenter };
 }
 function lintSceneProse(brandJson, scene) {
-  const haystack = `${scene.prompt} ${scene.description}`.toLowerCase();
+  const haystack = `${scene.prompt} ${scene.description} ${scene.figure ?? ""} ${scene.figureTreatment ?? ""}`.toLowerCase();
   const named = /* @__PURE__ */ new Set();
   const consider = (raw) => {
     const n = String(raw ?? "").trim();
@@ -5576,7 +5644,10 @@ function startAssetBuild(deps, input) {
   const { core } = deps;
   const brand = core.store.getBrand(input.brandId);
   if (!brand) throw Object.assign(new Error("brand not found"), { statusCode: 404 });
-  const hashes = input.imageHashes.filter((h) => /^[a-f0-9]{32}$/.test(h) && core.images.has(h));
+  const prior = input.sceneId ? brandSceneById(brand.json, input.sceneId) : void 0;
+  if (input.sceneId && !prior) throw Object.assign(new Error("scene not found"), { statusCode: 404 });
+  const supplied = input.imageHashes.length ? input.imageHashes : (prior?.refs ?? []).map((r) => String(r?.file ?? "").replace(/^asset:/, ""));
+  const hashes = supplied.filter((h) => /^[a-f0-9]{32}$/.test(h) && core.images.has(h));
   if (input.kind === "presenter" && !hashes.length) {
     throw Object.assign(new Error("add at least one photo of this person"), { statusCode: 400 });
   }
@@ -5597,6 +5668,7 @@ function startAssetBuild(deps, input) {
     warnings: [],
     coverage: [],
     facets: strList(input.facets, 8, 40),
+    sceneId: input.sceneId ?? null,
     error: null,
     startedAt: (/* @__PURE__ */ new Date()).toISOString(),
     finished: false
@@ -5906,15 +5978,17 @@ async function crop(core, hash, region) {
 }
 async function runSceneBuild(deps, job, hashes, instruction, signal) {
   const { core } = deps;
+  const prior = job.sceneId ? brandSceneById(core.store.getBrand(job.brandId)?.json ?? {}, job.sceneId) : void 0;
   let draft = null;
   if (deps.analyzer) {
-    patch(job, { stage: "analyzing", message: "Reading the references" });
+    patch(job, { stage: "analyzing", message: prior ? "Reading the references again" : "Reading the references" });
     draft = await deps.analyzer.analyze(
       {
         kind: "scene",
         imagePaths: hashes.map((h) => core.images.pathFor(h)),
         name: job.name,
         instruction: instruction || void 0,
+        ...prior ? { priorDraft: prior, correction: instruction || void 0 } : {},
         vocabulary: deps.vocabulary
       },
       signal
@@ -5923,29 +5997,41 @@ async function runSceneBuild(deps, job, hashes, instruction, signal) {
     throw new Error("describe the place in a sentence, or install the Codex CLI to read the references");
   }
   if (signal.aborted) throw new Error("cancelled");
-  const built = sceneRecordFrom({
-    name: job.name || draft?.name || "New scene",
-    promptName: draft?.promptName,
-    lighting: draft?.lighting,
-    description: draft?.description ?? instruction,
-    subject: draft?.subject ?? "either",
-    prompt: draft?.prompt ?? instruction,
-    camera: draft?.camera,
-    collections: draft?.collections,
-    verticals: job.facets.length ? job.facets : draft?.verticals,
-    keywords: draft?.keywords,
-    instruction,
-    refHashes: hashes
-  });
+  const built = sceneRecordFrom(
+    {
+      name: job.name || draft?.name || "New scene",
+      promptName: draft?.promptName,
+      lighting: draft?.lighting,
+      description: draft?.description ?? instruction,
+      subject: draft?.subject ?? "either",
+      prompt: draft?.prompt ?? instruction,
+      camera: draft?.camera,
+      figure: draft?.figure,
+      figureTreatment: draft?.figureTreatment,
+      collections: draft?.collections,
+      verticals: job.facets.length ? job.facets : draft?.verticals,
+      keywords: draft?.keywords,
+      instruction,
+      refHashes: hashes
+    },
+    prior
+  );
   if (!built.ok) throw new Error(built.error);
   const scene = built.scene;
+  if (draft?.coverage?.length) patch(job, { coverage: draft.coverage });
   let previewHash = null;
   if (deps.engine) {
     patch(job, { stage: "building", steps: 1, message: "Drawing the place" });
     try {
+      const previewRefs = hashes.slice(0, deps.engine.capabilities().maxReferenceImages).map((h) => core.images.pathFor(h));
       previewHash = await trimEdgeBars(
         core,
-        await draw(deps, { prompt: scenePreviewPrompt(scene), brandId: job.brandId, signal })
+        await draw(deps, {
+          prompt: scenePreviewPrompt(scene),
+          brandId: job.brandId,
+          ...previewRefs.length ? { referenceImages: previewRefs, referenceRoles: previewRefs.map(() => "scene") } : {},
+          signal
+        })
       );
       scene.preview = `asset:${previewHash}`;
       patch(job, { step: 1, previewHash });
@@ -5959,7 +6045,9 @@ async function runSceneBuild(deps, job, hashes, instruction, signal) {
   const brand = core.store.getBrand(job.brandId);
   const warnings = [...job.warnings, ...lintSceneProse(brand?.json ?? {}, scene)];
   commit(core, job.brandId, (json) => {
-    json.scenes = [...brandScenes(json), scene];
+    const rows = brandScenes(json);
+    const at = rows.findIndex((s) => s?.id === scene.id);
+    json.scenes = at >= 0 ? rows.map((s, i) => i === at ? scene : s) : [...rows, scene];
   });
   patch(job, {
     stage: "done",
@@ -5971,7 +6059,8 @@ async function runSceneBuild(deps, job, hashes, instruction, signal) {
   });
 }
 function scenePreviewPrompt(scene) {
-  return `Full-bleed photograph filling the entire frame edge to edge with no border, frame, letterbox band or matte of any kind. ${scene.prompt} ${scene.lighting ? `${scene.lighting}. ` : ""}The set is empty: no product, no person, no hands, no text, no logos, no watermarks anywhere in the frame.`;
+  const body = scene.figure ? `A figure is in this photograph: ${scene.figure.replace(/[.\s]+$/, "")}. ` + (scene.figureTreatment ? `The art direction is what has been done to them: ${scene.figureTreatment.replace(/[.\s]+$/, "")}, rendered as a real physical treatment that follows the shape it sits on. ` : "") + "They are nobody in particular: do not reproduce any person from the attached reference images, and give them no recognisable identity. No product, no logos, no watermarks, and no readable words anywhere in the frame." : "The set is empty: no product, no person, no hands, no text, no logos, no watermarks anywhere in the frame.";
+  return `Full-bleed photograph filling the entire frame edge to edge with no border, frame, letterbox band or matte of any kind. ${scene.prompt} ${scene.lighting ? `${scene.lighting}. ` : ""}` + body;
 }
 async function draw(deps, req) {
   const engine = deps.engine;
@@ -5997,6 +6086,12 @@ async function draw(deps, req) {
 function runningAssetBuildCount() {
   return running2.size;
 }
+function sceneBuildRunning(brandId, sceneId) {
+  for (const b of builds.values()) {
+    if (b.brandId === brandId && b.sceneId === sceneId && !b.finished) return true;
+  }
+  return false;
+}
 var LOOPBACK = ["localhost", "127.0.0.1", "::1"];
 var ACCESS_COOKIE = "sc_access";
 var LEGACY_ACCESS_COOKIE = "bt_access";
@@ -7372,6 +7467,30 @@ function registerAssetBuildRoutes(app, deps) {
     });
     return { ok: true };
   });
+  app.post("/api/brands/:id/scenes/:sceneId/reread", async (req, reply) => {
+    const brand = brandOr404(req, reply);
+    if (!brand) return;
+    const id = String(req.params.sceneId);
+    const scene = brandScenes(brand.json).find((s) => s.id === id);
+    if (!scene) return reply.status(404).send({ error: "scene not found" });
+    if (!(scene.refs ?? []).length)
+      return reply.status(400).send({ error: "this scene was written from words, so there is nothing to read again" });
+    if (sceneBuildRunning(brand.id, id))
+      return reply.status(409).send({ error: "this scene is already being read again" });
+    const body = req.body ?? {};
+    try {
+      return startAssetBuild(await buildDeps(), {
+        brandId: brand.id,
+        kind: "scene",
+        sceneId: id,
+        name: scene.name,
+        instruction: body.correction == null ? void 0 : String(body.correction),
+        imageHashes: []
+      });
+    } catch (err) {
+      return reply.status(err.statusCode ?? 500).send({ error: err.message ?? "could not start" });
+    }
+  });
   app.post("/api/brands/:id/scenes/:sceneId/preview", async (req, reply) => {
     const brand = brandOr404(req, reply);
     if (!brand) return;
@@ -7380,9 +7499,11 @@ function registerAssetBuildRoutes(app, deps) {
     if (!scene) return reply.status(404).send({ error: "scene not found" });
     const engine = await buildEngine();
     if (!engine) return reply.status(400).send({ error: "no engine here can draw a preview" });
+    const refs = (scene.refs ?? []).map((r) => String(r?.file ?? "").replace(/^asset:/, "")).filter((h) => /^[a-f0-9]{32}$/.test(h) && core.images.has(h)).slice(0, engine.capabilities().maxReferenceImages).map((h) => core.images.pathFor(h));
     const request = {
       prompt: scenePreviewPrompt(scene),
       brand: brandContext(core, brand.id),
+      ...refs.length ? { referenceImages: refs, referenceRoles: refs.map(() => "scene") } : {},
       width: scene.width,
       height: scene.height,
       count: 1
@@ -7823,6 +7944,29 @@ function registerImageRoutes(app, deps) {
 
 // src/release/notes.data.ts
 var RELEASES = [
+  {
+    version: "0.6.2",
+    date: "2026-08-28",
+    title: "Scenes keep what makes them distinctive.",
+    sections: [
+      {
+        heading: "Scenes",
+        body: "A scene built from references that are about a person now keeps that person as part of its art direction: where they sit in the composition, and what has been done to them, whether that is a face covered in stickers or a figure behind fabric. Before, a reference like that was read as an empty room and the idea was lost."
+      },
+      {
+        heading: "Create",
+        body: "Attach a presenter to a scene like that and they take the role, wearing their own face under the treatment. Attach nobody and the person stays anonymous. Ask for no people and the treatment stays on whatever is left in the frame."
+      },
+      {
+        heading: "Building a scene",
+        body: "The notes field is now Direction, and it decides how your references are read. Say what matters in them and what to ignore, and it carries more weight than the pictures alone. You can edit it later from the scene page."
+      },
+      {
+        heading: "Fixes",
+        body: "Reading a scene's references again no longer clears the direction you wrote. Scenes you build yourself now appear on the home shelf beside the built-in ones, and a scene that finishes while you are looking at the library no longer stays hidden until you reload."
+      }
+    ]
+  },
   {
     version: "0.6.1",
     date: "2026-08-26",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scenri",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "author": "Tony Gorb <hello@scenri.co>",
   "license": "AGPL-3.0-only",
   "type": "module",