@slatesvideo/shared 0.6.11 → 0.7.1

package/exports/slates-chatgpt-images/generated/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: slates-chatgpt-images
+description: Generate images using a connected ChatGPT account or the desktop host's built-in image tool, preserving Slates project context, exact prompts and reference lineage. Use when the user requests ChatGPT generation rather than Slates credits.
+---
+
+# ChatGPT images in Slates
+
+Resolve the project with `slates_list_projects` and references with
+`slates_get_selection` or `slates_list_assets`. Badge codes are project-specific.
+Inspect the selected images before generating. Keep the ordered reference IDs
+alongside the exact prompt submitted for every output.
+
+Retrieve relevant craft with `slates_get_prompting_guide`: use `cinematic-look`
+or `style-prompting` for those requests, with section/query retrieval when useful.
+Do not apply another API model's settings or capabilities to the host generator.
+
+## Connected desktop path
+
+This add-on is off by default. The user enables Settings → AI tools → ChatGPT images in
+Slates before connecting. It requires an installed Codex host and an eligible
+ChatGPT account; a subscription alone does not install or connect the host.
+Settings offers installation instructions, Connect ChatGPT and Check again in
+place, and reports the same connection state as the image picker.
+Never install software or enable the add-on silently. Ordinary Slates use needs
+neither this add-on nor Codex.
+
+Call `slates_get_chatgpt_status`. If connected, use
+`slates_generate_chatgpt_image` with projectId, a fresh UUID requestId, the prompt
+and ordered referenceAssetIds. This is also the path used by Slates' prompt bar
+and Studio Agent. Use background mode for long calls and inspect
+`slates_get_generation_status` with the returned generationId.
+The desktop bridge removes only its own temporary thread's original image after
+saving and byte-verifying the project copy. Failed cleanup keeps the original.
+This does not authorize deletion of files from ordinary host conversations or
+files supplied to `slates_save_external_image`.
+
+On timeout or an uncertain response, reuse the SAME requestId. Do not create
+a new request to check the old one. Failed or unavailable connections preserve
+the user's prompt and refs. Start sign-in with `slates_connect_chatgpt` only when
+the user requests connecting; give the returned URL to the user to complete it.
+
+## Host-tool path
+
+If this conversation exposes a built-in image generator and the user chooses
+that host workflow, retrieve originals through `slates_get_asset_image` with
+fullRes, or use the returned local paths when the host can read them. Inspect
+local images using the host's image viewer before editing. Supply every selected
+reference in its intended order using the generator's actual schema.
+
+Use the built-in generator. No API key, paid API, browser automation, invented
+model identifier, hidden quality setting or silent fallback. If unavailable,
+report that limitation and retain the prepared prompt and references.
+
+Save EACH returned image through `slates_save_external_image`, using its actual
+filePath or image dataUrl, exact submitted prompt, observed generator label and
+the IDs of the references actually sent. Omit model unless the host reports it.
+Requested settings are requests, not output facts. Text-only images have no
+references. Never substitute a screenshot of the result for the original bytes.
+
+For an uncertain save, inspect the project's new assets and compare prompt,
+lineage and output bytes before retrying. The external save operation is not
+idempotent for new imports. Reuse assetId to annotate a confirmed existing
+upload; do not import the same file again. If identification is ambiguous, stop
+and report the uncertainty. A missing output or host failure saves nothing and
+does not authorize another generation.
+
+## Framing and quality requests
+
+The connected operation accepts optional `aspectRatio`, with presets supplied
+by its schema. Slates appends that request in words through the same composer
+used by the UI's What gets sent preview. Do not also append a second ratio
+instruction yourself. Saved metadata preserves the original text, requested
+ratio and exact submitted prompt; actual dimensions remain measured separately.
+
+For a new prompt, choose only an aspect-ratio preset supported by the current
+flagship GPT image model in Slates' capability SSOT. Resolve the current model
+through `slates_list_available_models` and `slates_get_prompting_guide` for
+model-selection; read the generated `slates_generate_image` aspectRatio schema
+for its allowed presets. Do not call that paid operation. Do not maintain a
+second hard-coded ratio list here. If the current presets cannot be retrieved,
+retain the prepared prompt and resolve them before adding a framing request.
+An explicit user request takes precedence; never silently rewrite their prompt.
+
+State the chosen ratio and orientation in the submitted text. This is a prompt
+request, not a host size parameter or an assertion of the host's limits. Measure
+the returned file and report requested versus actual framing; never silently
+crop or stretch it to make the numbers match.
+
+Describe desired detail, legibility, materials and lighting concretely. Words
+such as “higher quality” do not establish a quality enum or select a backend.
+Only record an actual model or quality tier if the host reports it. The built-in
+tool and App Server receipt inspected for this workflow do not expose those
+fields. Preserve revisedPrompt separately when supplied.
+
+OpenAI's [image prompting guide](https://developers.openai.com/api/docs/guides/image-prompting)
+separates API parameters from prompt language. Its quality and pixel controls
+are not automatically controls of the built-in tool. Product launch names and
+the `chatgpt-image-latest` API alias are not per-result model receipts.
+
+## Verify the saved result
+
+Read back the returned asset(s) and inspect the images. Report project, badge
+code, generator, reference codes and measured dimensions. Distinguish submitted
+prompt from any host-reported revised prompt. Do not claim a model/quality tier
+from appearance. Reuse Prompt restores text and references; check the displayed
+generation destination before another generation. No plugin publication or
+directory listing is required for this workflow.

package/exports/slates-prompt-builder/generated/SKILL.md

