Use when the user wants a short video from a one-line idea. Writes a multi-scene screenplay with shot-to-shot continuity, fills each shot with stock footage (Pexels/Pixabay/Unsplash, only if their keys are set) or an offline storyboard frame, optionally adds narration (offline system TTS + captions) and a soundtrack fitted to the cut, edits a frame-accurate timeline (hard cuts in a scene, dissolves between scenes) and renders an MP4 with Remotion or ffmpeg. TIP: call with dry_run:true first — it returns the screenplay, shot list, provider choice and a cost/network estimate instantly without writing files, so you can show the user before producing. Network/money: stock APIs are used automatically when keys exist (free; set stock:false to stay offline). generative:true calls paid-or-quota video APIs (budget-guarded; approveOverBudget:true to exceed). With no keys everything runs offline. Returns: projectId, rendered MP4 path (if rendered), screenplay.md, timeline.json, attributions, warnings, next steps. interactive_montage pauses before the edit so a human can reorder/replace clips, then compile_montage finishes.

Use after run_cinema_pipeline in interactive_montage mode, or to re-cut any project: rebuilds the timeline from the project folder (honoring an optional montage-order.json and any clip files you replaced), validates it (no gaps, no missing files) and renders the MP4. Offline; no network. Returns the MP4 path, validation warnings and next steps.

Use when rendering fails because ffmpeg, Blender or the Remotion toolchain is missing. With consent:false (default) it only detects the OS and returns the exact commands it WOULD run — nothing is installed. Only call with consent:true after the user explicitly agrees; it then runs the package manager (may need sudo) and npm (network).

Use to answer 'what can this server do with my keys?'. Lists every catalogued provider (stock, generative video/image, audio) with whether its key/model env vars are set. Offline; reads tools-registry.json and env only.

Use when the user asks to find new video/model tools. Searches the public Hugging Face Hub and GitHub Search APIs (network, no key needed; GITHUB_TOKEN optional) and QUEUES candidates in data/review-queue.json. Never installs, enables or runs anything. Returns the top candidates and the queue size.

Use only after the user approves a discovered candidate. Adds it to tools-registry.json as DISABLED and unimplemented (a human must write an adapter and enable it). No network. Requires approve:true; otherwise does nothing.

Use before generating to show/tune the strategy. Runs the persona consultation (Director of Photography, Graphic Designer, Voice Director, Music Producer) for an asset kind and returns the compiled brief: positive/negative prompt, technical params (palette, lens, BPM/key/structure, pacing) and the debate transcript. Instant, offline, writes nothing.

Use for logos, illustrations, app/web mockups, photos and textures.

• logo / vector-art / ui-mockup: designed OFFLINE as clean SVG (plus a PNG export when rsvg-convert or ffmpeg is installed). Logos come with -reversed (dark backgrounds) and -icon variants. Free, instant, no network.

• cinematic-photo / texture: need an image API. Without generative:true you get a clearly LABELLED placeholder, not a photo. generative:true calls Replicate/Hugging Face with your key (uses quota; budget-guarded → returns a halt with a cost breakdown; retry with approveOverBudget:true only if the user agrees). Style words steer the result: palette ('vibrant', 'warm', 'earth', 'mono'), logo layout ('monogram', 'wordmark', 'horizontal', 'emblem'), type voice ('luxury', 'tech', 'playful'), 'sharp' corners. Returns file paths, size, license.

Use to turn a script into spoken audio (WAV). Offline by default via the system TTS engine (macOS 'say', pico2wave, ffmpeg's flite, or espeak-ng): intelligible but synthetic-sounding, loudness-normalized to -16 LUFS. If no engine exists you get a timing placeholder TONE that is explicitly labelled NOT SPEECH. generative:true uses your Hugging Face TTS model (HF_TTS_MODEL; quota, budget-guarded) for a natural voice. Returns the WAV path and exact duration in ms.

Use for background music or a beat in a genre: hip-hop, trap/rap, cinematic orchestral, rock, lo-fi, electronic, ambient. Offline by default: the Music Producer plans tempo/key/structure/instruments and the engine composes and synthesizes a stereo WAV (voice-led chords, bass, drums, a melody, section dynamics, mastered to about -14 LUFS) plus an editable multi-track MIDI. It is a synthesized demo, not a studio recording. generative:true uses your MusicGen model on Replicate/HF (quota, budget-guarded). Returns WAV + MIDI paths, exact duration, and the arrangement.

Use for a sound effect or ambience. Offline by default: procedural synthesis matched to the request (whoosh, rain, thunder, wind, ocean, impact, riser, click, ding, beep, fire, footsteps, heartbeat). generative:true searches Freesound with your FREESOUND_API_KEY (network, CC-licensed results, budget-guarded). Returns the file path, exact duration and license.

Use before a generative run or when the user asks about remaining quota. Reports per-provider usage vs the budget guard's daily/weekly/monthly limits from data/usage-limits.json. Offline.

Use when another local program needs to request assets from this engine over HTTP. Starts a server bound to 127.0.0.1 with a bearer token (stored in data/ipc-token.txt, mode 0600). Returns the URL and token. Stop it with ipc_stop.

Use to check whether the local REST API is running and where. Offline.

Use to shut down the local REST API started by ipc_start.