@nodaro/prompts 1.16.0 → 1.17.1

package/src/described-references.ts

@@ -0,0 +1,138 @@
+/**
+ * Described references + per-reference description overrides + rail captions —
+ * the ONE place either lane phrases "what this reference IS".
+ *
+ * Three shapes, one grammar (`<subject> — <description>.`) plus the caption's
+ * `<binding>: <caption>.`:
+ *
+ *   - a DESCRIBED reference (`DescribedReference`, no media) → `Natalie — a
+ *     tall woman in a red coat.` The subject is the NAME, because a described
+ *     reference has no seat to bind to: correlation with the prose is by name,
+ *     which is why the caller leaves the name in the prompt rather than an
+ *     indexed `@slug:N` mention (that grammar is url-gated).
+ *   - a per-use `descriptionOverride` on a reference the HYBRID format gives no
+ *     description slot (a mention / canonical-fallback / location / object role
+ *     phrase carries none) → `reference image A — a tall woman in a red coat.`
+ *     Same grammar, the BINDING as the subject. Where a description slot DOES
+ *     exist (every legacy bullet, and the hybrid extras' `, <desc>` clause) the
+ *     override fills THAT slot instead, so the model is never told twice.
+ *   - a rail CAPTION for a video / audio reference → `@video_1: the establishing
+ *     drone shot.` Index-aligned with the caller's url array.
+ *
+ * Rendering is separate from JOINING on purpose: the lines are format-agnostic
+ * text, and each lane already owns where a trailing directive goes (the image
+ * hybrid's `trailingLines`, the video core's `trailingLines` /
+ * `allFallbackLines`). `appendReferenceLines` is the joiner for the call sites
+ * that have no such array to push into — it bullets the lines into the legacy
+ * "Use these characters:" block or lands them ahead of the `[style]` section in
+ * hybrid, matching what each lane's own assembly does.
+ */
+
+import type { DescribedReference } from "@nodaro/shared"
+import { insertBeforeStyleSection } from "./prompt-style-section.js"
+
+/** Which reference-prompt format the lines are being rendered for. */
+export type ReferenceLineFormat = "legacy" | "hybrid"
+
+/** The legacy directive block every lane consolidates its bullets into. */
+const CHARACTER_BLOCK_HEADER = "Use these characters:"
+
+/**
+ * The ONE phrasing for "this subject is described as …":
+ * `<subject> — <description>.`
+ *
+ * `subject` is the name for a described reference and the reference's binding
+ * (`reference image A` / `@image_2`) for a per-use description override. Both
+ * halves are trimmed; an empty half yields `""` (the caller drops the line).
+ */
+export function referenceDescriptionLine(
+  subject: string,
+  description: string | null | undefined,
+): string {
+  const s = subject.trim()
+  const d = description?.trim()
+  if (!s || !d) return ""
+  return `${s} — ${d}.`
+}
+
+/**
+ * Render the described references (name + description, no media) as trailing
+ * lines. Entries missing either half contribute nothing; entries repeating a
+ * name (case-insensitively) render once — a description a caller sent twice
+ * says nothing new to the model, and every sibling renderer in both lanes
+ * dedups the same way.
+ */
+export function renderDescribedReferenceLines(
+  refs: readonly DescribedReference[] | undefined,
+): string[] {
+  if (!refs || refs.length === 0) return []
+  const lines: string[] = []
+  const seen = new Set<string>()
+  for (const r of refs) {
+    const key = r.name?.trim().toLowerCase()
+    if (!key || seen.has(key)) continue
+    const line = referenceDescriptionLine(r.name, r.description)
+    if (!line) continue
+    seen.add(key)
+    lines.push(line)
+  }
+  return lines
+}
+
+/**
+ * Render the video / audio rail captions as `@video_N: <caption>.` /
+ * `@audio_N: <caption>.` lines, index-aligned with the caller's url arrays.
+ *
+ * Each list is bounded by the count of references of that kind that actually
+ * ship, so a caption for a url the provider cap dropped never binds a phantom
+ * `@video_N`. Blank captions are holes in an aligned array, not lines.
+ */
+export function renderReferenceCaptionLines(
+  videoCaptions: readonly string[] | undefined,
+  audioCaptions: readonly string[] | undefined,
+  counts: { readonly video: number; readonly audio: number },
+): string[] {
+  const lines: string[] = []
+  const render = (captions: readonly string[] | undefined, kind: "video" | "audio", cap: number) => {
+    if (!captions) return
+    for (let i = 0; i < captions.length && i < cap; i++) {
+      const text = captions[i]?.trim()
+      if (!text) continue
+      lines.push(`@${kind}_${i + 1}: ${text}.`)
+    }
+  }
+  render(videoCaptions, "video", counts.video)
+  render(audioCaptions, "audio", counts.audio)
+  return lines
+}
+
+/**
+ * Append reference lines to an assembled prompt the way the surrounding lane
+ * would have.
+ *
+ *   - hybrid → trailing scene directives ahead of the `[style]` section (the
+ *     section has no terminator, so a flat append would read as one more look
+ *     clause).
+ *   - legacy → `- ` bullets consolidated into the existing
+ *     "Use these characters:" block, or a new block prepended ahead of the
+ *     body — the same splice-or-create both lanes already do for their
+ *     canonical-fallback and extra-ref bullets.
+ *
+ * No lines → the prompt is returned unchanged, byte-for-byte.
+ */
+export function appendReferenceLines(
+  prompt: string,
+  lines: readonly string[],
+  format: ReferenceLineFormat,
+): string {
+  if (lines.length === 0) return prompt
+  if (format === "hybrid") return insertBeforeStyleSection(prompt, lines)
+  const bullets = lines.map((l) => `- ${l}`).join("\n")
+  if (prompt.startsWith(`${CHARACTER_BLOCK_HEADER}\n`)) {
+    const splitIdx = prompt.indexOf("\n\n")
+    if (splitIdx === -1) return `${prompt}\n${bullets}`
+    return `${prompt.slice(0, splitIdx)}\n${bullets}${prompt.slice(splitIdx)}`
+  }
+  const block = `${CHARACTER_BLOCK_HEADER}\n${bullets}`
+  return prompt ? `${block}\n\n${prompt}` : block
+}

package/src/index.ts

@@ -16,6 +16,7 @@ export * from "./term.js"
 export * from "./parameter-prompt-hint.js"
 export * from "./entity-prompts.js"
 export * from "./brand-tokens.js"
+export * from "./described-references.js"
 export * from "./prompt-builder.js"
 export * from "./prompt-builder-structured-fields.js"
 export * from "./direction-registry.js"

package/src/node-prompt-fields.ts

@@ -118,6 +118,8 @@ export const NODE_PROMPT_FIELDS: Readonly<Record<string, PromptFieldSpec>> = {
   // ── Composition / FX (compact, no media-result preview → no inline editor) ──
   "image-critic": { prompt: "prompt", promptLabel: "Criteria", media: "image", inline: false },
   "motion-graphics": { prompt: "motionPrompt", promptLabel: "Motion prompt", media: "video", inline: false },
+  "generate-3d-scene": { prompt: "scenePrompt", promptLabel: "Scene", media: "text", inline: false },
+  "edit-3d-scene": { prompt: "editPrompt", promptLabel: "Edit instruction", media: "text", inline: false },
   "3d-title": { prompt: "titlePrompt", promptLabel: "Title", media: "text", inline: false },
   // ── Script / alignment (their primary text field) ──
   "generate-script": { prompt: "styleGuide", promptLabel: "Style guide", media: "text", inline: false },

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,