@slatesvideo/shared 0.6.2 → 0.6.4

package/dist/prompts/prompting-tips.js

@@ -640,6 +640,127 @@ const MINIMAX_H3 = {
         'Slates disables the provider\'s prompt expander, so what you write is what the model reads — nothing will pad a thin prompt. Aim for a 350-500 word body on a reference-carrying shot, and let dialogue-heavy scenes run longer if that is what fits the spoken timeline.',
     ],
 };
+const LTX_2_5 = {
+    label: 'LTX-2.5',
+    intro: [
+        'LTX-2.5 scores the picture on the same pass that draws it, so SOUND IS THE FIRST THING YOU WRITE, not the last. Lightricks ranks the six parts of a prompt in this order: sound, camera, character detail, shot type and scene, then scene dressing — and scene dressing is the first thing to cut when a prompt sprawls. Everything goes in ONE flowing paragraph, not a list of labelled sections.',
+        'Two seats. Base LTX-2.5 is the distilled build: 720p / 1080p / 1440p / 4K and clips from 6 to 20 seconds, and it is the cheapest native 1080p second in Slates. LTX-2.5 Pro is the full diffusion build ("Diffusion Fidelity Rendering" spends extra compute on busy frames) but reaches a SHORTER ladder — 1080p and 10 seconds maximum — while costing about a third more. Pro is for a dense final render; base is for iteration, long takes and 4K.',
+    ],
+    columns: [
+        [
+            {
+                heading: 'Anchor every sound to something in frame',
+                example: 'the rope creaks against the cleat, gulls somewhere off the port bow',
+                note: 'Write the audio line last, then check each cue has a visible or at least locatable source. Anything unanchored gets invented for you. "Not visible but locatable" passes — a whistle is fine if you name the marshal post it comes from.',
+                critical: true,
+            },
+            {
+                heading: 'Never write mood words for sound',
+                example: 'Bad: "tense atmosphere, sense of dread"\nGood: "a loose shutter knocks twice against the frame"',
+                note: 'Atmosphere adjectives produce nothing. If a scene feels thin, add one more MOVING OBJECT with a sound attached to it rather than another adjective.',
+            },
+            {
+                heading: 'Dialogue takes quotes, language and accent',
+                example: '"We should not have come back," in English with a slight German accent.',
+                note: 'Give the character a beat of stillness before they speak so the lip sync has something to lock against. Describe the beat: looks, waits, speaks, looks away.',
+            },
+            {
+                heading: 'Emotion is physical, not abstract',
+                example: 'Bad: "she looks anxious"\nGood: "her jaw sets, she turns the ring on her finger twice"',
+                note: 'The model renders actions, not adjectives. Tension in the jaw, weight shifts, fidgeting hands — these read; "anxious" does not.',
+            },
+        ],
+        [
+            {
+                heading: 'Multishot: two to four shots, and re-establish at every cut',
+                example: 'wide establishing shot — hard cut — macro close-up — match cut — medium shot',
+                note: 'One generation can carry several connected shots holding character, light and voice across the cuts. Name the edit ("hard cut", "dissolve") in the prose, then RESET scale, angle, lens and light. Two to four is the working range.',
+                critical: true,
+            },
+            {
+                heading: 'Re-identify characters at every cut',
+                example: 'Good: "the woman in the bronze gown"\nBad: "she"',
+                note: 'Pronouns lose the character across a cut. Repeat the original descriptor every time. Also state what the SOUND does at the cut — silence is not assumed.',
+            },
+            {
+                heading: 'Write the camera into the sentence',
+                example: 'a slow push-in settles as she reaches the door, then holds',
+                note: 'Slates does not expose the camera_motion enum, and prose is the better tool anyway: a written move can be tied to a specific moment, an enum value cannot. Name lens, framing and the moment the move resolves.',
+            },
+            {
+                heading: 'Durations are even numbers only, from six',
+                note: '6, 8, 10, 12, 14, 16, 18 or 20 seconds — there is no 5s or 7s LTX clip. And the long end is 1080p-and-below only: at 1440p and 4K the ceiling drops to 10s. Slates always sends an explicit length rather than letting the model pick one, so what you choose is what you are billed for.',
+                critical: true,
+            },
+            {
+                heading: 'Do not ask for text on screen',
+                note: 'Neither the spelling nor its stability frame to frame can be relied on. Signage, labels and captions belong in post.',
+            },
+        ],
+    ],
+    footer: [
+        'Frames, not references. LTX takes a start frame and an optional end frame (which generates a transition between the two) — it has no reference endpoint at all, so identity, style and environment reference images are not available on this model. For character consistency across separate shots, use MiniMax H3 or Kling.',
+        'Aspect ratios are 16:9 and 9:16 only, and native audio is included free at every resolution — there is no sound surcharge on either seat.',
+        'In image-to-video, do not cut away from the opening frame too early: you have paid for that frame, so let it play before the first move.',
+    ],
+};
+const INWORLD_TTS = {
+    label: 'Inworld TTS-2',
+    intro: [
+        'The voice seat: one named voice saying one line. Unlike every other surface in Slates, the prompt is not a description of what you want — it IS the words that get spoken, verbatim, and its length is what you are billed for.',
+        'A voice belongs to a character, the same way a face does. Build it once from a clip or a description, then send it lines.',
+    ],
+    columns: [
+        [
+            {
+                heading: 'Direction goes in SQUARE BRACKETS',
+                example: '\u2717 (quietly) I hope nobody notices\n\u2713 [whispering] I hope nobody notices',
+                note: 'Brackets are read as direction and never spoken. PARENTHESES ARE SPOKEN ALOUD \u2014 a parenthetical stage direction comes back with the narrator saying the word "quietly". This is the single easiest way to ruin a take.',
+                critical: true,
+            },
+            {
+                heading: 'Plain English inside the brackets',
+                example: '[very quiet] \u00b7 [very slow] \u00b7 [say excitedly] \u00b7 [whisper in a hushed style]',
+                note: 'It is natural-language steering across emotion, volume, pitch, speed, articulation and vocal style \u2014 not a fixed vocabulary. Write the direction the way you would say it to an actor.',
+            },
+            {
+                heading: 'Non-verbals are their own tags',
+                example: '[laugh] \u00b7 [sigh] \u00b7 [breathe] \u00b7 [cough] \u00b7 [yawn] \u00b7 [clear throat]',
+                note: 'They land inline, where they occur in the line.',
+            },
+            {
+                heading: 'A mistyped tag fails silently',
+                note: 'An instruction it does not recognise is still swallowed and still changes the delivery \u2014 it is never spoken and never errors. So a typo produces a strange read with no warning. If a take sounds off, suspect the tag before the voice.',
+                critical: true,
+            },
+        ],
+        [
+            {
+                heading: 'Tags persist until changed',
+                example: '[very slow] First line. Second line is still slow. [reset] Third is normal.',
+                note: 'A direction governs everything after it, across sentences. Use [reset] to return to a normal read rather than assuming the next sentence starts clean.',
+            },
+            {
+                heading: 'Punctuation is the timing',
+                example: 'Wait. Stop.  \u2260  Wait, stop.',
+                note: 'Full stops buy a beat; commas do not. Write the line the way it is said.',
+            },
+            {
+                heading: 'One line, one take',
+                note: 'Split a paragraph into separate generations so a bad clause costs one re-roll instead of the whole speech. Max 2,000 characters per take.',
+            },
+            {
+                heading: 'Spell out anything ambiguous',
+                example: 'twenty twenty-six \u00b7 Doctor Reyes',
+                note: 'Numbers, dates and abbreviations are read literally. Write them as they should sound.',
+            },
+            {
+                heading: 'Know its seat',
+                note: 'One voice, cleanly. Dialogue mixed with effects and room tone in one pass is Seed Audio; a single non-speech sound is Sound Effects.',
+            },
+        ],
+    ],
+};
 export const PROMPTING_TIPS = {
     seedance: SEEDANCE,
     'seedance-2-5': SEEDANCE_25,
@@ -650,10 +771,12 @@ export const PROMPTING_TIPS = {
     'omni-flash': OMNI_FLASH,
     'omni-flash-edit': OMNI_FLASH_EDIT,
     'minimax-h3': MINIMAX_H3,
+    'ltx-2-5': LTX_2_5,
     'nano-banana': NANO_BANANA,
     'nano-banana-lite': NANO_BANANA_LITE,
     'seed-audio': SEED_AUDIO,
     'eleven-sfx': ELEVEN_SFX,
+    'inworld-tts-2': INWORLD_TTS,
 };
 /** Null when no tips exist for the key — callers render an honest fallback. */
 export function getPromptingTips(key) {

package/dist/prompts/reference-composer.d.ts

@@ -50,16 +50,45 @@ export interface ComposedReferences {
      * Tokens written in the prompt that matched NO reference group, as authored
      * (`'#noir'`, `'@bob'`), first-appearance order, deduped case-insensitively.
      *
-     * 🚨 THIS FIELD EXISTS BECAUSE THE ALTERNATIVE IS A SILENT EDIT. A `#tag` with
-     * no matching style is DELETED from the text — a raw tag confuses every model,
-     * so removing it is right, but removing it without saying so changes what the
-     * user asked for behind their back. Prompt-transparency doctrine (slate
-     * `CLAUDE.md`) requires the surface to be able to say "this went nowhere", and
-     * this is the only record that the token was ever there. Callers that render a
-     * composed-prompt preview MUST surface it.
+     * 🚨 IT IS A REPORT, NOT A RECEIPT FOR A DELETION. These tokens are left in
+     * `prompt` EXACTLY as the user typed them (see step 2) — nothing is removed
+     * and nothing is humanised. What the field says is narrower and more useful:
+     * "no reference is attached for this word", which is the difference between a
+     * mistyped mention and a `@handle` you meant to typeset. Callers that render a
+     * composed-prompt preview SHOULD surface it — as a note, never as an error,
+     * because nothing has gone wrong.
      */
     unresolvedTokens: string[];
 }
+/**
+ * 🚨 A HEX COLOUR IS NOT A TAG. `#000000` is to `#` what `eric@gmail.com` is to
+ * `@`: an everyday literal that happens to open with our sigil, written by
+ * someone who was not reaching for our feature at all.
+ *
+ * The TEXT was already safe — an unresolved token is returned byte-identical
+ * (see TOKEN_RE) — so what this guards is the REPORT. The `@` half of that
+ * grammar gets its everyday literal excluded for free, because an email's `@`
+ * sits after a word character and the boundary lookbehind kills it. A hex
+ * colour gets no such help: `#` at a word boundary is exactly how a real tag is
+ * written too, so `#000000` reaches `noteUnresolved` and a palette prompt
+ * ("pure black #000000 with #c8ff00 accents") comes back with every colour
+ * listed as *matching nothing saved* — an accusation about words that were
+ * never mentions. That is the asymmetry this closes, and it is the same
+ * complaint, in the same place, as `#3a3a3c` being eaten for months.
+ *
+ * 🚨 IT GATES THE REPORT, NOT THE GRAMMAR, and that is the whole design.
+ * `fade`, `cafe`, `dead`, `beef`, `decade` and `facade` are all valid hex
+ * digits AND plausible style names, so excluding hex shapes from TOKEN_RE would
+ * quietly stop `#fade` from attaching a style called "Fade" — trading a noisy
+ * note for a silent drop, which is the worse half of the trade every time.
+ * Resolution is checked first and always wins; only a token that binds to
+ * nothing ever reaches here.
+ *
+ * Lengths are CSS's: 3 (`#fff`), 4 (`#fff8`), 6 (`#c8ff00`), 8 (`#c8ff00ff`).
+ * `#1` and `#2026` are deliberately NOT covered — an ordinal is not a colour,
+ * and widening this to "anything numeric" would start swallowing tags.
+ */
+export declare function isHexColorToken(sigil: string, token: string): boolean;
 /**
  * Compose the raw prompt (mentions intact) + an ORDERED list of reference groups
  * into the named prompt text + ordered media the API receives. The group order

package/dist/prompts/reference-composer.js

@@ -44,13 +44,66 @@ function joinNums(nums) {
         return `${nums[0]} and ${nums[1]}`;
     return `${nums.slice(0, -1).join(', ')} and ${nums[nums.length - 1]}`;
 }
-// Humanize an unresolved @token to plain words (preserve the legacy cleanPrompt
-// fallback: @big_red → "Big Red", @forest3 → "Forest3"). Never send a raw token.
-function humanizeToken(raw) {
-    return raw
-        .split(/[_-]/)
-        .map((w) => (w ? w.charAt(0).toUpperCase() + w.slice(1) : w))
-        .join(' ');
+/**
+ * 🚨 A SIGIL IS A MENTION ONLY IF IT RESOLVES. Everything else is prose, and
+ * prose is not ours to edit.
+ *
+ * This grammar used to be `/([@#])([\w-]+)/g` with "unresolved" as a rewrite
+ * branch: an unknown `@word` was humanised (`@woodland.candle` → "Woodland" +
+ * ".candle") and an unknown `#word` was deleted outright. Both assumed anyone
+ * typing a sigil was reaching for OUR feature, so the app quietly rewrote the
+ * one thing the composer exists to protect — and it failed precisely where the
+ * literal characters matter most: a poster's `@handle`, an email address, a hex
+ * colour. That last one is not hypothetical: `#3a3a3c` was eaten out of every
+ * identity-sheet prompt for months (`reference-rules.ts`, 2026-07-30), which is
+ * the same bug wearing a different sigil.
+ *
+ * Two changes make the sigil safe to type:
+ *
+ * 1. THE GRAMMAR IS NARROW. A sigil only opens a token at a boundary, so
+ *    `eric@gmail.com` is never even a candidate, and a token may carry interior
+ *    dots, so `@woodland.candle` is ONE token rather than a mention with debris
+ *    stuck to it. Interior only — a trailing `.` stays with the sentence.
+ * 2. AN UNRESOLVED TOKEN IS RETURNED UNTOUCHED. A mention is a BINDING; when it
+ *    binds to nothing there is nothing to translate, so there is nothing to
+ *    rewrite. It is reported through `unresolvedTokens` and sent as written.
+ *
+ * There is deliberately NO escape syntax (`\@`, quoting). Making someone learn
+ * our grammar to opt OUT of a feature they never invoked is the shoehorn this
+ * change exists to remove — the sandbox rule from the root `CLAUDE.md`: a
+ * capability attaches to the primitive, it does not stand in the way of it.
+ */
+const TOKEN_RE = /(?<![\w.@#])([@#])([\w-]+(?:\.[\w-]+)*)/g;
+/**
+ * 🚨 A HEX COLOUR IS NOT A TAG. `#000000` is to `#` what `eric@gmail.com` is to
+ * `@`: an everyday literal that happens to open with our sigil, written by
+ * someone who was not reaching for our feature at all.
+ *
+ * The TEXT was already safe — an unresolved token is returned byte-identical
+ * (see TOKEN_RE) — so what this guards is the REPORT. The `@` half of that
+ * grammar gets its everyday literal excluded for free, because an email's `@`
+ * sits after a word character and the boundary lookbehind kills it. A hex
+ * colour gets no such help: `#` at a word boundary is exactly how a real tag is
+ * written too, so `#000000` reaches `noteUnresolved` and a palette prompt
+ * ("pure black #000000 with #c8ff00 accents") comes back with every colour
+ * listed as *matching nothing saved* — an accusation about words that were
+ * never mentions. That is the asymmetry this closes, and it is the same
+ * complaint, in the same place, as `#3a3a3c` being eaten for months.
+ *
+ * 🚨 IT GATES THE REPORT, NOT THE GRAMMAR, and that is the whole design.
+ * `fade`, `cafe`, `dead`, `beef`, `decade` and `facade` are all valid hex
+ * digits AND plausible style names, so excluding hex shapes from TOKEN_RE would
+ * quietly stop `#fade` from attaching a style called "Fade" — trading a noisy
+ * note for a silent drop, which is the worse half of the trade every time.
+ * Resolution is checked first and always wins; only a token that binds to
+ * nothing ever reaches here.
+ *
+ * Lengths are CSS's: 3 (`#fff`), 4 (`#fff8`), 6 (`#c8ff00`), 8 (`#c8ff00ff`).
+ * `#1` and `#2026` are deliberately NOT covered — an ordinal is not a colour,
+ * and widening this to "anything numeric" would start swallowing tags.
+ */
+export function isHexColorToken(sigil, token) {
+    return sigil === '#' && /^(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(token);
 }
 export function composeReferences(rawPrompt, groups, opts = {}) {
     // ── 1. Assign global numbers by walking the list in order ──
@@ -99,11 +152,16 @@ export function composeReferences(rawPrompt, groups, opts = {}) {
     const seenFirst = new Set();
     const matchedInPrompt = new Set();
     // Every token that named nothing, recorded as authored and deduped by the
-    // same normalisation used for matching. This is what makes the deletion
-    // below reportable instead of silent — see ComposedReferences.unresolvedTokens.
+    // same normalisation used for matching. Nothing is removed on its account —
+    // it is the "no reference is attached for this word" report. See
+    // ComposedReferences.unresolvedTokens.
     const unresolvedTokens = [];
     const unresolvedSeen = new Set();
     const noteUnresolved = (sigil, tok) => {
+        // A hex colour that binds to no style is a colour, not a mistyped tag.
+        // See isHexColorToken — the text is unchanged either way; this is the note.
+        if (isHexColorToken(sigil, tok))
+            return;
         const key = normToken(`${sigil}${tok}`);
         if (unresolvedSeen.has(key))
             return;
@@ -112,27 +170,24 @@ export function composeReferences(rawPrompt, groups, opts = {}) {
     };
     // First strip "in/with the style of #tag" phrases so the style reads as a
     // clean trailing clause, not a dangling preposition (legacy cleanPrompt
-    // behaviour). An UNRESOLVED token in that phrase is stripped too: leaving the
-    // preposition behind ("…a portrait in the style of") was the worse half of the
-    // silent edit — the tag vanished a step later anyway and the sentence was left
-    // broken. Stripped or not, the token is reported.
-    let body = rawPrompt.replace(/\s+(with|in)\s+the\s+style\s+of\s+([@#])([\w-]+)/gi, (_full, _prep, sigil, tok) => {
+    // behaviour). ONLY when the tag resolves: an unresolved one leaves the whole
+    // phrase exactly as authored and falls through to the token pass below, which
+    // reports it and sends it as written.
+    let body = rawPrompt.replace(/\s+(with|in)\s+the\s+style\s+of\s+([@#])([\w-]+(?:\.[\w-]+)*)/gi, (_full, _prep, sigil, tok) => {
         const g = byNorm.get(normToken(`${sigil}${tok}`));
         if (g && g.kind === 'style') {
             matchedInPrompt.add(normToken(`${sigil}${tok}`));
             return '';
         }
-        noteUnresolved(sigil, tok);
-        return '';
+        return _full;
     });
-    body = body.replace(/([@#])([\w-]+)/g, (_full, _sigil, tok) => {
+    body = body.replace(TOKEN_RE, (_full, _sigil, tok) => {
         const key = normToken(`${_sigil}${tok}`);
         const g = byNorm.get(key);
         if (!g) {
-            // Unresolved token. A #unknown vanishes; an @unknown humanizes to words.
-            // Both are edits the user never asked for, so both are reported.
+            // Not a mention — see TOKEN_RE. Reported, returned byte-identical.
             noteUnresolved(_sigil, tok);
-            return _sigil === '#' ? '' : humanizeToken(tok);
+            return _full;
         }
         matchedInPrompt.add(key);
         if (g.kind === 'style')

package/dist/prompts/reference-rules.d.ts

@@ -1,17 +1,4 @@
 export { PARTIALS } from './partials.generated.js';
-export type SourceGrade = 'Eric-test' | 'community' | 'code-verified' | 'creator-demo';
-export interface ReferenceRule {
-    id: string;
-    title: string;
-    rule: string;
-    why: string;
-    grade: SourceGrade;
-}
-/**
- * The 10 verified reference rules. These are the WHY; the fragments below
- * are the reusable text the templates compose.
- */
-export declare const REFERENCE_RULES: ReferenceRule[];
 /** Flat, even, shadowless identity lighting on a deep neutral-grey plate. */
 export declare const IDENTITY_LIGHTING = "flat, even, shadowless lighting";
 /**
@@ -21,21 +8,23 @@ export declare const IDENTITY_LIGHTING = "flat, even, shadowless lighting";
  */
 export declare const IDENTITY_PLATE_HEX = "#3a3a3c";
 /**
- * 🚨 THE HEX IS EMITTED WITHOUT ITS `#` AND THAT IS LOAD-BEARING (2026-07-30).
- *
- * `#` is a REFERENCE-TOKEN SIGIL in the desktop's prompt composer
- * (`slate/src/shared/promptComposition.ts` — `/([@#])([\w-]+)/g`), and an
- * unresolved `#token` is SILENTLY DELETED. So `#3a3a3c` never survived to any
- * model: fal echoed back `deep neutral-grey background ()` on a real 2026-07-30
- * request. The plate value has been doing nothing since the composer shipped.
+ * THE HEX IS EMITTED WITHOUT ITS `#`. This USED to be load-bearing (2026-07-30):
+ * `#` is a reference-token sigil in the prompt composer, and an unresolved
+ * `#token` was SILENTLY DELETED, so `#3a3a3c` never survived to any model — fal
+ * echoed back `deep neutral-grey background ()` on a real 2026-07-30 request and
+ * the plate value had been doing nothing since the composer shipped.
  *
- * Writing it bare keeps the value in the prompt. `IDENTITY_PLATE_HEX` keeps its
- * `#` because it is a colour constant and may have non-prompt consumers.
+ * 🚨 THE HAZARD IS GONE, AND THE OLD GENERAL RULE WITH IT. The composer now
+ * treats a sigil as a mention ONLY when it resolves and passes every other
+ * `@`/`#` through byte-identically (`reference-composer.ts` → `TOKEN_RE`) — the
+ * exact "HOW YOU'D KNOW THIS IS BEATEN" this comment used to name. Emitting a
+ * `#hex` or an `@handle` into prompt text is safe again.
  *
- * GENERAL RULE FOR THIS FILE: never emit `#` or `@` into prompt text. Both are
- * sigils downstream and both mangle silently — no error, no log, just missing
- * words. HOW YOU'D KNOW THIS IS BEATEN: the composer stops treating bare
- * `#hex` as a token, or starts leaving unresolved tokens intact.
+ * It stays bare here anyway: "hex 3a3a3c" reads at least as clearly to a model,
+ * and rewording it would churn the generated skills/docs corpus for no gain.
+ * That is now a style choice, NOT a workaround — do not re-derive a "never emit
+ * a sigil" law from it. `IDENTITY_PLATE_HEX` keeps its `#` because it is a
+ * colour constant with possible non-prompt consumers.
  */
 export declare const IDENTITY_BACKGROUND: string;
 export declare const IDENTITY_LIGHTING_CLAUSE: string;

package/dist/prompts/reference-rules.js

@@ -1,90 +1,10 @@
 // Reference best-practices — the canonical "how to use reference images"
 // knowledge for every Slates surface (desktop templates, MCP skills, the
 // lead-magnet .skill). Authored ONCE here; consumers derive from it.
-//
-// Source grades: [Eric-test] = Eric's own hands-on result (doctrine-grade);
-// [community] = multi-guide consensus; [code-verified] = verified against
-// the slate codebase; [creator-demo] = single creator demonstration.
 // The generated partial store — one entry per skills/_partials/*.md file.
 // Re-exported so consumers can reach any partial, not just the rules block.
 export { PARTIALS } from './partials.generated.js';
 import { PARTIALS } from './partials.generated.js';
-/**
- * The 10 verified reference rules. These are the WHY; the fragments below
- * are the reusable text the templates compose.
- */
-export const REFERENCE_RULES = [
-    {
-        id: 'two-to-four-refs',
-        title: '2-4 strong references beat both extremes',
-        rule: 'Use 2-4 strong, focused references — not 1 (warps), not 12 (averages worse). Start with 2-3.',
-        why: 'One reference warps toward itself; a dozen averages everyone into mush. One tester cut drift ~60% going 6→2.',
-        grade: 'community',
-    },
-    {
-        id: 'one-ref-per-role',
-        title: 'One reference per ROLE, labeled in the prompt',
-        rule: 'Use one reference per role — identity, style-grade, environment — and label each role explicitly in the prompt text. The model does not infer roles from order.',
-        why: 'Same-role competitors drift; two "identity" refs of different people blend into a third face.',
-        grade: 'community',
-    },
-    {
-        id: 'identity-name-as-one-entity',
-        title: 'One identity sheet per character, named inline',
-        rule: 'Attach the character\'s single identity sheet (dominant portrait + body panels) rather than a pile of views — fewer competing renderings of a face is better, because the model cannot tell which is authoritative and averages them. Cite it inline as the subject ("Marcus (image 1)"). Do not inject a role essay ("use for identity, ignore the outfit/lighting, render neutral"): the user\'s prompt owns wardrobe, expression, and lighting.',
-        why: 'Distinct inline naming is each model\'s own consistency lever — NB2 "assign a distinct name to each character/object"; Seedance "Reference <Subject_N> in <Image_N>"; Kling "reuse a fixed label verbatim". One canonical identity image removes same-role competition before it starts.',
-        grade: 'Eric-test',
-    },
-    {
-        id: 'flat-light-identity',
-        title: 'Flat-light identity refs',
-        rule: 'Prep identity refs with flat, even, shadowless lighting on a plain neutral background. Studio-lit or scene-lit sheets bleed their lighting into every generation.',
-        why: "Eric's Norse-woman test: a studio-lit sheet produced a subject that looked green-screen-pasted in front of mountains. Reference prep beats prompting here.",
-        grade: 'Eric-test',
-    },
-    {
-        id: 'describe-environment',
-        title: 'Environment: describe it, don\'t feed a grid',
-        rule: 'Default to describing the environment in words. Reserve an environment reference for a mandatory exact-match location, and when you do, use ONE clean establishing image — never a multi-panel grid fed whole.',
-        why: "Eric's test: character sheet + 3x3 mountain grid → pasted-in mess; the same character + a described background → believable scene with natural lighting the model invented to fit.",
-        grade: 'Eric-test',
-    },
-    {
-        id: 'grids-explore-not-input',
-        title: 'Grids: generation/exploration = fine; INPUT reference = bad',
-        rule: 'Use grids to EXPLORE compositions (cheap multi-angle generation), then pick a cell. Do NOT feed a grid back in as a reference image — cells share a split detail budget and generate jointly, so flaws propagate.',
-        why: 'A picked cell re-generated with a "preserve the exact composition" prompt keeps its flaws faithfully (that is the budget path, kept on purpose). A loose prompt can fix anatomy but drifts off the picked composition.',
-        grade: 'code-verified',
-    },
-    {
-        id: 'reuse-refs',
-        title: 'Reuse the same refs across all shots',
-        rule: 'Lock a reference set and reuse it across every shot in a sequence. Swapping refs mid-sequence causes drift.',
-        why: 'The model adapts environment refs to each prompt rather than copying them, so swapping compounds inconsistency shot to shot.',
-        grade: 'community',
-    },
-    {
-        id: 'text-as-start-frame',
-        title: 'Legible in-shot text → image start-frame, never trust text-to-video',
-        rule: 'When a shot needs legible on-screen text, bake it into a still start frame (NB2) and animate from that. Do not expect a text-to-video model to render clean text.',
-        why: 'Video models smear text; an image model holds it, and the video inherits the locked frame.',
-        grade: 'community',
-    },
-    {
-        id: 'i2v-own-footage',
-        title: 'I2V / own-footage superpower — describe only what changes',
-        rule: 'Restyle your own clip while keeping the performance; "video one" delayed-VFX; marker-object insertion; video-as-ref for a series. In all cases describe ONLY what changes, not the whole scene.',
-        why: 'The source clip already carries motion, timing, and performance; re-describing them fights the model. Narrate the delta.',
-        grade: 'creator-demo',
-    },
-    {
-        id: 'style-transform-nl',
-        title: 'Style transform by natural language',
-        rule: 'Default: keep the source\'s artistic medium/style. To change it, add a plain-text instruction ("anime → real person") — no preset pickers.',
-        why: 'Paste/natural-language over preset menus is the product philosophy; the medium is inherited unless the user explicitly asks to transform it.',
-        grade: 'Eric-test',
-    },
-];
 // ── Reusable text fragments (the template-assembly building blocks) ──
 // These are the exact strings the desktop prompt templates, MCP skills,
 // and lead-magnet compose. Change a rule HERE and every consumer follows.
@@ -97,21 +17,23 @@ export const IDENTITY_LIGHTING = 'flat, even, shadowless lighting';
  */
 export const IDENTITY_PLATE_HEX = '#3a3a3c';
 /**
- * 🚨 THE HEX IS EMITTED WITHOUT ITS `#` AND THAT IS LOAD-BEARING (2026-07-30).
- *
- * `#` is a REFERENCE-TOKEN SIGIL in the desktop's prompt composer
- * (`slate/src/shared/promptComposition.ts` — `/([@#])([\w-]+)/g`), and an
- * unresolved `#token` is SILENTLY DELETED. So `#3a3a3c` never survived to any
- * model: fal echoed back `deep neutral-grey background ()` on a real 2026-07-30
- * request. The plate value has been doing nothing since the composer shipped.
+ * THE HEX IS EMITTED WITHOUT ITS `#`. This USED to be load-bearing (2026-07-30):
+ * `#` is a reference-token sigil in the prompt composer, and an unresolved
+ * `#token` was SILENTLY DELETED, so `#3a3a3c` never survived to any model — fal
+ * echoed back `deep neutral-grey background ()` on a real 2026-07-30 request and
+ * the plate value had been doing nothing since the composer shipped.
  *
- * Writing it bare keeps the value in the prompt. `IDENTITY_PLATE_HEX` keeps its
- * `#` because it is a colour constant and may have non-prompt consumers.
+ * 🚨 THE HAZARD IS GONE, AND THE OLD GENERAL RULE WITH IT. The composer now
+ * treats a sigil as a mention ONLY when it resolves and passes every other
+ * `@`/`#` through byte-identically (`reference-composer.ts` → `TOKEN_RE`) — the
+ * exact "HOW YOU'D KNOW THIS IS BEATEN" this comment used to name. Emitting a
+ * `#hex` or an `@handle` into prompt text is safe again.
  *
- * GENERAL RULE FOR THIS FILE: never emit `#` or `@` into prompt text. Both are
- * sigils downstream and both mangle silently — no error, no log, just missing
- * words. HOW YOU'D KNOW THIS IS BEATEN: the composer stops treating bare
- * `#hex` as a token, or starts leaving unresolved tokens intact.
+ * It stays bare here anyway: "hex 3a3a3c" reads at least as clearly to a model,
+ * and rewording it would churn the generated skills/docs corpus for no gain.
+ * That is now a style choice, NOT a workaround — do not re-derive a "never emit
+ * a sigil" law from it. `IDENTITY_PLATE_HEX` keeps its `#` because it is a
+ * colour constant with possible non-prompt consumers.
  */
 export const IDENTITY_BACKGROUND = `a plain, deep neutral-grey background (hex ${IDENTITY_PLATE_HEX.replace('#', '')})`;
 export const IDENTITY_LIGHTING_CLAUSE = `Render on ${IDENTITY_BACKGROUND} with ${IDENTITY_LIGHTING} so the sheet captures the character's identity, not scene lighting.`;