cascade-img: Instructions file for Codex

AGENTS.md

This file follows the agents.md convention — drop it in front of any LLM agent that operates cascade-img. The orientation block below is also the canonical source for the per-harness entry files (CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, .cursor/rules/, .windsurfrules, .clinerules): they are generated from it by packages/python/tools/render_agent_entrypoints.py and kept in sync by CI. Edit the block here; never edit a generated file by hand.

What cascade-img is, and how you drive it

What it is. cascade-img is an LLM-operable image-generation pipeline — Midjourney through a Discord bridge at v0.1, with pluggable backends (Flux, DALL-E, Imagen, …) behind one interface after. You, the agent, are its primary operator: it is built so you compose a prompt, generate, curate the winner, and log the attempt without a human on every generation.

Session start. Your first tool call is cascade_guide — it returns this full operating manual in one call and unlocks the rest. The generation and curation tools refuse with GUIDE_UNREAD until you've called it once this session.

The loop, per asset. compose_prompt → imagine → wait → inspect (read the PNG with vision) → curate (crop_grid → [alpha_key?] → promote) → log_append. Open each iteration with read_prompt_log(n=5) — the append-only log is your working memory across generation runs.

The shape — one daemon, two entry points, all over local HTTP:

• cascade-mj-bridge — the daemon, and the only process that talks to Discord. It must stay running the whole session: it holds the live Discord connection and the in-flight job table, while the two entry points below are stateless clients that reach it over local HTTP.
• cascade-mcp — the MCP server exposing 23 tools; this is how you, the agent, drive everything.
• cascade-mj — the CLI, for scripting and one-off generations.

The 23 MCP tools, by job. onboarding — cascade_guide (returns this full operating manual; call it first — the generation and curation tools are gated with GUIDE_UNREAD until you do); generation — imagine, generate_video (native image→video; composes + fires --video/--loop/--motion/--end/--bs), wait, status, bridge_health, mj_action; catch-up — channel_recent (the newest MJ results in the channel, including ones the human made by hand in Discord; tracked_job_id: null marks them), adopt_message (claim an untracked result into the job table so status/curation/mj_action work on it); composition — compose_prompt, compose_video (build a native image→video prompt without firing); curation — crop_grid, alpha_key, auto_trim, palette_quantize, contact_sheet, sprite_sheet, score_grid, video_filmstrip (sample a video's keyframes into a vision-readable still), loop_seam_delta (score how cleanly a --loop video closes), promote; working memory — log_append, read_prompt_log. Every call returns {ok, result} or {ok: false, error: {code, remediation}} — branch on the stable code, never the message.