@nodaro/prompts 1.19.0 → 1.21.0

package/src/__tests__/graph-composed-unwired-identity.test.ts

@@ -0,0 +1,166 @@
+import { describe, it, expect } from "vitest"
+
+import { getParameterPromptHint } from "../parameter-prompt-hint.js"
+import { getPickerCatalog, type PickerOption } from "../picker-catalogs.js"
+import { composeTransitionHintFromConnections } from "../transitions.js"
+import { composeCharacterFxHintFromConnections } from "../character-fx.js"
+import type { HintEdgeLike, HintGraphContext, HintNodeLike } from "@nodaro/shared"
+
+/**
+ * THE BOUND ON "compose transition and character-fx from the graph on every
+ * path", as a proof rather than a claim.
+ *
+ * Transition and character-fx joined `EXECUTION_GRAPH_COMPOSED_PARAMETER_TYPES`
+ * (@nodaro/shared) and `LABEL_REF_GRAPH_COMPOSED_PARAMETER_TYPES` (backend
+ * `services/workflow-engine/label-ref-hint-context.ts`), so every executor now
+ * hands them the graph. That deliberately changes the prompt of a workflow that
+ * WIRES them — signed off, and the new text is the text the picker's own
+ * injection preview has always shown.
+ *
+ * What was signed off with it is the BOUND: a picker with nothing wired to its
+ * own composing handles (`startState` / `endState` for transition, `target` for
+ * character-fx) must emit BYTE-IDENTICAL text with and without the graph, so a
+ * workflow that wires nothing cannot move at all. This file walks every entry
+ * of both catalogs, in both hint modes, under two unwired graph shapes, and
+ * asserts that equality — then proves it is not vacuous with wired positive
+ * controls that MUST differ.
+ *
+ * Why two unwired shapes: "unwired" in a real workflow does not mean an
+ * isolated node. The picker is normally wired INTO a consumer (an outgoing
+ * `cinematography` edge) while nothing feeds its own handles — the walker in
+ * `resolveParameterHint` only ever looks at edges whose TARGET is the picker,
+ * and this pins that.
+ */
+
+const MODES = ["full", "compact"] as const
+
+/** The two pickers this change admitted, with the data field each reads. */
+const SUBJECTS = [
+  { type: "transition", valueField: "transition" },
+  { type: "character-fx", valueField: "characterFx" },
+] as const
+
+function optionsFor(type: string): readonly PickerOption[] {
+  const catalog = getPickerCatalog(type)
+  if (!catalog?.options?.length) throw new Error(`no registered picker catalog options for ${type}`)
+  return catalog.options
+}
+
+function pickerNode(type: string, valueField: string, id: string, mode: string): HintNodeLike {
+  return { id: "picker", type, data: { [valueField]: id, hintMode: mode } }
+}
+
+/** Nothing at all around the picker. */
+function isolated(node: HintNodeLike): HintGraphContext {
+  return { nodes: [node], edges: [] }
+}
+
+/** The realistic unwired shape: the picker FEEDS a consumer, but nothing feeds it. */
+function wiredIntoConsumer(node: HintNodeLike): HintGraphContext {
+  const consumer: HintNodeLike = { id: "consumer", type: "generate-video", data: { prompt: "a man walks forward" } }
+  const edges: HintEdgeLike[] = [
+    { source: node.id, target: consumer.id, sourceHandle: null, targetHandle: "cinematography" },
+  ]
+  return { nodes: [node, consumer], edges }
+}
+
+const UNWIRED_SHAPES = [
+  { name: "isolated (no edges at all)", build: isolated },
+  { name: "wired INTO a consumer, nothing wired into it", build: wiredIntoConsumer },
+] as const
+
+describe("unwired transition / character-fx pickers are byte-identical with and without the graph", () => {
+  for (const { type, valueField } of SUBJECTS) {
+    for (const { name, build } of UNWIRED_SHAPES) {
+      it(`${type}: every catalog entry × both hint modes, ${name}`, () => {
+        const options = optionsFor(type)
+        const differences: string[] = []
+        let compared = 0
+
+        for (const option of options) {
+          for (const mode of MODES) {
+            const node = pickerNode(type, valueField, option.id, mode)
+            const withoutGraph = getParameterPromptHint(node)
+            const withGraph = getParameterPromptHint(node, build(node))
+            compared += 1
+            if (withGraph !== withoutGraph) {
+              differences.push(`${type}/${option.id}/${mode}: ${JSON.stringify(withoutGraph)} -> ${JSON.stringify(withGraph)}`)
+            }
+          }
+        }
+
+        // Non-vacuity of the WALK itself: a catalog that somehow arrived empty
+        // would pass a zero-difference assertion trivially.
+        expect(compared).toBe(options.length * MODES.length)
+        expect(compared).toBeGreaterThan(20)
+        expect(differences).toEqual([])
+      })
+    }
+  }
+
+  it("the catalogs really do carry injecting entries (the comparison is over real text, not all empty strings)", () => {
+    // `auto` / `none` inject "" by design and are legitimately compared; this
+    // asserts they are not ALL of it, so the identity above is meaningful.
+    for (const { type, valueField } of SUBJECTS) {
+      const injecting = optionsFor(type).filter(
+        (o) => getParameterPromptHint(pickerNode(type, valueField, o.id, "full")).trim().length > 0,
+      )
+      expect(injecting.length, type).toBeGreaterThan(20)
+    }
+  })
+})
+
+describe("positive control — a WIRED picker must differ (or the bound above proves nothing)", () => {
+  /** A tone node: free text, so its fragment is identical in both hint modes,
+   *  which keeps the control honest without re-deriving inherited-mode text. */
+  const tone = (id: string, text: string): HintNodeLike => ({ id, type: "tone", data: { tone: text } })
+
+  it("transition: a startState + endState wire changes the text, in both modes", () => {
+    const id = optionsFor("transition").find(
+      (o) => getParameterPromptHint(pickerNode("transition", "transition", o.id, "full")).trim().length > 0,
+    )!.id
+    const start = tone("start", "warm golden morning light")
+    const end = tone("end", "cold blue dusk")
+
+    for (const mode of MODES) {
+      const node = pickerNode("transition", "transition", id, mode)
+      const ctx: HintGraphContext = {
+        nodes: [node, start, end],
+        edges: [
+          { source: "start", target: node.id, sourceHandle: null, targetHandle: "startState" },
+          { source: "end", target: node.id, sourceHandle: null, targetHandle: "endState" },
+        ],
+      }
+      const composed = getParameterPromptHint(node, ctx)
+      expect(composed).not.toBe(getParameterPromptHint(node))
+      // Derived from the catalog composer, never a hand-written sentence.
+      expect(composed).toBe(
+        composeTransitionHintFromConnections(
+          id,
+          [getParameterPromptHint(start)],
+          [getParameterPromptHint(end)],
+          undefined,
+          mode,
+        ),
+      )
+    }
+  })
+
+  it("character-fx: a target ref wire changes the text, in both modes", () => {
+    const id = optionsFor("character-fx").find(
+      (o) => getParameterPromptHint(pickerNode("character-fx", "characterFx", o.id, "full")).trim().length > 0,
+    )!.id
+    const mira: HintNodeLike = { id: "mira", type: "character", data: { characterName: "Mira" } }
+
+    for (const mode of MODES) {
+      const node = pickerNode("character-fx", "characterFx", id, mode)
+      const ctx: HintGraphContext = {
+        nodes: [node, mira],
+        edges: [{ source: "mira", target: node.id, sourceHandle: null, targetHandle: "target" }],
+      }
+      const composed = getParameterPromptHint(node, ctx)
+      expect(composed).not.toBe(getParameterPromptHint(node))
+      expect(composed).toBe(composeCharacterFxHintFromConnections(id, ["Mira"], undefined, mode))
+    }
+  })
+})

