@nodaro/prompts 1.15.0 → 1.17.0

package/src/person.ts

@@ -437,10 +437,10 @@ export const PEOPLE: ReadonlyArray<Person> = [
   { id: "bust-small",     label: "Small",     dimension: "bust", description: "Small bust",     promptHint: "small bust", term: "small bust" , adultOnly: true },
   { id: "bust-average",   label: "Average",   dimension: "bust", description: "Average bust",   promptHint: "" },
   { id: "bust-full",      label: "Full",      dimension: "bust", description: "Full bust",      promptHint: "full bust", term: "full bust" , adultOnly: true },
-  { id: "bust-very-full", label: "Very Full", dimension: "bust", description: "Very full bust", promptHint: "very full bust", term: "very full bust" , adultOnly: true },
+  { id: "bust-very-full", label: "Very Full", dimension: "bust", description: "Very full bust", promptHint: "a fuller bust", term: "fuller bust" , adultOnly: true },
 
   // ----- Waist -----
-  { id: "waist-defined",  label: "Defined",  dimension: "waist", description: "Defined, cinched waist",    promptHint: "defined waist", term: "defined waist" , adultOnly: true },
+  { id: "waist-defined",  label: "Defined",  dimension: "waist", description: "Defined, cinched waist",    promptHint: "a defined waistline", term: "defined waistline" , adultOnly: true },
   { id: "waist-average",  label: "Average",  dimension: "waist", description: "Average waist",             promptHint: "" },
   { id: "waist-straight", label: "Straight", dimension: "waist", description: "Straight, undefined waist", promptHint: "straight waistline", term: "straight waistline" , adultOnly: true },
 
@@ -450,7 +450,7 @@ export const PEOPLE: ReadonlyArray<Person> = [
   { id: "hips-wide",     label: "Wide",     dimension: "hips", description: "Wide hips",     promptHint: "wide hips", term: "wide hips" , adultOnly: true },
 
   // ----- Silhouette (overall body shape; optional, no neutral) -----
-  { id: "silhouette-hourglass",   label: "Hourglass",         dimension: "silhouette", description: "Balanced bust + hips, defined waist", promptHint: "hourglass silhouette", term: "hourglass silhouette" , adultOnly: true },
+  { id: "silhouette-hourglass",   label: "Hourglass",         dimension: "silhouette", description: "Balanced bust + hips, defined waist", promptHint: "an hourglass figure", term: "hourglass figure" , adultOnly: true },
   { id: "silhouette-rectangular", label: "Rectangular",       dimension: "silhouette", description: "Straight up-and-down silhouette",      promptHint: "rectangular silhouette", term: "rectangular silhouette" },
   { id: "silhouette-pear",        label: "Pear",              dimension: "silhouette", description: "Hips wider than shoulders",            promptHint: "pear-shaped silhouette", term: "pear-shaped silhouette" , adultOnly: true },
   { id: "silhouette-inverted",    label: "Inverted Triangle", dimension: "silhouette", description: "Broad shoulders, narrow hips",         promptHint: "inverted-triangle silhouette", term: "inverted-triangle silhouette" },
@@ -553,11 +553,11 @@ export const PEOPLE: ReadonlyArray<Person> = [
 
   // -------------------- Lip State (what the lips are doing / wearing) --------------------
   { id: "lip-state-chapped",   label: "Chapped",   dimension: "lip-state", description: "Cracked, dry, weather-worn lips", promptHint: "with chapped, cracked, weather-worn dry lips", term: "chapped dry lips" },
-  { id: "lip-state-glossy",    label: "Glossy",    dimension: "lip-state", description: "High-shine, wet-look lips",       promptHint: "with high-shine glossy wet-look lips", term: "glossy wet-look lips" , adultOnly: true },
+  { id: "lip-state-glossy",    label: "Glossy",    dimension: "lip-state", description: "High-shine, wet-look lips",       promptHint: "with a glossy lip finish", term: "glossy lips" , adultOnly: true },
   { id: "lip-state-bare",      label: "Bare",      dimension: "lip-state", description: "Natural, untreated, no makeup",   promptHint: "with bare, natural, untreated lips", term: "bare natural lips" },
   { id: "lip-state-bold-red",  label: "Bold Red",  dimension: "lip-state", description: "Saturated red lipstick statement", promptHint: "with a bold, saturated red lipstick statement", term: "bold red lipstick" },
-  { id: "lip-state-bitten",    label: "Bitten",    dimension: "lip-state", description: "Slight playful lip-bite, lower lip caught", promptHint: "playfully biting the lower lip", term: "biting the lower lip" , adultOnly: true },
-  { id: "lip-state-parted",    label: "Parted",    dimension: "lip-state", description: "Lips slightly parted, breath of air", promptHint: "with lips slightly parted, taking a soft breath", term: "lips slightly parted" , adultOnly: true },
+  { id: "lip-state-bitten",    label: "Bitten",    dimension: "lip-state", description: "Slight playful lip-bite, lower lip caught", promptHint: "lightly biting the lower lip", term: "biting lower lip" , adultOnly: true },
+  { id: "lip-state-parted",    label: "Parted",    dimension: "lip-state", description: "Lips slightly parted, breath of air", promptHint: "with lips relaxed and slightly open, as if mid-sentence", term: "lips slightly open" , adultOnly: true },
   { id: "lip-state-pursed",    label: "Pursed",    dimension: "lip-state", description: "Lips pressed and pushed forward", promptHint: "with lips pursed, pressed and pushed forward", term: "pursed lips" },
   { id: "lip-state-bold-black", label: "Bold Black", dimension: "lip-state", description: "Saturated black lipstick statement (goth / avant-garde)", promptHint: "with a bold, saturated black lipstick statement, goth / avant-garde", term: "bold black lipstick" },
   { id: "lip-state-burgundy",   label: "Burgundy",   dimension: "lip-state", description: "Deep wine-red lipstick", promptHint: "with deep wine-red burgundy lipstick", term: "burgundy lipstick" },
@@ -676,9 +676,9 @@ export const PEOPLE: ReadonlyArray<Person> = [
 
   // -------------------- Eye State (what the eyes are doing / where they look) --------------------
   { id: "eye-state-closed",         label: "Closed",            dimension: "eye-state", description: "Eyes fully closed, peaceful",       promptHint: "with eyes fully closed in a peaceful expression", term: "eyes fully closed" },
-  { id: "eye-state-half-lidded",    label: "Half-lidded",       dimension: "eye-state", description: "Heavy-lidded sleepy gaze",          promptHint: "with heavy half-lidded sleepy eyes", term: "half-lidded sleepy eyes" , adultOnly: true },
+  { id: "eye-state-half-lidded",    label: "Half-lidded",       dimension: "eye-state", description: "Heavy-lidded sleepy gaze",          promptHint: "with drowsy, partly closed eyes, the lids sitting low over the iris", term: "drowsy, partly closed eyes" , adultOnly: true },
   { id: "eye-state-wide-eyed",      label: "Wide-eyed",         dimension: "eye-state", description: "Eyes wide open, alert / surprised", promptHint: "with eyes wide open, alert and surprised" },
-  { id: "eye-state-staring-camera", label: "Staring at Camera", dimension: "eye-state", description: "Direct unbroken eye contact with the lens", promptHint: "staring directly at the camera with unbroken eye contact" },
+  { id: "eye-state-staring-camera", label: "Staring at Camera", dimension: "eye-state", description: "Direct unbroken eye contact with the lens", promptHint: "looking directly into the camera", term: "direct gaze to camera" },
   { id: "eye-state-gazing-away",    label: "Gazing Away",       dimension: "eye-state", description: "Looking off-camera, contemplative", promptHint: "gazing off-camera with a contemplative expression", term: "gazing off-camera" },
   { id: "eye-state-gazing-up",      label: "Gazing Up",         dimension: "eye-state", description: "Eyes raised toward something above", promptHint: "with eyes gazing upward toward something above" },
   { id: "eye-state-gazing-down",    label: "Gazing Down",       dimension: "eye-state", description: "Eyes downcast",                     promptHint: "with eyes downcast, gazing softly downward" },
@@ -697,8 +697,8 @@ export const PEOPLE: ReadonlyArray<Person> = [
   { id: "texture-smooth",     label: "Smooth",      dimension: "skin-texture", description: "Flawless, silky smooth skin", promptHint: "with flawless, silky smooth skin", term: "flawless smooth skin" },
   { id: "texture-wrinkled",   label: "Wrinkled",    dimension: "skin-texture", description: "Aged, deeply lined skin",     promptHint: "with deep wrinkles and aged skin texture", term: "deeply wrinkled aged skin" },
   { id: "texture-goosebumps", label: "Goosebumps",  dimension: "skin-texture", description: "Raised goosebumps on skin",   promptHint: "with goosebumps raised on the skin" },
-  { id: "texture-dewy",       label: "Dewy",        dimension: "skin-texture", description: "Glowing, dewy fresh skin",    promptHint: "with dewy, glowing skin and a fresh sheen", term: "dewy glowing skin" },
-  { id: "texture-glistening", label: "Glistening",  dimension: "skin-texture", description: "Sweat or oil sheen",          promptHint: "with glistening skin, sweat or oil catching the light", term: "glistening skin" , adultOnly: true },
+  { id: "texture-dewy",       label: "Dewy",        dimension: "skin-texture", description: "Glowing, dewy fresh skin",    promptHint: "with dewy, luminous skin", term: "dewy skin" },
+  { id: "texture-glistening", label: "Glistening",  dimension: "skin-texture", description: "Sweat or oil sheen",          promptHint: "with a light glistening sheen on the skin", term: "glistening sheen" , adultOnly: true },
   { id: "texture-weathered",  label: "Weathered",   dimension: "skin-texture", description: "Sun-aged rough skin",         promptHint: "with weathered, sun-worn rough skin", term: "weathered sun-worn skin" },
   { id: "texture-porcelain",  label: "Porcelain",   dimension: "skin-texture", description: "Flawless near-translucent porcelain", promptHint: "with flawless, near-translucent porcelain skin", term: "porcelain skin" },
   { id: "texture-sun-kissed", label: "Sun-kissed",  dimension: "skin-texture", description: "Warm tan with healthy glow",  promptHint: "with sun-kissed skin, warmly tanned with a healthy glow", term: "sun-kissed skin" },
@@ -710,8 +710,8 @@ export const PEOPLE: ReadonlyArray<Person> = [
   { id: "texture-oily",       label: "Oily / Shiny", dimension: "skin-texture", description: "Slight oil sheen on T-zone", promptHint: "with a slight oily sheen across the T-zone", term: "oily shiny skin" , adultOnly: true },
   { id: "texture-matte",      label: "Matte",       dimension: "skin-texture", description: "Poreless matte finish",       promptHint: "with a poreless, matte skin finish", term: "matte skin finish" },
   { id: "texture-blemished",  label: "Blemished",   dimension: "skin-texture", description: "Visible blemishes, real-skin imperfections", promptHint: "with visible blemishes and natural real-skin imperfections", term: "blemished skin" },
-  { id: "texture-baby-soft",  label: "Baby-soft",   dimension: "skin-texture", description: "Smooth, fine-pored youthful skin", promptHint: "with baby-soft, fine-pored, youthful smooth skin", term: "baby-soft skin" },
-  { id: "texture-shower-fresh-wet", label: "Shower-Fresh Wet", dimension: "skin-texture", description: "Just-out-of-shower wet skin with water beads", promptHint: "with just-out-of-the-shower wet skin, water beading on the surface and rolling in slow droplets down the curves of the body", term: "shower-fresh wet skin" , adultOnly: true },
+  { id: "texture-baby-soft",  label: "Baby-soft",   dimension: "skin-texture", description: "Smooth, fine-pored youthful skin", promptHint: "with soft, fine-pored skin", term: "soft fine-pored skin" },
+  { id: "texture-shower-fresh-wet", label: "Shower-Fresh Wet", dimension: "skin-texture", description: "Just-out-of-shower wet skin with water beads", promptHint: "with fresh, water-dappled skin as if just out of the shower", term: "water-dappled skin" , adultOnly: true },
   { id: "texture-acne-scarred", label: "Acne-scarred", dimension: "skin-texture", description: "Visible acne scarring (distinct from blemished — healed scar pattern)", promptHint: "with visible acne scarring, healed pitted-skin texture and uneven surface from past breakouts", term: "acne-scarred skin" },
 
   // -------------------- Distinctive Features --------------------
@@ -741,9 +741,9 @@ export const PEOPLE: ReadonlyArray<Person> = [
   { id: "feature-ear-piercings", label: "Ear Piercings", dimension: "distinctive-features", description: "Multiple stacked ear piercings (cartilage, helix, conch)", promptHint: "with multiple stacked ear piercings — cartilage, helix, and conch", term: "multiple stacked ear piercings" },
   { id: "feature-lip-piercing", label: "Lip Piercing", dimension: "distinctive-features", description: "Lip ring / labret stud", promptHint: "with a lip piercing, a small ring or labret stud at the lip" },
   { id: "feature-nostril-piercing", label: "Nostril Piercing", dimension: "distinctive-features", description: "Single nostril stud or ring", promptHint: "with a single nostril piercing, a small stud or ring at the nostril" },
-  { id: "feature-bare-shoulders", label: "Bare Shoulders", dimension: "distinctive-features", description: "Bare shoulders exposed", promptHint: "with bare shoulders exposed, the line of the collarbone and shoulder muscles uncovered" , adultOnly: true },
-  { id: "feature-collarbone-visible", label: "Collarbone Visible", dimension: "distinctive-features", description: "Prominent collarbone catching light", promptHint: "with a prominent collarbone clearly defined and catching the light", term: "visible collarbone" , adultOnly: true },
-  { id: "feature-midriff-visible", label: "Midriff Visible", dimension: "distinctive-features", description: "Exposed midriff between top and bottom", promptHint: "wearing a cropped style with the midriff visible", term: "visible midriff" , adultOnly: true },
+  { id: "feature-bare-shoulders", label: "Bare Shoulders", dimension: "distinctive-features", description: "Bare shoulders exposed", promptHint: "with the shoulders uncovered", term: "shoulders uncovered" , adultOnly: true },
+  { id: "feature-collarbone-visible", label: "Collarbone Visible", dimension: "distinctive-features", description: "Prominent collarbone catching light", promptHint: "with an open neckline that leaves the collarbones uncovered", term: "open neckline, collarbones uncovered" , adultOnly: true },
+  { id: "feature-midriff-visible", label: "Midriff Visible", dimension: "distinctive-features", description: "Exposed midriff between top and bottom", promptHint: "with a cropped hemline", term: "cropped hemline" , adultOnly: true },
   { id: "feature-navel-visible", label: "Navel Visible", dimension: "distinctive-features", description: "Visible navel on bare stomach", promptHint: "with the navel visible", term: "visible navel" , adultOnly: true },
   { id: "feature-elongated-neck", label: "Elongated Neck", dimension: "distinctive-features", description: "Long swan-like neck", promptHint: "with an elongated, swan-like neck, long and gracefully extended", term: "elongated swan-like neck" },
   { id: "feature-under-eye-circles", label: "Under-Eye Circles", dimension: "distinctive-features", description: "Subtle dark circles under the eyes (distinct from puffy eye-bags)", promptHint: "with subtle dark circles under the eyes", term: "dark under-eye circles" },
@@ -1333,7 +1333,8 @@ function emitIndependentFragments(value: unknown, fragmentFor: PersonFragmentFor
   // "midriff visible" + "navel visible" as separate clauses reads twice as
   // exposed as it is, and stacked with glamour hints it tips borderline draws
   // into content blocks (observed on kie-standard, 2026-07-18 app_reports).
-  // When both are picked, fold them into ONE neutral clause.
+  // When both are picked, fold them into ONE neutral clause
+  // ("with a cropped hemline and the navel showing").
   const midriff = ids.includes("feature-midriff-visible")
   const navel = ids.includes("feature-navel-visible")
   for (const id of ids) {
@@ -1342,7 +1343,7 @@ function emitIndependentFragments(value: unknown, fragmentFor: PersonFragmentFor
       // floored `fragmentFor` (see `emit` in collectPersonFragments) returns
       // "" for a flagged id, so gate the fold on that instead of hardcoding
       // the minor check here.
-      if (id === "feature-midriff-visible" && fragmentFor(id) !== "") out.push("wearing a cropped style, midriff and navel visible")
+      if (id === "feature-midriff-visible" && fragmentFor(id) !== "") out.push("with a cropped hemline and the navel showing")
       continue
     }
     const fragment = fragmentFor(id)

package/src/pose.ts

@@ -105,7 +105,7 @@ export const POSES: ReadonlyArray<Pose> = [
   { id: "throwing",           label: "Throwing",           category: "action",   description: "Mid-throw motion",            promptHint: "caught mid-throw, body coiled and releasing", term: "caught mid-throw" },
   { id: "leaping",            label: "Leaping",            category: "action",   description: "Leaping forward dynamically", promptHint: "leaping forward dynamically with body extended" },
   { id: "dramatic-action",    label: "Dramatic Action",    category: "action",   description: "Exaggerated action pose",     promptHint: "in a dramatic, exaggerated action pose full of motion", term: "dramatic exaggerated action pose" },
-  { id: "biting-lip",         label: "Biting Lip",         category: "action",   description: "Slight playful lip-bite",     promptHint: "biting the lower lip with a subtle playful expression", term: "biting the lower lip" , adultOnly: true },
+  { id: "biting-lip",         label: "Biting Lip",         category: "action",   description: "Slight playful lip-bite",     promptHint: "lightly biting the lower lip, a subtle playful expression", term: "biting lower lip" , adultOnly: true },
   { id: "mid-laugh",          label: "Mid-Laugh",          category: "action",   description: "Caught mid-laugh, head back", promptHint: "caught mid-laugh with head tipped back, eyes crinkled" },
   { id: "pointing-at-camera", label: "Pointing at Camera", category: "action",   description: "Pointing directly at camera", promptHint: "pointing one finger directly at the camera, arm extended", term: "pointing directly at the camera" },
   { id: "tongue-out",         label: "Sticking Tongue Out", category: "action",  description: "Playful tongue-out expression", promptHint: "sticking the tongue out playfully" },

package/src/prompt-builder.ts

@@ -21,7 +21,8 @@ import { buildIdentityLockLine, withForcedIdentityLock } from "./identity-lock.j
 import { findLocationMentionTokens, DEFAULT_LOCATION_USAGE_MODE, type LocationMentionTokenInfo, type LocationUsageMode } from "@nodaro/shared"
 import { findImageMentionTokens, imageMentionSlugForRef, knownImageSlugsFromRefs, type ImageMentionTokenInfo } from "@nodaro/shared"
 import { findEntityMentionTokens, entityMentionSlugForRef, knownEntitySlugsFromRefs, type EntityMentionTokenInfo } from "@nodaro/shared"
-import type { CharacterDef, ConnectedReference, IdentityFidelity, IdentityMeta, ReferenceSource, SceneData } from "@nodaro/shared"
+import type { CharacterDef, ConnectedReference, DescribedReference, IdentityFidelity, IdentityMeta, ReferenceSource, SceneData } from "@nodaro/shared"
+import { appendReferenceLines, referenceDescriptionLine, renderDescribedReferenceLines } from "./described-references.js"
 import { locationReferencePhotoKindLabel, type LocationReferencePhotoKind } from "@nodaro/shared"
 
 export interface ResolveCharacterMentionsResult {
@@ -62,6 +63,30 @@ function composeIdentityDescPart(
   return parts.length > 0 ? `${subject} — ${parts.join(". ")}` : subject
 }
 
+/**
+ * The trailing line a per-use `descriptionOverride` contributes in HYBRID
+ * format. The hybrid role phrase ("the person from reference image A") carries
+ * no description slot, so the override is surfaced as its own binding-subject
+ * line via the ONE phrasing helper in `described-references.ts`. It is pushed
+ * onto the reference's `elementDirectives` — the array every hybrid renderer
+ * already uses for "the trailing scene directives this reference contributes" —
+ * so it lands with that reference's other lines instead of threading a ninth
+ * channel through eight call sites.
+ *
+ * The hybrid EXTRAS path does not call this: it has a real `, <desc>` clause,
+ * which the override fills instead (so the model is never told twice). Nothing
+ * is pushed without an override, which is what keeps every existing hybrid
+ * output byte-identical.
+ */
+function pushOverrideDirective(
+  out: string[],
+  ref: Pick<ConnectedReference, "descriptionOverride">,
+  binding: string,
+): void {
+  const line = referenceDescriptionLine(binding, ref.descriptionOverride)
+  if (line) out.push(line)
+}
+
 /**
  * Resolve @-mention tokens in a prompt against connected references.
  * Returns: augmented prompt (with directives prepended + tokens replaced
@@ -176,9 +201,15 @@ export function resolveCharacterMentions(
       // (held-prop / styling / text) ride the bullet in every mode that emits
       // one. Byte-identical to the old `${subject} — ${canonical}` form when no
       // injection is present.
+      // A per-use `descriptionOverride` IS the caller describing this subject
+      // for this run, so it fills the identity slot ahead of the entity's stored
+      // canonical description — and rides every mode that emits a bullet at all
+      // (the mode gate exists to suppress STORED identity noise, not the
+      // caller's own words). "none" still emits nothing: it returned above.
       const descPart = composeIdentityDescPart(
         subject,
-        includeCanonicalDesc ? match.characterCanonicalDescription : undefined,
+        match.descriptionOverride?.trim()
+          || (includeCanonicalDesc ? match.characterCanonicalDescription : undefined),
         match.elementInjection,
       )
       // `directive` is non-null here because usageModeDirective only returns
@@ -407,6 +438,7 @@ function resolveCharacterMentionsHybrid(
     const binding = bindingFor(m.url)
     const lock = buildIdentityLockLine(withForcedIdentityLock(ref, lockOverrideByUrl.get(m.url)), binding)
     if (lock) lockLines.push(lock)
+    pushOverrideDirective(elementDirectives, ref, binding)
     const inject = ref.elementInjection?.trim()
     if (inject) elementDirectives.push(inject)
   }
@@ -670,9 +702,13 @@ export function resolveLocationMentions(
     // description noise.
     const includeCanonicalDesc = effectiveMode === "identical"
     const canonicalDesc = match.locationCanonicalDescription?.trim()
-    const descPart = includeCanonicalDesc && canonicalDesc
-      ? `${subject} — ${canonicalDesc}`
-      : subject
+    // A per-use `descriptionOverride` IS the caller describing this place for
+    // this run, so it fills the identity slot ahead of the location's stored
+    // canonical description — and rides every mode that emits a bullet at all,
+    // the same rule the character resolvers apply.
+    const shownDesc = match.descriptionOverride?.trim()
+      || (includeCanonicalDesc ? canonicalDesc : undefined)
+    const descPart = shownDesc ? `${subject} — ${shownDesc}` : subject
     directiveLines.push(`- ${descPart}.${directive ? ` ${directive}` : ""}`)
 
     // Variant display-name sub-line: only when the user pinned a specific
@@ -830,6 +866,7 @@ function resolveLocationMentionsHybrid(
     const binding = bindingFor(m.url)
     const lock = buildIdentityLockLine(withForcedIdentityLock(ref, lockOverrideByUrl.get(m.url)), binding)
     if (lock) lockLines.push(lock)
+    pushOverrideDirective(elementDirectives, ref, binding)
     const inject = ref.elementInjection?.trim()
     if (inject) elementDirectives.push(inject)
   }
@@ -848,6 +885,14 @@ interface ResolveImageMentionsHybridResult {
    *  mentioned refs out of `connectedReferences`, and this pass deliberately
    *  does no such filtering (see the caller's NOTE). Carrying the set anyway
    *  would advertise a filter that does not exist. */
+  /**
+   * The URLs a mention BOUND (deduped). This pass already surfaced each bound
+   * ref's per-use `descriptionOverride` as its own trailing line, so the
+   * caller's untold-override sweep skips them — the same by-URL suppression
+   * contract `resolveEntityMentionsHybrid` carries, for the same reason: told
+   * once, never twice.
+   */
+  mentionedUrls: Set<string>
   /** Per-reference identity-lock lines (deduped per URL). Caller prepends them
    *  as ONE block, merged with the character/location lock lines. */
   lockLines: string[]
@@ -955,11 +1000,12 @@ function resolveImageMentionsHybrid(
     const binding = bindingFor(m.url)
     const lock = buildIdentityLockLine(withForcedIdentityLock(ref, lockOverrideByUrl.get(m.url)), binding)
     if (lock) lockLines.push(lock)
+    pushOverrideDirective(elementDirectives, ref, binding)
     const inject = ref.elementInjection?.trim()
     if (inject) elementDirectives.push(inject)
   }
 
-  return { prompt: resolvedPrompt, additionalUrls, lockLines, elementDirectives }
+  return { prompt: resolvedPrompt, additionalUrls, mentionedUrls: seenUrls, lockLines, elementDirectives }
 }
 
 interface ResolveEntityMentionsHybridResult {
@@ -1137,6 +1183,7 @@ function resolveEntityMentionsHybrid(
     const binding = bindingFor(m.url)
     const lock = buildIdentityLockLine(withForcedIdentityLock(ref, lockOverrideByUrl.get(m.url)), binding)
     if (lock) lockLines.push(lock)
+    pushOverrideDirective(elementDirectives, ref, binding)
     const inject = ref.elementInjection?.trim()
     if (inject) elementDirectives.push(inject)
   }
@@ -1221,9 +1268,12 @@ function buildCanonicalFallback(
     // the (mode-gated) canonical description. This is the reported path — a
     // character wired with no @-mention — so a composed character surfaces its
     // elements wherever it's used downstream.
+    // Per-use override ahead of the stored canonical description, mode-gate
+    // included — same rule as the mention path above.
     const descPart = composeIdentityDescPart(
       subject,
-      includeCanonicalDesc ? r.characterCanonicalDescription : undefined,
+      r.descriptionOverride?.trim()
+        || (includeCanonicalDesc ? r.characterCanonicalDescription : undefined),
       r.elementInjection,
     )
     // `directive` is non-null here ("none"/"name" already short-circuited).
@@ -1283,7 +1333,12 @@ function buildExtraRefDirectives(
   for (const r of refs) {
     if (!r.isExtraRef) continue
     if (!r.url) continue
-    const description = (r.description ?? r.variantDescription ?? "").trim()
+    // A per-use `descriptionOverride` fills THIS extra's description slot —
+    // every branch below reads one `description`, so the override lands in the
+    // pair-back tail, the name-mode bullet and the first-sight descriptor alike
+    // (and, being the caller's own words, outranks the stored canonical too).
+    const description = (r.descriptionOverride ?? "").trim()
+      || (r.description ?? r.variantDescription ?? "").trim()
     // Character extra
     if (r.source === "wired-character" && r.characterSlug) {
       const effectiveMode: UsageMode = r.defaultUsageMode ?? DEFAULT_USAGE_MODE
@@ -1421,6 +1476,7 @@ function renderCanonicalFallbackHybrid(
     phrases.push(roleToPhrase(resolveDefaultRole(r.defaultRole, r.defaultUsageMode, r.source), binding))
     const lock = buildIdentityLockLine(r, binding)
     if (lock) lockLines.push(lock)
+    pushOverrideDirective(elementDirectives, r, binding)
     const inject = r.elementInjection?.trim()
     if (inject) elementDirectives.push(inject)
   }
@@ -1464,7 +1520,10 @@ function renderExtraRefsHybrid(
     if (!r.url) continue
     const letter = letterForUrl(r.url)
     const binding = `reference image ${letter}`
-    const description = (r.description ?? r.variantDescription ?? "").trim()
+    // Per-use override fills the extras' own `, <desc>` clause — the one
+    // description slot the hybrid format has (see `described-references.ts`).
+    const description = (r.descriptionOverride ?? "").trim()
+      || (r.description ?? r.variantDescription ?? "").trim()
     if (r.source === "wired-character" && r.characterSlug) {
       const earlier = firstLetterByChar.get(r.characterSlug)
       if (earlier !== undefined && earlier !== letter) {
@@ -1523,12 +1582,16 @@ function renderExtraRefsHybrid(
  * the call site). A location that is BOTH unmentioned AND `{image:N}`-token-
  * referenced is rendered ONCE (inline, via the scene); we `continue` here so it
  * is not ALSO emitted as a trailing canonical phrase (the C1 review Minor).
+ *
+ * `renderedUrls` reports the URLs that DID render here — and therefore already
+ * carry their per-use `descriptionOverride` line — so the caller's untold-
+ * override sweep skips them instead of re-deriving this loop's predicate.
  */
 function renderLocationCanonicalHybrid(
   nonCharacterRefs: readonly ConnectedReference[],
   finalIndexByUrl: ReadonlyMap<string, number>,
   coveredUrls: ReadonlySet<string>,
-): { phrases: string[]; lockLines: string[]; elementDirectives: string[] } {
+): { phrases: string[]; lockLines: string[]; elementDirectives: string[]; renderedUrls: Set<string> } {
   const phrases: string[] = []
   const lockLines: string[] = []
   const elementDirectives: string[] = []
@@ -1546,10 +1609,11 @@ function renderLocationCanonicalHybrid(
     phrases.push(roleToPhrase(resolveLocationRole(null, null, r), binding))
     const lock = buildIdentityLockLine(r, binding)
     if (lock) lockLines.push(lock)
+    pushOverrideDirective(elementDirectives, r, binding)
     const inject = r.elementInjection?.trim()
     if (inject) elementDirectives.push(inject)
   }
-  return { phrases, lockLines, elementDirectives }
+  return { phrases, lockLines, elementDirectives, renderedUrls: seenUrls }
 }
 
 /**
@@ -1576,13 +1640,15 @@ function renderLocationCanonicalHybrid(
  * has to happen HERE, per URL. The mention pass emits the same lock line and
  * `elementInjection` this loop would have, so nothing is lost by skipping it.
  *
- * Deduped per URL (an object wired twice → one phrase).
+ * Deduped per URL (an object wired twice → one phrase). `renderedUrls` reports
+ * the URLs that DID render — already carrying their per-use
+ * `descriptionOverride` line — for the caller's untold-override sweep.
  */
 function renderObjectCreatureCanonicalHybrid(
   nonCharacterRefs: readonly ConnectedReference[],
   finalIndexByUrl: ReadonlyMap<string, number>,
   coveredUrls: ReadonlySet<string>,
-): { phrases: string[]; lockLines: string[]; elementDirectives: string[] } {
+): { phrases: string[]; lockLines: string[]; elementDirectives: string[]; renderedUrls: Set<string> } {
   const phrases: string[] = []
   const lockLines: string[] = []
   const elementDirectives: string[] = []
@@ -1597,10 +1663,49 @@ function renderObjectCreatureCanonicalHybrid(
     phrases.push(roleToPhrase(defaultRoleForSource(r.source), binding))
     const lock = buildIdentityLockLine(r, binding)
     if (lock) lockLines.push(lock)
+    pushOverrideDirective(elementDirectives, r, binding)
     const inject = r.elementInjection?.trim()
     if (inject) elementDirectives.push(inject)
   }
-  return { phrases, lockLines, elementDirectives }
+  return { phrases, lockLines, elementDirectives, renderedUrls: seenUrls }
+}
+
+/**
+ * The per-use `descriptionOverride` of every non-character reference the hybrid
+ * format renders NO role phrase for — the last leg of "the override is honoured
+ * wherever the reference ships".
+ *
+ * Three kinds land here: a ref a `{image:N:label}` token expanded INLINE (the
+ * expansion carries no description slot, and the covered set suppresses both
+ * canonical renders), an unmentioned `wired-image` / `manual` / `wired-face` ref
+ * (no canonical render exists for those sources at all), and any other seated
+ * ref the passes above left unspoken. Each gets ONE
+ * `reference image <LETTER> — <override>.` line, from the same helper every
+ * other site uses, numbered against `finalIndexByUrl`.
+ *
+ * `toldUrls` is every URL a pass above ALREADY gave an override line — the two
+ * canonical renders' `renderedUrls` plus the image / entity mention passes'
+ * bound URLs — so a reference that is both @-mentioned and token-covered is told
+ * once, never twice. A URL is marked swept only when it actually emitted a line,
+ * so two refs sharing one URL where only the later carries an override still
+ * speak.
+ */
+function renderUntoldOverridesHybrid(
+  nonCharacterRefs: readonly ConnectedReference[],
+  finalIndexByUrl: ReadonlyMap<string, number>,
+  toldUrls: ReadonlySet<string>,
+): string[] {
+  const lines: string[] = []
+  const sweptUrls = new Set<string>()
+  for (const r of nonCharacterRefs) {
+    if (!r.url || toldUrls.has(r.url) || sweptUrls.has(r.url)) continue
+    const slot = finalIndexByUrl.get(r.url)
+    if (!slot) continue
+    const before = lines.length
+    pushOverrideDirective(lines, r, `reference image ${slotToLetter(slot)}`)
+    if (lines.length > before) sweptUrls.add(r.url)
+  }
+  return lines
 }
 
 /**
@@ -1874,6 +1979,16 @@ export interface BuildImagePromptConfig {
    * in order, and tokens expand to "the {label} from image {N}".
    */
   connectedReferences?: ConnectedReference[]
+  /**
+   * References the caller can NAME and DESCRIBE but has no media for (an
+   * un-bound cast role, an analysis slot). They attach no URL and claim no
+   * `Image N` / lettered slot — they reach the model as prose, rendered once by
+   * `renderDescribedReferenceLines` and joined the way the active format joins
+   * its trailing directives. Present with NO `connectedReferences` is the normal
+   * case (a story landing before any entity exists), so they enter the
+   * connected-reference path on their own.
+   */
+  describedReferences?: readonly DescribedReference[]
   /** Per-identity (imageIndex+label) user overrides for fidelity / custom text. */
   identityMeta?: readonly IdentityMeta[]
   /**
@@ -2141,6 +2256,13 @@ function buildImagePromptInternal(config: BuildImagePromptConfig, marks?: Assemb
   // reassignment, so computing this once up front is stable. Gates the hybrid
   // character convergence (Phase 0) and the non-capitalizing scene render below.
   const isHybrid = config.referenceFormat === "hybrid"
+  // Described references (name + description, no media) — rendered ONCE, up
+  // front, so the reassignments below can't lose them. They attach no URL, so
+  // they take no part in numbering; they are joined onto the assembled prompt at
+  // the single site in the connected-reference path below, ahead of the provider
+  // cap so a shed sees them like any other body text. Empty for every caller
+  // that doesn't send them → nothing downstream changes.
+  const describedLines = renderDescribedReferenceLines(config.describedReferences)
   // Set when Phase 0 converged character OR location @-mentions into inline
   // hybrid role phrases (+ identity-lock + element directives). Tells the hybrid
   // scene render to expand any remaining {image:N} tokens WITHOUT capitalizing
@@ -2155,6 +2277,12 @@ function buildImagePromptInternal(config: BuildImagePromptConfig, marks?: Assemb
   // every prompt without an entity mention, which is what keeps those outputs
   // byte-identical.
   const mentionedEntityUrls = new Set<string>()
+  // URLs bound by a Phase-0 named-image (`@<image-name>`) mention. Bridges the
+  // same two blocks for the OTHER suppression the New path owes: that pass
+  // already emitted each bound ref's per-use `descriptionOverride` line, so the
+  // untold-override sweep must not say it a second time. Empty for every prompt
+  // without an image mention.
+  const mentionedImageUrls = new Set<string>()
 
   // Character LoRA inference path: trigger word + LoRA model carry identity,
   // so we strip raw `@slug[:V[:variant]]` tokens from the prompt AND drop the
@@ -2410,6 +2538,10 @@ function buildImagePromptInternal(config: BuildImagePromptConfig, marks?: Assemb
           resolved.additionalUrls = [...resolved.additionalUrls, ...hi.additionalUrls]
           hybridImageLockLines = hi.lockLines
           hybridImageElementDirectives = hi.elementDirectives
+          // The override handoff to the New path: a bound URL was already told
+          // its per-use description here, inline with the mention, so the
+          // untold-override sweep below skips it.
+          for (const u of hi.mentionedUrls) mentionedImageUrls.add(u)
           // Inline role phrases now live in the body → skip line-initial
           // capitalization, which would otherwise corrupt a mid-sentence
           // "the background from reference image C".
@@ -2646,9 +2778,25 @@ function buildImagePromptInternal(config: BuildImagePromptConfig, marks?: Assemb
   // wired-image, wired-face, wired-object, wired-location) still auto-
   // attach so unchanged behavior for them.
   // -------------------------------------------------------------------------
-  if (connectedReferences) {
+  // Entered by `connectedReferences` OR by described references alone: a story
+  // landing whose cast has no entities yet sends only names + descriptions, and
+  // the legacy path below has no directive seam to join them onto.
+  if (connectedReferences || describedLines.length > 0) {
+    const structuredRefs = connectedReferences ?? []
     let prompt = config.prompt
 
+    // Described references, LEGACY half — joined BEFORE the directive assembly
+    // below, because the block it creates is the block that assembly consolidates
+    // into. Joined AFTER instead, a request whose references produce the
+    // "Use these references for the output image:" wrap (any non-character ref,
+    // no wired character) would get a SECOND "Use these characters:" header
+    // prepended above it. Prepending here also keeps `marks.directivesPrefix`
+    // honest: the prepend branch that records it is only reachable when the
+    // prompt does NOT already open with the character block.
+    if (!isHybrid && describedLines.length > 0) {
+      prompt = appendReferenceLines(prompt, describedLines, "legacy")
+    }
+
     // Non-character refs are still emitted as per-identity directives + URLs.
     // Character refs are filtered out here — Phase 0 has already added their
     // URLs to `referenceImageUrls` (via mention resolution) and prepended the
@@ -2658,7 +2806,7 @@ function buildImagePromptInternal(config: BuildImagePromptConfig, marks?: Assemb
     // subject as Image M, …") and merged their URLs into `referenceImageUrls`.
     // Letting them through here would double-emit the URLs (and append a
     // second positional directive via the {image:N:label} path).
-    const nonCharacterRefs = connectedReferences.filter(
+    const nonCharacterRefs = structuredRefs.filter(
       (r) => r.source !== "wired-character" && r.isExtraRef !== true,
     )
 
@@ -2761,9 +2909,27 @@ function buildImagePromptInternal(config: BuildImagePromptConfig, marks?: Assemb
       const objCanon = renderObjectCreatureCanonicalHybrid(nonCharacterRefs, finalIndexByUrl, objCoveredUrls)
       const canonLockLines = [...locCanon.lockLines, ...objCanon.lockLines]
       const canonLockBlock = canonLockLines.length > 0 ? `${canonLockLines.join("\n")}\n\n` : ""
+      // Per-use descriptions nothing above spoke for: a `{image:N}`-covered ref
+      // (expanded inline, suppressed from both canonical renders) and a seated
+      // `wired-image` / `manual` ref (which has no canonical render at all)
+      // would otherwise drop their `descriptionOverride` silently — the one
+      // place the hybrid format renders neither a description slot nor a role
+      // phrase. Deduped against every URL a pass above already told.
+      const toldOverrideUrls = new Set<string>([
+        ...locCanon.renderedUrls,
+        ...objCanon.renderedUrls,
+        ...mentionedEntityUrls,
+        ...mentionedImageUrls,
+      ])
+      const untoldOverrides = renderUntoldOverridesHybrid(
+        nonCharacterRefs,
+        finalIndexByUrl,
+        toldOverrideUrls,
+      )
       const canonTrailingLines = [
         ...locCanon.phrases, ...objCanon.phrases,
         ...locCanon.elementDirectives, ...objCanon.elementDirectives,
+        ...untoldOverrides,
       ]
       // Role phrases and element injections are scene content → they extend the
       // BODY, ahead of the `[style]` section (which has no terminator, so a flat
@@ -2811,6 +2977,14 @@ function buildImagePromptInternal(config: BuildImagePromptConfig, marks?: Assemb
       }
     }
 
+    // Described references, HYBRID half: trailing scene directives, so they land
+    // behind the reference role phrases the branch above appended (the legacy
+    // half ran before it — see the comment at that call). Still ahead of the
+    // provider cap below, so the lines are body text like any other.
+    if (isHybrid && describedLines.length > 0) {
+      prompt = appendReferenceLines(prompt, describedLines, "hybrid")
+    }
+
     const styleText = style?.trim()
     const styleLine = styleText && !isDeniedStyleId(styleText) ? `Style: ${getStylePromptHint(styleText) || styleText}` : ""
 
@@ -2883,7 +3057,7 @@ function buildImagePromptInternal(config: BuildImagePromptConfig, marks?: Assemb
       const reordered = applyReferenceOrder(
         assembledUrls,
         prompt,
-        connectedReferences,
+        structuredRefs,
         referenceOrder,
         sourceNodeIdById,
       )
@@ -3110,7 +3284,10 @@ function collectIdentities(
       label,
       fidelity: m?.fidelity ?? defaultFidelityForSource(ref?.source),
       customText: m?.customText?.trim() || undefined,
-      description: ref?.description,
+      // Per-use override ahead of the ref's own description; the directive
+      // builder's location-canonical fallback only fires when BOTH are absent,
+      // so an override outranks the stored location wording too.
+      description: ref?.descriptionOverride?.trim() || ref?.description,
       source: ref?.source,
       locationCanonicalDescription: ref?.locationCanonicalDescription,
       locationSlug: ref?.locationSlug,
@@ -3303,7 +3480,7 @@ function buildNonCharacterDirectives(
             ? "creature"
             : "object",
         fidelity: defaultFidelityForSource(ref.source),
-        description: ref.description?.trim() || undefined,
+        description: ref.descriptionOverride?.trim() || ref.description?.trim() || undefined,
         source: ref.source,
         locationCanonicalDescription: ref.locationCanonicalDescription,
         locationSlug: ref.locationSlug,