From f2461fe2b14f14632bc1e51e4c8d287e7cd504a8 Mon Sep 17 00:00:00 2001
From: Ziyu Huang <ziyu4huang@gmail.com>
Date: Mon, 6 Jul 2026 22:04:18 +0800
Subject: [PATCH 1/5] =?UTF-8?q?feat(graphics):=20mlx=5Fimage=20provider=20?=
 =?UTF-8?q?=E2=80=94=20bridge=20MLX=20native=20gen=20into=20OpenMontage?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add the first Apple-Silicon-native image provider. `mlx_image` shells to the
sibling mlx-movie-director repo's `run.py image` (Z-Image / Flux2 Klein / Lens)
and is auto-discovered by `image_selector` with zero selector edits — the
selector-plus-provider seam from the story→image review.

Closes OpenMontage's biggest verified image gap: a local, $0 path that
advertises the full control surface (controlnet / img2img / reference_image /
faceswap / lora / multi_lora) that today only grok_image's edit mode partially
covers. The scorer rewards it accordingly — it ranks #1 by weighted score
(control=1.0, cost_efficiency=1.0) and survives the edit-mode candidate filter.

- tools/graphics/mlx_image.py: provider; action routing (t2i/i2i/controlnet/
  faceswap), CLI arg mapping, availability gate (arm64 + MLX_MOVIE_DIRECTOR_DIR
  + venv + models), JSON_SUMMARY output parsing with dir-scan fallback.
- .agents/skills/mlx-movie-director/SKILL.md: Layer-3 bridge (env contract,
  pipeline choice, controlnet/i2i/faceswap mapping, LoRA stacks).
- tests/tools/test_mlx_image.py: 24 tests — registration, capability surface,
  zero-edit discovery, edit-filter survival, gate (env/venv/full), action
  routing, arg building, mocked-subprocess execute success + error paths.
- docs/REVIEW-story-to-image.md, docs/REVIEW-image-to-video-voice.md: the
  grounded reviews that motivated this provider (gap analysis + MLX side-by-side).

Verified end-to-end: a real Z-Image generation (828 KB PNG, 17.6s, $0) flows
through image_selector -> mlx_image -> run.py and lands at output_path with
asset_manifest-ready provenance (source_tool=mlx_image, model=mlx-zimage, seed).

Two upstream MLX-repo deps (opencv-python, mflux) are missing from its
requirements.txt — noted in install_instructions + the skill (tracked upstream).

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .agents/skills/mlx-movie-director/SKILL.md | 109 +++++
 docs/REVIEW-image-to-video-voice.md        | 532 ++++++++++++++++++++
 docs/REVIEW-story-to-image.md              | 255 ++++++++++
 tests/tools/test_mlx_image.py              | 310 ++++++++++++
 tools/graphics/mlx_image.py                | 535 +++++++++++++++++++++
 5 files changed, 1741 insertions(+)
 create mode 100644 .agents/skills/mlx-movie-director/SKILL.md
 create mode 100644 docs/REVIEW-image-to-video-voice.md
 create mode 100644 docs/REVIEW-story-to-image.md
 create mode 100644 tests/tools/test_mlx_image.py
 create mode 100644 tools/graphics/mlx_image.py

