cascade-img / rules

---
description: cascade-img — what it is and how an agent operates it
alwaysApply: true
---

<!-- Generated from the AGENT-ORIENTATION block in AGENTS.md by packages/python/tools/render_agent_entrypoints.py.
     Do not edit by hand — edit that block in AGENTS.md and regenerate. -->

## 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.

**Where to go next.**
- [RUNBOOK.md](../../RUNBOOK.md) — install, the Discord `.env` values to capture, bring-up, and every failure mode with its error code and fix. Read this to set up or to recover.
- [CAPABILITIES.md](../../CAPABILITIES.md) — every Midjourney prompt parameter and `mj_action`, the V8.1/V7 version split, with ranges and effects.
- [README.md](../../README.md) — the overview and why cascade-img exists.
- [examples/](../../examples/) — three end-to-end walkthroughs: one image, a batch sharing one style, and a video.
- [AGENT_RUNDOWN.md](../../AGENT_RUNDOWN.md) — a paste-in prompt that has an LLM read the source and brief you from it.

**The one constraint.** cascade-img drives Midjourney through a Discord *user* account; both services' Terms of Service prohibit that automation, and the human who configured the daemon has acknowledged it. Treat a persistent token rejection (`DISCORD_401` after re-capture, or `DISCORD_RECONNECT_FAILED(reason=auth)`) as a structural failure that needs the human — the daemon cannot self-recover.

**Full operator guide:** [AGENTS.md](../../AGENTS.md) — the complete tool reference, the prompt-part details, identity-lock guidance, and the failure-mode→action table.