@@ -18,7 +18,7 @@ This portable skill is deliberately thin. Its reference files are generated dire
 |---|---|---|
 | **Kling 3.0** | THE COST-EFFECTIVE SEAT — strong start-frame adherence (identity, layout, text), acting, dialogue, lip-sync and the widest aspect-ratio set; pick it when the budget matters and the shot is a performance or a start-frame animation. Kling is also the ONLY engine behind the Motion Transfer and Lip Sync tools. | `reference-kling.md` |
 | **Seedance 2.0** | THE 4K AND VALUE SEAT beside the 2.5 default — the only Seedance with native 4K (Pro-gated; base accounts get PRO_REQUIRED) and cheaper than 2.5 at every resolution they share, with the same physics, effects and scale strengths; shorter takes, fewer references, no timestamps. VIDEO-ONLY. A bare "seedance" still resolves here for older CLIs that expect 4K. | `reference-seedance.md` |
-| **Nano Banana 2 (Gemini 3.1 Flash Image)** | DEFAULT image model and the all-rounder — route here unless another seat's speciality is the point. Best start-frame for legible in-scene text. Knowledge cutoff Jan 2025: anything later needs reference images. | `reference-nano-banana.md` |
+| **Nano Banana 2 (Gemini 3.1 Flash Image)** | The all-rounder and the only image seat with a headless path: holds many subjects coherently in one frame, and the start-frame for legible in-scene text. Knowledge cutoff Jan 2025: anything later needs reference images. | `reference-nano-banana.md` |
 <!-- @end:model-routing -->
 
 If the user names a model, use it. Otherwise route by the generated table above.

package/exports/slates-prompt-builder/generated/reference-character.md

@@ -52,7 +52,15 @@ If text only: generate from prompt-only — less consistent, so warn the user.
 
 ### Generate the sheet
 
-- Default to Nano Banana 2 at 2K. **Never 4K** — no identity gain at sheet scale, wasted spend.
+<!-- @inject:sheet-tool-defaults -->
+**What the sheet tools render on** (you do not pick these; omit `model`):
+
+- **Character identity sheet:** `gpt-image-2-5-sunburst` at 3k, quality `high`, one 16:9 image.
+- **Establishing image:** `gpt-image-2-5-sunburst` at 3k, quality `high`, one 16:9 image.
+
+Price a sheet for that model at 16:9, with resolution and quality left at their defaults. **Never 4K** — no identity gain at sheet scale, wasted spend.
+<!-- @end:sheet-tool-defaults -->
+
 - When the result returns inline, **evaluate it before binding**:
   - Is the portrait clearly the largest panel, and is it off-frontal?
   - **Is the front body panel cleanly headless** — an empty collar above a normally rendered body, no partial face, no floating jaw, no smeared neck stump? A botched crop is worse than no crop.

package/exports/slates-prompt-builder/generated/reference-kling.md

@@ -145,7 +145,7 @@ Every reference rule below is a corollary of that one sentence, which is why "pr
 Identity = a few flat-lit neutral angles; one reference per role, named inline; 2-4 refs not 12; describe environments instead of feeding a grid.
 
 1. **2-4 strong references beat both extremes.** Not 1 (warps toward itself), not 12 (averages worse). Start with 2-3 focused refs — each one adds context AND another variable to balance.
-2. **One reference per ROLE, named in the prompt** — identity / style-grade / environment. The model does **not** infer a reference's role from its position in the list; the inline name carries it. Same-role competitors drift (two "identity" refs of different people blend into a third face). Slates composes the naming for you from your `@mentions` / `#tags` — you never hand-write role labels.
+2. **One reference per ROLE, named in the prompt** — identity / style-grade / environment. The model does **not** infer a reference's role from its position in the list; the inline name carries it. Same-role competitors drift (two "identity" refs of different people blend into a third face). Slates resolves `@mentions` / `#tags` into numbered citations. You can also bind references directly in scene prose, naming what each image supplies.
 3. **One identity sheet per character, named inline.** A character's identity is a single asset (dominant portrait + body panels), so attach that one asset rather than a pile of views: **fewer competing renderings of a face is better, because the model cannot tell which one is authoritative and averages them.** Slates cites it as `Marcus (image 1)`. **Do NOT hand-write a "Reference Image Instructions" block or role essays** ("use for identity, ignore the outfit, render a neutral expression") — that drags the sheet's studio lighting and wardrobe into a scene that asked for neither. The prompt leads; the user's words own wardrobe, expression, lighting, and action.
 4. **Flat-light identity refs.** Prep identity references with flat, even, shadowless lighting on a plain neutral background. A studio-lit or scene-lit character sheet bleeds its lighting into every generation — the failure looks like the subject was green-screen-pasted in front of the location. Reference prep beats prompting here.
 5. **Environment: describe it, don't feed a grid.** Default to describing the location in words and let the model build a space that fits the shot. Reserve an environment reference for a mandatory exact-match, and then use ONE clean establishing image with natural ambient light that reads as the location's real light — never a multi-panel grid fed whole.