diff --git a/.agents/skills/mlx-movie-director/SKILL.md b/.agents/skills/mlx-movie-director/SKILL.md
new file mode 100644
index 000000000..b9cccc208
--- /dev/null
+++ b/.agents/skills/mlx-movie-director/SKILL.md
@@ -0,0 +1,109 @@
+---
+name: mlx-movie-director
+description: Use when routing image generation to the mlx_image provider (Apple-Silicon-native MLX via the sibling mlx-movie-director repo). Covers pipeline choice (zimage / flux2-klein / lens), ControlNet, i2i, LoRA stacks, faceswap, availability gating, and the MLX_MOVIE_DIRECTOR_DIR / MLX_VENV_PYTHON environment contract.
+---
+
+# MLX Movie Director (run.py) in OpenMontage
+
+Use this skill before calling `mlx_image`, and whenever a brief wants a local,
+`$0` Apple-Silicon path for ControlNet, true image-to-image, LoRA conditioning,
+or BFS face/head swap — the surface no other OpenMontage image provider covers
+fully (only `grok_image`'s edit mode partially overlaps).
+
+## Environment Contract
+
+`mlx_image` shells out to the sibling MLX repo. Two env vars wire it up (set
+them in the OpenMontage deployment environment, not per-call):
+
+- **`MLX_MOVIE_DIRECTOR_DIR`** — repo root containing
+  `python/mlx-movie-director/run.py`. Without this the tool is UNAVAILABLE.
+- **`MLX_VENV_PYTHON`** — the MLX venv interpreter. Defaults to
+  `<MLX_MOVIE_DIRECTOR_DIR>/python/venv/bin/python`. **This venv is per-machine
+  and NOT auto-created** (per the MLX repo's CLAUDE.md). On a fresh clone or
+  after `git clean` it is absent; recreate it:
+  ```
+  uv venv python/venv --python 3.12
+  uv pip install -r python/mlx-movie-director/requirements.txt --python python/venv/bin/python
+  ```
+  Two runtime deps are not yet in that requirements.txt (tracked as an upstream
+  MLX-repo gap) — install them into the same venv after the requirements
+  install: `opencv-python` (the image-quality command imports `cv2`) and
+  `mflux` (the Z-Image VAE loader).
+
+Apple Silicon (`arm64`) is required. The provider's `get_status()` returns
+UNAVAILABLE with the exact recreate command when the venv is missing — surface
+that reason to the user; do not retry silently.
+
+## Choosing a Pipeline
+
+The `pipeline` input selects the MLX model family (the `--pipeline` flag passed
+through to `run.py image`):
+
+- **`zimage`** (default) — Moody 12.6 DPO turbo. ~1.5 s/step, 9 steps default.
+  Best for portraits and general T2I. CFG is opt-in (the model was distilled at
+  guidance 0.0; set `cfg_scale` > 1.0 only for an experimental dual-forward).
+- **`flux2-klein`** — Klein 9B (or 4B). ~10 s/step, 4 steps. Better for
+  consistent characters; the edit-class backend for angle / i2i / faceswap /
+  profile. Distilled — CFG inert for T2I.
+- **`lens`** — Microsoft Lens 3.8B, pure MLX, high-res. ~0.4 s/step, 20 steps,
+  1024² default. `cfg_scale` default 4.0. No LoRA / ControlNet / i2i.
+
+Resolution: omit `width`/`height` to use the per-pipeline model-optimal default
+(zimage/klein 640×960, lens 1024²). Pass `resolution` for a named tier
+(`model` / `benchmark` / `large`) or explicit `WxH` (snapped to a multiple of
+16) — useful for QA / self-learning at larger sizes.
+
+## ControlNet, i2i, and Faceswap
+
+These are the capabilities that justify choosing `mlx_image` over cloud
+providers. The provider infers the `run.py image` action from the inputs:
+
+| Inputs present | run.py action | Notes |
+|---|---|---|
+| `image`/`image_path` + `face` | `faceswap` | BFS face/head swap (Flux2 Klein + BFS LoRA). Set `face_mode`: `face` (face only) or `head` (head + hair). |
+| `image` + `controlnet_type` or `controlnet_strength` | `controlnet` | Z-Image native ControlNet. `controlnet_type` e.g. `pose`. |
+| `image` only | `i2i` | Image-to-image. Set `denoise_strength` (0–1; higher = more change). Optional `reference_image` for pose/style conditioning. |
+| neither | `t2i` | Text-to-image. |
+
+For i2i and controlnet, `image`/`image_path` maps to run.py's `--input-image`
+(not `--input`). For faceswap it maps to `--input` (the body) and `face` to
+`--face` (the source). The provider handles this mapping; callers just pass
+`image`/`image_path` and `face`.
+
+## LoRA Stacks
+
+Pass `lora_path` (list of `.safetensors` paths) and a paired `lora_scale` list
+(same order, one per path). The provider emits `--lora-path`/`--lora-scale`
+pairs. If a single scale is given it is broadcast to the first path only —
+prefer explicit per-path scales. LoRAs apply to the zimage and flux2-klein
+pipelines (lens has no LoRA story).
+
+## What mlx_image Does NOT Support
+
+- **No `negative_prompt`** — run.py image T2I has no `--negative-prompt` flag
+  (Z-Image handles negatives internally). Do not pass one; the selector strips
+  it.
+- **No CUDA / non-Apple-Silicon** — the MLX runtime is MPS-only. On a CUDA box
+  prefer `comfyui_image` (which bundles FLUX2 NVFP4 for Blackwell/DGX Spark).
+- **No `custom_workflow`** — `mlx_image` is not a ComfyUI-graph backend. For an
+  arbitrary ComfyUI workflow, route to `comfyui_image` instead (the selector's
+  `_filter_candidates` handles this when `workflow_json`/`workflow_path` +
+  `output_node` are present).
+
+## Provenance
+
+Each result carries `provider: "mlx"`, `model: "mlx-<pipeline>"` (or
+`mlx-<pipeline>/<transformer>` when a transformer is named), `pipeline`,
+`action`, `seed`, and `mlx_run_py` (the exact `run.py` path invoked). Treat
+seed + pipeline + transformer + prompt as the reproducibility contract; MLX
+generation is byte-deterministic for a fixed seed on the same stack.
+
+## When to Pick mlx_image
+
+- A brief asks for ControlNet-conditioned generation, true i2i edit, LoRA
+  character/style conditioning, or face/head swap — and the box is Apple Silicon.
+- Cost matters (every cloud provider charges per image; mlx_image is `$0`).
+- Offline / air-gapped generation is required.
+- The scorer ranks it highly: it advertises the full `control` surface
+  (controlnet/img2img/reference_image/faceswap/lora), so it wins the `control`
+  and `cost_efficiency` dimensions decisively.
diff --git a/docs/REVIEW-image-to-video-voice.md b/docs/REVIEW-image-to-video-voice.md
new file mode 100644
index 000000000..712d2675e
--- /dev/null
+++ b/docs/REVIEW-image-to-video-voice.md
@@ -0,0 +1,532 @@
+# Review — Image → Video / Voice / Music / Compose path in OpenMontage
+
+> Collected 2026-07-06 from a grounded read of the OpenMontage codebase, with a
+> side-by-side against the sibling MLX-on-Apple-Silicon repo
+> (`video_generation__image_workflow` / `python/mlx-movie-director`). Scope: every
+> post-image stage — motion generation, voice/TTS, music + audio mixing, the
+> avatar/lip-sync layer, and the compose stage that finalizes the deliverable.
+> This is the second half of the review started in
+> `docs/REVIEW-story-to-image.md`.
+>
+> Companion to `docs/ARCHITECTURE.md`, `docs/PROVIDERS.md`, and the story→image
+> review. All excerpts carry `file:line` references.
+
+## TL;DR
+
+The image→deliverable half of OpenMontage is **governance-heavy by design** —
+this is where a wrong choice costs real money (cloud motion/TTS) or breaks the
+creative contract (a runtime swap). Three locks hold the line:
+
+1. **`render_runtime` lock** — locked at proposal, carried through `edit_decisions`
+   unchanged; a silent swap is a **CRITICAL** violation, detected in-tool by a
+   three-source comparator (`video_compose._run_final_review`).
+2. **"Present Both Composition Runtimes" HARD RULE** — when both Remotion and
+   HyperFrames are installed, the agent MUST surface both at proposal; a
+   single-runtime `options_considered` is a **CRITICAL** reviewer finding.
+3. **Motion-required prohibition** — for any `motion_required=true` brief, a
+   still-image / FFmpeg-Ken-Burns / animatic substitute is forbidden without
+   explicit user approval of the downgrade. Stated in 5 reinforcing locations.
+
+The tool layer mirrors the image side's selector-plus-provider seam:
+`video_selector`, `tts_selector`, `music_gen`(+`suno_music`/library/stock), and
+`audio_mixer` are all registry-auto-discovered. The compose stage dispatches one
+tool (`video_compose`) across three runtimes (FFmpeg / Remotion / HyperFrames),
+orthogonal to a Templated-vs-Atelier authoring axis.
+
+The honest gaps (all verified): (1) **seedance dedup race** — fal.ai and Replicate
+Seedance share `provider="seedance"`, so the second-registered is invisible to the
+selector; (2) **LUFS mismatch** — `audio_mixer` hard-codes `-16 LUFS` while
+`sound-design.md` targets `-14` for YouTube; (3) **ducking schema drift** —
+`edit_decisions` declares `threshold_db`/`reduction_db`, but `audio_mixer._duck`
+consumes `music_volume_during_speech` with no translation step; (4) **no MLX
+motion path** — OM's local video providers (wan/hunyuan/ltx/cogvideo) need CUDA
+`diffusers`; on Apple Silicon there is no native i2v (the `mlx_video` port fills
+this); (5) the **faceswap orphan** stands, refined — the skill is HeyGen-API-backed,
+not a dangling local-tool reference.
+
+---
+
+## 1. The chain, stage by stage (post-image)
+
+The canonical state machine continues from where the story→image review left off
+(`AGENT_GUIDE.md:185`):
+
+```
+… scene_plan → assets → edit → compose
+```
+
+| Stage | Director skill (explainer) | Canonical artifact | Post-image content |
+|---|---|---|---|
+| assets | `pipelines/explainer/asset-director.md` | `asset_manifest` | narration (TTS), music/sfx, generated video clips; per-asset `source_tool`/`cost_usd`/`scene_id` |
+| edit | `pipelines/explainer/edit-director.md` | `edit_decisions` | cut list, audio layers (narration/music/sfx + ducking), subtitles, **`render_runtime` lock carried forward** |
+| compose | `pipelines/explainer/compose-director.md` | render + `final_review` | dispatch on `render_runtime` → FFmpeg/Remotion/HyperFrames; promise-preservation check |
+
+The **proposal** stage is where the post-image commitments are locked:
+`production_plan.render_runtime` + `composition_mode` (the lock), the mandatory
+**Music Plan** (`music_source`), and `delivery_promise.motion_required`. These
+three are the governance seeds for everything downstream.
+
+## 2. The motion tool layer
+
+### 2.1 `video_selector` — the routing entry point
+
+`tools/video/video_selector.py` — `capability="video_generation"`,
+`provider="selector"`. Same auto-discovery seam as `image_selector`:
+`registry.get_by_capability("video_generation")` minus itself
+(`video_selector.py:135-140`). Adding a provider = drop a file in `tools/video/`.
+
+Routing (`execute()`, `video_selector.py:175-231`):
+
+1. discover candidates → `_filter_candidates` (operation-aware: `image_to_video`
+   needs `supports.image_to_video` or an `image_url`/`reference_image_url` schema
+   key; `reference_to_video` needs `reference_image_urls`; custom workflows need
+   `custom_workflow` capability — `video_selector.py:328-366`);
+2. score with `lib/scoring.rank_providers` (reused, not reimplemented);
+3. honor `preferred_provider` (a booster, see gap §6.4) and `allowed_providers`;
+4. read the `VIDEO_GEN_LOCAL_MODEL` env hint (`video_selector.py:252-262`) to
+   pre-select a local model when `preferred=="auto"`;
+5. delegate `tool.execute(adapted)` and annotate `selected_tool`/`selected_provider`/
+   `provider_score`/`alternatives_considered` **and** `selected_tool_agent_skills`.
+
+Supports `operation: "rank"` (score without generating) for preflight. Note the
+`fallback_tools` property (`video_selector.py:142-145`) **unconditionally appends
+`image_selector`** — a latent footgun for motion-required briefs (§6.7).
+
+### 2.2 Concrete providers (`tools/video/`)
+
+17 providers. Local providers gate on `VIDEO_GEN_LOCAL_ENABLED=true` + importable
+`diffusers`/`torch` (`_shared.py:183-195`) — i.e. **CUDA-oriented**, not Apple
+Silicon native.
+
+| tool | provider | runtime | cost | i2v/t2v | motion strength | `agent_skills` | key `supports` |
+|---|---|---|---|---|---|---|---|
+| `wan_video` | wan | LOCAL_GPU | $0 | both | 1.3B 832×480@16fps 81f (8 GB) / 14B 720p (24 GB) | `ltx2` | reference_image, offline, local_gpu |
+| `hunyuan_video` | hunyuan | LOCAL_GPU | $0 | both | 848×480@24fps 121f (14 GB) | `ltx2` | reference_image, offline, local_gpu |
+| `ltx_video_local` | ltx | LOCAL_GPU | $0 | both | 768×512@30fps 121f (12 GB) | `ltx2` | reference_image, offline, local_gpu |
+| `cogvideo_video` | cogvideo | LOCAL_GPU | $0 | both (but `cogvideo-2b` variant is i2v=False — gap §6.3) | 5B 720×480@8fps 49f (12 GB) / 2B (6 GB) | `ltx2` | reference_image, offline, local_gpu |
+| `ltx_video_modal` | ltx-modal | API | flat $0.25/gen | both | self-hosted cloud LTX2 (`MODAL_LTX2_ENDPOINT_URL`) | `ltx2` | reference_image, self_hosted_cloud |
+| `comfyui_video` | comfyui | HYBRID | $0 | both | server-driven, bundled WAN 2.2 14B FP8 (16 GB) | `comfyui`, `ai-video-gen`, `ltx2` | custom_workflow, custom_output_node, offline |
+| `heygen_video` | heygen | API | $0.15–0.50/gen (quality tier) | both | veo3.1/veo3/kling/sora/runway/seedance variants | `ai-video-gen`, `create-video` | reference_image, cloud_generation |
+| `seedance_video` | **seedance** | API (fal.ai) | $0.3034/s std, $0.2419/s fast | t2v+i2v+ref | quality_score 0.95; lip_sync, multi_shot, native_audio | `seedance-2-0`, `ai-video-gen` | text/image/reference_to_video, multiple_reference, native_audio, lip_sync, multi_shot |
+| `seedance_replicate` | **seedance** | API (Replicate) | via Replicate | t2v+i2v | quality_score 0.95 | `seedance-2-0`, `ai-video-gen` | text_to_video, image_to_video, native_audio, lip_sync, multi_shot |
+| `kling_video` | kling | API | $0.30 master / $0.20 pro / $0.10 std per 5s | t2v+i2v | v2.1/v3; native_audio | `ai-video-gen` | text/image_to_video, native_audio, cinematic_quality |
+| `minimax_video` | minimax | API | $0.08–0.15/gen | t2v+i2v | hailuo-02/2.3 variants | `ai-video-gen` | text/image_to_video, camera_direction |
+| `veo_video` | veo | API | $0.10/s fast, $0.20/s base, $0.40/s 4k, +$0.20–0.40/s audio | t2v+i2v+ref+first_last | veo3/3.1; dialogue_generation, ambient_sound | `ai-video-gen` | text/image/reference/first_last_frame, native_audio, dialogue_generation |
+| `runway_video` | runway | API | $0.05–0.30/s by model | t2v+i2v | gen3a/gen4/seedance_2.0; quality_score 0.9 | `seedance-2-0`, `ai-video-gen` | text/image_to_video, professional_control, lip_sync, multi_shot |
+| `higgsfield_video` | higgsfield | API | $0.10–0.80/clip | t2v+i2v | multi_model_routing; quality_score 0.9 | `seedance-2-0`, `ai-video-gen` | text/image_to_video, character_consistency, multi_model_routing |
+| `grok_video` | grok | API | $0.05/s 480p, $0.07/s 720p, +$0.002/in img | t2v+i2v+ref | 1–15s; lip_sync | `grok-media`, `ai-video-gen` | text/image/reference_to_video, native_audio, lip_sync — **no quality_score (gap §6.5)** |
+| `pexels_video` / `pixabay_video` | pexels / pixabay | API | free (SOURCE tier) | stock only | stock footage; not i2v/t2v | — | orientation/size/category filters, free_commercial_use |
+
+### 2.3 Motion-required governance (the crown jewels)
+
+For any `delivery_promise.motion_required=true` brief, five locations state the
+prohibition consistently:
+
+- **`AGENT_GUIDE.md:391-406`** — "Critical Rule: Motion-Required Requests":
+  still-image fallback is forbidden; FFmpeg-only fallback is forbidden when it
+  changes the deliverable from motion-led to still-led; **silent runtime swap is
+  forbidden** ("If `render_runtime='hyperframes'` was locked and HyperFrames is
+  unavailable, do NOT route to Remotion instead. Surface the blocker…").
+- **`skills/core/hyperframes.md:74-82`** — the locked runtime is "a commitment,
+  not a hint"; Compose MUST NOT downgrade to FFmpeg Ken Burns.
+- **`skills/pipelines/cinematic/compose-director.md:15,35`** — silent swap
+  (including FFmpeg Ken Burns) is a **CRITICAL governance violation**.
+- **`skills/pipelines/cinematic/asset-director.md:46-82`** — for motion-required
+  jobs, use `video_selector` first; `image_selector` does not satisfy the motion
+  requirement by itself.
+- **`skills/pipelines/cinematic/proposal-director.md:30,101`** — preflight
+  enforcement: if neither generation nor stock can deliver motion, "do not
+  silently downgrade to still-led… present the constraint honestly."
+
+## 3. The voice path
+
+### 3.1 The `script.voice_performance` contract
+
+`schemas/artifacts/script.schema.json:12-33` — a top-level (optional) object:
+`performance_intent`, `pacing_profile` (enum: contemplative/conversational/
+energetic/technical/cinematic/custom), `energy_curve`, `pause_policy`,
+`sample_section_id` ("most performance-sensitive section to use for TTS sample
+approval"), `provider_notes`. Section-level `delivery_cues` (`:46-68`) carry
+`pace`/`energy`/`emphasis_words`/`pause_before_seconds`/`pause_after_seconds`/
+`delivery_note` and **`provider_text`** — the provider-ready string that may
+contain SSML `<break time="0.6s"/>` tags. This is the SSML contract.
+
+### 3.2 `tts_selector` + 6 providers
+
+`tools/audio/tts_selector.py` — `capability="tts"`, `provider="selector"`.
+Auto-discovers via `registry.get_by_capability("tts")` (`tts_selector.py:124-129`),
+reuses `lib/scoring.rank_providers`, supports `operation: "rank"`. Annotates
+`selected_tool`/`selected_provider`/`provider_score`/`selected_tool_agent_skills`/
+`alternatives_considered`.
+
+| provider | runtime | cost | cloning | SSML | `agent_skills` | fallback |
+|---|---|---|---|---|---|---|
+| `elevenlabs_tts` | API | $0.0003/char (**$300/1M**) | **yes** | voice settings, not tags | `elevenlabs`, `text-to-speech` | openai → piper |
+| `openai_tts` | API | $0.000015/char (**$15/1M**) | no | no; `instructions` on `gpt-4o-mini-tts` only | `openai-docs` | piper |
+| `google_tts` | API | $4–$160/1M (tiered: Standard→Chirp3-HD) | no | **yes** — `input_type:"ssml"` wraps `<speak>`, `<break>` supported | `text-to-speech` | openai → elevenlabs → piper |
+| `dashscope_tts` | API | $15/1M | no | no; `instructions` on `qwen3-tts-instruct-flash` | `dashscope` | doubao → elevenlabs → openai → piper |
+| `doubao_tts` | API (ASYNC poll) | $15/1M | no | no; **`enable_timestamp`** → word/sentence alignment (subtitle specialist) | `doubao-tts`, `text-to-speech` | google → elevenlabs → openai → piper |
+| `piper_tts` | LOCAL | **$0** | no | no; `length_scale` + `sentence_silence` | `text-to-speech` | terminal (universal floor) |
+
+No `edge-tts`. Piper is the universal offline floor — every API chain terminates
+there. ElevenLabs is the only cloning provider. Google is the only first-class
+SSML provider. Doubao is the only one returning timestamp metadata.
+
+### 3.3 `voice-performance-director` + sample-then-batch
+
+`skills/meta/voice-performance-director.md` sits above the asset-director. Its
+thesis (`:3-7`): "make generated narration sound **directed**, not merely read."
+It mandates the `voice_performance` contract, translates intent into per-provider
+knobs (`:56-71`: OpenAI `instructions` only on `gpt-4o-mini-tts`; Google `ssml`+
+`speaking_rate 0.25..2.0`; ElevenLabs `stability`/`similarity_boost`/`style`),
+and defines four failure conditions (`:83-94`): no plan, vague directions,
+provider/voice change after sample approval, and generating from raw text when
+`provider_text` exists.
+
+The asset-director runs **sample-first, batch-second** (`asset-director.md:69-82`):
+generate the `sample_section_id` (most demanding section, ~$0.03–0.08), play it,
+confirm voice/pace/pauses/tone (max 3 iterations), then batch. Each narration
+asset records `voice_performance` provenance (`asset_manifest.schema.json:37-53`):
+`source_section_id`, `delivery_cues_applied`, `provider_text_used`,
+`provider_settings`, `sample_approved`, `sample_path`, `review_notes`.
+
+## 4. Music + audio mixing
+
+### 4.1 Generation + sources
+
+- `tools/audio/music_gen.py` — **ElevenLabs Music only** (`music_v1`),
+  `~$0.05/30s`, 3–600s, `agent_skills: ["music","sound-effects","elevenlabs"]`.
+  No `supports` flags. The `force_instrumental=true` mandate lives only in the
+  usage skill (`skills/creative/music-gen-usage.md:14`); the tool never sends it
+  (gap §6.8).
+- `tools/audio/suno_music.py` — Suno V4/V4_5/V5, ASYNC, BETA, vocals + custom
+  lyrics; declares `supports = {instrumental, vocals, custom_lyrics,
+  style_control, long_form}`; `fallback_tools = ["music_gen"]`.
+- `tools/audio/music_library.py` — local filesystem scan (read-only), default
+  `<root>/music_library/`. **No mood/BPM/genre/license metadata**
+  (`music_library.py:102-122`) — selection is by filename + duration only (gap
+  §6.9).
+- `freesound_music` / `pixabay_music` — stock search/download.
+
+### 4.2 Mandatory Music Plan
+
+At proposal, `skills/pipelines/explainer/proposal-director.md:362-397` ("Step 5b:
+Music Plan (Mandatory)") requires surfacing music availability in order:
+user library → AI generation → stock → none (told to user explicitly). The
+decision lands in `proposal_packet.production_plan.music_source`
+(`proposal_packet.schema.json:167-178`: `source_type` user_library/ai_generated/
+bring_your_own/none, `track_path`, `provider`, `mood_direction`, `estimated_cost_usd`).
+**Policy-mandatory, not schema-enforced** (`music_source` is not in `production_plan.required`).
+
+### 4.3 `audio_mixer` + ducking + LUFS
+
+`tools/audio/audio_mixer.py` — pure **FFmpeg** `filter_complex` engine
+(`provider="ffmpeg"`, `agent_skills: ["ffmpeg","video-toolkit"]`). Operations:
+`mix`, `duck`, `extract`, `full_mix`, `segmented_music`.
+
+**Ducking = real sidechain compression, not static gain** (`audio_mixer.py:356-362`):
+
+```python
+[1:a]sidechaincompress=threshold=0.02:ratio=9:attack={attack}:release={release}:level_sc=1:mix=0.9[ducked];
+[ducked]volume={music_vol * 3}[music_out];
+[0:a][music_out]amix=inputs=2:duration=longest[out]
+```
+
+Speech is the sidechain key; music is compressed by it. `full_mix` layers
+narration+music+sfx, runs the music subgroup through the same sidechain keyed by
+the speech subgroup (`:526-531`), then `loudnorm`.
+
+**LUFS target = `-16`** (`audio_mixer.py:254,578`):
+`loudnorm=I=-16:LRA=11:TP=-1.5`. This is the **podcast/Apple** target, NOT the
+YouTube `-14` that `skills/creative/sound-design.md:17,138` targets — a
+documented inconsistency (gap §6.1). The mixer does not parameterize the target.
+
+`segmented_music` (`:606-706`) builds a per-frame `volume` expression for
+"music during talking-head, silence during showcase", looping the bed with
+`-stream_loop -1`.
+
+### 4.4 edit-director ducking wiring (and the schema drift)
+
+`skills/pipelines/explainer/edit-director.md:84-113` configures audio layers:
+narration segments + a music bed (volume `0.08`, fade in/out) + a `ducking`
+object (`threshold_db: -3`, `reduction_db: -8`, attack 200ms, release 500ms) +
+sfx. **But** the `edit_decisions` ducking shape (`threshold_db`/`reduction_db`)
+is **not** the shape `audio_mixer._duck` consumes (`music_volume_during_speech`/
+`attack_ms`/`release_ms` + fixed `threshold=0.02`/`ratio=9`). No translation step
+exists in the mixer (gap §6.2). Note also: when rendering via **Remotion** (the
+default), `audio_mixer` is not used at all — Remotion's `<Audio>` components mix
+natively (`compose-director.md:188-201`); `audio_mixer` is the FFmpeg-fallback
+path only.
+
+## 5. The compose stage + 3 runtimes
+
+### 5.1 `video_compose` dispatch
+
+`tools/video/video_compose.py` — `operation: "render"` resolves asset IDs and
+dispatches on **`edit_decisions.render_runtime`** (`video_compose.py:1307-1402`).
+The field is mandatory and enum-validated (`remotion`/`hyperframes`/`ffmpeg`); an
+unset runtime returns a structured error that explicitly refuses to default
+(`:1314`). `get_info()["render_engines"]` (`:256-323`) surfaces `{ffmpeg: True,
+remotion: <bool>, hyperframes: <bool>}` so the proposal stage knows what's
+installed.
+
+### 5.2 The three runtimes
+
+| runtime | what it does | deps | strengths | scene fit |
+|---|---|---|---|---|
+| **FFmpeg** (`_compose`/`_render_via_ffmpeg`) | per-cut trim+re-encode to 1920×1080@30fps yuv420p, concat-demuxer join, ASS subtitle burn, audio mux | `ffmpeg`/`ffprobe` only | pure-video concat/trim/subtitle/encode; the floor | talking-head raw cuts, no composition |
+| **Remotion** (`_remotion_render`/`_render_via_atelier`) | React/TSX frame-accurate render via `npx remotion render` | Node + `remotion-composer/` + node_modules | animated text/stat cards, data-driven charts (spring physics), word-level captions (`remotion_caption_burn`), `TalkingHead` avatar, `CinematicRenderer`, `<OffthreadVideo>` embed | explainer, cinematic, screen-demo, talking-head, data-viz |
+| **HyperFrames** (`_render_via_hyperframes`→`hyperframes_compose`) | HTML/CSS/GSAP render via `npx hyperframes` (upstream npm pkg) | Node ≥22 + ffmpeg + `npx hyperframes doctor`==0 | kinetic typography, product promos, GSAP-native animation, SVG rigs, registry blocks (grain/shimmer/shader) | motion-graphics-heavy, animation-first |
+
+Composition ID is resolved from `renderer_family` via `RENDERER_FAMILY_MAP`
+(`:683-692`): explainer-data/teacher/product-reveal/screen-demo/animation-first →
+`Explainer`; cinematic-trailer/documentary-montage → `CinematicRenderer`;
+presenter → `TalkingHead`.
+
+### 5.3 The `render_runtime` lock (CRITICAL severity)
+
+Stated in 5 places; enforced in-tool by a three-source swap comparator.
+
+- **Tool docstring** (`video_compose.py:7-8,26-29`) + **routing comment**
+  (`:1307-1312`): "Silent runtime swaps are forbidden by governance."
+- **Schema** (`edit_decisions.schema.json:197-201`): `render_runtime` enum,
+  "Locked at proposal… Edit MUST carry this forward unchanged unless a logged
+  `render_runtime_selection` decision overrides it." Same lock language on
+  `renderer_family` (`:192-196`) and `composition_mode` (`:202-206`).
+- **AGENT_GUIDE** (`:389`): locked at proposal, carried through edit_decisions
+  unchanged.
+- **Reviewer** (`skills/meta/reviewer.md:236-240`): a mismatch without a logged
+  `render_runtime_selection` decision → **CRITICAL**.
+- **In-tool detection** (`video_compose._run_final_review`, `:2189-2242`):
+  three-source priority ladder — (1) `proposal_packet.production_plan.render_runtime`
+  (authoritative), (2) `edit_decisions.metadata.proposal_render_runtime`
+  (edit-stage opt-in), (3) `edit_decisions.render_runtime` alone (cannot detect a
+  swap solo). If proposal ≠ edit → `runtime_swap_detected = true` + an issue
+  appended. `final_review.schema.json:91,95` carries the field.
+
+The tool itself refuses silent substitution: `_render_via_hyperframes` returns a
+structured BLOCKER if HyperFrames is unavailable (`:1504-1516`); the Remotion
+failure path (`:1418-1432`) refuses silent FFmpeg fallback.
+
+### 5.4 "Present Both Composition Runtimes" HARD RULE
+
+`AGENT_GUIDE.md:123-137` — when both Remotion and HyperFrames report `True` in
+`get_info()["render_engines"]`, the agent MUST present both at proposal (per
+runtime: what it's best at for **this brief**, an honest tradeoff, a
+recommendation tied to `delivery_promise`/`visual_approach`), then wait for
+explicit approval. **A `render_runtime_selection` decision with only one runtime
+in `options_considered` when both were available is a CRITICAL reviewer finding**
+(`reviewer.md:242-246`). If only one is available, the unavailable one is still
+recorded with `rejected_because: "runtime not available on this machine"`.
+
+### 5.5 Templated vs Atelier
+
+`AGENT_GUIDE.md:139-146` — orthogonal to `render_runtime`.
+- **Templated** — assemble stock `cut.type` scene-types (`text_card`, `stat_card`,
+  `bar_chart`, …) into `Explainer`/`CinematicRenderer`. Fast/cheap/reliable.
+- **Atelier** — hand-author from scratch (`composition_mode: "atelier"`), bespoke
+  scenes + one-off theme; no reusable creative components. Default for hero/brand
+  work. Enforced mechanically by `_run_atelier_checks` (`video_compose.py:976-1034`)
+  via `_ATELIER_STOCK_IMPORT_RE` — bespoke projects importing stock components
+  (`Explainer`, `CinematicRenderer`, `TalkingHead`, `CollageBurst`, …) fail the
+  render. Missing `bespoke.art_direction` is a warning. For HyperFrames, atelier
+  is the default and needs no flag.
+
+### 5.6 `edit_decisions` artifact
+
+`schemas/artifacts/edit_decisions.schema.json` — `required: [version, cuts,
+render_runtime]`. Carries: `cuts[]` (`source`/`in_seconds`/`out_seconds`/`speed`/
+`layer`/`transform`/`transition_in`/`transition_out`), `overlays[]`, `audio`
+(`narration.segments[]`/`music`+`ducking`/`sfx[]`), `subtitles` (style
+sentence/word-by-word/karaoke), `renderer_family`, `render_runtime`,
+`composition_mode`, `bespoke` (required when atelier), `slideshow_risk_score`
+(verdict `fail` blocks render, `video_compose.py:1240-1256`), `metadata`
+(`compose_target`/`delivery_promise`/`playbook`/`proposal_render_runtime`).
+
+## 6. Avatar / lip-sync layer + faceswap (refined)
+
+### 6.1 Local GPU avatar tools
+
+- `tools/avatar/talking_head.py` — still portrait + audio → talking video.
+  `capability="avatar"`, `provider="sadtalker"`, LOCAL_GPU, $0. **SadTalker
+  implemented** (`:175-242`); **MuseTalk is a stub** (`:244-258`, returns "not yet
+  implemented, use sadtalker"). `fallback="lip_sync"`. Status: AVAILABLE iff
+  `SADTALKER_PATH` or `import sadtalker`.
+- `tools/avatar/lip_sync.py` — video with face + new audio → re-lined video.
+  `provider="wav2lip"`, LOCAL_GPU, $0. **Wav2Lip + Wav2Lip-GAN** implemented
+  (`MODEL_CHECKPOINTS`, `:30-33`). No LatentSync/muse-talk-lip. No fallback
+  declared (it is the fallback target).
+
+### 6.2 `avatar-spokesperson` pipeline
+
+`pipeline_defs/avatar-spokesperson.yaml` (production, $2.00 budget, 12-min).
+Stages: idea → script → scene_plan → assets → edit → compose → publish. The
+**idea-director classifies the avatar path** into `platform_avatar` /
+`photo_talking_head` / `presenter_plate_lip_sync` (`idea-director.md:27-30`) and
+**locks Remotion** (HyperFrames rejected — no TalkingHead parity). The
+**Executive Producer Pivot Decision Matrix** (`executive-producer.md:47-71`)
+runs at **G1 (after IDEA)**, not deferred to assets:
+
+```
+IF talking_head AVAILABLE                          → Standard avatar path
+IF talking_head UNAVAILABLE, lip_sync AVAILABLE    → Lip-sync path (user supplies plate)
+IF NEITHER                                          → Narration-Over-Graphics pivot (or block)
+```
+
+Asset-director locks ONE avatar path; narration resolved via `tts_selector`
+**before** graphics; manifest carries `metadata.avatar_generation_path`. The
+avatar clip enters `asset_manifest` as a generic `type:"video"` asset tagged
+`source_tool:"talking_head"`/`"lip_sync"` — **no avatar-specific schema field**
+exists.
+
+### 6.3 Layer-3 skills — all HeyGen-API
+
+`.agents/skills/{avatar-video,heygen,faceswap,create-video}/` are **all HeyGen v2
+API skills** (`allowed-tools: mcp__heygen__*`, fallback to direct HTTP). They do
+**not** call the local `talking_head`/`lip_sync` tools — a separate (cloud, paid)
+avatar stack. `heygen` is **DEPRECATED** (superseded by `create-video` +
+`avatar-video`).
+
+### 6.4 Faceswap orphan — refined
+
+The prior review (`docs/REVIEW-story-to-image.md:39-40,216-218`) flagged
+`.agents/skills/faceswap/` as orphaned (no backing tool). **Verified still true**
+— `find tools -iname '*faceswap*' -o '*face_swap*' -o '*swap*'` returns zero
+files; the registry auto-discovers `tools/` via `pkgutil.walk_packages`
+(`tool_registry.py:118-134`), so no `faceswap` tool is registered. **But the
+refinement matters**: the skill is **not a dangling reference** — it documents
+direct HeyGen FaceswapNode workflow calls (`POST …/v1/workflows/executions` with
+`workflow_type: "FaceswapNode"`, `faceswap/SKILL.md:23-27,40-49`). It is
+**API-backed, not tool-backed**. If `HEYGEN_API_KEY`/MCP is configured it is
+functional; otherwise dead weight. `.claude/skills/faceswap/SKILL.md` is a
+byte-identical duplicate.
+
+## 7. Side-by-side vs the MLX repo
+
+The MLX repo (`python/mlx-movie-director/run.py`) is native generation on Apple
+Silicon with no orchestration/story layer. For the post-image stages it is
+**mostly silent** — it has motion gen + upscale + ASR, but **no TTS, no music, no
+mixer, no compose, no avatar/lip-sync**.
+
+| Concern | OpenMontage | MLX repo (`run.py`) | Map |
+|---|---|---|---|
+| Motion i2v | cloud (seedance/kling/veo/runway/higgsfield/grok/heygen) + **CUDA locals** (wan/hunyuan/ltx/cogvideo — need `diffusers`/torch VRAM) + comfyui | **LTX-2.3 native MLX I2V** (`video t2i2v`: ZImage T2I → VLM prompt → LTX-2.3 dasiwa animate); `video generate` | `mlx_video` provider fills the **Apple-Silicon-native** i2v gap (OM's CUDA locals don't run on MPS) |
+| Motion t2v | cloud + CUDA locals | `video generate` (LTX-2.3) | same seam |
+| Voice / TTS | full chain (elevenlabs/openai/google/dashscope/doubao/piper) | **NONE** (`video-asr-gate.py:9` "there is no native [MLX TTS]") | no MLX TTS port possible — OM stays as-is |
+| ASR / transcription | (not a first-class tool) | **mlx-whisper** (ASR only; used as t2i2v audio quality gate) | MLX could be OM's local ASR provider (new finding) |
+| Music | music_gen/suno/library/stock + mixer | **NONE** | OM-only |
+| Audio mix / ducking / LUFS | `audio_mixer` (FFmpeg sidechain, -16 LUFS) | **NONE** | OM-only |
+| Compose | FFmpeg/Remotion/HyperFrames + render_runtime lock | **NONE** (generates clips only) | OM-only |
+| Avatar / lip-sync | talking_head (SadTalker)/lip_sync (Wav2Lip) + HeyGen skills | **NONE** | OM-only |
+| Upscale / restore | Real-ESRGAN/CodeFormer/GFPGAN (torch) | ESRGAN (torch vision-venv) + **SeedVR2 7B** (`--upscale-method seedvr2`) | overlap; SeedVR2 could enhance OM's upscale |
+| Visual QA | planned `test_02_image_gen.py` (**missing**) | `caption` (Qwen3-VL 4B) + CLIP `video_understand` | MLX already has the QA brain |
+| Motion governance | render_runtime lock + motion-required prohibition | n/a | OM-only (the value of plugging MLX in) |
+
+**The bidirectional findings:**
+1. **`mlx_video` (LTX-2.3 i2v) is the highest-value motion port** — but its value
+   is specifically **Apple-Silicon-native**. OM already has 4 local i2v providers
+   (wan/hunyuan/ltx/cogvideo) that are `$0`, but they require CUDA `diffusers`
+   (8–24 GB VRAM). On an Apple Silicon box they don't run; MLX LTX-2.3 does. This
+   refines F2: it's not "OM has no offline i2v" — it's "OM's offline i2v is
+   CUDA-only; MLX is the MPS-native path."
+2. **mlx-whisper → OM local ASR provider** is a new finding. OM's video path has
+   no first-class transcription tool; MLX's mlx-whisper (already proven as the
+   t2i2v audio gate) could fill it.
+3. **No MLX TTS / music / compose / avatar port is possible** — these are OM's
+   exclusive value; the MLX repo has nothing to contribute here. Recorded as a
+   negative so no future goal chases it.
+
+## 8. Seams, gaps, and what I'd touch first
+
+Verified gaps (from the post-image sweep):
+
+1. **LUFS target mismatch** — `audio_mixer` hard-codes `I=-16` (podcast/Apple);
+   `sound-design.md` targets `-14` for YouTube. The mixer doesn't parameterize
+   it. Either make the target a `edit_decisions.metadata.loudnorm_target` field
+   or align the docs.
+2. **Ducking schema drift** — `edit_decisions` declares
+   `threshold_db`/`reduction_db`; `audio_mixer._duck` consumes
+   `music_volume_during_speech` + fixed `threshold=0.02`/`ratio=9`. No
+   translation step. The declarative intent and the executed params diverge
+   silently.
+3. **Seedance dedup race** — `seedance_video` (fal) and `seedance_replicate`
+   share `provider="seedance"`; `_select_best_tool` keys `tool_by_provider` by
+   provider string (`video_selector.py:267-270`), so the second-registered is
+   invisible to the selector.
+4. **`cogvideo-2b` i2v mismatch** — `_shared.py:122-136` declares the 2B variant
+   `i2v: False`, but `cogvideo_video` advertises `image_to_video` +
+   `reference_image: True` unconditionally; the variant flag is never consulted.
+5. **`preferred_provider` has no score-gap gate** — `video_selector.py:272-277`
+   returns the preferred provider on the first ranking match regardless of how
+   much lower its score is than the top (comment claims "unless drastically
+   worse").
+6. **`grok_video` has no `quality_score`** — every other premium provider sets
+   0.9–0.95; grok (lip_sync + native_audio) is scored only on supports/stability,
+   likely under-ranked.
+7. **`video_selector.fallback_tools` appends `image_selector` unconditionally**
+   (`:145`) — the motion-required prohibition lives in director skills, not in
+   the selector; a direct caller (no director) can silently fall back to an image
+   tool for a motion-required brief.
+8. **`force_instrumental` mandate never sent** — `music-gen-usage.md:14` says
+   "always set `force_instrumental=true`"; `music_gen.py` never sets it.
+9. **`music_library` has no mood/BPM/genre/license metadata** — selection is by
+   filename + duration; the BPM-driven selection the skills assume is impossible
+   on the local library.
+10. **Missing tests** — no `tests/qa/test_02_image_gen.py` (carried from
+    story→image review) **and** no video tests (`ls tests | grep video` empty);
+    provider routing/`estimate_cost`/`estimate_runtime` entirely untested.
+11. **`.env.example` drift** — missing `REPLICATE_API_TOKEN`,
+    `HIGGSFIELD_API_KEY`/`_SECRET`/`HIGGSFIELD_KEY`, and the `FAL_AI_API_KEY`
+    alias (only `FAL_KEY` listed).
+12. **Faceswap orphan (refined)** — still no local tool; the skill is HeyGen-API-
+    backed. Either add `tools/avatar/faceswap.py` wrapping the HeyGen workflow
+    (MLX repo has `image faceswap` for a local option), reclassify as
+    `heygen-faceswap`, or remove.
+13. **`asset_manifest` has no music/avatar structured fields** — no `bpm`/`mood`/
+    `loop_points` for music; no avatar-specific field (clip is generic
+    `type:"video"`). `additionalProperties: false` blocks ad-hoc fields.
+
+**What I'd land first:** the **`mlx_video` provider** (LTX-2.3 i2v, future-plan
+F2). It is the single change that (a) gives OM an Apple-Silicon-native i2v path —
+the gap its CUDA-only locals leave on every MPS box — (b) is auto-discovered by
+`video_selector` with zero selector edits, (c) costs `$0` (scorer rewards), and
+(d) is the motion analog of the story→image review's `mlx_image` (F1). Together
+F1+F2 are the first two stitches of the OM-story-front / MLX-native-back seam.
+
+## 9. File reference (image → video / voice only)
+
+```
+# motion generation
+tools/video/video_selector.py                         # THE routing entry point
+tools/video/_shared.py                                # local-provider gating + variant metadata
+tools/video/{wan,hunyuan,ltx_video_local,ltx_video_modal,cogvideo}_video.py   # CUDA locals
+tools/video/{heygen,seedance,seedance_replicate,kling,minimax,veo,runway,higgsfield,grok,comfyui}_video.py
+tools/video/{pexels,pixabay}_video.py                 # stock (SOURCE tier)
+
+# voice / TTS
+tools/audio/tts_selector.py                           # selector (reuses lib/scoring)
+tools/audio/{elevenlabs,openai,google,dashscope,doubao,piper}_tts.py
+skills/meta/voice-performance-director.md             # direction authority
+schemas/artifacts/script.schema.json                  # voice_performance + delivery_cues contract
+
+# music + audio
+tools/audio/{music_gen,suno_music,music_library,freesound_music,pixabay_music}.py
+tools/audio/audio_mixer.py                            # FFmpeg sidechain ducking, -16 LUFS
+skills/creative/{music-gen-usage,sound-design}.md
+schemas/artifacts/proposal_packet.schema.json         # music_source (mandatory by policy)
+
+# compose + runtimes
+tools/video/video_compose.py                          # dispatcher (render_runtime → 3 runtimes)
+tools/video/hyperframes_compose.py                    # HyperFrames sibling
+tools/video/{remotion_caption_burn,video_stitch,video_trimmer}.py
+skills/core/{remotion,hyperframes}.md
+remotion-composer/SCENE_TYPES.md                      # Remotion scene-type catalog
+schemas/artifacts/edit_decisions.schema.json          # render_runtime lock + audio/subtitles/bespoke
+skills/meta/reviewer.md                               # CRITICAL swap/single-runtime findings
+
+# avatar / lip-sync
+tools/avatar/{talking_head,lip_sync}.py               # SadTalker/Wav2Lip (MuseTalk stub)
+pipeline_defs/avatar-spokesperson.yaml
+skills/pipelines/avatar-spokesperson/                 # idea/asset/compose directors + EP pivot
+.agents/skills/{avatar-video,heygen,faceswap,create-video}/   # Layer-3 (all HeyGen-API)
+```
diff --git a/docs/REVIEW-story-to-image.md b/docs/REVIEW-story-to-image.md
new file mode 100644
index 000000000..49b322c8b
--- /dev/null
+++ b/docs/REVIEW-story-to-image.md
@@ -0,0 +1,255 @@
+# Review — Story-Line → Image path in OpenMontage
+
+> Collected 2026-07-06 from a grounded read of the OpenMontage codebase, with a
+> side-by-side against the sibling MLX-on-Apple-Silicon repo
+> (`video_generation__image_workflow` / `python/mlx-movie-director`). Scope: the
+> early pipeline stages that turn an idea/script into image assets. Image →
+> video / voice is deferred to a later pass.
+>
+> Companion to `docs/ARCHITECTURE.md`, `docs/PROVIDERS.md`, and the (now stale)
+> `docs/comfyui-adapter-plan.md`.
+
+## TL;DR
+
+OpenMontage's story→image path is a **clean, instruction-driven contract chain**:
+
+```
+research_brief → proposal_packet → script → scene_plan → asset_manifest
+```
+
+Each stage = a YAML-declared gate + a markdown director skill + one canonical
+JSON artifact (schema-validated). The agent (not Python) drives it. Image
+generation is reached through exactly one entry point — `image_selector` —
+which auto-discovers every `capability="image_generation"` tool and routes by a
+weighted score (`lib/scoring.rank_providers`). Providers are API-first (FLUX via
+fal.ai, OpenAI gpt-image-2, Imagen 4, Grok, Recraft, DashScope) with two local
+options (ComfyUI server, in-process `diffusers`) and two stock (Pexels/Pixabay).
+
+The strongest ideas worth keeping: (1) the **selector-plus-provider** discovery
+seam, (2) the **`shot_language` → `shot_prompt_builder.py`** cinematography
+vocabulary that turns structured enums into prompts, (3) the **playbook as the
+style contract** with `image_prompt_prefix` distilled (never pasted) +
+`consistency_anchors`, (4) the **CHAI pre/critique/post self-review** applied to
+every generation prompt.
+
+The honest gaps: (1) **no ControlNet / inpainting / true img2img** provider
+except Grok's edit mode — the scorer *weights* those `supports` flags but nothing
+advertises them; (2) **two providers share `FAL_KEY`** (flux + recraft) so one
+env-var flips both on, distorting the score; (3) the planned
+`tests/qa/test_02_image_gen.py` was never written; (4) the `.agents/skills/faceswap/`
+Layer-3 skill is **orphaned** — no `faceswap` tool exists in `tools/`.
+
+---
+
+## 1. The chain, stage by stage
+
+Canonical state machine (`AGENT_GUIDE.md:185`):
+
+```
+research → proposal → script → scene_plan → assets → edit → compose
+```
+
+`hybrid` collapses research+proposal into a single `idea` stage producing a
+`brief`. The research-first pipelines (`animated-explainer`, `animation`,
+`cinematic`) produce a richer `research_brief` then a `proposal_packet`.
+
+| Stage | Director skill (explainer) | Canonical artifact | Image-relevant content |
+|---|---|---|---|
+| research | `pipelines/explainer/research-director.md` | `research_brief` | `angles_discovered`, visual inspiration, `landscape.underserved_gaps` |
+| proposal | `pipelines/explainer/proposal-director.md` | `proposal_packet` + `decision_log` | **visual identity designed here** (not picked); playbook chosen/generated; cost estimate; **hard approval gate** |
+| script | `pipelines/explainer/script-director.md` | `script` | `sections[].enhancement_cues` = visual hand-off (`overlay/broll/diagram/stat_card/animation/code_snippet`); density ≥1 per 8–10 s |
+| scene_plan | `pipelines/explainer/scene-director.md` | `scene_plan` | `scenes[].shot_language` + `required_assets[]` (source: generate\|source\|provided\|record) |
+| assets | `pipelines/explainer/asset-director.md` | `asset_manifest` | per-asset `prompt/seed/model/cost_usd/source_tool/scene_id` |
+
+The **proposal** stage is the only hard money gate (`human_approval_default: true`
+everywhere; `AGENT_GUIDE.md:705` "Do not begin asset generation before user
+approval"). The **scene_plan → assets** hand-off is the real story→image
+contract — see §3.
+
+## 2. Image generation tool layer
+
+### 2.1 The selector (single entry point)
+
+`tools/graphics/image_selector.py` — `capability="image_generation"`,
+`provider="selector"`. Auto-discovers providers via
+`registry.get_by_capability("image_generation")` minus itself, so **adding a
+provider = drop a file in `tools/graphics/`, nothing else**. `fallback_tools`
+and `provider_matrix` are runtime properties — no hardcoded list.
+
+Routing (`execute()`, line 166):
+
+1. discover candidates → `_filter_candidates` (custom-workflow eligibility, or
+   edit-capable filter when `generation_mode=="edit"` / source images present);
+2. score with `lib/scoring.rank_providers` — weighted
+   `task_fit·0.30 + output_quality·0.20 + control·0.15 + reliability·0.15 +
+   cost_efficiency·0.10 + latency·0.05 + continuity·0.05`; stock providers
+   penalized ×0.55 when the prompt wants generated visuals;
+3. honor `preferred_provider`, else top-ranked selectable tool;
+4. adapt (rename `prompt`→`query` for stock; strip unsupported passthrough keys
+   with a warning) → `tool.execute(adapted)`;
+5. annotate result with `selected_tool/provider/score/alternatives_considered`
+   **and `selected_tool_agent_skills`** — the Layer-3 bridge the orchestrator
+   loads next.
+
+Supports `operation: "rank"` (score without generating) — useful at preflight.
+
+### 2.2 Concrete providers (`tools/graphics/`)
+
+| tool | provider | runtime | cost | strength | `agent_skills` |
+|---|---|---|---|---|---|
+| `flux_image` | flux | API (fal.ai) | $0.03 dev / $0.05 pro | photoreal workhorse; neg-prompt, seed, custom size | `flux-best-practices`, `bfl-api` |
+| `openai_image` | openai | API | $0.006–0.211/img | text-in-image, complex instructions; `gpt-image-2` | `flux-best-practices` |
+| `google_imagen` | google_imagen | API (AI Studio / Vertex) | $0.02–0.06 | aspect-ratio based, no exact px/seed | — |
+| `grok_image` | grok | API (xAI) | ~$0.02/out + $0.002/in img | **only true i2i edit / style transfer / multi-image composite**; `supports.image_edit=True` | `grok-media` |
+| `recraft_image` | recraft | API (fal.ai) | $0.04–0.25 | **SVG vector**, text render, brand palette | — |
+| `dashscope_image` | dashscope | API (Alibaba) | $0.02/img | Qwen-Image; zh prompts; n≤6; fallback `grok→openai→flux→recraft` | `dashscope` |
+| `comfyui_image` | comfyui | LOCAL_GPU | free | **custom `workflow_json`/`output_node`**; bundled FLUX2 NVFP4; DEGRADED+`missing_models` payload when models absent; fallback `flux→local_diffusion→openai` | `comfyui`, `flux-best-practices` |
+| `local_diffusion` | local_diffusion | LOCAL_GPU | free | offline/air-gapped `diffusers` SD 2.1 base | — |
+| `pexels_image` / `pixabay_image` | pexels / pixabay | API | free | stock; `query` not `prompt` | — |
+| `image_gen` | multi | HYBRID | varies | **DEPRECATED** (`best_for` literally says "prefer image_selector"); still discoverable | — |
+
+Related graphics producers are a **different** capability family (`"graphics"`,
+not routed by the selector): `diagram_gen` (Mermaid), `code_snippet` (Pygments),
+`math_animate` (ManimCE). Image transform/enhance lives in `tools/enhancement/`:
+`upscale` (Real-ESRGAN), `face_restore` (CodeFormer/GFPGAN), `bg_remove` (rembg),
+`color_grade` / `face_enhance` (FFmpeg), `eye_enhance` (MediaPipe).
+
+### 2.3 Cost governance
+
+`tools/cost_tracker.py` — `estimate → reserve → reconcile` to `cost_log.json`,
+with `single_action_approval_usd=$0.50`, `require_approval_for_new_paid_tool`,
+and a `CAP` mode with a 10% reserve holdback. `estimate_from_reference()` does
+pacing-aware estimation from a `VideoAnalysisBrief` (scenes from cuts/min, ×1.3
+retry buffer).
+
+## 3. The story→image contract (scene_plan ↔ asset_manifest)
+
+Encoded in three places, all schema-backed:
+
+**(a) `scene_plan.scenes[].required_assets[]`** —
+`{type, description, source}`. Any `source: "generate"` becomes an
+asset-director task. This is the explicit "make an image for this" instruction.
+
+**(b) `scene_plan.scenes[].shot_language`** — the structured cinematography
+vocabulary (`shot_size`, `camera_movement`, `lens_mm`, `lighting_key`,
+`depth_of_field`, `color_temperature`) + `texture_keywords`. Converted to a
+prompt by `lib/shot_prompt_builder.py` using a **5-layer framework**
+(Camera → Movement → Subject → Lighting → Style) with enum→phrase maps
+(`extreme_wide → "extreme wide shot showing vast environment"`, `dolly_in → …`,
+`orbital → …`). `build_shot_prompt` / `build_batch_prompts` are the API.
+
+**(c) The asset-director's prompt recipe** (`asset-director.md:108–119`):
+build each prompt from (1) the scene's shot/intent/texture cues, (2) an
+**adapted** visual anchor from the playbook (**never** the verbatim
+`image_prompt_prefix`), (3) the concrete subject/action/environment; add the
+playbook negative prompt; include `consistency_anchors` without copy-pasting;
+generate via `image_selector`; verify file exists; max 2 retries with prompt
+refinement. Every prompt runs through a **CHAI pre/critique/post self-review**
+before send, logged in asset metadata.
+
+**Back-validation:** `asset_manifest.assets[]` must carry `scene_id`,
+`source_tool`, `prompt`, `seed`, `model` — every image traceable to the scene
+that requested it. Manifest success criterion: "all file paths resolve."
+
+## 4. The playbook as style contract
+
+`schemas/styles/playbook.schema.json` (v2). Image-relevant sections:
+
+```yaml
+asset_generation:
+  image_prompt_prefix: "..."        # distilled into an anchor, NOT pasted
+  image_negative_prompt: "..."
+  diagram_style: "..."
+  consistency_anchors: [...]        # minItems 1 — what MUST stay consistent
+visual_language:
+  color_palette: {primary[], accent[], background, text, muted}
+  chart_palette: [...]              # v2
+  color_rules: {harmony_type, WCAG contrast, colorblind-safe}   # v2
+```
+
+Flow: manifest declares `compatible_playbooks` → proposal-director designs a
+visual identity (and may generate a custom playbook via
+`lib/playbook_generator.py`, recording `production_plan.playbook` + a
+`playbook_selection` decision) → scene-director validates every scene against
+the playbook (colors enforced, transitions/pacing rules) → asset-director folds
+`image_prompt_prefix`/neg-prompt/anchors into per-scene prompts via
+`shot_prompt_builder`. v2 `overrides` allow per-scene exceptions capped at
+`max_deviation_ratio: 0.2` (a "20% deviation budget").
+
+## 5. Side-by-side vs the MLX repo
+
+The MLX repo (`python/mlx-movie-director/run.py`) is the **inverse** of
+OpenMontage in one dimension: it is a **single generation runtime** (native MLX
+on Apple Silicon) with no orchestration/story layer; OpenMontage is **all
+orchestration/story** with no native generation (every provider is a cloud API
+or a vendored ComfyUI). They are nearly complementary.
+
+| Concern | OpenMontage | MLX repo (`run.py`) | Map |
+|---|---|---|---|
+| Orchestration / story | YAML manifests + director skills + schema artifacts | none | OM is the front; MLX is a backend |
+| Image gen entry | `image_selector` (scored) | `image t2i` (+ angle/i2i/faceswap/quality/…) | OM selector → MLX adapter |
+| Providers | fal/OpenAI/Google/Grok/Recraft/DashScope + ComfyUI + diffusers | Z-Image, Flux2 Klein, Lens (all MLX) | MLX = one more provider |
+| ControlNet / i2i / regional | **gap** (only Grok edit) | full: controlnet, i2i pose/style, regional attn, faceswap | MLX fills OM's biggest hole |
+| LoRA | none | import-lora-image, multi-LoRA, anime2real | OM has no LoRA story at all |
+| Upscale / restore | Real-ESRGAN, CodeFormer, GFPGAN (torch) | ESRGAN (torch via vision-venv), SeedVR2 | overlap |
+| Visual QA | planned `test_02_image_gen.py` (**missing**) | `caption` (Qwen3-VL), CLIP `video_understand` | MLX already has the QA brain |
+| Prompt vocabulary | `shot_prompt_builder` 5-layer cinematography | prompt-only (no structured shot language) | OM's builder is portable |
+
+**The mapping opportunity is concrete:** a new `mlx_image` provider tool in
+`tools/graphics/` (capability `image_generation`, runtime `LOCAL_GPU`, cost
+`0.0`, `agent_skills: ["mlx-movie-director"]`) that shells to
+`python/mlx-movie-director/run.py image t2i|i2i|faceswap|...` would (a) be
+auto-discovered by `image_selector` with zero selector edits, (b) give OM a
+free ControlNet/i2i/LoRA/faceswap path it currently lacks, (c) be the cheapest
+provider on the box (cost_efficiency bonus in the scorer). The selector's
+`custom_workflow` + `output_node` machinery (already proven for `comfyui_image`)
+is the template — `run.py` is structurally a custom-workflow backend.
+
+## 6. Seams, gaps, and what I'd touch first
+
+Verified gaps (from the tool-layer sweep):
+
+1. **No ControlNet / inpainting / true img2img** — the scorer's `control`
+   dimension weights `controlnet`/`inpainting`/`img2img`/`reference_image`
+   `supports` flags, but only `grok_image` advertises `image_edit`. The MLX
+   repo has all of these; a `mlx_image` provider closes it.
+2. **Orphaned `faceswap` skill** — `.agents/skills/faceswap/` exists, but no
+   `tools/**/faceswap*.py` does. Either add the tool (MLX repo has
+   `image faceswap`) or remove the skill.
+3. **`FAL_KEY` shared by `flux_image` + `recraft_image`** — one env var lights
+   both up; the scorer then ranks between them on `best_for` prose alone.
+   Split or document.
+4. **`image_gen` (deprecated) still discoverable** — appears under
+   `provider="multi"` in `provider_menu` unless filtered; `best_for` steers the
+   scorer off it, but it is not hard-excluded.
+5. **`test_02_image_gen.py` missing** — called out in `tests/qa/QA_PLAN.md`,
+   never on disk. The image QA lane is unwritten.
+6. **No `schemas/tools/*.schema.json` for image tools** — contracts live only
+   inline on the class (`input_schema`/`output_schema`); fine, but inconsistent
+   with `video_stitch.schema.json`.
+
+What I'd land first (smallest high-value step): the **`mlx_image` provider**.
+It is the single change that (a) fills OM's ControlNet/i2i/LoRA gap, (b) gives
+the MLX repo a real story/orchestration front-end, and (c) costs $0 — which the
+scorer rewards. The selector pattern means it is a one-file add; the
+`comfyui_image` custom-workflow path is the structural twin.
+
+## 7. File reference (story→image only)
+
+```
+pipeline_defs/{animated-explainer,animation,cinematic,hybrid}.yaml
+skills/pipelines/explainer/{idea,proposal,script,scene,asset}-director.md
+skills/pipelines/animation/asset-director.md            # image-animation multi-image workflow
+schemas/artifacts/{brief,research_brief,script,scene_plan,asset_manifest}.schema.json
+schemas/styles/playbook.schema.json
+styles/{clean-professional,flat-motion-graphics,minimalist-diagram,anime-ghibli}.yaml
+tools/graphics/image_selector.py                         # THE routing entry point
+tools/graphics/{flux,openai,google_imagen,grok,recraft,dashscope,comfyui,local_diffusion,pexels,pixabay}_image.py
+tools/enhancement/{upscale,face_restore,bg_remove,color_grade,face_enhance,eye_enhance}.py
+lib/shot_prompt_builder.py                               # shot_language → prompt
+lib/scoring.py                                           # rank_providers weighted score
+lib/playbook_generator.py                                # custom playbook synthesis
+styles/playbook_loader.py                                # load + validate
+skills/creative/{image-gen-usage,image-provider-usage}.md
+.agents/skills/{flux-best-practices,bfl-api,grok-media,dashscope,comfyui}/   # Layer 3
+```
diff --git a/tests/tools/test_mlx_image.py b/tests/tools/test_mlx_image.py
new file mode 100644
index 000000000..11955ce48
--- /dev/null
+++ b/tests/tools/test_mlx_image.py
@@ -0,0 +1,310 @@
+"""Regression tests for the mlx_image provider.
+
+Locks the contract that ``mlx_image`` is auto-discovered by ``image_selector``
+with zero selector edits, advertises the full ControlNet / i2i / LoRA / faceswap
+surface (the gap it fills — see docs/REVIEW-story-to-image.md §6.1 and
+docs/REVIEW-image-to-video-voice.md §7), and maps inputs to the ``run.py image``
+CLI correctly without spawning the runtime.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import types
+from pathlib import Path
+
+import pytest
+
+from tools.graphics.mlx_image import MLXImage, _JSON_SUMMARY_RE
+from tools.base_tool import ToolStatus
+
+
+# --------------------------------------------------------------------------
+# Registration + capability surface
+# --------------------------------------------------------------------------
+
+def test_registers_as_image_generation_provider():
+    tool = MLXImage()
+    assert tool.capability == "image_generation"
+    assert tool.provider == "mlx"
+    assert tool.name == "mlx_image"
+    assert tool.runtime.value in ("LOCAL_GPU", "local_gpu")
+
+
+def test_advertises_full_control_surface():
+    """The whole point of mlx_image: cover the surface no other provider does."""
+    tool = MLXImage()
+    for flag in ("controlnet", "img2img", "reference_image", "faceswap", "lora", "multi_lora"):
+        assert tool.supports.get(flag) is True, f"mlx_image must advertise supports.{flag}"
+
+
+def test_cost_is_zero():
+    assert MLXImage().estimate_cost({"prompt": "x"}) == 0.0
+
+
+def test_agent_skill_bridge_present():
+    """The Layer-3 skill dir the orchestrator loads must be declared."""
+    assert MLXImage().agent_skills == ["mlx-movie-director"]
+
+
+# --------------------------------------------------------------------------
+# image_selector discovers it with ZERO selector edits
+# --------------------------------------------------------------------------
+
+def test_image_selector_discovers_mlx_image():
+    from tools.tool_registry import registry
+    registry.ensure_discovered()
+    selector = next(
+        t for t in registry.get_by_capability("image_generation")
+        if t.name == "image_selector"
+    )
+    candidates = selector._providers()
+    assert any(t.name == "mlx_image" for t in candidates), (
+        "mlx_image must be auto-discovered by image_selector — adding the file "
+        "required no selector edit. If this fails, the discovery seam is broken."
+    )
+
+
+def test_mlx_image_survives_edit_mode_filter():
+    """An i2i/controlnet/faceswap scene (image_path present) must keep mlx_image."""
+    from tools.tool_registry import registry
+    registry.ensure_discovered()
+    selector = next(
+        t for t in registry.get_by_capability("image_generation")
+        if t.name == "image_selector"
+    )
+    candidates = selector._providers()
+    filtered = selector._filter_candidates({"prompt": "x", "image_path": "x.png"}, candidates)
+    assert any(t.name == "mlx_image" for t in filtered)
+
+
+# --------------------------------------------------------------------------
+# Availability gate (no subprocess — pure filesystem)
+# --------------------------------------------------------------------------
+
+def test_status_unavailable_when_env_unset(monkeypatch):
+    monkeypatch.delenv("MLX_MOVIE_DIRECTOR_DIR", raising=False)
+    monkeypatch.delenv("MLX_VENV_PYTHON", raising=False)
+    env = MLXImage._resolve_env()
+    assert env["ok"] is False
+    assert "MLX_MOVIE_DIRECTOR_DIR" in env["reason"]
+    assert MLXImage().get_status() == ToolStatus.UNAVAILABLE
+
+
+def test_status_unavailable_when_venv_missing(monkeypatch, tmp_path):
+    """Env dir + run.py present but venv absent → UNAVAILABLE with recreate hint."""
+    mlx_dir = tmp_path / "mlx_repo"
+    (mlx_dir / "python" / "mlx-movie-director").mkdir(parents=True)
+    (mlx_dir / "python" / "mlx-movie-director" / "run.py").write_text("# stub")
+    monkeypatch.setenv("MLX_MOVIE_DIRECTOR_DIR", str(mlx_dir))
+    monkeypatch.delenv("MLX_VENV_PYTHON", raising=False)
+    env = MLXImage._resolve_env()
+    assert env["ok"] is False
+    assert "venv" in env["reason"].lower()
+    assert "uv venv" in env["reason"]
+
+
+def test_status_available_with_full_env(monkeypatch, tmp_path):
+    """arm64 + run.py + venv python + model subdirs → AVAILABLE."""
+    mlx_dir = tmp_path / "mlx_repo"
+    (mlx_dir / "python" / "mlx-movie-director").mkdir(parents=True)
+    (mlx_dir / "python" / "mlx-movie-director" / "run.py").write_text("# stub")
+    venv_py = mlx_dir / "python" / "venv" / "bin" / "python"
+    venv_py.parent.mkdir(parents=True)
+    venv_py.write_text("#!/bin/sh\nexit 0\n")
+    venv_py.chmod(0o755)
+    for sub in ("transformer", "vae"):
+        (mlx_dir / "mlx-models" / sub).mkdir(parents=True)
+    monkeypatch.setenv("MLX_MOVIE_DIRECTOR_DIR", str(mlx_dir))
+    monkeypatch.delenv("MLX_VENV_PYTHON", raising=False)
+    env = MLXImage._resolve_env()
+    assert env["ok"] is True, env.get("reason")
+    # arm64 is required — skip the status assertion on non-Apple-Silicon CI.
+    if env["arm64"]:
+        assert MLXImage().get_status() == ToolStatus.AVAILABLE
+
+
+# --------------------------------------------------------------------------
+# Action routing + CLI argument building (no subprocess)
+# --------------------------------------------------------------------------
+
+@pytest.mark.parametrize(
+    "inputs, expected_action",
+    [
+        ({"prompt": "a cat"}, "t2i"),
+        ({"prompt": "edit", "image": "x.png"}, "i2i"),
+        ({"prompt": "edit", "image_path": "x.png"}, "i2i"),
+        ({"prompt": "pose", "image": "x.png", "controlnet_type": "pose"}, "controlnet"),
+        ({"prompt": "swap", "image": "body.png", "face": "src.png"}, "faceswap"),
+    ],
+)
+def test_action_routing(inputs, expected_action):
+    action, _ = MLXImage._resolve_action(inputs)
+    assert action == expected_action
+
+
+def test_t2i_arg_building():
+    args = MLXImage._build_args(
+        {"prompt": "a cat", "width": 1024, "height": 768, "seed": 42, "pipeline": "zimage"},
+        [],
+    )
+    assert args == ["--prompt", "a cat", "--width", "1024", "--height", "768",
+                    "--seed", "42", "--pipeline", "zimage"]
+
+
+def test_i2i_uses_input_image_flag():
+    """run.py i2i/controlnet read --input-image, not --input."""
+    args = MLXImage._build_args(
+        {"prompt": "oil", "image": "a.jpg", "denoise_strength": 0.5}, []
+    )
+    assert "--input-image" in args and "a.jpg" in args
+    assert "--input " not in " ".join(args)  # no bare --input for i2i
+
+
+def test_faceswap_uses_input_and_face_flags():
+    args = MLXImage._build_args(
+        {"prompt": "p", "image": "body.png", "face": "src.png", "face_mode": "head"}, []
+    )
+    joined = " ".join(args)
+    assert "--input body.png" in joined
+    assert "--face src.png" in joined
+    assert "--mode head" in joined
+
+
+def test_lora_paths_paired_with_scales():
+    args = MLXImage._build_args(
+        {"prompt": "p",
+         "lora_path": ["a.safetensors", "b.safetensors"],
+         "lora_scale": [0.7, 0.4]},
+        [],
+    )
+    # Each path must be immediately followed by its scale.
+    assert args == ["--prompt", "p",
+                    "--lora-path", "a.safetensors", "--lora-scale", "0.7",
+                    "--lora-path", "b.safetensors", "--lora-scale", "0.4"]
+
+
+def test_lora_scale_mismatch_rejected():
+    from tools.graphics.mlx_image import _BadInput
+    with pytest.raises(_BadInput):
+        MLXImage._build_args(
+            {"prompt": "p",
+             "lora_path": ["a.safetensors", "b.safetensors"],
+             "lora_scale": [0.7]},  # wrong count
+            [],
+        )
+
+
+# --------------------------------------------------------------------------
+# execute() — error paths + output parsing (subprocess mocked)
+# --------------------------------------------------------------------------
+
+def test_execute_returns_error_when_env_unset(monkeypatch):
+    monkeypatch.delenv("MLX_MOVIE_DIRECTOR_DIR", raising=False)
+    result = MLXImage().execute({"prompt": "a cat"})
+    assert result.success is False
+    assert "MLX_MOVIE_DIRECTOR_DIR" in result.error
+
+
+def test_parse_outputs_prefers_json_summary(monkeypatch, tmp_path):
+    img = tmp_path / "out.png"
+    img.write_bytes(b"\x89PNG")
+    payload = json.dumps({"outputs": [str(img)], "status": "ok"})
+    stdout = f"some log\nJSON_SUMMARY:{payload}\n"
+    outs = MLXImage._parse_outputs(stdout, str(tmp_path))
+    assert outs == [str(img)]
+
+
+def test_parse_outputs_falls_back_to_dir_scan(tmp_path):
+    """If no JSON_SUMMARY line, pick the newest image in the gen-output-dir."""
+    import os, time
+    older = tmp_path / "a.png"; older.write_bytes(b"x")
+    newer = tmp_path / "b.png"; newer.write_bytes(b"x")
+    # ensure newer mtime > older mtime
+    os.utime(older, (time.time() - 10, time.time() - 10))
+    outs = MLXImage._parse_outputs("", str(tmp_path))
+    # Returns all images newest-first; the newest (b.png) must lead.
+    assert outs and outs[0] == str(newer)
+    assert str(older) in outs
+
+
+def test_execute_success_path(monkeypatch, tmp_path):
+    """Full execute() with the run.py subprocess mocked to emit a JSON summary."""
+    # Stage a fake but complete MLX env.
+    mlx_dir = tmp_path / "mlx_repo"
+    run_py = mlx_dir / "python" / "mlx-movie-director" / "run.py"
+    run_py.parent.mkdir(parents=True)
+    run_py.write_text("# stub")
+    venv_py = mlx_dir / "python" / "venv" / "bin" / "python"
+    venv_py.parent.mkdir(parents=True)
+    venv_py.write_text("#!/bin/sh\nexit 0\n")
+    venv_py.chmod(0o755)
+    (mlx_dir / "mlx-models" / "transformer").mkdir(parents=True)
+    (mlx_dir / "mlx-models" / "vae").mkdir(parents=True)
+    monkeypatch.setenv("MLX_MOVIE_DIRECTOR_DIR", str(mlx_dir))
+    monkeypatch.delenv("MLX_VENV_PYTHON", raising=False)
+
+    if not MLXImage._resolve_env()["arm64"]:
+        pytest.skip("Apple-Silicon-only fixture (the gate requires arm64)")
+
+    # The image the fake run.py "produces".
+    produced = tmp_path / "generated.png"
+    produced.write_bytes(b"\x89PNG")
+
+    fake_proc = types.SimpleNamespace(
+        returncode=0,
+        stdout=f"JSON_SUMMARY:{json.dumps({'outputs': [str(produced)]})}\n",
+        stderr="",
+    )
+
+    captured: dict = {}
+
+    def fake_run(cmd, **kwargs):
+        captured["cmd"] = cmd
+        return fake_proc
+
+    monkeypatch.setattr("tools.graphics.mlx_image.subprocess.run", fake_run)
+
+    out_path = tmp_path / "final" / "result.png"
+    result = MLXImage().execute({
+        "prompt": "a cat", "seed": 42, "pipeline": "zimage", "output_path": str(out_path),
+    })
+
+    assert result.success is True, result.error
+    assert result.data["provider"] == "mlx"
+    assert result.data["model"] == "mlx-zimage"
+    assert result.data["action"] == "t2i"
+    assert result.data["seed"] == 42
+    assert result.cost_usd == 0.0
+    assert out_path.exists()  # copied to the requested output_path
+    # The command invoked run.py with the image action + json-summary.
+    assert "image" in captured["cmd"] and "t2i" in captured["cmd"]
+    assert "--gen-output-dir" in captured["cmd"] and "--json-summary" in captured["cmd"]
+    assert "--seed" in captured["cmd"]
+
+
+def test_execute_nonzero_exit_returns_failure(monkeypatch, tmp_path):
+    mlx_dir = tmp_path / "mlx_repo"
+    run_py = mlx_dir / "python" / "mlx-movie-director" / "run.py"
+    run_py.parent.mkdir(parents=True)
+    run_py.write_text("# stub")
+    venv_py = mlx_dir / "python" / "venv" / "bin" / "python"
+    venv_py.parent.mkdir(parents=True)
+    venv_py.write_text("#!/bin/sh\nexit 0\n")
+    venv_py.chmod(0o755)
+    (mlx_dir / "mlx-models" / "transformer").mkdir(parents=True)
+    (mlx_dir / "mlx-models" / "vae").mkdir(parents=True)
+    monkeypatch.setenv("MLX_MOVIE_DIRECTOR_DIR", str(mlx_dir))
+    monkeypatch.delenv("MLX_VENV_PYTHON", raising=False)
+    if not MLXImage._resolve_env()["arm64"]:
+        pytest.skip("Apple-Silicon-only fixture")
+
+    monkeypatch.setattr(
+        "tools.graphics.mlx_image.subprocess.run",
+        lambda cmd, **k: types.SimpleNamespace(returncode=1, stdout="", stderr="boom"),
+    )
+    result = MLXImage().execute({"prompt": "a cat"})
+    assert result.success is False
+    assert "run.py exited 1" in result.error
+    assert "boom" in result.error
diff --git a/tools/graphics/mlx_image.py b/tools/graphics/mlx_image.py
new file mode 100644
index 000000000..bcf01f02a
--- /dev/null
+++ b/tools/graphics/mlx_image.py
@@ -0,0 +1,535 @@
+"""MLX image generation via the sibling ``mlx-movie-director`` runtime.
+
+Bridges OpenMontage's image-generation capability to the Apple-Silicon-native
+MLX pipeline (``python/mlx-movie-director/run.py`` — Z-Image / Flux2 Klein /
+Lens, plus ControlNet, i2i, LoRA, faceswap). This is the provider that fills
+OpenMontage's biggest verified gap: a local, ``$0`` path that advertises
+``controlnet`` / ``img2img`` / ``reference_image`` / ``faceswap`` / ``lora``,
+which today only Grok's edit mode partially covers.
+
+Like ``comfyui_image``, this provider shells out to an external generator and
+reads the result back. The contract:
+
+* ``MLX_MOVIE_DIRECTOR_DIR``  — repo root containing ``python/mlx-movie-director/run.py``.
+* ``MLX_VENV_PYTHON``         — the MLX venv interpreter (default
+  ``<MLX_MOVIE_DIRECTOR_DIR>/python/venv/bin/python``). Per the MLX repo's
+  CLAUDE.md, this venv is per-machine and NOT auto-created; on a fresh clone it
+  is absent and must be recreated
+  (``uv venv python/venv --python 3.12 && uv pip install -r .../requirements.txt --python ...``).
+
+Discovery is automatic — ``image_selector`` picks up any
+``capability="image_generation"`` tool, so adding this file required zero
+selector edits. See ``docs/REVIEW-story-to-image.md`` §2.1 and
+``docs/REVIEW-image-to-video-voice.md`` §7.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import re
+import shutil
+import subprocess
+import tempfile
+import time
+from pathlib import Path
+from typing import Any
+
+from tools.base_tool import (
+    BaseTool,
+    Determinism,
+    ExecutionMode,
+    ResourceProfile,
+    RetryPolicy,
+    ToolResult,
+    ToolRuntime,
+    ToolStability,
+    ToolStatus,
+    ToolTier,
+)
+
+# Where the MLX repo lives. Configured by the OM deployment; the provider is
+# UNAVAILABLE without it (we do not guess a sibling path — explicit config only).
+_MLX_DIR_ENV = "MLX_MOVIE_DIRECTOR_DIR"
+_MLX_PYTHON_ENV = "MLX_VENV_PYTHON"
+
+# Relative layout inside the MLX repo (stable per the MLX repo's CLAUDE.md).
+_RUN_PY_REL = "python/mlx-movie-director/run.py"
+_VENV_PYTHON_REL = "python/venv/bin/python"
+_MODELS_REL = "mlx-models"
+
+# Subdirectories under mlx-models/ whose presence implies at least one usable
+# image-generation model is staged. transformer + vae are the minimum stack.
+_REQUIRED_MODEL_SUBDIRS = ("transformer", "vae")
+
+# The stdout marker emitted by `run.py ... --json-summary` (see
+# app/commands/_shared.py:681 — execute_generation prints "JSON_SUMMARY:{...}").
+_JSON_SUMMARY_RE = re.compile(r"JSON_SUMMARY:(\{.*\})\s*$", re.MULTILINE)
+
+
+class MLXImage(BaseTool):
+    name = "mlx_image"
+    version = "0.1.0"
+    tier = ToolTier.GENERATE
+    capability = "image_generation"
+    provider = "mlx"
+    stability = ToolStability.EXPERIMENTAL
+    execution_mode = ExecutionMode.SYNC
+    determinism = Determinism.SEEDED
+    runtime = ToolRuntime.LOCAL_GPU
+
+    dependencies = []  # resolved at runtime via _resolve_env()
+    install_instructions = (
+        "Set MLX_MOVIE_DIRECTOR_DIR to the mlx-movie-director repo root "
+        "(contains python/mlx-movie-director/run.py).\n"
+        "Optionally set MLX_VENV_PYTHON to its venv interpreter (default "
+        "<MLX_MOVIE_DIRECTOR_DIR>/python/venv/bin/python).\n"
+        "The MLX venv is per-machine and NOT auto-created — recreate it with:\n"
+        "  uv venv python/venv --python 3.12\n"
+        "  uv pip install -r python/mlx-movie-director/requirements.txt "
+        "--python python/venv/bin/python\n"
+        "Plus two runtime deps not yet in that requirements.txt (tracked as an "
+        "upstream MLX-repo gap): opencv-python (image-quality imports cv2) and "
+        "mflux (the Z-Image VAE loader). Install both into the same venv.\n"
+        "Requires Apple Silicon (arm64)."
+    )
+    agent_skills = ["mlx-movie-director"]
+
+    capabilities = [
+        "text_to_image",
+        "image_to_image",
+        "controlnet",
+        "faceswap",
+        "provider_selection",
+    ]
+    # These feed the scorer's `control` dimension — today only grok_image
+    # advertises image_edit, so mlx_image is the first provider to cover the
+    # full ControlNet / i2i / LoRA / faceswap surface (see REVIEW-story-to-image §6.1).
+    supports = {
+        "seed": True,
+        "custom_size": True,
+        "controlnet": True,
+        "img2img": True,
+        "image_edit": True,
+        "reference_image": True,
+        "faceswap": True,
+        "lora": True,
+        "multi_lora": True,
+        "offline": True,
+    }
+    best_for = [
+        "local Apple Silicon image generation with no API cost",
+        "ControlNet-conditioned generation (pose / depth / region)",
+        "true image-to-image edit and inpainting (denoise-strength controlled)",
+        "LoRA / multi-LoRA character and style conditioning",
+        "BFS face / head swap",
+    ]
+    not_good_for = [
+        "non-Apple-Silicon hosts (no CUDA / no MPS)",
+        "setups without the MLX venv recreated (see install_instructions)",
+    ]
+    # No `negative_prompt` here on purpose: run.py image t2i has no
+    # --negative-prompt flag (Z-Image handles negatives internally). The
+    # selector strips unsupported passthrough keys, so omitting it is correct.
+    fallback = "flux_image"
+    fallback_tools = ["comfyui_image", "flux_image", "local_diffusion", "openai_image"]
+
+    input_schema = {
+        "type": "object",
+        "required": ["prompt"],
+        "properties": {
+            "prompt": {"type": "string", "description": "Text prompt for image generation."},
+            "width": {"type": "integer", "description": "Image width in pixels."},
+            "height": {"type": "integer", "description": "Image height in pixels."},
+            "resolution": {
+                "type": "string",
+                "description": (
+                    "Resolution tier or explicit WxH passed through to run.py "
+                    "('--resolution'). One of: model (default), benchmark, large, "
+                    "or 'WxH'/'W:H' snapped to a multiple of 16."
+                ),
+            },
+            "steps": {"type": "integer", "description": "Sampling steps (pipeline default if unset)."},
+            "seed": {"type": "integer", "description": "Random seed (default 777)."},
+            "pipeline": {
+                "type": "string",
+                "enum": ["zimage", "flux2-klein", "lens", "auto"],
+                "description": "MLX pipeline family (default zimage).",
+            },
+            "cfg_scale": {"type": "number", "description": "Classifier-free guidance (opt-in; pipeline-dependent)."},
+            # Edit-capable inputs — presence of `image`/`image_path` also makes
+            # image_selector's _filter_candidates pick mlx_image for edit mode.
+            "image": {"type": "string", "description": "Source image path for i2i / controlnet edit."},
+            "image_path": {"type": "string", "description": "Alias of `image` (source image path)."},
+            "reference_image": {
+                "type": "string",
+                "description": "Optional reference image for i2i pose/style conditioning.",
+            },
+            "denoise_strength": {
+                "type": "number",
+                "description": "i2i denoise strength (0–1; higher = more change).",
+            },
+            "controlnet_type": {
+                "type": "string",
+                "description": "ControlNet conditioning type (e.g. 'pose'). Forces the controlnet action.",
+            },
+            "controlnet_strength": {"type": "number", "description": "ControlNet strength (0–1)."},
+            "face": {"type": "string", "description": "Face/head source image for faceswap (with `image` = body)."},
+            "face_mode": {
+                "type": "string",
+                "enum": ["face", "head"],
+                "description": "faceswap mode: 'face' (face only) or 'head' (head + hair).",
+            },
+            "lora_path": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "LoRA .safetensors path(s). Repeatable; paired with lora_scale.",
+            },
+            "lora_scale": {
+                "type": "array",
+                "items": {"type": "number"},
+                "description": "LoRA scale per lora_path entry (same order).",
+            },
+            "output_path": {"type": "string", "description": "Where to save the generated image."},
+        },
+    }
+
+    resource_profile = ResourceProfile(
+        cpu_cores=4, ram_mb=12000, vram_mb=0, disk_mb=500, network_required=False,
+    )
+    retry_policy = RetryPolicy(max_retries=1, retryable_errors=["timeout"])
+    idempotency_key_fields = ["prompt", "width", "height", "steps", "seed", "pipeline"]
+    side_effects = ["spawns python/venv/bin/python run.py image …", "writes image file to output_path"]
+    user_visible_verification = ["Inspect generated image for quality and prompt adherence."]
+
+    # ------------------------------------------------------------------
+    # Environment + availability
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _resolve_env() -> dict[str, Any]:
+        """Resolve MLX repo dir + venv interpreter + presence flags.
+
+        Returns a dict with: mlx_dir, run_py, venv_python, arm64, ok (bool),
+        reason (str when not ok). Pure filesystem checks — no subprocess spawn,
+        so get_status() stays cheap.
+        """
+        mlx_dir = os.environ.get(_MLX_DIR_ENV)
+        arm64 = platform.machine() in ("arm64", "aarch64")
+
+        if not mlx_dir:
+            return {
+                "ok": False,
+                "reason": f"{_MLX_DIR_ENV} is not set (point it at the mlx-movie-director repo root).",
+                "arm64": arm64,
+            }
+        mlx_dir = os.path.expanduser(mlx_dir)
+        run_py = os.path.join(mlx_dir, _RUN_PY_REL)
+        if not os.path.isfile(run_py):
+            return {
+                "ok": False,
+                "reason": f"{_MLX_DIR_ENV}={mlx_dir} has no {_RUN_PY_REL}.",
+                "arm64": arm64,
+                "mlx_dir": mlx_dir,
+            }
+
+        venv_python = os.environ.get(_MLX_PYTHON_ENV) or os.path.join(mlx_dir, _VENV_PYTHON_REL)
+        if not os.path.isfile(venv_python):
+            return {
+                "ok": False,
+                "reason": (
+                    f"MLX venv interpreter not found at {venv_python}. Recreate it: "
+                    f"uv venv {mlx_dir}/python/venv --python 3.12 && "
+                    f"uv pip install -r {mlx_dir}/python/mlx-movie-director/requirements.txt "
+                    f"--python {mlx_dir}/python/venv/bin/python"
+                ),
+                "arm64": arm64,
+                "mlx_dir": mlx_dir,
+                "run_py": run_py,
+            }
+
+        models_dir = os.path.join(mlx_dir, _MODELS_REL)
+        missing_subdirs = [s for s in _REQUIRED_MODEL_SUBDIRS if not os.path.isdir(os.path.join(models_dir, s))]
+        if missing_subdirs:
+            return {
+                "ok": False,
+                "reason": (
+                    f"MLX models incomplete under {models_dir}: missing {missing_subdirs}. "
+                    f"Stage models before use."
+                ),
+                "arm64": arm64,
+                "mlx_dir": mlx_dir,
+                "run_py": run_py,
+                "venv_python": venv_python,
+            }
+
+        if not arm64:
+            return {
+                "ok": False,
+                "reason": f"MLX runs on Apple Silicon only (got {platform.machine()}).",
+                "arm64": False,
+                "mlx_dir": mlx_dir,
+                "run_py": run_py,
+                "venv_python": venv_python,
+            }
+
+        return {
+            "ok": True,
+            "arm64": True,
+            "mlx_dir": mlx_dir,
+            "run_py": run_py,
+            "venv_python": venv_python,
+        }
+
+    def get_status(self) -> ToolStatus:
+        env = self._resolve_env()
+        return ToolStatus.AVAILABLE if env["ok"] else ToolStatus.UNAVAILABLE
+
+    def estimate_cost(self, inputs: dict[str, Any]) -> float:
+        return 0.0
+
+    def estimate_runtime(self, inputs: dict[str, Any]) -> float:
+        # Z-Image ~1.5s/step @ 9 steps; Flux2 Klein ~10s/step @ 4 steps; Lens ~0.4s/step.
+        steps = inputs.get("steps")
+        pipeline = inputs.get("pipeline", "zimage")
+        if steps is None:
+            steps = {"zimage": 9, "flux2-klein": 4, "lens": 20, "auto": 9}.get(pipeline, 9)
+        per_step = {"flux2-klein": 10.0, "lens": 0.4}.get(pipeline, 1.5)
+        return float(steps) * per_step
+
+    def get_info(self) -> dict[str, Any]:
+        info = super().get_info()
+        env = self._resolve_env()
+        info["mlx_env"] = {
+            "configured": env["ok"],
+            "reason": env.get("reason"),
+            "arm64": env.get("arm64"),
+            "mlx_dir": env.get("mlx_dir"),
+            "venv_python": env.get("venv_python"),
+        }
+        return info
+
+    # ------------------------------------------------------------------
+    # Execute
+    # ------------------------------------------------------------------
+
+    def execute(self, inputs: dict[str, Any]) -> ToolResult:
+        env = self._resolve_env()
+        if not env["ok"]:
+            return ToolResult(success=False, error=env["reason"])
+
+        run_py = env["run_py"]
+        venv_python = env["venv_python"]
+
+        action, action_args = self._resolve_action(inputs)
+        cmd = [venv_python, run_py, "image", action]
+
+        try:
+            cmd.extend(self._build_args(inputs, action_args))
+        except _BadInput as exc:
+            return ToolResult(success=False, error=str(exc))
+
+        # Force a deterministic output dir + JSON summary so we can locate the result.
+        out_dir = tempfile.mkdtemp(prefix="mlx_image_")
+        cmd.extend(["--gen-output-dir", out_dir, "--json-summary"])
+
+        start = time.time()
+        try:
+            proc = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=900,
+                check=False,
+            )
+        except subprocess.TimeoutExpired:
+            shutil.rmtree(out_dir, ignore_errors=True)
+            return ToolResult(success=False, error="MLX image generation timed out (>900s).")
+        except Exception as exc:  # pragma: no cover — defensive
+            shutil.rmtree(out_dir, ignore_errors=True)
+            return ToolResult(success=False, error=f"Failed to spawn MLX runtime: {exc}")
+
+        elapsed = round(time.time() - start, 2)
+
+        if proc.returncode != 0:
+            shutil.rmtree(out_dir, ignore_errors=True)
+            tail = (proc.stderr or proc.stdout or "").strip().splitlines()[-12:]
+            return ToolResult(
+                success=False,
+                error=f"run.py exited {proc.returncode}:\n" + "\n".join(tail),
+            )
+
+        outputs = self._parse_outputs(proc.stdout, out_dir)
+        if not outputs:
+            shutil.rmtree(out_dir, ignore_errors=True)
+            tail = (proc.stderr or proc.stdout or "").strip().splitlines()[-12:]
+            return ToolResult(
+                success=False,
+                error="run.py produced no image output:\n" + "\n".join(tail),
+            )
+
+        src = Path(outputs[0])
+        output_path = inputs.get("output_path")
+        final_path = src
+        if output_path:
+            dest = Path(output_path)
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            if dest.resolve() != src.resolve():
+                shutil.copy2(src, dest)
+            final_path = dest
+
+        seed = self._effective_seed(inputs)
+        model = self._model_label(inputs)
+
+        return ToolResult(
+            success=True,
+            data={
+                "provider": "mlx",
+                "model": model,
+                "prompt": inputs["prompt"],
+                "pipeline": inputs.get("pipeline", "zimage"),
+                "action": action,
+                "width": inputs.get("width"),
+                "height": inputs.get("height"),
+                "steps": inputs.get("steps"),
+                "seed": seed,
+                "output": str(final_path),
+                "format": final_path.suffix.lstrip(".") or "png",
+                "mlx_run_py": run_py,
+            },
+            artifacts=[str(final_path)],
+            cost_usd=0.0,
+            duration_seconds=elapsed,
+            seed=seed,
+            model=model,
+        )
+
+    # ------------------------------------------------------------------
+    # Action + argument mapping
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _effective_seed(inputs: dict[str, Any]) -> int:
+        seed = inputs.get("seed")
+        if isinstance(seed, int):
+            return seed
+        return 777  # run.py default (app/commands/_shared.py:296)
+
+    @staticmethod
+    def _model_label(inputs: dict[str, Any]) -> str:
+        pipeline = inputs.get("pipeline", "zimage")
+        transformer = inputs.get("transformer")
+        if transformer:
+            return f"mlx-{pipeline}/{transformer}"
+        return f"mlx-{pipeline}"
+
+    @staticmethod
+    def _resolve_action(inputs: dict[str, Any]) -> tuple[str, list[str]]:
+        """Decide the run.py image action + any action-only flags.
+
+        faceswap wins if both a body image and a face image are present;
+        else controlnet if a controlnet_type / controlnet source is set;
+        else i2i if any source image is present; else t2i.
+        """
+        body_image = inputs.get("image") or inputs.get("image_path")
+        face_image = inputs.get("face")
+
+        if body_image and face_image:
+            return "faceswap", []
+        if inputs.get("controlnet_type") or inputs.get("controlnet_strength") is not None:
+            return "controlnet", []
+        if body_image:
+            return "i2i", []
+        return "t2i", []
+
+    @staticmethod
+    def _build_args(inputs: dict[str, Any], action_args: list[str]) -> list[str]:
+        """Map provider inputs to run.py CLI flags. Raises _BadInput on bad values."""
+        out: list[str] = []
+        prompt = inputs.get("prompt")
+        if not prompt:
+            raise _BadInput("prompt is required.")
+        out += ["--prompt", str(prompt)]
+
+        for key, flag, cast in (
+            ("width", "--width", int),
+            ("height", "--height", int),
+            ("steps", "--steps", int),
+            ("seed", "--seed", int),
+            ("resolution", "--resolution", str),
+            ("pipeline", "--pipeline", str),
+            ("cfg_scale", "--cfg-scale", float),
+            ("denoise_strength", "--denoise-strength", float),
+            ("controlnet_strength", "--controlnet-strength", float),
+        ):
+            if inputs.get(key) is not None:
+                out += [flag, str(cast(inputs[key]))]  # type: ignore[call-arg]
+
+        if inputs.get("controlnet_type"):
+            out += ["--controlnet-type", str(inputs["controlnet_type"])]
+
+        body_image = inputs.get("image") or inputs.get("image_path")
+        face_image = inputs.get("face")
+        action, _ = MLXImage._resolve_action(inputs)
+
+        if action == "faceswap":
+            if not (body_image and face_image):
+                raise _BadInput("faceswap requires both a body image (`image`) and a `face` source.")
+            out += ["--input", str(body_image), "--face", str(face_image)]
+            if inputs.get("face_mode"):
+                out += ["--mode", str(inputs["face_mode"])]
+        elif action in ("i2i", "controlnet"):
+            if not body_image:
+                raise _BadInput(f"{action} requires a source image (`image` or `image_path`).")
+            # run.py i2i/controlnet use --input-image (NOT --input).
+            out += ["--input-image", str(body_image)]
+            if inputs.get("reference_image"):
+                out += ["--reference-image", str(inputs["reference_image"])]
+
+        # LoRA: --lora-path is repeatable, paired with --lora-scale (same order).
+        lora_paths = inputs.get("lora_path") or []
+        lora_scales = inputs.get("lora_scale") or []
+        if lora_paths:
+            if isinstance(lora_paths, str):
+                lora_paths = [lora_paths]
+            if isinstance(lora_scales, (int, float)):
+                lora_scales = [float(lora_scales)]
+            if len(lora_scales) and len(lora_scales) != len(lora_paths):
+                raise _BadInput("lora_scale must have one entry per lora_path (or be omitted).")
+            for i, lp in enumerate(lora_paths):
+                out += ["--lora-path", str(lp)]
+                if i < len(lora_scales):
+                    out += ["--lora-scale", str(lora_scales[i])]
+
+        out += action_args
+        return out
+
+    # ------------------------------------------------------------------
+    # Output parsing
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _parse_outputs(stdout: str, out_dir: str) -> list[str]:
+        """Prefer the JSON_SUMMARY line; fall back to scanning the output dir."""
+        match = _JSON_SUMMARY_RE.search(stdout or "")
+        if match:
+            try:
+                payload = json.loads(match.group(1))
+                outs = payload.get("outputs") or []
+                if isinstance(outs, list):
+                    resolved = [o for o in outs if o and os.path.isfile(str(o))]
+                    if resolved:
+                        return resolved
+            except json.JSONDecodeError:
+                pass
+        # Fallback: newest image under the gen-output-dir.
+        candidates: list[Path] = []
+        for ext in ("*.png", "*.jpg", "*.jpeg", "*.webp"):
+            candidates.extend(Path(out_dir).glob(ext))
+        candidates.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+        return [str(p) for p in candidates]
+
+
+class _BadInput(Exception):
+    """Raised when provider inputs cannot map cleanly to run.py flags."""

From 79897cb18091903240bb3f9fd1eee8b77003f7cd Mon Sep 17 00:00:00 2001
From: Ziyu Huang <ziyu4huang@gmail.com>
Date: Mon, 6 Jul 2026 22:18:28 +0800
Subject: [PATCH 2/5] =?UTF-8?q?feat(video):=20mlx=5Fvideo=20provider=20?=
 =?UTF-8?q?=E2=80=94=20LTX-2.3=20motion=20analog=20of=20mlx=5Fimage?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The motion stitch of the OM↔MLX seam. `mlx_video` wraps LTX-2.3 22B
(`run.py video generate` / `video t2i2v`) and is auto-discovered by
`video_selector` with zero selector edits.

Refined value (REVIEW-image-to-video-voice §7): OM's four $0 local i2v
providers (wan/hunyuan/ltx/cogvideo) need CUDA diffusers and don't run on
Apple Silicon. MLX LTX-2.3 is the MPS-native i2v/t2v path — a free offline
local default, NOT a premium-cinema replacement (deliberately does NOT
advertise cinematic_quality/lip_sync/multi_shot/native_audio).

- tools/video/mlx_video.py: provider; action routing (prompt-only → t2i2v
  3-stage; image present → generate I2V; explicit action override),
  LTX-2.3 arg mapping (frames 8k+1, /64 dims), availability gate reusing
  the mlx_image pattern, dir-scan output fallback (video subparser doesn't
  register --json-summary — an upstream MLX-repo asymmetry, documented).
  fallback_tools excludes image_selector so a motion-required brief can
  never silently degrade to a still.
- .agents/skills/mlx-movie-director/SKILL.md: video section (action routing
  table, honest surface, motion-required governance note).
- tests/tools/test_mlx_video.py: 25 tests — registration, honest-surface
  assertion (premium flags MUST be absent), zero-edit discovery, i2v filter
  survival, gate (env/venv/full), action routing, arg building, output
  parsing, mocked-subprocess execute success + error paths.

End-to-end smoke status: DEFERRED to G1. The MLX video path needs a heavier
upstream dep stack than requirements.txt provides — cv2, mflux, and the three
ltx-2-mlx workspace members (ltx-core-mlx / ltx-pipelines-mlx / ltx-trainer,
installable per-member since the ltx-2-mlx root fails uv install under PEP
639), plus a transformers/mlx_lm version conflict at the NewlineTokenizer
register call. The provider logic is fully covered by mocked-subprocess
tests; the image analog (mlx_image) is smoked end-to-end. install_instructions
documents the full chain.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .agents/skills/mlx-movie-director/SKILL.md |  57 ++-
 tests/tools/test_mlx_video.py              | 287 +++++++++++++
 tools/video/mlx_video.py                   | 447 +++++++++++++++++++++
 3 files changed, 786 insertions(+), 5 deletions(-)
 create mode 100644 tests/tools/test_mlx_video.py
 create mode 100644 tools/video/mlx_video.py

diff --git a/.agents/skills/mlx-movie-director/SKILL.md b/.agents/skills/mlx-movie-director/SKILL.md
index b9cccc208..77fd78a1a 100644
--- a/.agents/skills/mlx-movie-director/SKILL.md
+++ b/.agents/skills/mlx-movie-director/SKILL.md
@@ -1,14 +1,15 @@
 ---
 name: mlx-movie-director
-description: Use when routing image generation to the mlx_image provider (Apple-Silicon-native MLX via the sibling mlx-movie-director repo). Covers pipeline choice (zimage / flux2-klein / lens), ControlNet, i2i, LoRA stacks, faceswap, availability gating, and the MLX_MOVIE_DIRECTOR_DIR / MLX_VENV_PYTHON environment contract.
+description: Use when routing image generation to mlx_image OR video generation to mlx_video (Apple-Silicon-native MLX via the sibling mlx-movie-director repo). Covers image pipeline choice (zimage/flux2-klein/lens), ControlNet, i2i, LoRA, faceswap, video LTX-2.3 i2v/t2v/t2i2v, availability gating, and the MLX_MOVIE_DIRECTOR_DIR / MLX_VENV_PYTHON environment contract.
 ---
 
 # MLX Movie Director (run.py) in OpenMontage
 
-Use this skill before calling `mlx_image`, and whenever a brief wants a local,
-`$0` Apple-Silicon path for ControlNet, true image-to-image, LoRA conditioning,
-or BFS face/head swap — the surface no other OpenMontage image provider covers
-fully (only `grok_image`'s edit mode partially overlaps).
+Use this skill before calling `mlx_image` (image) or `mlx_video` (motion), and
+whenever a brief wants a local, `$0` Apple-Silicon path for ControlNet, true
+image-to-image, LoRA conditioning, BFS face/head swap, or native LTX-2.3 i2v/t2v
+— surfaces no other OpenMontage provider covers on Apple Silicon (only
+`grok_image`'s edit mode partially overlaps on the image side).
 
 ## Environment Contract
 
@@ -107,3 +108,49 @@ generation is byte-deterministic for a fixed seed on the same stack.
 - The scorer ranks it highly: it advertises the full `control` surface
   (controlnet/img2img/reference_image/faceswap/lora), so it wins the `control`
   and `cost_efficiency` dimensions decisively.
+
+---
+
+# Video (mlx_video)
+
+`mlx_video` wraps LTX-2.3 22B (`run.py video generate` / `video t2i2v`). It is
+the **Apple-Silicon-native** motion path: OM's other local i2v providers
+(wan/hunyuan/ltx/cogvideo) need CUDA `diffusers` and don't run on MPS.
+
+## Action Routing
+
+| Inputs | run.py action | Mode | Notes |
+|---|---|---|---|
+| prompt only | `video t2i2v` | T2V | The 3-stage ZImage T2I → VLM prompt → LTX-2.3 dasiwa animate pipeline (MLX's headline path). Richer, slower. |
+| `reference_image`/`image_path` present | `video generate` | I2V | Direct LTX-2.3 image-to-video with `--input-image`. Faster. |
+| explicit `action: "generate"` (no image) | `video generate` | T2V | Direct LTX-2.3 text-to-video. |
+| explicit `action: "t2i2v"` + image | `video t2i2v` | I2V | t2i2v with a keyframe; otherwise generates the keyframe from the prompt. |
+
+Frame count must be `8k+1` (25, 33, 41, 49, 57, 65, …, default 97 ≈ 4 s @ 24 fps).
+Dimensions auto-snap to a multiple of 64 (default 704×448).
+
+## Honest Surface — What mlx_video Is NOT
+
+`mlx_video` deliberately does NOT advertise `cinematic_quality`, `lip_sync`,
+`multi_shot`, `native_audio`, or `dialogue_generation`. Those are premium cloud
+flags (seedance / veo / kling / runway). LTX-2.3 local is a **free offline
+default** — the right pick when cost or offline operation matters, NOT a
+replacement for premium cinematic delivery. The `best_for` / `not_good_for`
+fields steer the scorer accordingly.
+
+## Motion-Required Governance
+
+For a `motion_required=true` brief, the locked `render_runtime`
+(FFmpeg / Remotion / HyperFrames) is a **compose-stage** commitment.
+`mlx_video` is a *generation* provider — it produces a clip, it does not
+satisfy or substitute for the compose runtime, and a silent runtime swap
+remains a CRITICAL violation (see `AGENT_GUIDE.md` "Motion-Required Requests").
+`mlx_video`'s `fallback_tools` deliberately excludes `image_selector` so a
+motion-required brief can never silently degrade to a still image.
+
+## When to Pick mlx_video
+
+- An image-led scene needs motion on Apple Silicon without a cloud call.
+- Cost matters (cloud motion providers charge per second; mlx_video is `$0`).
+- Offline / air-gapped motion generation.
+- Preflight draft motion before spending on a premium seedance/veo render.
diff --git a/tests/tools/test_mlx_video.py b/tests/tools/test_mlx_video.py
new file mode 100644
index 000000000..8d644a98f
--- /dev/null
+++ b/tests/tools/test_mlx_video.py
@@ -0,0 +1,287 @@
+"""Regression tests for the mlx_video provider.
+
+Locks the contract that ``mlx_video`` is auto-discovered by ``video_selector``
+with zero selector edits, advertises an HONEST surface (free local default —
+no premium ``cinematic_quality`` / ``lip_sync`` / ``multi_shot`` flags), routes
+to the right ``run.py video`` action, and parses outputs without spawning the
+runtime. See docs/REVIEW-image-to-video-voice.md §7.
+"""
+
+from __future__ import annotations
+
+import json
+import types
+from pathlib import Path
+
+import pytest
+
+from tools.video.mlx_video import MLXVideo, _VIDEO_EXTS
+from tools.base_tool import ToolStatus
+
+
+# --------------------------------------------------------------------------
+# Registration + capability surface
+# --------------------------------------------------------------------------
+
+def test_registers_as_video_generation_provider():
+    tool = MLXVideo()
+    assert tool.capability == "video_generation"
+    assert tool.provider == "mlx"
+    assert tool.name == "mlx_video"
+    assert tool.runtime.value in ("LOCAL_GPU", "local_gpu")
+
+
+def test_advertises_honest_surface():
+    """mlx_video is a free local default — it must NOT claim premium flags."""
+    tool = MLXVideo()
+    for flag in ("text_to_video", "image_to_video", "reference_image", "offline", "local_gpu", "seed"):
+        assert tool.supports.get(flag) is True, f"mlx_video must advertise supports.{flag}"
+    # Premium cinema/audio flags belong to seedance/veo/kling — NOT to LTX-2.3 local.
+    for flag in ("cinematic_quality", "lip_sync", "multi_shot", "native_audio", "dialogue_generation"):
+        assert not tool.supports.get(flag), f"mlx_video must NOT advertise supports.{flag} (honest best_for)"
+
+
+def test_cost_is_zero():
+    assert MLXVideo().estimate_cost({"prompt": "x"}) == 0.0
+
+
+def test_agent_skill_bridge_present():
+    assert MLXVideo().agent_skills == ["mlx-movie-director"]
+
+
+def test_fallback_does_not_include_image_selector():
+    """Motion-required governance: mlx_video must never degrade to a still image."""
+    assert "image_selector" not in MLXVideo().fallback_tools
+
+
+# --------------------------------------------------------------------------
+# video_selector discovers it with ZERO selector edits
+# --------------------------------------------------------------------------
+
+def test_video_selector_discovers_mlx_video():
+    from tools.tool_registry import registry
+    registry.ensure_discovered()
+    selector = next(t for t in registry.get_by_capability("video_generation") if t.name == "video_selector")
+    candidates = selector._providers()
+    assert any(t.name == "mlx_video" for t in candidates), (
+        "mlx_video must be auto-discovered by video_selector — zero selector edits. "
+        "If this fails, the discovery seam is broken."
+    )
+
+
+def test_mlx_video_survives_i2v_filter():
+    """An image_to_video request must keep mlx_video as a candidate."""
+    from tools.tool_registry import registry
+    registry.ensure_discovered()
+    selector = next(t for t in registry.get_by_capability("video_generation") if t.name == "video_selector")
+    candidates = selector._providers()
+    filtered = selector._filter_candidates(
+        {"prompt": "animate", "operation": "image_to_video", "reference_image": "x.png"},
+        candidates,
+    )
+    assert any(t.name == "mlx_video" for t in filtered)
+
+
+# --------------------------------------------------------------------------
+# Availability gate (mirrors mlx_image — pure filesystem)
+# --------------------------------------------------------------------------
+
+def test_status_unavailable_when_env_unset(monkeypatch):
+    monkeypatch.delenv("MLX_MOVIE_DIRECTOR_DIR", raising=False)
+    monkeypatch.delenv("MLX_VENV_PYTHON", raising=False)
+    env = MLXVideo._resolve_env()
+    assert env["ok"] is False
+    assert "MLX_MOVIE_DIRECTOR_DIR" in env["reason"]
+    assert MLXVideo().get_status() == ToolStatus.UNAVAILABLE
+
+
+def test_status_unavailable_when_venv_missing(monkeypatch, tmp_path):
+    mlx_dir = tmp_path / "mlx_repo"
+    (mlx_dir / "python" / "mlx-movie-director").mkdir(parents=True)
+    (mlx_dir / "python" / "mlx-movie-director" / "run.py").write_text("# stub")
+    monkeypatch.setenv("MLX_MOVIE_DIRECTOR_DIR", str(mlx_dir))
+    monkeypatch.delenv("MLX_VENV_PYTHON", raising=False)
+    env = MLXVideo._resolve_env()
+    assert env["ok"] is False
+    assert "venv" in env["reason"].lower() and "uv venv" in env["reason"]
+
+
+def test_status_available_with_full_env(monkeypatch, tmp_path):
+    mlx_dir = tmp_path / "mlx_repo"
+    (mlx_dir / "python" / "mlx-movie-director").mkdir(parents=True)
+    (mlx_dir / "python" / "mlx-movie-director" / "run.py").write_text("# stub")
+    venv_py = mlx_dir / "python" / "venv" / "bin" / "python"
+    venv_py.parent.mkdir(parents=True)
+    venv_py.write_text("#!/bin/sh\nexit 0\n")
+    venv_py.chmod(0o755)
+    for sub in ("transformer", "vae"):
+        (mlx_dir / "mlx-models" / sub).mkdir(parents=True)
+    monkeypatch.setenv("MLX_MOVIE_DIRECTOR_DIR", str(mlx_dir))
+    monkeypatch.delenv("MLX_VENV_PYTHON", raising=False)
+    env = MLXVideo._resolve_env()
+    assert env["ok"] is True, env.get("reason")
+    if env["arm64"]:
+        assert MLXVideo().get_status() == ToolStatus.AVAILABLE
+
+
+# --------------------------------------------------------------------------
+# Action routing + CLI argument building (no subprocess)
+# --------------------------------------------------------------------------
+
+@pytest.mark.parametrize(
+    "inputs, expected_action, expected_mode",
+    [
+        ({"prompt": "a dog running"}, "t2i2v", "t2v"),                  # prompt-only → rich 3-stage
+        ({"prompt": "animate", "image_path": "x.png"}, "generate", "i2v"),  # image present → I2V
+        ({"prompt": "animate", "reference_image": "x.png"}, "generate", "i2v"),
+        ({"prompt": "x", "action": "generate"}, "generate", "t2v"),     # explicit generate, no image → T2V
+        ({"prompt": "x", "action": "t2i2v"}, "t2i2v", "t2v"),           # explicit t2i2v
+    ],
+)
+def test_action_routing(inputs, expected_action, expected_mode):
+    action = MLXVideo._resolve_action(inputs)
+    assert action == expected_action
+    mode = "i2v" if MLXVideo._has_reference_image(inputs) else "t2v"
+    assert mode == expected_mode
+
+
+def test_t2v_arg_building():
+    args = MLXVideo._build_args({"prompt": "a dog", "num_frames": 49, "seed": 7, "fps": 24.0}, "generate")
+    # _build_args emits in a fixed field order (frames → fps → seed), not call order.
+    assert args == ["--prompt", "a dog", "--frames", "49", "--fps", "24.0", "--seed", "7"]
+
+
+def test_i2v_passes_input_image():
+    args = MLXVideo._build_args(
+        {"prompt": "animate", "image_path": "still.png", "num_frames": 41}, "generate"
+    )
+    joined = " ".join(args)
+    assert "--input-image still.png" in joined
+    assert "--frames 41" in joined
+
+
+def test_t2i2v_with_optional_input_image():
+    """t2i2v may animate a specific still; otherwise generates the keyframe first."""
+    args_no_img = MLXVideo._build_args({"prompt": "a scene"}, "t2i2v")
+    assert "--input-image" not in args_no_img
+    args_with_img = MLXVideo._build_args({"prompt": "a scene", "reference_image": "k.png"}, "t2i2v")
+    assert "--input-image k.png" in " ".join(args_with_img)
+
+
+def test_cfg_and_transformer_passed_through():
+    args = MLXVideo._build_args(
+        {"prompt": "x", "cfg_scale": 3.0, "transformer": "dasiwa", "stage1_steps": 30}, "t2i2v"
+    )
+    joined = " ".join(args)
+    assert "--cfg-scale 3.0" in joined
+    assert "--transformer dasiwa" in joined
+    assert "--stage1-steps 30" in joined
+
+
+# --------------------------------------------------------------------------
+# Output parsing
+# --------------------------------------------------------------------------
+
+def test_parse_outputs_prefers_json_summary(tmp_path):
+    clip = tmp_path / "out.mp4"
+    clip.write_bytes(b"\x00\x00\x00")  # not a real mp4; existence is all _parse_outputs checks
+    payload = json.dumps({"outputs": [str(clip)], "status": "ok"})
+    outs = MLXVideo._parse_outputs(f"JSON_SUMMARY:{payload}\n", str(tmp_path))
+    assert outs == [str(clip)]
+
+
+def test_parse_outputs_falls_back_to_dir_scan(tmp_path):
+    """No JSON_SUMMARY → newest video file in the gen-output-dir."""
+    import os, time
+    older = tmp_path / "a.mp4"; older.write_bytes(b"x")
+    newer = tmp_path / "b.mp4"; newer.write_bytes(b"x")
+    os.utime(older, (time.time() - 10, time.time() - 10))
+    outs = MLXVideo._parse_outputs("", str(tmp_path))
+    assert outs and outs[0] == str(newer)
+
+
+def test_video_output_extensions_covered():
+    exts = " ".join(_VIDEO_EXTS)
+    for e in ("mp4", "mov", "webm", "gif"):
+        assert e in exts
+
+
+# --------------------------------------------------------------------------
+# execute() — error path + mocked success (no real run.py spawn)
+# --------------------------------------------------------------------------
+
+def test_execute_returns_error_when_env_unset(monkeypatch):
+    monkeypatch.delenv("MLX_MOVIE_DIRECTOR_DIR", raising=False)
+    result = MLXVideo().execute({"prompt": "a dog"})
+    assert result.success is False
+    assert "MLX_MOVIE_DIRECTOR_DIR" in result.error
+
+
+def test_execute_success_path(monkeypatch, tmp_path):
+    mlx_dir = tmp_path / "mlx_repo"
+    run_py = mlx_dir / "python" / "mlx-movie-director" / "run.py"
+    run_py.parent.mkdir(parents=True)
+    run_py.write_text("# stub")
+    venv_py = mlx_dir / "python" / "venv" / "bin" / "python"
+    venv_py.parent.mkdir(parents=True)
+    venv_py.write_text("#!/bin/sh\nexit 0\n")
+    venv_py.chmod(0o755)
+    (mlx_dir / "mlx-models" / "transformer").mkdir(parents=True)
+    (mlx_dir / "mlx-models" / "vae").mkdir(parents=True)
+    monkeypatch.setenv("MLX_MOVIE_DIRECTOR_DIR", str(mlx_dir))
+    monkeypatch.delenv("MLX_VENV_PYTHON", raising=False)
+    if not MLXVideo._resolve_env()["arm64"]:
+        pytest.skip("Apple-Silicon-only fixture")
+
+    produced = tmp_path / "clip.mp4"
+    produced.write_bytes(b"\x00\x00\x00")
+    fake_proc = types.SimpleNamespace(
+        returncode=0,
+        stdout=f"JSON_SUMMARY:{json.dumps({'outputs': [str(produced)]})}\n",
+        stderr="",
+    )
+    captured: dict = {}
+    monkeypatch.setattr("tools.video.mlx_video.subprocess.run", lambda cmd, **k: (captured.__setitem__("cmd", cmd), fake_proc)[1])
+
+    out_path = tmp_path / "final" / "result.mp4"
+    result = MLXVideo().execute({
+        "prompt": "a dog running", "seed": 7, "num_frames": 49,
+        "image_path": "still.png", "output_path": str(out_path),
+    })
+    assert result.success is True, result.error
+    assert result.data["provider"] == "mlx"
+    assert result.data["action"] == "generate"  # image present → generate (I2V)
+    assert result.data["mode"] == "i2v"
+    assert result.data["seed"] == 7
+    assert result.cost_usd == 0.0
+    assert out_path.exists()
+    cmd = captured["cmd"]
+    assert "video" in cmd and "generate" in cmd
+    assert "--gen-output-dir" in cmd
+    # --json-summary is intentionally NOT passed (video subparser doesn't register it).
+    assert "--json-summary" not in cmd
+    assert "--input-image" in cmd
+
+
+def test_execute_nonzero_exit_returns_failure(monkeypatch, tmp_path):
+    mlx_dir = tmp_path / "mlx_repo"
+    run_py = mlx_dir / "python" / "mlx-movie-director" / "run.py"
+    run_py.parent.mkdir(parents=True)
+    run_py.write_text("# stub")
+    venv_py = mlx_dir / "python" / "venv" / "bin" / "python"
+    venv_py.parent.mkdir(parents=True)
+    venv_py.write_text("#!/bin/sh\nexit 0\n")
+    venv_py.chmod(0o755)
+    (mlx_dir / "mlx-models" / "transformer").mkdir(parents=True)
+    (mlx_dir / "mlx-models" / "vae").mkdir(parents=True)
+    monkeypatch.setenv("MLX_MOVIE_DIRECTOR_DIR", str(mlx_dir))
+    monkeypatch.delenv("MLX_VENV_PYTHON", raising=False)
+    if not MLXVideo._resolve_env()["arm64"]:
+        pytest.skip("Apple-Silicon-only fixture")
+    monkeypatch.setattr(
+        "tools.video.mlx_video.subprocess.run",
+        lambda cmd, **k: types.SimpleNamespace(returncode=1, stdout="", stderr="gpu oom"),
+    )
+    result = MLXVideo().execute({"prompt": "a dog"})
+    assert result.success is False
+    assert "run.py exited 1" in result.error and "gpu oom" in result.error
diff --git a/tools/video/mlx_video.py b/tools/video/mlx_video.py
new file mode 100644
index 000000000..a176c90a1
--- /dev/null
+++ b/tools/video/mlx_video.py
@@ -0,0 +1,447 @@
+"""MLX video generation via the sibling ``mlx-movie-director`` runtime.
+
+The motion analog of ``mlx_image``: bridges OpenMontage's video-generation
+capability to the Apple-Silicon-native MLX LTX-2.3 22B pipeline
+(``python/mlx-movie-director/run.py video {generate, t2i2v}``).
+
+Why this provider exists (see ``docs/REVIEW-image-to-video-voice.md`` §7):
+OpenMontage already has four ``$0`` local i2v providers (wan / hunyuan / ltx /
+cogvideo), but they require CUDA ``diffusers`` (8–24 GB VRAM) and do not run on
+Apple Silicon. MLX LTX-2.3 is the **MPS-native** i2v/t2v path — a free, offline
+local default, NOT a premium-cinema replacement for Seedance / Veo / Kling
+(those advertise ``cinematic_quality`` / ``lip_sync`` / ``multi_shot``; this
+provider deliberately does not).
+
+Governance note: for a ``motion_required=true`` brief the locked ``render_runtime``
+(FFmpeg / Remotion / HyperFrames) is a compose-stage commitment. ``mlx_video``
+is a *generation* provider — it produces a clip, it does not satisfy or
+substitute for the compose runtime. The motion-required prohibition
+(``AGENT_GUIDE.md`` §"Motion-Required Requests") still applies upstream.
+
+Env contract (same as ``mlx_image``):
+* ``MLX_MOVIE_DIRECTOR_DIR``  — repo root containing ``python/mlx-movie-director/run.py``.
+* ``MLX_VENV_PYTHON``         — venv interpreter (default
+  ``<dir>/python/venv/bin/python``). Per-machine, NOT auto-created — see
+  ``install_instructions``.
+
+Discovery is automatic — ``video_selector`` picks up any
+``capability="video_generation"`` tool, so this file required zero selector
+edits.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import re
+import shutil
+import subprocess
+import tempfile
+import time
+from pathlib import Path
+from typing import Any
+
+from tools.base_tool import (
+    BaseTool,
+    Determinism,
+    ExecutionMode,
+    ResourceProfile,
+    RetryPolicy,
+    ToolResult,
+    ToolRuntime,
+    ToolStability,
+    ToolStatus,
+    ToolTier,
+)
+
+# Env contract (mirrors mlx_image; copied rather than imported to keep this a
+# one-file add — no cross-tool graphics↔video coupling. If a third MLX provider
+# appears, factor into tools/_mlx/env.py).
+_MLX_DIR_ENV = "MLX_MOVIE_DIRECTOR_DIR"
+_MLX_PYTHON_ENV = "MLX_VENV_PYTHON"
+_RUN_PY_REL = "python/mlx-movie-director/run.py"
+_VENV_PYTHON_REL = "python/venv/bin/python"
+_MODELS_REL = "mlx-models"
+_REQUIRED_MODEL_SUBDIRS = ("transformer", "vae")
+
+# LTX-2.3 output extensions (broader than mlx_image's image set).
+_VIDEO_EXTS = ("*.mp4", "*.mov", "*.webm", "*.gif")
+_JSON_SUMMARY_RE = re.compile(r"JSON_SUMMARY:(\{.*\})\s*$", re.MULTILINE)
+
+# LTX-2.3 frame count must be 8k+1 (25, 33, 41, 49, 57, …). Default 97 ≈ 4s @ 24fps.
+_DEFAULT_FRAMES = 97
+_DEFAULT_FPS = 24.0
+
+
+class MLXVideo(BaseTool):
+    name = "mlx_video"
+    version = "0.1.0"
+    tier = ToolTier.GENERATE
+    capability = "video_generation"
+    provider = "mlx"
+    stability = ToolStability.EXPERIMENTAL
+    execution_mode = ExecutionMode.SYNC
+    determinism = Determinism.SEEDED  # LTX-2.3 is seed-deterministic on a fixed stack
+    runtime = ToolRuntime.LOCAL_GPU
+
+    dependencies = []
+    install_instructions = (
+        "Set MLX_MOVIE_DIRECTOR_DIR to the mlx-movie-director repo root "
+        "(contains python/mlx-movie-director/run.py).\n"
+        "Optionally set MLX_VENV_PYTHON to its venv interpreter (default "
+        "<MLX_MOVIE_DIRECTOR_DIR>/python/venv/bin/python).\n"
+        "The MLX venv is per-machine and NOT auto-created — recreate it with:\n"
+        "  uv venv python/venv --python 3.12\n"
+        "  uv pip install -r python/mlx-movie-director/requirements.txt "
+        "--python python/venv/bin/python\n"
+        "The VIDEO path needs substantially more than requirements.txt (tracked "
+        "as upstream MLX-repo gap G1 — heavier than the image path):\n"
+        "  - opencv-python (image-quality imports cv2)\n"
+        "  - mflux (the Z-Image VAE loader)\n"
+        "  - the ltx-2-mlx workspace members (editable): ltx-core-mlx,\n"
+        "    ltx-pipelines-mlx, ltx-trainer from the sibling ltx-2-mlx repo\n"
+        "    (`uv pip install -e <ltx-2-mlx>/packages/<member>`). The ltx-2-mlx\n"
+        "    root pyproject currently fails under uv (PEP 639 license classifier)\n"
+        "    so install each packages/* member directly.\n"
+        "  - a transformers version compatible with the mlx_lm the members pull\n"
+        "    (a known conflict point — the NewlineTokenizer register call).\n"
+        "Until G1 lands, image (mlx_image) works end-to-end but video may need\n"
+        "manual env resolution. Requires Apple Silicon (arm64)."
+    )
+    agent_skills = ["mlx-movie-director"]
+
+    capabilities = ["text_to_video", "image_to_video"]
+    # Honest surface: a free local default. Deliberately NOT advertising
+    # cinematic_quality / native_audio / lip_sync / multi_shot — those are the
+    # premium cloud flags (seedance/veo/kling); LTX-2.3 local is not that.
+    supports = {
+        "text_to_video": True,
+        "image_to_video": True,
+        "reference_image": True,
+        "offline": True,
+        "native_audio": False,
+        "local_gpu": True,
+        "seed": True,
+    }
+    best_for = [
+        "local Apple Silicon video generation with no API cost",
+        "free offline image-to-video (animating a still into a short clip)",
+        "text-to-video local default before escalating to paid cloud providers",
+    ]
+    not_good_for = [
+        "premium cinematic delivery (use seedance/veo/kling/runway)",
+        "native audio / dialogue generation",
+        "long-form video (LTX-2.3 local is short-clip oriented)",
+        "non-Apple-Silicon hosts (no CUDA / no MPS)",
+    ]
+    fallback = "ltx_video_local"
+    # Note: unlike the cloud/local diffusers providers, we do NOT append
+    # image_selector here — mlx_video is motion-only and must never silently
+    # degrade a motion-required brief to a still image.
+    fallback_tools = ["ltx_video_local", "wan_video", "hunyuan_video", "ltx_video_modal"]
+
+    input_schema = {
+        "type": "object",
+        "required": ["prompt"],
+        "properties": {
+            "prompt": {"type": "string", "description": "Text prompt describing the desired motion / scene."},
+            "action": {
+                "type": "string",
+                "enum": ["auto", "generate", "t2i2v"],
+                "default": "auto",
+                "description": (
+                    "'generate' = direct LTX-2.3 (T2V or I2V depending on whether a "
+                    "reference image is given). 't2i2v' = the 3-stage ZImage T2I → VLM "
+                    "prompt → LTX-2.3 I2V pipeline (richer, slower). 'auto' picks "
+                    "generate for I2V (image present) and t2i2v for pure T2V."
+                ),
+            },
+            # I2V conditioning. Presence of reference_image/_path also satisfies
+            # video_selector's _filter_candidates for the image_to_video operation.
+            "reference_image": {"type": "string", "description": "Source image for I2V (image-to-video)."},
+            "reference_image_path": {"type": "string", "description": "Alias of reference_image (source image path)."},
+            "image_url": {"type": "string", "description": "Alias of reference_image (selector compatibility)."},
+            "image_path": {"type": "string", "description": "Alias of reference_image (selector compatibility)."},
+            "width": {"type": "integer", "description": "Video width (default 704; auto-snapped to multiple of 64)."},
+            "height": {"type": "integer", "description": "Video height (default 448; auto-snapped to multiple of 64)."},
+            "num_frames": {
+                "type": "integer",
+                "description": "Frame count (default 97 ≈ 4s @ 24fps; must be 8k+1: 25,33,41,49,…).",
+            },
+            "fps": {"type": "number", "description": "Output frame rate (default 24.0)."},
+            "seed": {"type": "integer", "description": "Random seed (default 42)."},
+            "cfg_scale": {
+                "type": "number",
+                "description": "Text guidance (default 5.0 T2V/I2V; lower = softer motion). Does not affect image conditioning.",
+            },
+            "stg_scale": {"type": "number", "description": "Spatial-temporal guidance (default 1.5 for dasiwa)."},
+            "stage1_steps": {"type": "integer", "description": "Stage 1 denoising steps (default 8; 30 for max quality, slower)."},
+            "transformer": {
+                "type": "string",
+                "description": "Transformer instance under models/transformer/ (e.g. 'dasiwa'). t2i2v default uses dasiwa.",
+            },
+            "output_path": {"type": "string", "description": "Where to save the generated video."},
+        },
+    }
+
+    resource_profile = ResourceProfile(
+        cpu_cores=4, ram_mb=18000, vram_mb=0, disk_mb=2000, network_required=False,
+    )
+    retry_policy = RetryPolicy(max_retries=1, retryable_errors=["timeout"])
+    idempotency_key_fields = ["prompt", "action", "num_frames", "seed", "width", "height"]
+    side_effects = ["spawns python/venv/bin/python run.py video …", "writes video file to output_path"]
+    user_visible_verification = ["Watch generated clip for motion coherence and artifacts."]
+
+    # ------------------------------------------------------------------
+    # Environment + availability (mirrors mlx_image)
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _resolve_env() -> dict[str, Any]:
+        mlx_dir = os.environ.get(_MLX_DIR_ENV)
+        arm64 = platform.machine() in ("arm64", "aarch64")
+        if not mlx_dir:
+            return {"ok": False, "reason": f"{_MLX_DIR_ENV} is not set (point it at the mlx-movie-director repo root).", "arm64": arm64}
+        mlx_dir = os.path.expanduser(mlx_dir)
+        run_py = os.path.join(mlx_dir, _RUN_PY_REL)
+        if not os.path.isfile(run_py):
+            return {"ok": False, "reason": f"{_MLX_DIR_ENV}={mlx_dir} has no {_RUN_PY_REL}.", "arm64": arm64, "mlx_dir": mlx_dir}
+        venv_python = os.environ.get(_MLX_PYTHON_ENV) or os.path.join(mlx_dir, _VENV_PYTHON_REL)
+        if not os.path.isfile(venv_python):
+            return {
+                "ok": False,
+                "reason": (
+                    f"MLX venv interpreter not found at {venv_python}. Recreate it: "
+                    f"uv venv {mlx_dir}/python/venv --python 3.12 && "
+                    f"uv pip install -r {mlx_dir}/python/mlx-movie-director/requirements.txt "
+                    f"--python {mlx_dir}/python/venv/bin/python"
+                ),
+                "arm64": arm64, "mlx_dir": mlx_dir, "run_py": run_py,
+            }
+        models_dir = os.path.join(mlx_dir, _MODELS_REL)
+        missing = [s for s in _REQUIRED_MODEL_SUBDIRS if not os.path.isdir(os.path.join(models_dir, s))]
+        if missing:
+            return {"ok": False, "reason": f"MLX models incomplete under {models_dir}: missing {missing}.", "arm64": arm64, "mlx_dir": mlx_dir, "run_py": run_py, "venv_python": venv_python}
+        if not arm64:
+            return {"ok": False, "reason": f"MLX runs on Apple Silicon only (got {platform.machine()}).", "arm64": False, "mlx_dir": mlx_dir, "run_py": run_py, "venv_python": venv_python}
+        return {"ok": True, "arm64": True, "mlx_dir": mlx_dir, "run_py": run_py, "venv_python": venv_python}
+
+    def get_status(self) -> ToolStatus:
+        return ToolStatus.AVAILABLE if self._resolve_env()["ok"] else ToolStatus.UNAVAILABLE
+
+    def estimate_cost(self, inputs: dict[str, Any]) -> float:
+        return 0.0
+
+    def estimate_runtime(self, inputs: dict[str, Any]) -> float:
+        # LTX-2.3 ~2-4s/step stage1 × ~8 steps + decode; rough clip budget.
+        steps = inputs.get("stage1_steps") or 8
+        frames = inputs.get("num_frames") or _DEFAULT_FRAMES
+        return float(steps) * 3.0 + frames * 0.15
+
+    def get_info(self) -> dict[str, Any]:
+        info = super().get_info()
+        env = self._resolve_env()
+        info["mlx_env"] = {"configured": env["ok"], "reason": env.get("reason"), "arm64": env.get("arm64"), "mlx_dir": env.get("mlx_dir"), "venv_python": env.get("venv_python")}
+        return info
+
+    # ------------------------------------------------------------------
+    # Execute
+    # ------------------------------------------------------------------
+
+    def execute(self, inputs: dict[str, Any]) -> ToolResult:
+        env = self._resolve_env()
+        if not env["ok"]:
+            return ToolResult(success=False, error=env["reason"])
+
+        run_py = env["run_py"]
+        venv_python = env["venv_python"]
+
+        action = self._resolve_action(inputs)
+        cmd = [venv_python, run_py, "video", action]
+
+        try:
+            cmd.extend(self._build_args(inputs, action))
+        except _BadInput as exc:
+            return ToolResult(success=False, error=str(exc))
+
+        out_dir = tempfile.mkdtemp(prefix="mlx_video_")
+        # --gen-output-dir is a top-level run.py flag (accepted); --json-summary is
+        # NOT registered on the video subparser (video.py:132 deliberately skips
+        # add_common_generation_args, even though video-generate.py:875 reads
+        # args.json_summary — an upstream MLX-repo asymmetry). So we rely on the
+        # dir-scan fallback in _parse_outputs: the gen-output-dir is a fresh
+        # isolated temp dir, so its only .mp4 is this run's output.
+        cmd.extend(["--gen-output-dir", out_dir])
+
+        start = time.time()
+        try:
+            proc = subprocess.run(cmd, capture_output=True, text=True, timeout=1800, check=False)
+        except subprocess.TimeoutExpired:
+            shutil.rmtree(out_dir, ignore_errors=True)
+            return ToolResult(success=False, error="MLX video generation timed out (>1800s).")
+        except Exception as exc:  # pragma: no cover
+            shutil.rmtree(out_dir, ignore_errors=True)
+            return ToolResult(success=False, error=f"Failed to spawn MLX runtime: {exc}")
+
+        elapsed = round(time.time() - start, 2)
+
+        if proc.returncode != 0:
+            shutil.rmtree(out_dir, ignore_errors=True)
+            tail = (proc.stderr or proc.stdout or "").strip().splitlines()[-12:]
+            return ToolResult(success=False, error=f"run.py exited {proc.returncode}:\n" + "\n".join(tail))
+
+        outputs = self._parse_outputs(proc.stdout, out_dir)
+        if not outputs:
+            shutil.rmtree(out_dir, ignore_errors=True)
+            tail = (proc.stderr or proc.stdout or "").strip().splitlines()[-12:]
+            return ToolResult(success=False, error="run.py produced no video output:\n" + "\n".join(tail))
+
+        src = Path(outputs[0])
+        output_path = inputs.get("output_path")
+        final_path = src
+        if output_path:
+            dest = Path(output_path)
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            if dest.resolve() != src.resolve():
+                shutil.copy2(src, dest)
+            final_path = dest
+
+        seed = self._effective_seed(inputs)
+        model = self._model_label(inputs, action)
+
+        return ToolResult(
+            success=True,
+            data={
+                "provider": "mlx",
+                "model": model,
+                "prompt": inputs["prompt"],
+                "action": action,
+                "mode": "i2v" if self._has_reference_image(inputs) else "t2v",
+                "width": inputs.get("width"),
+                "height": inputs.get("height"),
+                "num_frames": inputs.get("num_frames"),
+                "fps": inputs.get("fps"),
+                "seed": seed,
+                "output": str(final_path),
+                "format": final_path.suffix.lstrip(".") or "mp4",
+                "mlx_run_py": run_py,
+            },
+            artifacts=[str(final_path)],
+            cost_usd=0.0,
+            duration_seconds=elapsed,
+            seed=seed,
+            model=model,
+        )
+
+    # ------------------------------------------------------------------
+    # Action + argument mapping
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _effective_seed(inputs: dict[str, Any]) -> int:
+        s = inputs.get("seed")
+        return s if isinstance(s, int) else 42  # run.py video default
+
+    @staticmethod
+    def _model_label(inputs: dict[str, Any], action: str) -> str:
+        transformer = inputs.get("transformer") or ("dasiwa" if action == "t2i2v" else None)
+        if transformer:
+            return f"mlx-ltx2.3/{transformer}"
+        return "mlx-ltx2.3"
+
+    @staticmethod
+    def _has_reference_image(inputs: dict[str, Any]) -> bool:
+        return bool(
+            inputs.get("reference_image")
+            or inputs.get("reference_image_path")
+            or inputs.get("image_url")
+            or inputs.get("image_path")
+        )
+
+    @staticmethod
+    def _resolve_reference(inputs: dict[str, Any]) -> str | None:
+        return (
+            inputs.get("reference_image")
+            or inputs.get("reference_image_path")
+            or inputs.get("image_url")
+            or inputs.get("image_path")
+        )
+
+    @classmethod
+    def _resolve_action(cls, inputs: dict[str, Any]) -> str:
+        """Decide the run.py video action.
+
+        - Explicit `action` input wins (generate | t2i2v).
+        - auto: image present → generate (I2V); prompt only → t2i2v (the richer
+          3-stage prompt→image→video path — MLX's headline feature).
+        """
+        action = inputs.get("action") or "auto"
+        has_image = cls._has_reference_image(inputs)
+        if action == "generate":
+            return "generate"
+        if action == "t2i2v":
+            return "t2i2v"
+        # auto
+        return "generate" if has_image else "t2i2v"
+
+    @classmethod
+    def _build_args(cls, inputs: dict[str, Any], action: str) -> list[str]:
+        out: list[str] = []
+        prompt = inputs.get("prompt")
+        if not prompt:
+            raise _BadInput("prompt is required.")
+        out += ["--prompt", str(prompt)]
+
+        for key, flag, cast in (
+            ("width", "--width", int),
+            ("height", "--height", int),
+            ("num_frames", "--frames", int),
+            ("fps", "--fps", float),
+            ("seed", "--seed", int),
+            ("cfg_scale", "--cfg-scale", float),
+            ("stg_scale", "--stg-scale", float),
+            ("stage1_steps", "--stage1-steps", int),
+            ("transformer", "--transformer", str),
+        ):
+            if inputs.get(key) is not None:
+                out += [flag, str(cast(inputs[key]))]  # type: ignore[call-arg]
+
+        ref = cls._resolve_reference(inputs)
+        if action == "generate":
+            if ref:
+                out += ["--input-image", str(ref)]
+            # t2v when no reference image
+        elif action == "t2i2v":
+            # t2i2v accepts an optional --input-image to animate a specific still;
+            # otherwise it generates the keyframe from the prompt first.
+            if ref:
+                out += ["--input-image", str(ref)]
+        return out
+
+    # ------------------------------------------------------------------
+    # Output parsing
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _parse_outputs(stdout: str, out_dir: str) -> list[str]:
+        match = _JSON_SUMMARY_RE.search(stdout or "")
+        if match:
+            try:
+                payload = json.loads(match.group(1))
+                outs = payload.get("outputs") or []
+                if isinstance(outs, list):
+                    resolved = [o for o in outs if o and os.path.isfile(str(o))]
+                    if resolved:
+                        return resolved
+            except json.JSONDecodeError:
+                pass
+        candidates: list[Path] = []
+        for ext in _VIDEO_EXTS:
+            candidates.extend(Path(out_dir).glob(ext))
+        candidates.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+        return [str(p) for p in candidates]
+
+
+class _BadInput(Exception):
+    """Raised when provider inputs cannot map cleanly to run.py flags."""

From be1ddce2900d7724801dee4ad411731c4cc7f40d Mon Sep 17 00:00:00 2001
From: Ziyu Huang <ziyu4huang@gmail.com>
Date: Mon, 6 Jul 2026 23:29:30 +0800
Subject: [PATCH 3/5] feat(analysis): mlx_caption provider (local LM-Studio
 VLM) + shared MLX env
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The third leg of the MLX-runtime trio (image gen + video gen + VLM analysis),
all bridging the sibling mlx-movie-director run.py on Apple Silicon.

mlx_caption (tools/analysis/mlx_caption.py):
- Bridges run.py `caption` (Qwen3-VL via LM Studio localhost:1234/v1) into the
  `analysis` capability — the $0, offline, private image/video-understanding
  path. Fills a verified gap: no tool used local LM Studio before (video_understand
  is a direct-transformers VLM that downloads+loads a model each run; mlx_caption
  talks to an already-running server the box already serves mlx_image/video from).
- Auto-discovered by the registry (13th analysis tool, zero selector edits).
- Availability gate: MLX_MOVIE_DIRECTOR_DIR + venv + LM Studio socket-probe
  (need_models=False — caption talks to LM Studio, not the mlx-models stack).
- 21 spawn-free tests (capability surface, env gates incl. LM Studio down,
  arg-mapping for all --style/--lang/--model/--api-url combos, output parsing).

Shared env module (tools/_mlx/env.py):
- Factors the duplicated _resolve_env() out of mlx_image + mlx_video (the TODO
  both files carried: 'if a third MLX provider appears, factor into
  tools/_mlx/env.py'). resolve_mlx_env(need_models, need_lm_studio) serves all
  three. All 49 existing mlx_image/mlx_video tests still green.
---
 tests/tools/test_mlx_caption.py | 212 ++++++++++++++++++
 tools/_mlx/__init__.py          |  12 +
 tools/_mlx/env.py               | 158 +++++++++++++
 tools/analysis/mlx_caption.py   | 383 ++++++++++++++++++++++++++++++++
 tools/graphics/mlx_image.py     |  91 +-------
 tools/video/mlx_video.py        |  44 +---
 6 files changed, 780 insertions(+), 120 deletions(-)
 create mode 100644 tests/tools/test_mlx_caption.py
 create mode 100644 tools/_mlx/__init__.py
 create mode 100644 tools/_mlx/env.py
 create mode 100644 tools/analysis/mlx_caption.py

diff --git a/tests/tools/test_mlx_caption.py b/tests/tools/test_mlx_caption.py
new file mode 100644
index 000000000..7e57e067c
--- /dev/null
+++ b/tests/tools/test_mlx_caption.py
@@ -0,0 +1,212 @@
+"""Regression tests for the mlx_caption provider.
+
+Locks the contract that ``mlx_caption`` is the analysis-tier analog of
+``mlx_image`` / ``mlx_video`` — the local-VLM (LM Studio) understanding path —
+and that it maps inputs to the ``run.py caption`` CLI correctly without spawning
+the runtime or requiring LM Studio to be up.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+import pytest
+
+from tools.analysis.mlx_caption import MLXCaption, _BadInput
+from tools.base_tool import ToolStatus
+
+
+# --------------------------------------------------------------------------
+# Registration + capability surface
+# --------------------------------------------------------------------------
+
+def test_registers_as_analysis_provider():
+    tool = MLXCaption()
+    assert tool.capability == "analysis"
+    assert tool.provider == "mlx"
+    assert tool.name == "mlx_caption"
+    assert tool.tier.value == "analyze"
+    assert tool.runtime.value in ("LOCAL_GPU", "local_gpu")
+
+
+def test_advertises_vision_surface():
+    """The point of mlx_caption: local LM-Studio vision understanding."""
+    tool = MLXCaption()
+    for flag in ("vision", "image_understanding", "video_understanding", "offline", "local"):
+        assert tool.supports.get(flag) is True, f"mlx_caption must advertise supports.{flag}"
+
+
+def test_cost_is_zero():
+    assert MLXCaption().estimate_cost({"image": "x.png"}) == 0.0
+
+
+def test_agent_skill_bridge_present():
+    assert MLXCaption().agent_skills == ["mlx-movie-director"]
+
+
+def test_fallback_targets_analysis_peers():
+    """When MLX/LM Studio is down, fall back to other local/cloud vision tools."""
+    fallbacks = {MLXCaption().fallback, *MLXCaption().fallback_tools}
+    assert "video_understand" in fallbacks
+
+
+# --------------------------------------------------------------------------
+# Availability gate (no subprocess — pure filesystem + socket probe)
+# --------------------------------------------------------------------------
+
+def test_status_unavailable_when_env_unset(monkeypatch):
+    monkeypatch.delenv("MLX_MOVIE_DIRECTOR_DIR", raising=False)
+    monkeypatch.delenv("MLX_VENV_PYTHON", raising=False)
+    env = MLXCaption._resolve_env()
+    assert env["ok"] is False
+    assert "MLX_MOVIE_DIRECTOR_DIR" in env["reason"]
+    assert MLXCaption().get_status() == ToolStatus.UNAVAILABLE
+
+
+def test_status_unavailable_when_venv_missing(monkeypatch, tmp_path):
+    """Env dir + run.py present but venv absent → UNAVAILABLE with recreate hint."""
+    mlx_dir = tmp_path / "mlx_repo"
+    (mlx_dir / "python" / "mlx-movie-director").mkdir(parents=True)
+    (mlx_dir / "python" / "mlx-movie-director" / "run.py").write_text("# stub")
+    monkeypatch.setenv("MLX_MOVIE_DIRECTOR_DIR", str(mlx_dir))
+    monkeypatch.delenv("MLX_VENV_PYTHON", raising=False)
+    env = MLXCaption._resolve_env()
+    assert env["ok"] is False
+    assert "venv" in env["reason"].lower()
+    assert "uv venv" in env["reason"]
+
+
+def test_status_unavailable_when_lm_studio_down(monkeypatch, tmp_path):
+    """Full MLX env but LM Studio not reachable → UNAVAILABLE with LM Studio hint.
+
+    mlx_caption does NOT require the mlx-models generation stack (need_models=False)
+    — the gate is MLX runtime + LM Studio, not model files.
+    """
+    mlx_dir = tmp_path / "mlx_repo"
+    (mlx_dir / "python" / "mlx-movie-director").mkdir(parents=True)
+    (mlx_dir / "python" / "mlx-movie-director" / "run.py").write_text("# stub")
+    venv_py = mlx_dir / "python" / "venv" / "bin" / "python"
+    venv_py.parent.mkdir(parents=True)
+    venv_py.write_text("#!/bin/sh\nexit 0\n")
+    venv_py.chmod(0o755)
+    monkeypatch.setenv("MLX_MOVIE_DIRECTOR_DIR", str(mlx_dir))
+    monkeypatch.delenv("MLX_VENV_PYTHON", raising=False)
+    # Force the socket probe to fail without touching the network.
+    monkeypatch.setattr("tools._mlx.env.lm_studio_reachable", lambda **_: False)
+    env = MLXCaption._resolve_env()
+    assert env["ok"] is False
+    assert "LM Studio" in env["reason"]
+    assert MLXCaption().get_status() == ToolStatus.UNAVAILABLE
+
+
+def test_status_available_with_full_env_and_lm_studio(monkeypatch, tmp_path):
+    """MLX runtime + LM Studio reachable → AVAILABLE (no model-dir requirement)."""
+    mlx_dir = tmp_path / "mlx_repo"
+    (mlx_dir / "python" / "mlx-movie-director").mkdir(parents=True)
+    (mlx_dir / "python" / "mlx-movie-director" / "run.py").write_text("# stub")
+    venv_py = mlx_dir / "python" / "venv" / "bin" / "python"
+    venv_py.parent.mkdir(parents=True)
+    venv_py.write_text("#!/bin/sh\nexit 0\n")
+    venv_py.chmod(0o755)
+    monkeypatch.setenv("MLX_MOVIE_DIRECTOR_DIR", str(mlx_dir))
+    monkeypatch.delenv("MLX_VENV_PYTHON", raising=False)
+    monkeypatch.setattr("tools._mlx.env.lm_studio_reachable", lambda **_: True)
+    # NOTE: no mlx-models/transformer+vae staged — caption must NOT require them.
+    env = MLXCaption._resolve_env()
+    assert env["ok"] is True, env.get("reason")
+
+
+def test_caption_does_not_require_generation_models(monkeypatch, tmp_path):
+    """need_models=False: an env that would FAIL mlx_image (no models) is fine here."""
+    mlx_dir = tmp_path / "mlx_repo"
+    (mlx_dir / "python" / "mlx-movie-director").mkdir(parents=True)
+    (mlx_dir / "python" / "mlx-movie-director" / "run.py").write_text("# stub")
+    venv_py = mlx_dir / "python" / "venv" / "bin" / "python"
+    venv_py.parent.mkdir(parents=True)
+    venv_py.write_text("#!/bin/sh\nexit 0\n")
+    venv_py.chmod(0o755)
+    monkeypatch.setenv("MLX_MOVIE_DIRECTOR_DIR", str(mlx_dir))
+    monkeypatch.delenv("MLX_VENV_PYTHON", raising=False)
+    monkeypatch.setattr("tools._mlx.env.lm_studio_reachable", lambda **_: True)
+    # mlx_image would be UNAVAILABLE (no transformer/vae staged); caption is fine.
+    from tools.graphics.mlx_image import MLXImage
+    assert MLXImage._resolve_env()["ok"] is False
+    assert MLXCaption._resolve_env()["ok"] is True
+
+
+# --------------------------------------------------------------------------
+# CLI argument building (no subprocess)
+# --------------------------------------------------------------------------
+
+@pytest.mark.parametrize(
+    "inputs, expected_flags",
+    [
+        ({}, ["--style", "photography", "--lang", "en"]),
+        ({"style": "score"}, ["--style", "score", "--lang", "en"]),
+        ({"style": ["photography", "t2i"]}, ["--style", "photography", "t2i", "--lang", "en"]),
+        ({"lang": "zh_TW"}, ["--style", "photography", "--lang", "zh_TW"]),
+        (
+            {"style": "video_analysis", "lang": "en", "model": "qwen3-vl-4b"},
+            ["--style", "video_analysis", "--lang", "en", "--model", "qwen3-vl-4b"],
+        ),
+        (
+            {"style": "score", "api_url": "http://host:8080/v1"},
+            ["--style", "score", "--lang", "en", "--api-url", "http://host:8080/v1"],
+        ),
+    ],
+)
+def test_build_args(inputs, expected_flags):
+    assert MLXCaption._build_args(inputs) == expected_flags
+
+
+def test_build_args_rejects_non_string_style():
+    with pytest.raises(_BadInput):
+        MLXCaption._build_args({"style": 123})
+
+
+# --------------------------------------------------------------------------
+# Output parsing (no subprocess)
+# --------------------------------------------------------------------------
+
+def test_parse_output_styles_map_shape():
+    """run.py writes {styles: {<style>: <text>}}; we surface the map + joined text."""
+    payload = {"styles": {"photography": "cinematic, warm light", "score": 8.5}}
+    tmp = Path(_write_tmp(payload))
+    styles_map, text = MLXCaption._parse_output(str(tmp))
+    tmp.unlink()
+    assert styles_map["photography"] == "cinematic, warm light"
+    assert styles_map["score"] == 8.5
+    assert text == "cinematic, warm light"  # numeric-score style excluded from text join
+
+
+def test_parse_output_flat_legacy_shape():
+    """Older caption files may be a flat {<style>: <text>} dict."""
+    tmp = Path(_write_tmp({"t2i": "a red cube on a table"}))
+    styles_map, text = MLXCaption._parse_output(str(tmp))
+    tmp.unlink()
+    assert styles_map == {"t2i": "a red cube on a table"}
+    assert text == "a red cube on a table"
+
+
+def test_parse_output_dict_value_with_text_field():
+    payload = {"styles": {"review": {"text": "good composition", "score": 9}}}
+    tmp = Path(_write_tmp(payload))
+    styles_map, text = MLXCaption._parse_output(str(tmp))
+    tmp.unlink()
+    assert text == "good composition"
+
+
+def test_parse_output_missing_file_returns_empty(tmp_path):
+    styles_map, text = MLXCaption._parse_output(str(tmp_path / "nope.json"))
+    assert styles_map == {} and text == ""
+
+
+def _write_tmp(payload: dict) -> str:
+    import tempfile
+
+    fd, path = tempfile.mkstemp(suffix=".json")
+    with os.fdopen(fd, "w") as fh:
+        json.dump(payload, fh)
+    return path
diff --git a/tools/_mlx/__init__.py b/tools/_mlx/__init__.py
new file mode 100644
index 000000000..21a773f76
--- /dev/null
+++ b/tools/_mlx/__init__.py
@@ -0,0 +1,12 @@
+"""Shared helpers for the MLX provider family (``mlx_image`` / ``mlx_video`` /
+``mlx_caption``).
+
+All three bridge OpenMontage capabilities to the sibling ``mlx-movie-director``
+runtime (``python/mlx-movie-director/run.py``) on Apple Silicon. They share the
+same environment contract (``MLX_MOVIE_DIRECTOR_DIR`` + venv + run.py), so the
+resolution logic lives here once — see ``resolve_mlx_env()``.
+
+Factored out of ``tools/graphics/mlx_image.py`` and ``tools/video/mlx_video.py``
+(per a TODO both files carried: "If a third MLX provider appears, factor into
+tools/_mlx/env.py"). The third provider is ``mlx_caption``.
+"""
diff --git a/tools/_mlx/env.py b/tools/_mlx/env.py
new file mode 100644
index 000000000..5312d97da
--- /dev/null
+++ b/tools/_mlx/env.py
@@ -0,0 +1,158 @@
+"""Shared MLX-runtime environment resolution for the ``mlx_*`` provider family.
+
+Every MLX provider shells out to the sibling ``mlx-movie-director`` repo's
+``run.py``. The availability contract is identical across them, so it is defined
+once here and the providers delegate via ``resolve_mlx_env()``.
+
+Env contract (mirrors the MLX repo's own CLAUDE.md):
+
+* ``MLX_MOVIE_DIRECTOR_DIR``  — repo root containing ``python/mlx-movie-director/run.py``.
+* ``MLX_VENV_PYTHON``         — the MLX venv interpreter (default
+  ``<MLX_MOVIE_DIRECTOR_DIR>/python/venv/bin/python``). Per-machine, NOT auto-created.
+
+The resolution is pure filesystem (+ an optional LM Studio socket probe for the
+caption provider) — no subprocess spawn, so ``get_status()`` stays cheap.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import socket
+from typing import Any
+
+# Where the MLX repo lives. Configured by the OM deployment; the provider is
+# UNAVAILABLE without it (we do not guess a sibling path — explicit config only).
+MLX_DIR_ENV = "MLX_MOVIE_DIRECTOR_DIR"
+MLX_PYTHON_ENV = "MLX_VENV_PYTHON"
+
+# Relative layout inside the MLX repo (stable per the MLX repo's CLAUDE.md).
+RUN_PY_REL = "python/mlx-movie-director/run.py"
+VENV_PYTHON_REL = "python/venv/bin/python"
+MODELS_REL = "mlx-models"
+
+# Subdirectories under mlx-models/ whose presence implies at least one usable
+# generation model is staged. transformer + vae are the minimum stack. Only the
+# generation providers (mlx_image / mlx_video) need this — caption does not.
+REQUIRED_MODEL_SUBDIRS = ("transformer", "vae")
+
+# LM Studio (the local VLM server that run.py `caption` talks to). The caption
+# provider needs this reachable; generation providers do not.
+LM_STUDIO_HOST = "localhost"
+LM_STUDIO_PORT = 1234
+LM_STUDIO_URL = f"http://{LM_STUDIO_HOST}:{LM_STUDIO_PORT}/v1"
+
+
+def lm_studio_reachable(timeout: float = 0.5) -> bool:
+	"""True if a TCP connection to the LM Studio server port succeeds.
+
+	Cheap socket probe (no HTTP) — used by ``mlx_caption``'s availability gate so
+	the menu can show ANALYZE::mlx as unavailable when LM Studio isn't running,
+	rather than failing at execute() time.
+	"""
+	try:
+		with socket.create_connection((LM_STUDIO_HOST, LM_STUDIO_PORT), timeout=timeout):
+			return True
+	except OSError:
+		return False
+
+
+def resolve_mlx_env(
+	*,
+	need_models: bool = True,
+	need_lm_studio: bool = False,
+) -> dict[str, Any]:
+	"""Resolve the MLX repo dir + venv interpreter (+ optional checks).
+
+	Returns a dict with: ``mlx_dir``, ``run_py``, ``venv_python``, ``arm64``,
+	``ok`` (bool), ``reason`` (str when not ok). Pure filesystem + socket — no
+	subprocess spawn, so ``get_status()`` stays cheap.
+
+	Parameters
+	----------
+	need_models:
+		Generation providers (mlx_image / mlx_video) require the ``mlx-models``
+		stack staged AND Apple Silicon. Caption does not (it talks to LM Studio).
+	need_lm_studio:
+		The caption provider requires LM Studio listening on localhost:1234.
+		Generation providers do not.
+	"""
+	mlx_dir = os.environ.get(MLX_DIR_ENV)
+	arm64 = platform.machine() in ("arm64", "aarch64")
+
+	if not mlx_dir:
+		return {
+			"ok": False,
+			"reason": f"{MLX_DIR_ENV} is not set (point it at the mlx-movie-director repo root).",
+			"arm64": arm64,
+		}
+	mlx_dir = os.path.expanduser(mlx_dir)
+	run_py = os.path.join(mlx_dir, RUN_PY_REL)
+	if not os.path.isfile(run_py):
+		return {
+			"ok": False,
+			"reason": f"{MLX_DIR_ENV}={mlx_dir} has no {RUN_PY_REL}.",
+			"arm64": arm64,
+			"mlx_dir": mlx_dir,
+		}
+
+	venv_python = os.environ.get(MLX_PYTHON_ENV) or os.path.join(mlx_dir, VENV_PYTHON_REL)
+	if not os.path.isfile(venv_python):
+		return {
+			"ok": False,
+			"reason": (
+				f"MLX venv interpreter not found at {venv_python}. Recreate it: "
+				f"uv venv {mlx_dir}/python/venv --python 3.12 && "
+				f"uv pip install -r {mlx_dir}/python/mlx-movie-director/requirements.txt "
+				f"--python {mlx_dir}/python/venv/bin/python"
+			),
+			"arm64": arm64,
+			"mlx_dir": mlx_dir,
+			"run_py": run_py,
+		}
+
+	if need_models:
+		models_dir = os.path.join(mlx_dir, MODELS_REL)
+		missing_subdirs = [s for s in REQUIRED_MODEL_SUBDIRS if not os.path.isdir(os.path.join(models_dir, s))]
+		if missing_subdirs:
+			return {
+				"ok": False,
+				"reason": (
+					f"MLX models incomplete under {models_dir}: missing {missing_subdirs}. "
+					f"Stage models before use."
+				),
+				"arm64": arm64,
+				"mlx_dir": mlx_dir,
+				"run_py": run_py,
+				"venv_python": venv_python,
+			}
+		if not arm64:
+			return {
+				"ok": False,
+				"reason": f"MLX runs on Apple Silicon only (got {platform.machine()}).",
+				"arm64": False,
+				"mlx_dir": mlx_dir,
+				"run_py": run_py,
+				"venv_python": venv_python,
+			}
+
+	if need_lm_studio and not lm_studio_reachable():
+		return {
+			"ok": False,
+			"reason": (
+				f"LM Studio not reachable at {LM_STUDIO_URL}. Start it and load a "
+				f"vision model (e.g. Qwen3-VL 4B) — run.py `caption` talks to it."
+			),
+			"arm64": arm64,
+			"mlx_dir": mlx_dir,
+			"run_py": run_py,
+			"venv_python": venv_python,
+		}
+
+	return {
+		"ok": True,
+		"arm64": arm64,
+		"mlx_dir": mlx_dir,
+		"run_py": run_py,
+		"venv_python": venv_python,
+	}
diff --git a/tools/analysis/mlx_caption.py b/tools/analysis/mlx_caption.py
new file mode 100644
index 000000000..a7e1f03f5
--- /dev/null
+++ b/tools/analysis/mlx_caption.py
@@ -0,0 +1,383 @@
+"""MLX image/video understanding via the sibling ``mlx-movie-director`` runtime.
+
+Bridges OpenMontage's ``analysis`` capability to the local VLM served by LM
+Studio (Qwen3-VL 4B by default), invoked through ``python/mlx-movie-director/
+run.py caption``. This is the analysis analog of ``mlx_image`` / ``mlx_video``:
+the third leg of the MLX-runtime trio (image gen + video gen + VLM analysis),
+all talking to the same Apple-Silicon-native runtime.
+
+Why this provider exists alongside ``video_understand`` (also a local VLM):
+``video_understand`` drives a HuggingFace ``transformers`` VLM directly (needs a
+downloaded model + GPU/torch). ``mlx_caption`` talks to an *already-running* LM
+Studio server loading an MLX-quantized model — the same server the
+mlx-movie-director runtime itself uses, so a production Apple-Silicon box that
+serves ``mlx_image``/``mlx_video`` already has it up. It is the $0, offline,
+private, no-extra-download vision path.
+
+Contract (mirrors mlx_image/mlx_video — env resolution is shared via
+``tools/_mlx/env.py``):
+
+* ``MLX_MOVIE_DIRECTOR_DIR``  — repo root containing ``python/mlx-movie-director/run.py``.
+* ``MLX_VENV_PYTHON``         — the MLX venv interpreter.
+* LM Studio reachable at ``http://localhost:1234/v1`` with a vision model loaded
+  (e.g. Qwen3-VL 4B). The availability gate socket-probes this port.
+
+run.py writes the caption to a JSON file (``--output``) with a ``styles`` map —
+one entry per requested style (e.g. ``photography``, ``score``,
+``video_analysis``). We surface that map verbatim plus a joined ``text`` field.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+import time
+from pathlib import Path
+from typing import Any
+
+from tools._mlx.env import LM_STUDIO_URL, resolve_mlx_env
+from tools.base_tool import (
+    BaseTool,
+    Determinism,
+    ExecutionMode,
+    ResourceProfile,
+    RetryPolicy,
+    ToolResult,
+    ToolRuntime,
+    ToolStability,
+    ToolStatus,
+    ToolTier,
+)
+
+# Styles accepted by `run.py caption --style` (see app/commands/caption.py
+# _STYLE_PROMPTS). Kept as a closed enum so the selector + caller see a stable
+# surface; run.py itself is the authority (it rejects unknown styles).
+_CAPTION_STYLES = (
+    "t2i",
+    "photography",
+    "profile",
+    "style",
+    "score",
+    "video_score",
+    "video_analysis",
+    "compare",
+    "review",
+    "playwright",
+    "lora_quality",
+    "ltx_i2v",
+    "pose_dsg",
+)
+_LANGS = ("en", "zh_TW", "ja")
+
+
+class MLXCaption(BaseTool):
+    name = "mlx_caption"
+    version = "0.1.0"
+    tier = ToolTier.ANALYZE
+    capability = "analysis"
+    provider = "mlx"
+    stability = ToolStability.EXPERIMENTAL
+    execution_mode = ExecutionMode.SYNC
+    determinism = Determinism.DETERMINISTIC  # VLM at temp 0 is effectively deterministic
+    runtime = ToolRuntime.LOCAL_GPU  # the VLM runs on-GPU via the LM Studio server
+
+    dependencies = []  # resolved at runtime via _resolve_env()
+    install_instructions = (
+        "Set MLX_MOVIE_DIRECTOR_DIR to the mlx-movie-director repo root "
+        "(contains python/mlx-movie-director/run.py).\n"
+        "Optionally set MLX_VENV_PYTHON to its venv interpreter (default "
+        "<MLX_MOVIE_DIRECTOR_DIR>/python/venv/bin/python).\n"
+        "The MLX venv is per-machine and NOT auto-created — recreate it with:\n"
+        "  uv venv python/venv --python 3.12\n"
+        "  uv pip install -r python/mlx-movie-director/requirements.txt "
+        "--python python/venv/bin/python\n"
+        "Then start LM Studio, load a vision model (e.g. Qwen3-VL 4B), and "
+        "enable its local server (default http://localhost:1234/v1).\n"
+        "Requires Apple Silicon (arm64) for the mlx-movie-director runtime."
+    )
+    agent_skills = ["mlx-movie-director"]
+
+    capabilities = [
+        "image_understanding",
+        "video_understanding",
+        "quality_scoring",
+        "vision",
+    ]
+    # The analysis-tier analog of mlx_image's control surface: the only provider
+    # that serves vision understanding from an already-running local LM Studio
+    # (video_understand downloads + loads a transformers model each run).
+    supports = {
+        "offline": True,
+        "local": True,
+        "vision": True,
+        "image_understanding": True,
+        "video_understanding": True,
+        "quality_scoring": True,
+    }
+    best_for = [
+        "local, $0, private image/video understanding via LM Studio (Qwen3-VL)",
+        "VLM quality scoring of generated frames (style 'score' / 'video_score')",
+        "scene/shot analysis for automated review (style 'video_analysis')",
+        "describing a reference image to seed a t2i/i2v prompt (style 't2i'/'photography')",
+    ]
+    not_good_for = [
+        "hosts without LM Studio running a vision model",
+        "setups without the MLX venv recreated (see install_instructions)",
+    ]
+    fallback = "video_understand"
+    fallback_tools = ["video_understand", "visual_qa"]
+
+    input_schema = {
+        "type": "object",
+        "required": ["image"],
+        "properties": {
+            "image": {
+                "type": "string",
+                "description": "Path to the image (or video) to analyze.",
+            },
+            "style": {
+                "anyOf": [
+                    {"type": "string", "enum": list(_CAPTION_STYLES)},
+                    {"type": "array", "items": {"type": "string", "enum": list(_CAPTION_STYLES)}},
+                ],
+                "description": (
+                    "Caption style(s). run.py accepts one OR MORE. Common: "
+                    "'photography' (art-style desc), 't2i' (prompt-ready desc), "
+                    "'score'/'video_score' (quality score), 'video_analysis', "
+                    "'review'. Default 'photography'."
+                ),
+            },
+            "lang": {
+                "type": "string",
+                "enum": list(_LANGS),
+                "description": "Output language (default 'en').",
+            },
+            "model": {
+                "type": "string",
+                "description": "Override the LM Studio vision model id (default: server-loaded).",
+            },
+            "api_url": {
+                "type": "string",
+                "description": f"Override the LM Studio OpenAI-compatible endpoint (default {LM_STUDIO_URL}).",
+            },
+            "output_path": {
+                "type": "string",
+                "description": "Where to save the caption JSON (default: a temp file, returned in data).",
+            },
+        },
+    }
+
+    resource_profile = ResourceProfile(
+        cpu_cores=2, ram_mb=4000, vram_mb=0, disk_mb=100, network_required=False,
+    )
+    retry_policy = RetryPolicy(max_retries=1, retryable_errors=["timeout"])
+    idempotency_key_fields = ["image", "style", "lang", "model"]
+    side_effects = ["spawns python/venv/bin/python run.py caption …", "writes caption JSON"]
+    user_visible_verification = ["Inspect the returned caption text for accuracy."]
+
+    # ------------------------------------------------------------------
+    # Environment + availability
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _resolve_env() -> dict[str, Any]:
+        """Resolve MLX runtime + LM Studio reachability.
+
+        Delegates to ``tools/_mlx/env.py`` with need_models=False (caption talks
+        to LM Studio, not the mlx-models generation stack) and need_lm_studio=True
+        (socket-probes localhost:1234).
+        """
+        return resolve_mlx_env(need_models=False, need_lm_studio=True)
+
+    def get_status(self) -> ToolStatus:
+        return ToolStatus.AVAILABLE if self._resolve_env()["ok"] else ToolStatus.UNAVAILABLE
+
+    def estimate_cost(self, inputs: dict[str, Any]) -> float:
+        return 0.0
+
+    def estimate_runtime(self, inputs: dict[str, Any]) -> float:
+        # Qwen3-VL 4B caption: ~3-8s for an image, ~10-25s for a video sample.
+        image = str(inputs.get("image", ""))
+        return 20.0 if any(image.lower().endswith(ext) for ext in (".mp4", ".mov", ".webm", ".gif")) else 6.0
+
+    def get_info(self) -> dict[str, Any]:
+        info = super().get_info()
+        env = self._resolve_env()
+        info["mlx_env"] = {
+            "configured": env["ok"],
+            "reason": env.get("reason"),
+            "arm64": env.get("arm64"),
+            "mlx_dir": env.get("mlx_dir"),
+            "venv_python": env.get("venv_python"),
+            "lm_studio_url": LM_STUDIO_URL,
+        }
+        return info
+
+    # ------------------------------------------------------------------
+    # Execute
+    # ------------------------------------------------------------------
+
+    def execute(self, inputs: dict[str, Any]) -> ToolResult:
+        env = self._resolve_env()
+        if not env["ok"]:
+            return ToolResult(success=False, error=env["reason"])
+
+        run_py = env["run_py"]
+        venv_python = env["venv_python"]
+
+        image = inputs.get("image")
+        if not image:
+            return ToolResult(success=False, error="image is required.")
+        image_path = Path(os.path.expanduser(str(image)))
+        if not image_path.is_file():
+            return ToolResult(success=False, error=f"image not found: {image}")
+
+        cmd: list[str] = [venv_python, run_py, "caption", str(image_path)]
+        cmd += self._build_args(inputs)
+
+        # Deterministic output path so we can read the result back.
+        out_json = tempfile.NamedTemporaryFile(
+            prefix="mlx_caption_", suffix=".json", delete=False
+        )
+        out_json.close()
+        cmd += ["--output", out_json.name]
+
+        start = time.time()
+        try:
+            proc = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=300,
+                check=False,
+            )
+        except subprocess.TimeoutExpired:
+            os.unlink(out_json.name)
+            return ToolResult(success=False, error="MLX caption timed out (>300s).")
+        except Exception as exc:  # pragma: no cover — defensive
+            os.unlink(out_json.name)
+            return ToolResult(success=False, error=f"Failed to spawn MLX runtime: {exc}")
+
+        elapsed = round(time.time() - start, 2)
+
+        if proc.returncode != 0:
+            os.unlink(out_json.name)
+            tail = (proc.stderr or proc.stdout or "").strip().splitlines()[-12:]
+            return ToolResult(
+                success=False,
+                error=f"run.py caption exited {proc.returncode}:\n" + "\n".join(tail),
+            )
+
+        styles_map, joined_text = self._parse_output(out_json.name)
+        if not styles_map:
+            os.unlink(out_json.name)
+            tail = (proc.stderr or proc.stdout or "").strip().splitlines()[-12:]
+            return ToolResult(
+                success=False,
+                error="run.py caption produced no caption output:\n" + "\n".join(tail),
+            )
+
+        # Persist to a caller-chosen path if requested.
+        final_json = out_json.name
+        output_path = inputs.get("output_path")
+        if output_path:
+            dest = Path(output_path)
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            if dest.resolve() != Path(final_json).resolve():
+                shutil.copy2(final_json, dest)
+            os.unlink(final_json)
+            final_json = str(dest)
+        else:
+            # Keep the temp file only if no explicit destination; unlink the temp
+            # handle but leave the JSON on disk under output_path semantics.
+            # (Caller gets the full map via data, so the temp file is redundant.)
+            os.unlink(final_json)
+            final_json = ""
+
+        model = inputs.get("model") or "qwen3-vl (lm-studio)"
+        return ToolResult(
+            success=True,
+            data={
+                "provider": "mlx",
+                "model": model,
+                "image": str(image_path),
+                "styles": styles_map,
+                "text": joined_text,
+                "lang": inputs.get("lang", "en"),
+                "lm_studio_url": inputs.get("api_url", LM_STUDIO_URL),
+            },
+            artifacts=[final_json] if final_json else [],
+            cost_usd=0.0,
+            duration_seconds=elapsed,
+            model=model,
+        )
+
+    # ------------------------------------------------------------------
+    # Argument mapping + output parsing
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _build_args(inputs: dict[str, Any]) -> list[str]:
+        """Map provider inputs to run.py caption CLI flags."""
+        out: list[str] = []
+
+        styles = inputs.get("style", "photography")
+        if isinstance(styles, str):
+            styles = [styles]
+        elif not isinstance(styles, list):
+            raise _BadInput("style must be a string or array of style strings.")
+        if not styles:
+            styles = ["photography"]
+        # run.py --style is nargs="+": each style as its own token after the flag.
+        out += ["--style", *styles]
+
+        if inputs.get("lang"):
+            out += ["--lang", str(inputs["lang"])]
+        else:
+            out += ["--lang", "en"]
+
+        if inputs.get("model"):
+            out += ["--model", str(inputs["model"])]
+        if inputs.get("api_url"):
+            out += ["--api-url", str(inputs["api_url"])]
+
+        return out
+
+    @staticmethod
+    def _parse_output(out_json: str) -> tuple[dict[str, Any], str]:
+        """Read the caption JSON. Returns (styles_map, joined_plain_text).
+
+        run.py writes a dict with a ``styles`` key (style → text/score). Older
+        files may be flat; we normalize both. ``text`` joins the non-score style
+        values for callers that just want a single description string.
+        """
+        try:
+            with open(out_json, "r", encoding="utf-8") as fh:
+                payload = json.load(fh)
+        except (OSError, json.JSONDecodeError):
+            return {}, ""
+
+        styles_map: dict[str, Any]
+        if isinstance(payload.get("styles"), dict):
+            styles_map = payload["styles"]
+        elif isinstance(payload, dict) and all(isinstance(k, str) for k in payload):
+            # Flat legacy shape: top-level keys are styles.
+            styles_map = payload
+        else:
+            return {}, ""
+
+        # Join textual styles; skip numeric score-only entries.
+        text_parts: list[str] = []
+        for _style, value in styles_map.items():
+            if isinstance(value, str):
+                text_parts.append(value)
+            elif isinstance(value, dict) and isinstance(value.get("text"), str):
+                text_parts.append(value["text"])
+        return styles_map, "\n\n".join(text_parts).strip()
+
+
+class _BadInput(Exception):
+    """Raised when provider inputs cannot map cleanly to run.py flags."""
diff --git a/tools/graphics/mlx_image.py b/tools/graphics/mlx_image.py
index bcf01f02a..803b39daa 100644
--- a/tools/graphics/mlx_image.py
+++ b/tools/graphics/mlx_image.py
@@ -27,7 +27,6 @@
 
 import json
 import os
-import platform
 import re
 import shutil
 import subprocess
@@ -48,20 +47,10 @@
     ToolStatus,
     ToolTier,
 )
+from tools._mlx.env import resolve_mlx_env
 
-# Where the MLX repo lives. Configured by the OM deployment; the provider is
-# UNAVAILABLE without it (we do not guess a sibling path — explicit config only).
-_MLX_DIR_ENV = "MLX_MOVIE_DIRECTOR_DIR"
-_MLX_PYTHON_ENV = "MLX_VENV_PYTHON"
-
-# Relative layout inside the MLX repo (stable per the MLX repo's CLAUDE.md).
-_RUN_PY_REL = "python/mlx-movie-director/run.py"
-_VENV_PYTHON_REL = "python/venv/bin/python"
-_MODELS_REL = "mlx-models"
-
-# Subdirectories under mlx-models/ whose presence implies at least one usable
-# image-generation model is staged. transformer + vae are the minimum stack.
-_REQUIRED_MODEL_SUBDIRS = ("transformer", "vae")
+# Env constants + resolution live in tools/_mlx/env.py (shared with mlx_video +
+# mlx_caption). Only the JSON-summary marker is local to image generation.
 
 # The stdout marker emitted by `run.py ... --json-summary` (see
 # app/commands/_shared.py:681 — execute_generation prints "JSON_SUMMARY:{...}").
@@ -211,76 +200,12 @@ class MLXImage(BaseTool):
     def _resolve_env() -> dict[str, Any]:
         """Resolve MLX repo dir + venv interpreter + presence flags.
 
-        Returns a dict with: mlx_dir, run_py, venv_python, arm64, ok (bool),
-        reason (str when not ok). Pure filesystem checks — no subprocess spawn,
-        so get_status() stays cheap.
+        Delegates to the shared ``tools/_mlx/env.py`` resolver (need_models=True
+        — image generation needs the mlx-models stack + Apple Silicon). Returns
+        a dict with: mlx_dir, run_py, venv_python, arm64, ok (bool), reason (str
+        when not ok). Pure filesystem checks — no subprocess spawn.
         """
-        mlx_dir = os.environ.get(_MLX_DIR_ENV)
-        arm64 = platform.machine() in ("arm64", "aarch64")
-
-        if not mlx_dir:
-            return {
-                "ok": False,
-                "reason": f"{_MLX_DIR_ENV} is not set (point it at the mlx-movie-director repo root).",
-                "arm64": arm64,
-            }
-        mlx_dir = os.path.expanduser(mlx_dir)
-        run_py = os.path.join(mlx_dir, _RUN_PY_REL)
-        if not os.path.isfile(run_py):
-            return {
-                "ok": False,
-                "reason": f"{_MLX_DIR_ENV}={mlx_dir} has no {_RUN_PY_REL}.",
-                "arm64": arm64,
-                "mlx_dir": mlx_dir,
-            }
-
-        venv_python = os.environ.get(_MLX_PYTHON_ENV) or os.path.join(mlx_dir, _VENV_PYTHON_REL)
-        if not os.path.isfile(venv_python):
-            return {
-                "ok": False,
-                "reason": (
-                    f"MLX venv interpreter not found at {venv_python}. Recreate it: "
-                    f"uv venv {mlx_dir}/python/venv --python 3.12 && "
-                    f"uv pip install -r {mlx_dir}/python/mlx-movie-director/requirements.txt "
-                    f"--python {mlx_dir}/python/venv/bin/python"
-                ),
-                "arm64": arm64,
-                "mlx_dir": mlx_dir,
-                "run_py": run_py,
-            }
-
-        models_dir = os.path.join(mlx_dir, _MODELS_REL)
-        missing_subdirs = [s for s in _REQUIRED_MODEL_SUBDIRS if not os.path.isdir(os.path.join(models_dir, s))]
-        if missing_subdirs:
-            return {
-                "ok": False,
-                "reason": (
-                    f"MLX models incomplete under {models_dir}: missing {missing_subdirs}. "
-                    f"Stage models before use."
-                ),
-                "arm64": arm64,
-                "mlx_dir": mlx_dir,
-                "run_py": run_py,
-                "venv_python": venv_python,
-            }
-
-        if not arm64:
-            return {
-                "ok": False,
-                "reason": f"MLX runs on Apple Silicon only (got {platform.machine()}).",
-                "arm64": False,
-                "mlx_dir": mlx_dir,
-                "run_py": run_py,
-                "venv_python": venv_python,
-            }
-
-        return {
-            "ok": True,
-            "arm64": True,
-            "mlx_dir": mlx_dir,
-            "run_py": run_py,
-            "venv_python": venv_python,
-        }
+        return resolve_mlx_env(need_models=True)
 
     def get_status(self) -> ToolStatus:
         env = self._resolve_env()
diff --git a/tools/video/mlx_video.py b/tools/video/mlx_video.py
index a176c90a1..76dd768ec 100644
--- a/tools/video/mlx_video.py
+++ b/tools/video/mlx_video.py
@@ -33,7 +33,6 @@
 
 import json
 import os
-import platform
 import re
 import shutil
 import subprocess
@@ -54,16 +53,11 @@
     ToolStatus,
     ToolTier,
 )
+from tools._mlx.env import resolve_mlx_env
 
-# Env contract (mirrors mlx_image; copied rather than imported to keep this a
-# one-file add — no cross-tool graphics↔video coupling. If a third MLX provider
-# appears, factor into tools/_mlx/env.py).
-_MLX_DIR_ENV = "MLX_MOVIE_DIRECTOR_DIR"
-_MLX_PYTHON_ENV = "MLX_VENV_PYTHON"
-_RUN_PY_REL = "python/mlx-movie-director/run.py"
-_VENV_PYTHON_REL = "python/venv/bin/python"
-_MODELS_REL = "mlx-models"
-_REQUIRED_MODEL_SUBDIRS = ("transformer", "vae")
+# Env contract + resolution live in tools/_mlx/env.py (shared with mlx_image +
+# mlx_caption). Only the video-specific frame-count + output-extension
+# constants are local to this file.
 
 # LTX-2.3 output extensions (broader than mlx_image's image set).
 _VIDEO_EXTS = ("*.mp4", "*.mov", "*.webm", "*.gif")
@@ -199,33 +193,9 @@ class MLXVideo(BaseTool):
 
     @staticmethod
     def _resolve_env() -> dict[str, Any]:
-        mlx_dir = os.environ.get(_MLX_DIR_ENV)
-        arm64 = platform.machine() in ("arm64", "aarch64")
-        if not mlx_dir:
-            return {"ok": False, "reason": f"{_MLX_DIR_ENV} is not set (point it at the mlx-movie-director repo root).", "arm64": arm64}
-        mlx_dir = os.path.expanduser(mlx_dir)
-        run_py = os.path.join(mlx_dir, _RUN_PY_REL)
-        if not os.path.isfile(run_py):
-            return {"ok": False, "reason": f"{_MLX_DIR_ENV}={mlx_dir} has no {_RUN_PY_REL}.", "arm64": arm64, "mlx_dir": mlx_dir}
-        venv_python = os.environ.get(_MLX_PYTHON_ENV) or os.path.join(mlx_dir, _VENV_PYTHON_REL)
-        if not os.path.isfile(venv_python):
-            return {
-                "ok": False,
-                "reason": (
-                    f"MLX venv interpreter not found at {venv_python}. Recreate it: "
-                    f"uv venv {mlx_dir}/python/venv --python 3.12 && "
-                    f"uv pip install -r {mlx_dir}/python/mlx-movie-director/requirements.txt "
-                    f"--python {mlx_dir}/python/venv/bin/python"
-                ),
-                "arm64": arm64, "mlx_dir": mlx_dir, "run_py": run_py,
-            }
-        models_dir = os.path.join(mlx_dir, _MODELS_REL)
-        missing = [s for s in _REQUIRED_MODEL_SUBDIRS if not os.path.isdir(os.path.join(models_dir, s))]
-        if missing:
-            return {"ok": False, "reason": f"MLX models incomplete under {models_dir}: missing {missing}.", "arm64": arm64, "mlx_dir": mlx_dir, "run_py": run_py, "venv_python": venv_python}
-        if not arm64:
-            return {"ok": False, "reason": f"MLX runs on Apple Silicon only (got {platform.machine()}).", "arm64": False, "mlx_dir": mlx_dir, "run_py": run_py, "venv_python": venv_python}
-        return {"ok": True, "arm64": True, "mlx_dir": mlx_dir, "run_py": run_py, "venv_python": venv_python}
+        # Delegates to the shared resolver (need_models=True — video generation
+        # needs the mlx-models stack + Apple Silicon). See tools/_mlx/env.py.
+        return resolve_mlx_env(need_models=True)
 
     def get_status(self) -> ToolStatus:
         return ToolStatus.AVAILABLE if self._resolve_env()["ok"] else ToolStatus.UNAVAILABLE

From 491efafbb00744ad10eb132dba47bf5e8a1bee0d Mon Sep 17 00:00:00 2001
From: Ziyu Huang <ziyu4huang@gmail.com>
Date: Tue, 7 Jul 2026 05:25:09 +0800
Subject: [PATCH 4/5] test(mlx): mock Apple Silicon in available-path tests for
 CI portability
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The two test_status_available_with_full_env tests asserted env["ok"] is True
unconditionally, but resolve_mlx_env() correctly rejects non-Apple-Silicon
hosts (MLX runs on Apple Silicon only). So both tests failed on the Windows/
AMD64 review machine and on ubuntu x86_64 CI — the production code was right,
the tests were not portable.

Mock platform.machine() -> "arm64" inside these two tests so the full
available-path (including the arch guard) executes on ANY host, and drop the
now-stale `if env["arm64"]` skip-guard in favor of direct assertions. The
unavailable-path tests stay honest (they don't force arch).

Verified:
- real arm64:        70 passed (3 MLX suites)
- simulated AMD64:   66 passed, 4 skipped (unrelated caption/LM Studio), 0 failed
  — incl. both previously-failing tests green under the simulated host

Addresses calesthio review on #311 (CHANGES_REQUESTED).

Co-Authored-By: Claude <noreply@anthropic.com>
---
 tests/tools/test_mlx_image.py | 8 +++++---
 tests/tools/test_mlx_video.py | 7 +++++--
 2 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/tests/tools/test_mlx_image.py b/tests/tools/test_mlx_image.py
index 11955ce48..8684d519e 100644
--- a/tests/tools/test_mlx_image.py
+++ b/tests/tools/test_mlx_image.py
@@ -118,11 +118,13 @@ def test_status_available_with_full_env(monkeypatch, tmp_path):
         (mlx_dir / "mlx-models" / sub).mkdir(parents=True)
     monkeypatch.setenv("MLX_MOVIE_DIRECTOR_DIR", str(mlx_dir))
     monkeypatch.delenv("MLX_VENV_PYTHON", raising=False)
+    # Mock Apple Silicon so the full available-path (incl. the arch guard in
+    # resolve_mlx_env) runs on ANY CI host, not just native arm64 reviewers.
+    monkeypatch.setattr("tools._mlx.env.platform.machine", lambda: "arm64")
     env = MLXImage._resolve_env()
     assert env["ok"] is True, env.get("reason")
-    # arm64 is required — skip the status assertion on non-Apple-Silicon CI.
-    if env["arm64"]:
-        assert MLXImage().get_status() == ToolStatus.AVAILABLE
+    assert env["arm64"] is True
+    assert MLXImage().get_status() == ToolStatus.AVAILABLE
 
 
 # --------------------------------------------------------------------------
diff --git a/tests/tools/test_mlx_video.py b/tests/tools/test_mlx_video.py
index 8d644a98f..5f7702bde 100644
--- a/tests/tools/test_mlx_video.py
+++ b/tests/tools/test_mlx_video.py
@@ -118,10 +118,13 @@ def test_status_available_with_full_env(monkeypatch, tmp_path):
         (mlx_dir / "mlx-models" / sub).mkdir(parents=True)
     monkeypatch.setenv("MLX_MOVIE_DIRECTOR_DIR", str(mlx_dir))
     monkeypatch.delenv("MLX_VENV_PYTHON", raising=False)
+    # Mock Apple Silicon so the full available-path (incl. the arch guard in
+    # resolve_mlx_env) runs on ANY CI host, not just native arm64 reviewers.
+    monkeypatch.setattr("tools._mlx.env.platform.machine", lambda: "arm64")
     env = MLXVideo._resolve_env()
     assert env["ok"] is True, env.get("reason")
-    if env["arm64"]:
-        assert MLXVideo().get_status() == ToolStatus.AVAILABLE
+    assert env["arm64"] is True
+    assert MLXVideo().get_status() == ToolStatus.AVAILABLE
 
 
 # --------------------------------------------------------------------------

From b8331d8f72137678330564eaeedf66ce4731f71f Mon Sep 17 00:00:00 2001
From: Ziyu Huang <ziyu4huang@gmail.com>
Date: Tue, 7 Jul 2026 05:58:13 +0800
Subject: [PATCH 5/5] =?UTF-8?q?test(qa):=20MLX=20image-gen=20QA=20lane=20?=
 =?UTF-8?q?=E2=80=94=20t2i=20matrix=20+=20adversarial=20VLM=20scoring?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fills a QA slot for the mlx_image provider (shipped in feat/mlx-image-provider):
generates a small deterministic t2i matrix (portrait / still_life / hands — each
stresses a known weak spot) via the local MLX provider, then scores every output
with `run.py caption --style score --samples 3` (Qwen3-VL via LM Studio; median
of 3 samples to survive the local Gemma-4 VLM's image-dependent empty-response
flakiness). Writes per-image scores + flags to tests/qa/output/qa_image_gen_receipt.json
and leaves the PNGs for human inspection per the QA_PLAN protocol.

Dual purpose: (1) the QA_PLAN test_02 slot for local generation, and (2) a
regression gate for mlx_image — a score collapse or generation failure here
catches a provider/env regression before it reaches a user. Exit code is non-zero
only on generation/scoring FAILURE; low scores are flagged ⚠ (the scorer is
deliberately adversarial) but do not fail the run, since QA is human-inspected.

NOT CI pytest — needs MLX_MOVIE_DIRECTOR_DIR + mlx venv + staged models + Apple
Silicon + LM Studio on localhost:1234. All execution is under `if __name__`,
so pytest collection imports it cleanly and runs 0 tests.

Baseline receipt (mlx-zimage, this run):
  portrait   overall=6 artifacts=5 ⚠  (plasticky skin — known zimage base trait)
  still_life overall=9 artifacts=9     (excellent)
  hands      overall=6 artifacts=4 ⚠  (finger fusion — known AI weak spot)

Stacked on feat/mlx-image-provider (imports mlx_image); retarget to main once
that lands.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 tests/qa/QA_PLAN.md               |   2 +
 tests/qa/test_02_mlx_image_gen.py | 274 ++++++++++++++++++++++++++++++
 2 files changed, 276 insertions(+)
 create mode 100644 tests/qa/test_02_mlx_image_gen.py

diff --git a/tests/qa/QA_PLAN.md b/tests/qa/QA_PLAN.md
index 961fef860..aafd3e2f2 100644
--- a/tests/qa/QA_PLAN.md
+++ b/tests/qa/QA_PLAN.md
@@ -10,6 +10,7 @@ Run every tool with real API keys, inspect outputs (see images, listen to audio,
 |--------|-------------|---------------|-----------|
 | `test_01_tts.py` | `elevenlabs_tts` (ElevenLabs) | ELEVENLABS_API_KEY | ~$0.02 |
 | `test_02_image_gen.py` | `image_gen` (GPT Image 2 + FLUX) | OPENAI_API_KEY, FAL_AI_API_KEY | ~$0.15 |
+| `test_02_mlx_image_gen.py` | `mlx_image` t2i matrix + `run.py caption --style score` (local MLX + LM Studio VLM) | None (local Apple Silicon) | $0 |
 | `test_03_music.py` | `music_gen` (ElevenLabs) | ELEVENLABS_API_KEY | ~$0.10 |
 | `test_04_audio_mix.py` | `audio_mixer` | None (ffmpeg only) | $0 |
 | `test_05_video_compose.py` | `video_compose` | None (ffmpeg only) | $0 |
@@ -46,6 +47,7 @@ cd C:/Users/ishan/Documents/OpenMontage
 # Phase 1: Individual tools (can run in parallel)
 python tests/qa/test_01_tts.py
 python tests/qa/test_02_image_gen.py
+python tests/qa/test_02_mlx_image_gen.py   # local MLX only: MLX_MOVIE_DIRECTOR_DIR=... + LM Studio on :1234
 python tests/qa/test_03_music.py
 
 # Phase 2: Composition (depends on Phase 1 outputs)
diff --git a/tests/qa/test_02_mlx_image_gen.py b/tests/qa/test_02_mlx_image_gen.py
new file mode 100644
index 000000000..e15aa4a13
--- /dev/null
+++ b/tests/qa/test_02_mlx_image_gen.py
@@ -0,0 +1,274 @@
+#!/usr/bin/env python3
+"""QA Test 02: MLX image generation — t2i matrix + adversarial VLM scoring.
+
+Generates a small deterministic matrix of images via the local MLX provider
+(``mlx_image`` — shells out to the sibling mlx-movie-director ``run.py``;
+$0, Apple-Silicon-native), then scores each with ``run.py caption --style score``
+(Qwen3-VL via LM Studio). Produces, under ``tests/qa/output/``:
+
+  - the raw PNGs (for human inspection per the QA_PLAN protocol), and
+  - ``qa_image_gen_receipt.json`` — per-image scores + flags + gen metadata.
+
+This fills the ``test_02_image_gen.py`` slot in ``QA_PLAN.md`` AND serves as a
+regression gate for the ``mlx_image`` provider: a score collapse or generation
+failure here catches a provider/env regression before it reaches a user.
+
+NOT a CI pytest — it needs ``MLX_MOVIE_DIRECTOR_DIR`` + the mlx venv + staged
+models + Apple Silicon + LM Studio on localhost:1234. Run manually:
+
+    MLX_MOVIE_DIRECTOR_DIR=/path/to/video_generation \\
+        .venv/bin/python tests/qa/test_02_image_gen.py
+
+Exit code is non-zero only on a generation or scoring FAILURE (provider broke,
+caption broke). Low scores are flagged ⚠ in the table but do not fail the run —
+QA is human-inspected, and the adversarial scorer is deliberately harsh.
+"""
+
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent))
+
+from lib.env_loader import load_env  # noqa: E402
+
+load_env()
+
+from tools._mlx.env import resolve_mlx_env  # noqa: E402
+from tools.graphics.mlx_image import MLXImage  # noqa: E402
+
+OUT = os.path.join(os.path.dirname(__file__), "output")
+os.makedirs(OUT, exist_ok=True)
+RECEIPT = os.path.join(OUT, "qa_image_gen_receipt.json")
+
+# Adversarial-scorer advisory thresholds. The `score` style is deliberately
+# strict (it is told to FIND flaws, not praise), so these are soft flags, not
+# pass/fail gates. A consistent drop below these across the matrix is the real
+# regression signal — a single low image may just be a hard prompt.
+SOFT_OVERALL = 6
+SOFT_ARTIFACTS = 7
+
+# A small, deterministic matrix. Fixed seeds → reproducible regression baseline.
+# Each row stresses a different known weak spot (skin/hands/composition) so a
+# regression localizes instead of looking like a uniform dip.
+MATRIX = [
+    {
+        "tag": "portrait",
+        "prompt": (
+            "portrait of a young woman with freckles and loose hair, soft window "
+            "light from the left, shallow depth of field, neutral background, "
+            "photorealistic"
+        ),
+        "width": 1024,
+        "height": 1024,
+        "seed": 100,
+    },
+    {
+        "tag": "still_life",
+        "prompt": (
+            "a ceramic bowl of citrus fruit on a weathered wooden table, warm "
+            "morning sunlight, visible skin of the fruit, detailed texture, "
+            "photorealistic still life"
+        ),
+        "width": 1024,
+        "height": 1024,
+        "seed": 200,
+    },
+    {
+        "tag": "hands",
+        "prompt": (
+            "a barista's hands holding a ceramic latte cup with leaf latte art, "
+            "close-up, natural kitchen light, detailed fingers, photorealistic"
+        ),
+        "width": 1024,
+        "height": 1024,
+        "seed": 300,
+    },
+]
+
+
+def run_caption(run_py: str, venv_python: str, image: str) -> tuple[dict | None, float | None, str | None]:
+    """Score one image with `run.py caption --style score --samples 3`.
+
+    ``--samples 3`` runs 3 independent VLM passes and writes the per-dimension
+    MEDIAN — necessary because the local Gemma-4 VLM is image-dependent and can
+    return an empty response on a single pass. ``caption`` writes the canonical
+    structured result to ``<image>.caption.json`` (its stdout only echoes a
+    preview); we read that file and pull the score dict out of
+    ``styles["score"]["caption"]`` (a JSON-encoded string). Returns
+    ``(score_dict, elapsed_sec, error)``.
+    """
+    try:
+        proc = subprocess.run(
+            [venv_python, run_py, "caption", image, "--style", "score", "--samples", "3"],
+            capture_output=True,
+            text=True,
+            timeout=300,
+            check=False,
+        )
+    except subprocess.TimeoutExpired:
+        return None, None, "caption timed out (>180s)"
+    if proc.returncode != 0:
+        tail = (proc.stderr or proc.stdout or "").strip().splitlines()[-6:]
+        return None, None, f"caption rc={proc.returncode}:\n" + "\n".join(tail)
+
+    cap_json = Path(image).with_suffix(".caption.json")
+    if not cap_json.is_file():
+        return None, None, f"caption produced no {cap_json.name}"
+    try:
+        data = json.loads(cap_json.read_text())
+    except json.JSONDecodeError as exc:
+        return None, None, f"{cap_json.name} parse failed: {exc}"
+
+    style_block = (data.get("styles") or {}).get("score") or {}
+    raw = style_block.get("caption") or data.get("caption")
+    if not raw:
+        return None, None, f"{cap_json.name} has no score caption field"
+    try:
+        score = json.loads(raw) if isinstance(raw, str) else raw
+    except json.JSONDecodeError as exc:
+        return None, None, f"score caption JSON parse failed: {exc}"
+    return score, style_block.get("elapsed_sec"), None
+
+
+def main() -> int:
+    print("=" * 72)
+    print("QA Test 02: MLX image generation — t2i matrix + VLM scoring")
+    print("=" * 72)
+
+    # Resolve the MLX env once, requiring both generation (models + arm64) and
+    # caption (LM Studio). Fail fast with the provider's own reason if missing.
+    env = resolve_mlx_env(need_models=True, need_lm_studio=True)
+    if not env["ok"]:
+        print(f"\n✗ MLX env not ready: {env['reason']}")
+        print("  Set MLX_MOVIE_DIRECTOR_DIR, stage models, and start LM Studio (localhost:1234).")
+        return 1
+    run_py = env["run_py"]
+    venv_python = env["venv_python"]
+    print(f"  mlx_dir:     {env['mlx_dir']}")
+    print(f"  run.py:      {run_py}")
+    print(f"  venv python: {venv_python}")
+    print(f"  arm64:       {env['arm64']}")
+
+    tool = MLXImage()
+    print(f"  provider status: {tool.get_status().name}")
+
+    results = []
+    failures = []
+    for row in MATRIX:
+        tag = row["tag"]
+        out_png = os.path.join(OUT, f"t2i_{tag}_s{row['seed']}.png")
+        print(f"\n--- [{tag}] {row['prompt'][:60]}... ---")
+
+        inputs = {
+            "prompt": row["prompt"],
+            "width": row["width"],
+            "height": row["height"],
+            "seed": row["seed"],
+            "output_path": out_png,
+        }
+        t0 = time.time()
+        result = tool.execute(inputs)
+        gen_elapsed = round(time.time() - t0, 2)
+
+        if not result.success:
+            msg = result.error or "(unknown error)"
+            print(f"  ✗ GENERATION FAILED ({gen_elapsed}s): {msg[:160]}")
+            failures.append({"tag": tag, "stage": "generate", "error": msg})
+            results.append({"tag": tag, "ok": False, "stage": "generate", "error": msg})
+            continue
+
+        image_path = result.data.get("output") or (result.artifacts or [None])[0]
+        model = result.data.get("model")
+        print(f"  ✓ generated ({gen_elapsed}s, {model}) → {os.path.basename(image_path)}")
+
+        score, score_elapsed, err = run_caption(run_py, venv_python, image_path)
+        if err:
+            print(f"  ✗ SCORING FAILED: {err[:160]}")
+            failures.append({"tag": tag, "stage": "score", "error": err})
+            results.append(
+                {
+                    "tag": tag,
+                    "ok": False,
+                    "stage": "score",
+                    "image": image_path,
+                    "model": model,
+                    "gen_seconds": gen_elapsed,
+                    "error": err,
+                }
+            )
+            continue
+
+        overall = score.get("overall")
+        artifacts = score.get("artifacts")
+        flag = ""
+        if isinstance(overall, int) and overall < SOFT_OVERALL:
+            flag += f" ⚠overall<{SOFT_OVERALL}"
+        if isinstance(artifacts, int) and artifacts < SOFT_ARTIFACTS:
+            flag += f" ⚠artifacts<{SOFT_ARTIFACTS}"
+        sec = f" ({round(score_elapsed, 2)}s)" if isinstance(score_elapsed, (int, float)) else ""
+        print(
+            f"  scored{sec}: overall={overall} detail={score.get('detail')} "
+            f"sharpness={score.get('sharpness')} composition={score.get('composition')} "
+            f"prompt={score.get('prompt_adherence')} artifacts={artifacts}{flag}"
+        )
+        issues = score.get("issues") or []
+        if issues:
+            print(f"    issues: {issues}")
+        print(f"    summary: {score.get('summary')}")
+
+        results.append(
+            {
+                "tag": tag,
+                "ok": True,
+                "image": image_path,
+                "model": model,
+                "gen_seconds": gen_elapsed,
+                "prompt": row["prompt"],
+                "seed": row["seed"],
+                "size": [row["width"], row["height"]],
+                "scores": {
+                    "overall": overall,
+                    "detail": score.get("detail"),
+                    "sharpness": score.get("sharpness"),
+                    "composition": score.get("composition"),
+                    "prompt_adherence": score.get("prompt_adherence"),
+                    "artifacts": artifacts,
+                },
+                "issues": issues,
+                "strengths": score.get("strengths") or [],
+                "summary": score.get("summary"),
+                "flagged": bool(flag),
+            }
+        )
+
+    # Persist receipt.
+    receipt = {
+        "matrix_size": len(MATRIX),
+        "failures": failures,
+        "soft_thresholds": {"overall": SOFT_OVERALL, "artifacts": SOFT_ARTIFACTS},
+        "results": results,
+    }
+    with open(RECEIPT, "w") as fh:
+        json.dump(receipt, fh, indent=2, ensure_ascii=False)
+    print(f"\n→ receipt: {RECEIPT}")
+    print(f"→ images:  {OUT}")
+
+    # Summary line.
+    ok = [r for r in results if r.get("ok")]
+    flagged = [r for r in ok if r.get("flagged")]
+    print("\n" + "=" * 72)
+    print(
+        f"{len(ok)}/{len(MATRIX)} generated+scored"
+        + (f", {len(failures)} FAILURE(S)" if failures else "")
+        + (f", {len(flagged)} flagged below soft threshold" if flagged else "")
+    )
+    print("=" * 72)
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())