package/src/__tests__/parameter-hint-mode.test.ts

@@ -194,6 +194,33 @@ describe("hint mode: compact preserves everything but the base fragment", () =>
     expect(compact).toContain("with extreme exaggerated energy, wild flourishes, and dramatic distortion")
   })
 
+  it("character-motion timing clauses are emitted identically in compact mode", () => {
+    const move = firstInjectingId("character-motion")
+    const data = { characterMotion: move, position: "full", pace: "explosive" }
+    const compact = getParameterPromptHint({ id: "n1", type: "character-motion", data: { ...data, hintMode: "compact" } })
+    expect(compact).toContain("the movement plays out across the entire clip")
+    expect(compact).toContain("performed with an explosive burst of energy, snapping from stillness into full-speed motion")
+  })
+
+  it("character-motion names target and partner in both modes", () => {
+    const ctx: HintGraphContext = {
+      nodes: [
+        { id: "c1", type: "character-ref", data: { characterName: "Mira" } },
+        { id: "c2", type: "character-ref", data: { characterName: "Theo" } },
+      ],
+      edges: [
+        { source: "c1", target: "n1", targetHandle: "target" },
+        { source: "c2", target: "n1", targetHandle: "partner" },
+      ],
+    }
+    const node: HintNodeLike = { id: "n1", type: "character-motion", data: { characterMotion: "hug-partner" } }
+    for (const out of [getParameterPromptHint(node, ctx), getParameterPromptHint(withMode(node, "compact"), ctx)]) {
+      expect(out).toContain("Mira")
+      expect(out).toContain("Theo")
+      expect(out).not.toMatch(/\bthe (subject|partner)\b/)
+    }
+  })
+
   it("the wired character is NAMED in both modes", () => {
     // Regression: compact mode used to run the full mode's substitution — a
     // regex replace of "the subject" — over a `term` that never contains those
@@ -282,6 +309,7 @@ describe("hint mode: compact preserves everything but the base fragment", () =>
     for (const [type, field] of [
       ["transition", "transition"],
       ["character-fx", "characterFx"],
+      ["character-motion", "characterMotion"],
       ["camera-motion", "cameraMotion"],
     ] as const) {
       expect(getParameterPromptHint({ id: "n1", type, data: { [field]: "auto", hintMode: "compact" } })).toBe("")

package/src/__tests__/parameter-prompt-hint.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect } from "vitest"
 import { getParameterPromptHint } from "../parameter-prompt-hint.js"
 import { PARAMETER_NODE_TYPES, getParameterValue } from "@nodaro/shared"
 import { ACTION_FX } from "../action-fx.js"
+import { getCharacterMotionPromptHint, getCharacterMotionTerm } from "../character-motion.js"
 
 describe("getParameterPromptHint — action-fx", () => {
   it("returns the catalog hint for a single id", () => {
@@ -268,3 +269,167 @@ describe("getParameterPromptHint — preText/postText for graph-aware nodes", ()
     expect(out).toContain("POST_FX")
   })
 })
+
+describe("getParameterPromptHint — character-motion", () => {
+  const ctx = {
+    nodes: [
+      { id: "c1", type: "character", data: { characterName: "Mira" } },
+      { id: "c2", type: "character", data: { characterName: "Theo" } },
+    ],
+    edges: [
+      { source: "c1", target: "n1", targetHandle: "target" },
+      { source: "c2", target: "n1", targetHandle: "partner" },
+    ],
+  }
+
+  it("composes the ordered sequence with target and partner names from the graph", () => {
+    const out = getParameterPromptHint(
+      { id: "n1", type: "character-motion", data: { characterMotion: ["wave-hello", "hug-partner"] } },
+      ctx,
+    )
+    expect(out).toBe(
+      `${getCharacterMotionPromptHint("wave-hello").replace(/\bthe subject\b/g, "Mira")}, then ${getCharacterMotionPromptHint("hug-partner").replace(/\bthe subject\b/g, "Mira").replace(/\bthe partner\b/g, "Theo")}`,
+    )
+  })
+
+  it("reads position and pace and wraps preText / postText", () => {
+    const out = getParameterPromptHint({
+      id: "n1",
+      type: "character-motion",
+      data: { characterMotion: "wave-hello", position: "end", pace: "fast", preText: "PRE_M", postText: "POST_M" },
+    })
+    expect(out.startsWith("PRE_M")).toBe(true)
+    expect(out.endsWith("POST_M")).toBe(true)
+    expect(out).toContain("the movement happens in the closing moments of the clip")
+    expect(out).toContain("performed quickly")
+  })
+
+  it("compact mode names the target by prefix and the partner in the term", () => {
+    const out = getParameterPromptHint(
+      { id: "n1", type: "character-motion", data: { characterMotion: "hug-partner", hintMode: "compact" } },
+      ctx,
+    )
+    expect(out).toBe(`Mira: ${getCharacterMotionTerm("hug-partner").replace(/\bthe partner\b/g, "Theo")}`)
+  })
+
+  it("ignores edges on other handles", () => {
+    const out = getParameterPromptHint(
+      { id: "n1", type: "character-motion", data: { characterMotion: "wave-hello" } },
+      { nodes: ctx.nodes, edges: [{ source: "c1", target: "n1", targetHandle: "in" }] },
+    )
+    expect(out).toBe(getCharacterMotionPromptHint("wave-hello"))
+  })
+})
+
+// D9 option (b)-lite: a ref wired into `target` OR `partner` that describes a
+// minor (structured `person` age, or an age in its free-text description)
+// makes the composer drop every adultOnly move. wave-hello is neutral;
+// kiss-partner is adultOnly.
+describe("getParameterPromptHint — character-motion minor-age floor", () => {
+  const MINOR = { age: "age-child" }
+  const ADULT = { age: "age-30s" }
+  const motion = { id: "n1", type: "character-motion", data: { characterMotion: ["wave-hello", "kiss-partner"] } }
+  const wave = (target: string) => getCharacterMotionPromptHint("wave-hello").replace(/\bthe subject\b/g, target)
+  // kiss-partner names the partner twice. A wired name repeats; the unwired
+  // fallback is introduced once and referred back to after that.
+  const kiss = (target: string, ...partner: readonly string[]) => {
+    let i = 0
+    return getCharacterMotionPromptHint("kiss-partner")
+      .replace(/\bthe subject\b/g, target)
+      .replace(/\bthe partner\b/g, () => partner[Math.min(i++, partner.length - 1)]!)
+  }
+
+  it("a minor wired to target drops the adult-only move and keeps the neutral one", () => {
+    const out = getParameterPromptHint(motion, {
+      nodes: [{ id: "c1", type: "character", data: { characterName: "Mira", person: MINOR } }],
+      edges: [{ source: "c1", target: "n1", targetHandle: "target" }],
+    })
+    expect(out).toBe(wave("Mira"))
+    expect(out).not.toMatch(/kiss/i)
+  })
+
+  it("an adult wired to target keeps both moves", () => {
+    const out = getParameterPromptHint(motion, {
+      nodes: [{ id: "c1", type: "character", data: { characterName: "Mira", person: ADULT } }],
+      edges: [{ source: "c1", target: "n1", targetHandle: "target" }],
+    })
+    expect(out).toBe(`${wave("Mira")}, then ${kiss("Mira", "another person", "that same person")}`)
+    expect(out).toMatch(/kiss/)
+  })
+
+  it("a minor wired only to partner also drops the adult-only move", () => {
+    const out = getParameterPromptHint(motion, {
+      nodes: [
+        { id: "c1", type: "character", data: { characterName: "Mira", person: ADULT } },
+        { id: "c2", type: "character", data: { characterName: "Theo", person: MINOR } },
+      ],
+      edges: [
+        { source: "c1", target: "n1", targetHandle: "target" },
+        { source: "c2", target: "n1", targetHandle: "partner" },
+      ],
+    })
+    expect(out).toBe(wave("Mira"))
+    expect(out).not.toMatch(/kiss/i)
+  })
+
+  it("a minor described only in free text drops the adult-only move", () => {
+    for (const field of ["description", "seedPrompt", "canonicalDescription"] as const) {
+      const out = getParameterPromptHint(motion, {
+        nodes: [{ id: "c1", type: "character", data: { characterName: "Mira", [field]: "a 12-year-old girl in a red coat" } }],
+        edges: [{ source: "c1", target: "n1", targetHandle: "target" }],
+      })
+      expect(out, field).toBe(wave("Mira"))
+    }
+  })
+
+  it("an unnamed ref that describes a minor still floors", () => {
+    const out = getParameterPromptHint(motion, {
+      nodes: [{ id: "c1", type: "character", data: { person: MINOR } }],
+      edges: [{ source: "c1", target: "n1", targetHandle: "target" }],
+    })
+    expect(out).toBe(getCharacterMotionPromptHint("wave-hello"))
+    expect(out).not.toMatch(/kiss/i)
+  })
+
+  it("a minor on an unrelated handle does not floor", () => {
+    const out = getParameterPromptHint(motion, {
+      nodes: [{ id: "c1", type: "character", data: { characterName: "Mira", person: MINOR } }],
+      edges: [{ source: "c1", target: "n1", targetHandle: "in" }],
+    })
+    expect(out).toMatch(/kiss/)
+  })
+})
+
+// A Creature (data.creatureName) wired to Character Motion's target / partner is
+// named like the other identity refs. The creature read is local to Character
+// Motion: Character FX (and Camera Motion) keep the shared name read unchanged.
+describe("getParameterPromptHint — character-motion names a creature ref", () => {
+  const rex = { id: "k1", type: "creature", data: { creatureName: "  Rex  " } }
+
+  it("a creature on partner is named in the two-person move", () => {
+    const out = getParameterPromptHint(
+      { id: "n1", type: "character-motion", data: { characterMotion: "hug-partner" } },
+      { nodes: [rex], edges: [{ source: "k1", target: "n1", targetHandle: "partner" }] },
+    )
+    expect(out).toBe(getCharacterMotionPromptHint("hug-partner").replace(/\bthe partner\b/g, "Rex"))
+    expect(out).not.toContain("another person")
+  })
+
+  it("a creature on target becomes the subject", () => {
+    const out = getParameterPromptHint(
+      { id: "n1", type: "character-motion", data: { characterMotion: "wave-hello" } },
+      { nodes: [rex], edges: [{ source: "k1", target: "n1", targetHandle: "target" }] },
+    )
+    expect(out).toBe(getCharacterMotionPromptHint("wave-hello").replace(/\bthe subject\b/g, "Rex"))
+  })
+
+  it("Character FX with a creature on target is unchanged (still unnamed)", () => {
+    const fx = { id: "n1", type: "character-fx", data: { characterFx: "werewolf" } }
+    const out = getParameterPromptHint(fx, {
+      nodes: [rex],
+      edges: [{ source: "k1", target: "n1", targetHandle: "target" }],
+    })
+    expect(out).toBe(getParameterPromptHint(fx))
+    expect(out).not.toContain("Rex")
+  })
+})

package/src/__tests__/parameter-registry-sync.test.ts

@@ -146,6 +146,8 @@ const SAMPLE_DATA_BY_TYPE: Record<string, Record<string, unknown>> = {
   // CHARACTER_FX[0] is "auto" with an intentionally empty promptHint — use a
   // real effect id so the sync test exercises the hint dispatch.
   "character-fx": { characterFx:  "werewolf" },
+  // CHARACTER_MOTIONS[0] is the "auto" no-op head — use a real move.
+  "character-motion": { characterMotion: "wave-hello" },
   "loop-subject": { loopSubject: firstId(LOOP_SUBJECTS) },
   "scene-count": { count: 5 },
   "duration": { seconds: 8 },

package/src/__tests__/picker-analyzer-registry.test.ts

@@ -86,7 +86,7 @@ describe("registry invariants (all analyzable pickers)", () => {
         "lens", "camera-format", "setting", "atmosphere", "style", "mood", "color-look",
         "photographer", "aesthetic", "era", "photo-genre", "backdrop", "render-quality",
         "composition-effects", "post-process-effects", "action-fx", "loop-subject",
-        "transition", "character-fx", "pose", "material", "held-prop", "camera-motion",
+        "transition", "character-fx", "character-motion", "pose", "material", "held-prop", "camera-motion",
         "animal", "vehicle", "weapon", "furniture",
       ]),
     )

package/src/__tests__/transition-timing-catalogs.test.ts

@@ -148,6 +148,6 @@ describe("transition timing catalogs", () => {
     const singlesWithDims = PICKER_CATALOGS.filter(
       (c) => c.kind === "single" && c.dimensions,
     ).map((c) => c.nodeType)
-    expect(singlesWithDims).toEqual(["transition", "character-fx"])
+    expect(singlesWithDims).toEqual(["transition", "character-fx", "character-motion"])
   })
 })

package/src/__tests__/video-reference-features.test.ts

@@ -22,9 +22,18 @@ describe("video reference-image capability (catalog)", () => {
   // Replicate reference_images, and the `maxRefImages` merge for grok-i2v /
   // happyhorse-ref2v) — must keep advertising it. Subset check, so wiring a
   // NEW ref-capable model doesn't fail here; only breaking a wired one does.
+  // VEO 3.1 QUALITY (`veo3`) is the mirror case, and a costlier one: it DID
+  // advertise the feature, the adapter sent generationType:
+  // "REFERENCE_2_VIDEO", and KIE answered "Reference to video only supports
+  // the Veo Fast model and Veo Lite model." — a 422 after the credits were
+  // reserved (production 2026-09-04, app-reports lane G). Reference-to-video
+  // exists on the Fast and Lite SKUs only.
+  it("excludes veo3 / VEO 3.1 Quality (KIE serves reference-to-video on Fast + Lite only)", () => {
+    expect(refModels).not.toContain("veo3")
+  })
+
   it("includes the wired reference-capable video models", () => {
     for (const id of [
-      "veo3",
       "veo3.1",
       "veo3_lite",
       "gemini-omni-video",

package/src/age-floor.ts

@@ -34,7 +34,7 @@ export interface AdultOnlyEntry {
  *  sweeps for the flag, and which analyzer keys `FLOORED_PICKER_KEYS` strips
  *  flagged ids out of (a `photo-genre` swept for the flag but absent from the
  *  strip list let `glamour-portrait` survive on a minor). */
-export const ADULT_SWEPT_CATALOG_IDS = ["styling", "mood", "pose", "photo-genre"] as const
+export const ADULT_SWEPT_CATALOG_IDS = ["styling", "mood", "pose", "photo-genre", "character-motion"] as const
 
 /** Membership form of the list above (the sweep does one lookup per catalog). */
 const ADULT_SWEPT_CATALOG_ID_SET: ReadonlySet<string> = new Set(ADULT_SWEPT_CATALOG_IDS)

package/src/character-motion/animals-pets.ts

@@ -0,0 +1,116 @@
+import type { CharacterMotion } from "./types.js"
+
+/** animals-pets — authored motion fragments. Stable ids survive copy revisions. */
+export const ANIMALS_PETS_MOTIONS: ReadonlyArray<CharacterMotion> = [
+  { "id": "pet-a-dog", "label": "Pet a dog", "category": "animals-pets", "description": "Flat hand strokes over the dog's skull and neck",
+    "promptHint": "the subject lowers an open hand onto the counterpart's head, draws the flat palm back over the skull to the base of the neck, lifts the hand away and repeats the stroke", "term": "pets the counterpart on the head",
+    "counterpart": "a dog", "requires": ["dog"] },
+  { "id": "scratch-behind-ears", "label": "Scratch behind ears", "category": "animals-pets", "description": "Fingertips work in small circles behind an ear",
+    "promptHint": "the subject reaches to the side of the counterpart's head and works curled fingertips in small circles behind one ear, the wrist rocking, the other hand resting under the muzzle", "term": "scratches behind the ears with the counterpart",
+    "counterpart": "an animal", "requires": ["animal"] },
+  { "id": "ruffle-dog-fur", "label": "Ruffle dog fur", "category": "animals-pets", "description": "Fingers scrub through the thick fur at the neck",
+    "promptHint": "the subject sinks the fingers deep into the thick fur at the counterpart's neck and scrubs them briskly back and forth through the coat, elbows pumping, then opens the fingers and lifts the hands away", "term": "ruffles the counterpart's fur with both hands",
+    "counterpart": "a dog", "requires": ["dog"] },
+  { "id": "scoop-up-pet", "label": "Scoop up pet", "category": "animals-pets", "description": "Bends, slides both hands under, lifts to the chest",
+    "promptHint": "the subject bends at the knees, slides one hand under the counterpart's chest and the other under its hindquarters, and straightens upright, drawing the animal in against the subject's chest", "term": "scoops up the counterpart",
+    "counterpart": "a small pet", "requires": ["pet"] },
+  { "id": "offer-hand-to-sniff", "label": "Offer hand to sniff", "category": "animals-pets", "description": "Arm extends, knuckles down, hand held still",
+    "promptHint": "the subject extends one arm forward at waist height with the fingers curled and the knuckles down, stops the hand short of the counterpart and holds it motionless, shoulders loose", "term": "offers knuckles for the counterpart to sniff",
+    "counterpart": "the animal", "requires": ["animal"] },
+  { "id": "offer-a-treat", "label": "Offer treat to dog", "category": "animals-pets", "description": "Holds a treat out for the dog without requiring it to take it.",
+    "promptHint": "the subject extends an open palm holding a treat toward the counterpart and holds it steady, waiting for a response", "term": "offers the counterpart a treat on open palm",
+    "counterpart": "a dog", "requires": ["dog", "treat"], "aliases": ["Offer a Treat"] },
+  { "id": "get-pulled-by-leash", "label": "Get pulled by leash", "category": "animals-pets", "description": "Leash snaps taut and drags the arm forward",
+    "promptHint": "the subject is yanked forward as the leash snaps taut and stumbles a step with one shoulder dragged ahead of the torso, then leans the weight back and digs the heels in", "term": "gets pulled along by the leash" },
+  { "id": "reel-in-leash", "label": "Reel in leash", "category": "animals-pets", "description": "Hand over hand shortens the leash",
+    "promptHint": "the subject gathers the leash hand over hand, each fist closing on the line and drawing it back to the hip until the slack is gone, the elbow tucked tight against the ribs", "term": "reels in the leash hand over hand" },
+  { "id": "throw-ball-for-dog", "label": "Throw ball for dog", "category": "animals-pets", "description": "Throws a ball ahead of the dog without adding a fetch return.",
+    "promptHint": "the subject faces the same direction as the counterpart, draws the throwing arm back and throws a ball forward, following through with the arm", "term": "throws a ball ahead of the counterpart",
+    "counterpart": "a dog", "requires": ["dog", "ball"] },
+  { "id": "kneel-to-greet", "label": "Kneel to greet", "category": "animals-pets", "description": "Drops to one knee and opens both arms",
+    "promptHint": "the subject drops onto one knee, spreads both arms wide and leans the chest forward, closing both hands around the counterpart's shoulders and rocking back slightly under the weight", "term": "kneels down to greet the counterpart",
+    "counterpart": "a dog", "requires": ["dog"] },
+  { "id": "signal-dog-to-sit", "label": "Signal dog to sit", "category": "animals-pets", "description": "Gives the dog a downward hand signal without requiring a response.",
+    "promptHint": "the subject faces the counterpart, raises a flat palm to chest height and lowers it in a deliberate downward signal, then waits", "term": "gives the counterpart a downward sit signal",
+    "counterpart": "a dog", "requires": ["dog"] },
+  { "id": "call-dog-over", "label": "Call dog over", "category": "animals-pets", "description": "Crouches and beckons the dog, then waits.",
+    "promptHint": "the subject faces the counterpart, lowers into a crouch, pats one thigh and opens both hands in an inviting gesture, then waits", "term": "crouches and beckons the counterpart",
+    "counterpart": "a dog", "requires": ["dog"] },
+  { "id": "cuddle-pet-on-lap", "label": "Cuddle pet on lap", "category": "animals-pets", "description": "Curls over a pet on the lap and strokes its back",
+    "promptHint": "the subject curls the shoulders forward over the counterpart settled across the lap, runs one hand in long strokes down its back and lets the chin drop toward it", "term": "cuddles the counterpart on the lap",
+    "counterpart": "a pet", "requires": ["pet"] },
+  { "id": "hold-cat-to-chest", "label": "Hold cat to chest", "category": "animals-pets", "description": "Gathers a cat up against the sternum",
+    "promptHint": "the subject gathers the counterpart up against the chest, one forearm braced under its hindquarters and the other hand flat along its back, and lowers the chin toward its head", "term": "holds the counterpart against the chest",
+    "counterpart": "a cat", "requires": ["cat"] },
+  { "id": "lift-cat-up", "label": "Lift cat up", "category": "animals-pets", "description": "Chest and hindquarters supported, lifted to eye level",
+    "promptHint": "the subject slides one hand under the counterpart's chest just behind the front legs and the other under its hindquarters, lifts it up to eye level as the arms extend, holds it there a beat before drawing it back in against the chest", "term": "lifts the counterpart up to eye level",
+    "counterpart": "a cat", "requires": ["cat"] },
+  { "id": "lift-puppy-to-face", "label": "Lift puppy to face", "category": "animals-pets", "description": "Raises a puppy up nose to nose",
+    "promptHint": "the subject raises the counterpart in both hands from lap height up to eye level, lifts the chin and leans in until the two are nose to nose, then lowers the counterpart back down against the subject's chest", "term": "holds the counterpart up to the face",
+    "counterpart": "a puppy", "requires": ["puppy"] },
+  { "id": "let-bird-perch", "label": "Let bird perch", "category": "animals-pets", "description": "Index finger held out level and steady",
+    "promptHint": "the subject holds one index finger out level in front of the chest and locks the elbow against the ribs to keep the hand from shaking, lifting the whole arm upward as the counterpart steps onto the finger", "term": "holds out a finger for the counterpart",
+    "counterpart": "a bird", "requires": ["bird"] },
+  { "id": "feed-the-ducks", "label": "Feed ducks", "category": "animals-pets", "description": "Tosses small pieces of food toward the ducks.",
+    "promptHint": "the subject takes small pieces of food from a bag and tosses them underhand toward the counterpart", "term": "tosses small pieces of food toward the counterpart",
+    "counterpart": "the ducks", "requires": ["ducks", "food", "bag"], "aliases": ["Feed the Ducks"] },
+  { "id": "stroke-horse-neck", "label": "Stroke horse neck", "category": "animals-pets", "description": "Long flat-palm sweeps down the neck",
+    "promptHint": "the subject lays a flat palm high on the counterpart's neck and sweeps it down the length of the crest in long full strokes, the other hand resting at the counterpart's shoulder", "term": "strokes the counterpart's neck",
+    "counterpart": "a horse", "requires": ["horse"] },
+  { "id": "brush-the-horse", "label": "Brush the horse", "category": "animals-pets", "description": "Long brush strokes along the lie of the coat",
+    "promptHint": "the subject presses a brush to the counterpart's flank and pulls it in long strokes along the lie of the coat, the free hand steadying the counterpart ahead of each pass, the shoulder swinging with the motion", "term": "brushes the counterpart's coat",
+    "counterpart": "a horse", "requires": ["horse"] },
+  { "id": "pat-horse-flank", "label": "Pat horse flank", "category": "animals-pets", "description": "Two firm open-palm pats, then rests the hand",
+    "promptHint": "the subject brings a flat hand in to pat the counterpart's flank twice with a firm open palm, then leaves the hand resting there and leans a little weight onto it", "term": "pats the counterpart on the flank",
+    "counterpart": "a horse", "requires": ["horse"] },
+  { "id": "mount-the-horse", "label": "Mount the horse", "category": "animals-pets", "description": "Foot in the stirrup, swings the leg over",
+    "promptHint": "the subject sets one foot into the stirrup, grips the saddle with both hands, springs off the ground and swings the trailing leg over, then settles down and finds the other stirrup", "term": "mounts a horse",
+    "deprecated": true, "replacementId": "mount-horse", "aliases": ["mount horse"] },
+  { "id": "back-away-slowly", "label": "Back away slowly from animal", "category": "animals-pets", "description": "Takes small cautious backward steps while facing the animal.",
+    "promptHint": "the subject faces the counterpart and takes small cautious backward steps, keeping the upper body steady and the gaze forward", "term": "takes cautious backward steps away from the counterpart",
+    "counterpart": "an animal", "requires": ["animal"], "fixedPace": true, "startPose": "standing", "endPose": "standing", "aliases": ["Back Away Slowly", "retreat"] },
+  { "id": "let-it-approach", "label": "Let it approach", "category": "animals-pets", "description": "Goes completely still and waits it out",
+    "promptHint": "the subject stops mid-step and goes completely still, arms hanging loose at the sides, the breathing shallow so the chest barely moves, only the eyes tracking the counterpart", "term": "freezes as the counterpart comes near",
+    "counterpart": "the animal", "requires": ["animal"] },
+  { "id": "crouch-to-photograph", "label": "Crouch to photograph", "category": "animals-pets", "description": "Drops low and frames the animal with a phone",
+    "promptHint": "the subject drops into a low crouch, braces the elbows on the knees and lifts a phone in both hands up in front of the face, holding dead still before tapping the screen with a thumb", "term": "crouches to photograph an animal" },
+  { "id": "tug-the-toy", "label": "Tug toy with dog", "category": "animals-pets", "description": "Pulls one end of a rope toy while the dog holds the other.",
+    "promptHint": "the subject holds one end of a rope toy while the counterpart holds the other, leans back with a gentle pull and then steps forward to loosen the tension", "term": "tugs a rope toy held by the counterpart",
+    "counterpart": "a dog", "requires": ["dog", "rope toy"], "aliases": ["Tug the Toy"] },
+  { "id": "wipe-muddy-paws", "label": "Wipe muddy paws", "category": "animals-pets", "description": "Kneels and towels one paw at a time",
+    "promptHint": "the subject kneels on one knee, lifts the counterpart's paw into a cupped hand, wraps a towel around it and rubs it clean, sets it back down and reaches for the next one", "term": "wipes the counterpart's muddy paws",
+    "counterpart": "a dog", "requires": ["dog"] },
+  { "id": "brace-for-jump", "label": "Brace for jump", "category": "animals-pets", "description": "Plants the back foot to absorb a dog jumping up",
+    "promptHint": "the subject plants the back foot and drops the pelvis to take the counterpart's weight against the chest, both hands rising to catch its shoulders, the torso rocking back then steadying", "term": "braces as the counterpart jumps up",
+    "counterpart": "a dog", "requires": ["dog"] },
+  { "id": "dog-subject-sit", "label": "Dog sits", "category": "animals-pets", "description": "Dog sits.",
+    "term": "sits down on the hindquarters", "promptHint": "the subject is a dog that lowers its hindquarters to the ground while keeping the front legs upright",
+    "requires": ["dog as target subject"], "aliases": ["animal subject"] },
+  { "id": "dog-subject-lie-down", "label": "Dog lies down", "category": "animals-pets", "description": "Dog lies down.",
+    "term": "lies down with all four limbs resting", "promptHint": "the subject is a dog that lowers the chest and hindquarters to rest on the ground",
+    "requires": ["dog as target subject"], "aliases": ["animal subject"] },
+  { "id": "dog-subject-wag-tail", "label": "Dog wags tail", "category": "animals-pets", "description": "Dog wags tail.",
+    "term": "wags the tail", "promptHint": "the subject is a dog that wags its tail from side to side while keeping the body in place",
+    "requires": ["dog as target subject"], "aliases": ["animal subject"] },
+  { "id": "dog-subject-shake", "label": "Dog shakes body", "category": "animals-pets", "description": "Dog shakes body.",
+    "term": "shakes the body from head to tail", "promptHint": "the subject is a dog that shakes its body from head through torso to tail and then becomes still",
+    "requires": ["dog as target subject"], "aliases": ["animal subject"] },
+  { "id": "cat-subject-stretch", "label": "Cat stretches", "category": "animals-pets", "description": "Cat stretches.",
+    "term": "stretches the front legs and back", "promptHint": "the subject is a cat that extends both front legs, lowers the chest and lengthens the back before returning upright",
+    "requires": ["cat as target subject"], "aliases": ["animal subject"] },
+  { "id": "horse-subject-walk", "label": "Horse walks", "category": "animals-pets", "description": "Horse walks.",
+    "term": "walks with a steady four-beat gait", "promptHint": "the subject is a horse that walks steadily forward in a four-beat gait",
+    "requires": ["horse as target subject"], "aliases": ["animal subject"] },
+  { "id": "horse-subject-trot", "label": "Horse trots", "category": "animals-pets", "description": "Horse trots.",
+    "term": "trots with alternating diagonal leg pairs", "promptHint": "the subject is a horse that trots forward using alternating diagonal pairs of legs",
+    "requires": ["horse as target subject"], "aliases": ["animal subject"] },
+  { "id": "horse-subject-canter", "label": "Horse canters", "category": "animals-pets", "description": "Horse canters.",
+    "term": "canters in a rhythmic three-beat gait", "promptHint": "the subject is a horse that canters forward in a rhythmic three-beat gait",
+    "requires": ["horse as target subject"], "aliases": ["animal subject"] },
+  { "id": "bird-subject-hop", "label": "Bird hops", "category": "animals-pets", "description": "Bird hops.",
+    "term": "hops forward and settles", "promptHint": "the subject is a bird that makes a small hop forward and settles on both feet",
+    "requires": ["bird as target subject"], "aliases": ["animal subject"] },
+  { "id": "bird-subject-takeoff", "label": "Bird takes flight", "category": "animals-pets", "description": "Bird takes flight.",
+    "term": "pushes off, beating wings to take flight", "promptHint": "the subject is a bird that pushes off its perch and beats its wings to take flight",
+    "requires": ["bird as target subject"], "aliases": ["animal subject"] },
+]