@@ -167,11 +167,11 @@ Kling exposes `negative_prompt` on the fal endpoint (different from Seedance whi
 
 ```
 blurry, low quality, watermark, text overlay, distorted hands, extra fingers,
-duplicate limbs, unnatural skin texture, overly saturated colors, lens flare,
+duplicate limbs, unnatural skin texture, overly saturated colors,
 floating objects, inconsistent shadows, jittery, flickering, morphing face
 ```
 
-Layer scene-specific suppressions on top.
+Layer scene-specific suppressions on top, and never suppress something the prompt asks for. This block carried `lens flare` until 2026-09-15, which silently cancelled every flare a prompt described (`slates-cinematic-look` → `source-flare`); add it back only for a shot that must have none.
 
 ## Cinematic tactics
 

package/exports/slates-prompt-builder/generated/reference-nano-banana.md

@@ -8,15 +8,21 @@
 **Card — Nano Banana 2 (Gemini 3.1 Flash Image).** Brief it like a creative director, not a tag list. Structure: `Film still from [director] [genre]. Shot on [camera] with [lens]. [Subject and action]. [3-5 specific visual details]. [Lighting — direction + quality]. [Color palette]. [Film stock]. [1-2 word tone].`
 
 **The five levers**
-1. **Named lens + aperture** beats "shallow depth of field" — `85mm f/1.4`, `135mm f/2.8` (the cheat code for skin), `Panavision anamorphic`, `400mm telephoto`.
+1. **Named lens + aperture** beats "shallow depth of field" — `85mm f/1.4`, `135mm f/2.8`, `Panavision anamorphic`, `400mm telephoto`.
 2. **Light by direction and quality**, never "good lighting" — `hard sidelight from a single window, deep falloff`, `overcast north light`, `practical tungsten spill`.
 3. **A named film stock or sensor** carries a whole palette — `Kodak Portra 400`, `Cinestill 800T`, `ARRI Alexa 65`.
 4. **Composition as a shot** — `low angle`, `aerial view`, `rule of thirds with the subject camera-left`, `foreground occlusion`.
 5. **Positive framing only.** Describe what is there. "Empty street", never "no cars"; "unstaged documentary photography", never "not anime".
 
-**Examples**
-- `Film still from a Denis Villeneuve thriller. Shot on ARRI Alexa 65, 85mm f/1.4. A woman in a charcoal wool coat stands at a rain-slick bus stop, breath visible. Hard sodium light from a single overhead lamp, deep falloff into blue night. Kodak Vision3 500T. Isolated.`
-- `Editorial still life on seamless bone paper. 100mm macro, f/8. A cracked ceramic bowl holding three figs. Soft north light from camera-left, one gentle shadow. Muted earth palette. Portra 400 grain. Quiet.`
+<!-- @inject:cinematic-card -->
+**For a photographic look, use only what this frame needs.** Image models default to clean, evenly lit and fully exposed. Describe what the camera sees, not just gear or mood:
+- **Inspect every reference first.** Write its grade and imperfections in words: darkness, contrast, muddy or true blacks, colour, softness/noise, subject separation. Never grade cleaner or brighter than the look reference unless asked.
+- **One light system** — `low sun behind her`, `her face falls into deep shadow`, `no light in front of her`.
+- **Visible exposure** — `the sky burns out to white`, `dense, slightly crushed shadows`.
+- **Lens name plus effect** — `200mm telephoto`, `peaks loom huge behind her and melt into soft shapes`.
+- **Name every garment and close the foreground.** Omissions invite reference leakage or invented props.
+Bind references inline. A scene reference owns the grade; for a look-only reference, write the new scene's light. References are optional. For owned-frame edits, describe only the change and what stays.
+<!-- @end:cinematic-card -->
 
 **Hard constraint:** there is no `negativePrompt` field. Suppress by reframing positively, or inline `without` / `free of`. Knowledge cutoff January 2025 — anything later needs reference images.
 <!-- @card:end -->
@@ -46,12 +52,14 @@ Film still from [DIRECTOR] [GENRE]. Shot on [CAMERA] with [LENS]. [SUBJECT and a
 
 ## Photorealism positives — what consistently works
 
-> ⚠️ **This vocabulary is an IMAGE-model lever and a video-model anti-pattern — do not carry it across.**
-> Named lenses, apertures, film stocks and camera bodies (`85mm f/1.4`, `Kodak Portra 400`, `ARRI Alexa 65`) are correct and encouraged **here**. They are a **Seedance anti-pattern**: ByteDance's own guide uses shot sizes, camera moves, pacing words and its image-quality vocabulary throughout, and never once mentions fps, shutter angle, f-stop, or lens millimetres.
-> The leak happens in one specific way — you write an NB2 start frame, then write the video prompt to animate it and carry the look description straight across. **Translate instead of copying:** `85mm f/1.4, Portra 400` → `close-up, shallow depth of field, warm natural colors, cinematic texture, film-grain texture`. Full rule and the receipts: `reference-seedance.md` (Part 3, "Don't cross-pollinate image-model syntax").
+⚠️ **This vocabulary is correct here and does not carry into a video prompt.** The leak happens one way: you write an NB2 start frame, then carry its look description straight into the prompt that animates it.
+
+<!-- @inject:lens-video-split -->
+Named lenses, apertures, film stocks and camera bodies (`85mm f/1.4`, `Kodak Portra 400`, `ARRI Alexa 65`) are an image-model lever. On a video model, translate the look instead of pasting the gear list: `85mm f/1.4, Portra 400` becomes `close-up, shallow depth of field, warm natural colors, cinematic texture, film-grain texture`. ByteDance's Seedance 2.0 guide never mentions fps, shutter angle, f-stop or lens millimetres. Its Seedance 2.5 guide does, once: the visual-style line of its own storyboard example names one camera body and one 35 mm cinema lens. On 2.5 a single line like that is vendor-sanctioned; a stacked gear list still is not.
+<!-- @end:lens-video-split -->
 
 **Named lenses + apertures** beat generic "shallow depth of field":
-- `85mm f/1.4`, `135mm f/2.8` (the cheat code for skin texture), `50mm f/1.2`, `35mm f/2`
+- `85mm f/1.4`, `135mm f/2.8`, `50mm f/1.2`, `35mm f/2`
 - `Panavision anamorphic` for horizontal flares + cinematic width
 - `400mm telephoto` for compression + isolation
 - `24mm` for environmental interiors
@@ -76,6 +84,7 @@ Film still from [DIRECTOR] [GENRE]. Shot on [CAMERA] with [LENS]. [SUBJECT and a
 - `visible pores`, `natural skin grain`, `peach fuzz`, `slight hyperpigmentation`
 - `unretouched raw photography`, `ISO noise`, `sweat beading`
 - `crisp catchlights in the eyes`, `skin micro-detail`
+- Lead with the kind of photograph and the conditions on the skin (sun, wind, sweat), then add one or two of these. A bare list of flaw words read as tokens and produced plastic skin on GPT Image 2 (2026-08-24).
 
 **Director references** (use when locking style):
 | Director | Tone | Visual signature |
@@ -103,6 +112,9 @@ These are Stable-Diffusion-era tag soup. The model treats them as low-signal noi
 - `cinematic` standing alone — always specify *which cinema* (director, lens, era, stock)
 - `not anime, not cartoon, not 3D` — negation tag soup, replace with a positive style cue
 
+**Examples**
+- `Film still from a Denis Villeneuve thriller. Shot on ARRI Alexa 65, 85mm f/1.4. A woman in a charcoal wool coat stands at a rain-slick bus stop, breath visible. Hard sodium light from a single overhead lamp, deep falloff into blue night. Kodak Vision3 500T. Isolated.`
+
 ## Negative prompting — there is no field
 
 Nano Banana 2 has **no `negativePrompt` parameter**. Three patterns to suppress unwanted content:
@@ -116,7 +128,7 @@ Default to #1. Reach for #2 only when positive framing can't suppress the unwant
 ## Reference images
 
 - **Hard limit: 14 images** (10 object-fidelity + 4 character-consistency). Categories don't trade — you can't use 14 object slots even if no characters are referenced.
-- **Name each reference inline — Slates does this for you.** When you `@mention` a subject/environment or `#mention` a style, Slates composes the prompt so each reference is named inline as "image N" — e.g. `Marcus (image 1) sits across from the woman (image 2) in the cafe (image 3)`, with a trailing `Render in the visual style of image 4.` The model does NOT infer a reference's role from its position; the NAME carries it. NB2's own consistency lever is literally **"assign a distinct name to each character/object"**. **Do NOT hand-write a "Reference Image Instructions" block or role essays** ("use for identity, ignore the outfit, render the scene's expression") — that drags the sheet's wardrobe + studio lighting into the scene. The prompt leads; the user's words own wardrobe, expression, lighting, and action.
+- **Name each reference inline — Slates does this for you.** When you `@mention` a subject/environment or `#mention` a style, Slates composes the prompt so each reference is named inline as "image N" — e.g. `Marcus (image 1) sits across from the woman (image 2) in the cafe (image 3)`, or `lit and graded like image 4` where you placed the style mention. An unmentioned style attachment gets a short fallback clause The model does NOT infer a reference's role from its position; the NAME carries it. NB2's own consistency lever is literally **"assign a distinct name to each character/object"**. **Do NOT hand-write a "Reference Image Instructions" block or role essays** ("use for identity, ignore the outfit, render the scene's expression") — that drags the sheet's wardrobe + studio lighting into the scene. The prompt leads; the user's words own wardrobe, expression, lighting, and action.
 
 ### Reference rules (the verified ones)
 
@@ -138,7 +150,7 @@ Every reference rule below is a corollary of that one sentence, which is why "pr
 Identity = a few flat-lit neutral angles; one reference per role, named inline; 2-4 refs not 12; describe environments instead of feeding a grid.
 
 1. **2-4 strong references beat both extremes.** Not 1 (warps toward itself), not 12 (averages worse). Start with 2-3 focused refs — each one adds context AND another variable to balance.
-2. **One reference per ROLE, named in the prompt** — identity / style-grade / environment. The model does **not** infer a reference's role from its position in the list; the inline name carries it. Same-role competitors drift (two "identity" refs of different people blend into a third face). Slates composes the naming for you from your `@mentions` / `#tags` — you never hand-write role labels.
+2. **One reference per ROLE, named in the prompt** — identity / style-grade / environment. The model does **not** infer a reference's role from its position in the list; the inline name carries it. Same-role competitors drift (two "identity" refs of different people blend into a third face). Slates resolves `@mentions` / `#tags` into numbered citations. You can also bind references directly in scene prose, naming what each image supplies.
 3. **One identity sheet per character, named inline.** A character's identity is a single asset (dominant portrait + body panels), so attach that one asset rather than a pile of views: **fewer competing renderings of a face is better, because the model cannot tell which one is authoritative and averages them.** Slates cites it as `Marcus (image 1)`. **Do NOT hand-write a "Reference Image Instructions" block or role essays** ("use for identity, ignore the outfit, render a neutral expression") — that drags the sheet's studio lighting and wardrobe into a scene that asked for neither. The prompt leads; the user's words own wardrobe, expression, lighting, and action.
 4. **Flat-light identity refs.** Prep identity references with flat, even, shadowless lighting on a plain neutral background. A studio-lit or scene-lit character sheet bleeds its lighting into every generation — the failure looks like the subject was green-screen-pasted in front of the location. Reference prep beats prompting here.
 5. **Environment: describe it, don't feed a grid.** Default to describing the location in words and let the model build a space that fits the shot. Reserve an environment reference for a mandatory exact-match, and then use ONE clean establishing image with natural ambient light that reads as the location's real light — never a multi-panel grid fed whole.

package/exports/slates-prompt-builder/generated/reference-seedance.md

@@ -261,7 +261,7 @@ Every reference rule below is a corollary of that one sentence, which is why "pr
 Identity = a few flat-lit neutral angles; one reference per role, named inline; 2-4 refs not 12; describe environments instead of feeding a grid.
 
 1. **2-4 strong references beat both extremes.** Not 1 (warps toward itself), not 12 (averages worse). Start with 2-3 focused refs — each one adds context AND another variable to balance.
-2. **One reference per ROLE, named in the prompt** — identity / style-grade / environment. The model does **not** infer a reference's role from its position in the list; the inline name carries it. Same-role competitors drift (two "identity" refs of different people blend into a third face). Slates composes the naming for you from your `@mentions` / `#tags` — you never hand-write role labels.
+2. **One reference per ROLE, named in the prompt** — identity / style-grade / environment. The model does **not** infer a reference's role from its position in the list; the inline name carries it. Same-role competitors drift (two "identity" refs of different people blend into a third face). Slates resolves `@mentions` / `#tags` into numbered citations. You can also bind references directly in scene prose, naming what each image supplies.
 3. **One identity sheet per character, named inline.** A character's identity is a single asset (dominant portrait + body panels), so attach that one asset rather than a pile of views: **fewer competing renderings of a face is better, because the model cannot tell which one is authoritative and averages them.** Slates cites it as `Marcus (image 1)`. **Do NOT hand-write a "Reference Image Instructions" block or role essays** ("use for identity, ignore the outfit, render a neutral expression") — that drags the sheet's studio lighting and wardrobe into a scene that asked for neither. The prompt leads; the user's words own wardrobe, expression, lighting, and action.
 4. **Flat-light identity refs.** Prep identity references with flat, even, shadowless lighting on a plain neutral background. A studio-lit or scene-lit character sheet bleeds its lighting into every generation — the failure looks like the subject was green-screen-pasted in front of the location. Reference prep beats prompting here.
 5. **Environment: describe it, don't feed a grid.** Default to describing the location in words and let the model build a space that fits the shot. Reserve an environment reference for a mandatory exact-match, and then use ONE clean establishing image with natural ambient light that reads as the location's real light — never a multi-panel grid fed whole.
@@ -332,9 +332,9 @@ One primary anchor + 2-3 supporting details, as the trailing paragraph (both off
 
 ## ⚠️ Don't cross-pollinate image-model syntax
 
-Named **lenses, apertures, film stocks, and camera bodies** — `85mm f/1.4`, `Kodak Portra 400`, `ARRI Alexa 65`, `shot on Sony A7S3` — are an **image-model lever** (correct and encouraged in `reference-nano-banana.md`) and a **Seedance anti-pattern**. ByteDance's guide uses shot sizes, camera moves, pacing words, and the image-quality/style vocabulary throughout, and never once mentions fps, shutter angle, f-stop, or lens millimetres.
-
-If you are carrying a look over from an NB2 start frame, translate it: `85mm f/1.4, Portra 400` → `close-up, shallow depth of field, warm natural colors, cinematic texture, film-grain texture`.
+<!-- @inject:lens-video-split -->
+Named lenses, apertures, film stocks and camera bodies (`85mm f/1.4`, `Kodak Portra 400`, `ARRI Alexa 65`) are an image-model lever. On a video model, translate the look instead of pasting the gear list: `85mm f/1.4, Portra 400` becomes `close-up, shallow depth of field, warm natural colors, cinematic texture, film-grain texture`. ByteDance's Seedance 2.0 guide never mentions fps, shutter angle, f-stop or lens millimetres. Its Seedance 2.5 guide does, once: the visual-style line of its own storyboard example names one camera body and one 35 mm cinema lens. On 2.5 a single line like that is vendor-sanctioned; a stacked gear list still is not.
+<!-- @end:lens-video-split -->
 
 ## Negative prompting — inline only
 

package/exports/slates-prompt-builder/generated/slates-prompt-builder-manifest.json

@@ -8,19 +8,19 @@
     },
     {
       "path": "skills/slates-character-identity.md",
-      "sha256": "87ede794637553db0074dd64ea9a9cb27bfc3afda52fdc6489702d81e7f94b53"
+      "sha256": "0f8d2a51ad2b8f1504d5e554384a97ad28e27603c1404dc27d234c73680e8b57"
     },
     {
       "path": "skills/slates-prompting-seedance.md",
-      "sha256": "3f2d1f02096169a34da80a1f8a4ef70fb1b22d3dfc8f95cfbb40be908fc7e031"
+      "sha256": "426bd046a9ce8f2f0e466772e6f032d65ea773bbb96729e2161ac61c0d040135"
     },
     {
       "path": "skills/slates-prompting-kling-v3.md",
-      "sha256": "81edd7b060648c97d914017101345b0f0e122660a2050389c80f58f24b48aa9c"
+      "sha256": "ca609eddaa82fbccf103e9fdf91f2c68f4c28e3d9aa8d1e073b9fc6c8d0fe0bd"
     },
     {
       "path": "skills/slates-prompting-nano-banana-2.md",
-      "sha256": "9b746abb7bb3726e39d054a704e9a71f699e365e27e40ced14bca06f922f8a24"
+      "sha256": "1295e2be027cab84f0d96fd86d9cbcd6606e67c0537272ec916a8ed7c582ce3d"
     },
     {
       "path": "skills/slates-content-policy.md",
@@ -28,34 +28,34 @@
     },
     {
       "path": "src/prompts/model-facts.ts",
-      "sha256": "4df3ac4b003ed29c2e1992a34519e01957e5292211a294bb2af0045daf9d4194"
+      "sha256": "92f42aa5befd60cc7f2aa058fcd50c720278008b4665a2bb14a6c7892db280a3"
     }
   ],
   "outputs": [
     {
       "path": "SKILL.md",
-      "bytes": 4622,
-      "sha256": "0c3f1982796fe668824067b06e8d76070aaae2d00d47a978ef5bd8b489b2a3da"
+      "bytes": 4630,
+      "sha256": "416dce585f5ff042f4f83107ac907b0b10d77db171e34e4c5d3c6dfc51e50d75"
     },
     {
       "path": "reference-character.md",
-      "bytes": 10249,
-      "sha256": "75853dcf6b793df82924bf96bee1795b0a33014bb8cc8a2d18543455c0232761"
+      "bytes": 10639,
+      "sha256": "cdf991fd220d5bf0240ae21f15acb238d8970c89a27c5e5434f034160732752d"
     },
     {
       "path": "reference-seedance.md",
-      "bytes": 35043,
-      "sha256": "de7e38a0e54b5c244c2c6be62b74fff0298d1ebf08a77727cc14b093a7487b34"
+      "bytes": 35163,
+      "sha256": "46a4d6ae707bf5dffe622d62dbcc385dd29e9d2ffb3e270b5f91db5fecd5940e"
     },
     {
       "path": "reference-kling.md",
-      "bytes": 15908,
-      "sha256": "99430d96af4461404bb55a6e56e1c3581a2cae817f0e337d0046cbee41dbb0bf"
+      "bytes": 16192,
+      "sha256": "964ca2bc79d4e1b5fb0902293780c9cb7e46a0b3fc7cbfc6e1998fa04661e768"
     },
     {
       "path": "reference-nano-banana.md",
-      "bytes": 18239,
-      "sha256": "7efcaed812a39ddb5a88ba6f7029f975640b5ccc166002d620324d214944125b"
+      "bytes": 19415,
+      "sha256": "2146e05141da197be429ff50cbf6b16bd31fe081cfb74a3a73ca12e450277447"
     },
     {
       "path": "reference-content-policy.md",
@@ -65,8 +65,8 @@
   ],
   "archive": {
     "path": "slates-prompt-builder.skill",
-    "bytes": 40546,
-    "sha256": "0760799f957aac866590768dd00bc74cd4c32525364455c0eab96dba334c4de4",
+    "bytes": 41393,
+    "sha256": "0d9310955ad7e869d1caf195edafc20802944d238fa2350a832290400985b174",
     "entries": [
       "SKILL.md",
       "reference-character.md",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slatesvideo/shared",
-  "version": "0.6.11",
+  "version": "0.7.1",
   "description": "Shared operations layer for the Slates MCP server and CLI: auth, cloud/desktop clients, and the single tool surface both consume. Most users want @slatesvideo/mcp-server or @slatesvideo/cli instead.",
   "license": "MIT",
   "type": "module",
@@ -30,6 +30,10 @@
     "./asset-label": {
       "types": "./dist/prompts/asset-label.d.ts",
       "default": "./dist/prompts/asset-label.js"
+    },
+    "./model-facts": {
+      "types": "./dist/prompts/model-facts.d.ts",
+      "default": "./dist/prompts/model-facts.js"
     }
   },
   "files": [
@@ -37,15 +41,17 @@
     "!dist/**/*.map",
     "skills",
     "exports/slates-prompt-builder/generated",
+    "exports/slates-chatgpt-images/generated",
     "README.md"
   ],
   "scripts": {
     "sync-partials": "node scripts/sync-partials.mjs",
     "build-prompt-builder": "node scripts/build-prompt-builder.mjs",
     "check-prompt-builder": "node scripts/build-prompt-builder.mjs --check",
-    "build": "node scripts/sync-partials.mjs --check && node scripts/build-prompt-builder.mjs --check && node scripts/embed-skills.mjs && tsc && node scripts/render-capability-partials.mjs --check && node scripts/update-check-check.mjs",
+    "build-chatgpt-skill": "node scripts/build-chatgpt-skill.mjs",
+    "build": "node scripts/build-chatgpt-skill.mjs --check && node scripts/sync-partials.mjs --check && node scripts/build-prompt-builder.mjs --check && node scripts/embed-skills.mjs && tsc && node scripts/render-capability-partials.mjs --check && node scripts/update-check-check.mjs",
     "typecheck": "node scripts/sync-partials.mjs --check && node scripts/build-prompt-builder.mjs --check && node scripts/embed-skills.mjs && tsc --noEmit",
-    "prepublishOnly": "npm run build",
+    "prepublishOnly": "npm run build && node ../../scripts/cinematic-catalogue-check.mjs && node ../../scripts/prompt-control-check.mjs",
     "render-partials": "node scripts/render-capability-partials.mjs"
   },
   "repository": {

package/skills/_partials/cinematic-card.md

@@ -0,0 +1,8 @@
+**For a photographic look, use only what this frame needs.** Image models default to clean, evenly lit and fully exposed. Describe what the camera sees, not just gear or mood:
+- **Inspect every reference first.** Write its grade and imperfections in words: darkness, contrast, muddy or true blacks, colour, softness/noise, subject separation. Never grade cleaner or brighter than the look reference unless asked.
+- **One light system** — `low sun behind her`, `her face falls into deep shadow`, `no light in front of her`.
+- **Visible exposure** — `the sky burns out to white`, `dense, slightly crushed shadows`.
+- **Lens name plus effect** — `200mm telephoto`, `peaks loom huge behind her and melt into soft shapes`.
+- **Name every garment and close the foreground.** Omissions invite reference leakage or invented props.
+Bind references inline. A scene reference owns the grade; for a look-only reference, write the new scene's light. References are optional. For owned-frame edits, describe only the change and what stays.
+<!-- slates-only -->Use `slates-cinematic-look` with a technique ID or section query for more.<!-- /slates-only -->

package/skills/_partials/cinematic-routes-short.md

@@ -0,0 +1,2 @@
+<!-- consumer:ts -->
+Two routes: describe a new frame, or change a frame you own. For a new scene, name references where you use them, write the look reference's grade and imperfections in plain words, then describe one light system, visible exposure, lens plus effect, every garment and a closed foreground. Use only what the shot needs. For your own plate, sheet, photo, footage or Blender render, say only what changes and what stays. Never use a released film frame as the edit base; use it as an art-direction brief for a new scene.

package/skills/_partials/cinematic-tips-short.md

@@ -0,0 +1,2 @@
+<!-- consumer:ts -->
+Image models tend toward clean, evenly lit, fully exposed pictures. For a filmed look, describe what you see: one light source and its effect, a face almost in silhouette, a sky burned white. Name the lens and its visible effect together. Look at every reference first and describe its own darkness, contrast, colour, softness, noise and subject separation. Keep muddy blacks muddy; never clean up or brighten the reference's grade unless that is the change you want. Name every garment and exactly what is in the foreground. Use only what the shot needs; references are optional.

package/skills/_partials/decision-log.md

@@ -1,13 +1 @@
-When you surface the plan, include a short **decision log** — one line per decision *you* made that the user did not specify **and that no row already records**:
-
-```
-source phrase or declared default → what you wrote → what it resolves
-"in a diner"        → warm, and the light is the reason           → why the anchor was chosen, not what it is
-(no time of day)    → late afternoon, low warm key                 → default; say the word and it changes
-```
-
-🚨 **Keep it to what is NOT already data — and almost everything now IS.** A Shot holds the references and their roles, the model, every param, the shot size, the camera, the prop, the action and the spoken line, and `slates_list_shots` reads the whole board back in order with its variety counts. Narrating any of those is retelling a row the user can open. **Write the Shot, and let the log carry only the judgement no field holds** — why this world, why this light, why this register.
-
-**Hard rule: never silently add weather, props, style, or camera movement.** Four of those are now FIELDS: put the value on the Shot (`prop`, `camera`, `shotSize`, `action`) so the user can read and change it, and put the *reason* in the log only when you invented it rather than being told it. The rule has not softened — it moved from narration into data, which is stronger, because a field can be corrected and a sentence in chat cannot.
-
-> ❌ **Do NOT turn this into a question gate.** Clarifying questions before optimizing directly fight the locked fast-path rule: *if intent is clear, generate immediately with sane defaults, don't ask questions; only ask for production intent, and batch every question into one message.* Log the decisions, then go. The log is an **output**, not an interrogation — surfaced alongside the plan, never as a separate ceremony, and never as a reason to wait.
+Record production choices in the editable shot fields. Explain only consequential judgments the user did not specify and no field already records: for example, why a particular light or performance register supports the brief. Do not repeat the shot list in prose or turn this explanation into an approval gate. Follow the separate generation authorization policy before spending.

package/skills/_partials/image-defaults.md

@@ -0,0 +1,11 @@
+**Image default:** gpt-image-2-5-sunburst, quality `high`, 3k. User overrides take priority. Without a project, generation uses the headless Nano Banana 2 seat.
+
+| Model | Default resolution |
+|---|---|
+| nano-banana-2 | 2k |
+| nano-banana-2-lite | 1k |
+| nano-banana-pro | 2k |
+| gpt-image-2-5-flare | 2k |
+| gpt-image-2-5-sunburst | 3k |
+| flux-2-max | 1k |
+| seedream-5-lite | 2k |

package/skills/_partials/lens-video-split.md

@@ -0,0 +1 @@
+Named lenses, apertures, film stocks and camera bodies (`85mm f/1.4`, `Kodak Portra 400`, `ARRI Alexa 65`) are an image-model lever. On a video model, translate the look instead of pasting the gear list: `85mm f/1.4, Portra 400` becomes `close-up, shallow depth of field, warm natural colors, cinematic texture, film-grain texture`. ByteDance's Seedance 2.0 guide never mentions fps, shutter angle, f-stop or lens millimetres. Its Seedance 2.5 guide does, once: the visual-style line of its own storyboard example names one camera body and one 35 mm cinema lens. On 2.5 a single line like that is vendor-sanctioned; a stacked gear list still is not.

package/skills/_partials/reference-rules-core.md

@@ -1,7 +1,7 @@
 Identity = a few flat-lit neutral angles; one reference per role, named inline; 2-4 refs not 12; describe environments instead of feeding a grid.
 
 1. **2-4 strong references beat both extremes.** Not 1 (warps toward itself), not 12 (averages worse). Start with 2-3 focused refs — each one adds context AND another variable to balance.
-2. **One reference per ROLE, named in the prompt** — identity / style-grade / environment. The model does **not** infer a reference's role from its position in the list; the inline name carries it. Same-role competitors drift (two "identity" refs of different people blend into a third face). Slates composes the naming for you from your `@mentions` / `#tags` — you never hand-write role labels.
+2. **One reference per ROLE, named in the prompt** — identity / style-grade / environment. The model does **not** infer a reference's role from its position in the list; the inline name carries it. Same-role competitors drift (two "identity" refs of different people blend into a third face). Slates resolves `@mentions` / `#tags` into numbered citations. You can also bind references directly in scene prose, naming what each image supplies.
 3. **One identity sheet per character, named inline.** A character's identity is a single asset (dominant portrait + body panels), so attach that one asset rather than a pile of views: **fewer competing renderings of a face is better, because the model cannot tell which one is authoritative and averages them.** Slates cites it as `Marcus (image 1)`. **Do NOT hand-write a "Reference Image Instructions" block or role essays** ("use for identity, ignore the outfit, render a neutral expression") — that drags the sheet's studio lighting and wardrobe into a scene that asked for neither. The prompt leads; the user's words own wardrobe, expression, lighting, and action.
 4. **Flat-light identity refs.** Prep identity references with flat, even, shadowless lighting on a plain neutral background. A studio-lit or scene-lit character sheet bleeds its lighting into every generation — the failure looks like the subject was green-screen-pasted in front of the location. Reference prep beats prompting here.
 5. **Environment: describe it, don't feed a grid.** Default to describing the location in words and let the model build a space that fits the shot. Reserve an environment reference for a mandatory exact-match, and then use ONE clean establishing image with natural ambient light that reads as the location's real light — never a multi-panel grid fed whole.

package/skills/_partials/sheet-tool-defaults.md

@@ -0,0 +1,6 @@
+**What the sheet tools render on** (you do not pick these; omit `model`):
+
+- **Character identity sheet:** `gpt-image-2-5-sunburst` at 3k, quality `high`, one 16:9 image.
+- **Establishing image:** `gpt-image-2-5-sunburst` at 3k, quality `high`, one 16:9 image.
+
+Price a sheet for that model at 16:9, with resolution and quality left at their defaults. **Never 4K** — no identity gain at sheet scale, wasted spend.

package/skills/slates-character-identity.md

@@ -68,7 +68,15 @@ If text only: generate from prompt-only — less consistent, so warn the user.
 - Estimate cost first with `slates_estimate_generation_cost` and announce in **credits** — never quote a price from memory.
 <!-- /slates-only -->
 
-- Default to Nano Banana 2 at 2K. **Never 4K** — no identity gain at sheet scale, wasted spend.
+<!-- @inject:sheet-tool-defaults -->
+**What the sheet tools render on** (you do not pick these; omit `model`):
+
+- **Character identity sheet:** `gpt-image-2-5-sunburst` at 3k, quality `high`, one 16:9 image.
+- **Establishing image:** `gpt-image-2-5-sunburst` at 3k, quality `high`, one 16:9 image.
+
+Price a sheet for that model at 16:9, with resolution and quality left at their defaults. **Never 4K** — no identity gain at sheet scale, wasted spend.
+<!-- @end:sheet-tool-defaults -->
+
 - When the result returns inline, **evaluate it before binding**:
   - Is the portrait clearly the largest panel, and is it off-frontal?
   - **Is the front body panel cleanly headless** — an empty collar above a normally rendered body, no partial face, no floating jaw, no smeared neck stump? A botched crop is worse than no crop.

package/skills/slates-chatgpt-images.md

@@ -0,0 +1,107 @@
+---
+name: slates-chatgpt-images
+description: Generate images using a connected ChatGPT account or the desktop host's built-in image tool, preserving Slates project context, exact prompts and reference lineage. Use when the user requests ChatGPT generation rather than Slates credits.
+---
+
+# ChatGPT images in Slates
+
+Resolve the project with `slates_list_projects` and references with
+`slates_get_selection` or `slates_list_assets`. Badge codes are project-specific.
+Inspect the selected images before generating. Keep the ordered reference IDs
+alongside the exact prompt submitted for every output.
+
+Retrieve relevant craft with `slates_get_prompting_guide`: use `cinematic-look`
+or `style-prompting` for those requests, with section/query retrieval when useful.
+Do not apply another API model's settings or capabilities to the host generator.
+
+## Connected desktop path
+
+This add-on is off by default. The user enables Settings → AI tools → ChatGPT images in
+Slates before connecting. It requires an installed Codex host and an eligible
+ChatGPT account; a subscription alone does not install or connect the host.
+Settings offers installation instructions, Connect ChatGPT and Check again in
+place, and reports the same connection state as the image picker.
+Never install software or enable the add-on silently. Ordinary Slates use needs
+neither this add-on nor Codex.
+
+Call `slates_get_chatgpt_status`. If connected, use
+`slates_generate_chatgpt_image` with projectId, a fresh UUID requestId, the prompt
+and ordered referenceAssetIds. This is also the path used by Slates' prompt bar
+and Studio Agent. Use background mode for long calls and inspect
+`slates_get_generation_status` with the returned generationId.
+The desktop bridge removes only its own temporary thread's original image after
+saving and byte-verifying the project copy. Failed cleanup keeps the original.
+This does not authorize deletion of files from ordinary host conversations or
+files supplied to `slates_save_external_image`.
+
+On timeout or an uncertain response, reuse the SAME requestId. Do not create
+a new request to check the old one. Failed or unavailable connections preserve
+the user's prompt and refs. Start sign-in with `slates_connect_chatgpt` only when
+the user requests connecting; give the returned URL to the user to complete it.
+
+## Host-tool path
+
+If this conversation exposes a built-in image generator and the user chooses
+that host workflow, retrieve originals through `slates_get_asset_image` with
+fullRes, or use the returned local paths when the host can read them. Inspect
+local images using the host's image viewer before editing. Supply every selected
+reference in its intended order using the generator's actual schema.
+
+Use the built-in generator. No API key, paid API, browser automation, invented
+model identifier, hidden quality setting or silent fallback. If unavailable,
+report that limitation and retain the prepared prompt and references.
+
+Save EACH returned image through `slates_save_external_image`, using its actual
+filePath or image dataUrl, exact submitted prompt, observed generator label and
+the IDs of the references actually sent. Omit model unless the host reports it.
+Requested settings are requests, not output facts. Text-only images have no
+references. Never substitute a screenshot of the result for the original bytes.
+
+For an uncertain save, inspect the project's new assets and compare prompt,
+lineage and output bytes before retrying. The external save operation is not
+idempotent for new imports. Reuse assetId to annotate a confirmed existing
+upload; do not import the same file again. If identification is ambiguous, stop
+and report the uncertainty. A missing output or host failure saves nothing and
+does not authorize another generation.
+
+## Framing and quality requests
+
+The connected operation accepts optional `aspectRatio`, with presets supplied
+by its schema. Slates appends that request in words through the same composer
+used by the UI's What gets sent preview. Do not also append a second ratio
+instruction yourself. Saved metadata preserves the original text, requested
+ratio and exact submitted prompt; actual dimensions remain measured separately.
+
+For a new prompt, choose only an aspect-ratio preset supported by the current
+flagship GPT image model in Slates' capability SSOT. Resolve the current model
+through `slates_list_available_models` and `slates_get_prompting_guide` for
+model-selection; read the generated `slates_generate_image` aspectRatio schema
+for its allowed presets. Do not call that paid operation. Do not maintain a
+second hard-coded ratio list here. If the current presets cannot be retrieved,
+retain the prepared prompt and resolve them before adding a framing request.
+An explicit user request takes precedence; never silently rewrite their prompt.
+
+State the chosen ratio and orientation in the submitted text. This is a prompt
+request, not a host size parameter or an assertion of the host's limits. Measure
+the returned file and report requested versus actual framing; never silently
+crop or stretch it to make the numbers match.
+
+Describe desired detail, legibility, materials and lighting concretely. Words
+such as “higher quality” do not establish a quality enum or select a backend.
+Only record an actual model or quality tier if the host reports it. The built-in
+tool and App Server receipt inspected for this workflow do not expose those
+fields. Preserve revisedPrompt separately when supplied.
+
+OpenAI's [image prompting guide](https://developers.openai.com/api/docs/guides/image-prompting)
+separates API parameters from prompt language. Its quality and pixel controls
+are not automatically controls of the built-in tool. Product launch names and
+the `chatgpt-image-latest` API alias are not per-result model receipts.
+
+## Verify the saved result
+
+Read back the returned asset(s) and inspect the images. Report project, badge
+code, generator, reference codes and measured dimensions. Distinguish submitted
+prompt from any host-reported revised prompt. Do not claim a model/quality tier
+from appearance. Reuse Prompt restores text and references; check the displayed
+generation destination before another generation. No plugin publication or
+directory listing is required for this workflow.