flowkit: Instructions file for Codex

Flow Kit — Codex CLI Instructions

Base URL: http://127.0.0.1:8100

Pre-flight

Before ANY workflow:

curl -s http://127.0.0.1:8100/health
# Flow mode must return: {"extension_connected": true}
# Assistant mode (MEDIA_PROVIDER=assistant or provider=assistant per request):
# extension_connected may be false — no Chrome extension needed.
# Check provider status instead: GET /api/providers/status

Critical Rules (MUST follow)

1. Media ID is always UUID — format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Never use CAMS... / base64 strings.
2. Scene prompts = ACTION only — never describe character appearance. Reference images handle visual consistency via imageInputs.
3. All reference images must exist before scene images — verify every entity has media_id before generating scene images.
4. No throwaway scripts — NEVER write Python, shell, or any script file to loop over API requests. Use POST /api/requests/batch to submit all requests at once, then poll GET /api/requests/batch-status. The server throttles automatically.
5. Locations use landscape, characters use portrait — reference image orientation depends on entity type.
6. UUID extraction — if a response gives CAMS... instead of UUID, extract UUID from the fifeUrl in the response URL: /image/{UUID}?....
7. Cascade on regen — regenerating an image auto-clears downstream video + upscale.
8. REGENERATE vs GENERATE — GENERATE_* skips if already COMPLETED. REGENERATE_* always runs (clears + regenerates).
9. Image Material required — every project needs a material field (e.g. realistic, 3d_pixar, anime). List available: GET /api/materials.
10. Server handles throttling (per provider) — each media provider declares its own limits (Flow: max 5 concurrent + 10s cooldown; assistant: max 2 concurrent, no cooldown). Submit ALL requests via /batch; do NOT manually stagger or loop. Check effective limits: GET /api/providers/status.
11. Video prompts use sub-clip timing — structure 8s video as time segments: 0-3s: [action]. 3-6s: [action]. 6-8s: [action].
12. Character dialogue in sub-clips — embed speech in quotes: Luna says "Goodnight." Max 10-15 words per character per 2-3s segment.
13. Scenes are mutable — use PATCH /api/scenes/{sid} to update prompt, video_prompt, narrator_text, character_names after creation. Don't delete and recreate — patch instead.
14. Fact-check before scripting — ALWAYS research events via web search before writing project stories, scene prompts, or narrator text. Facts (events, dates, names, operations, outcomes) MUST match real sources. Editorial opinion and analysis are allowed but must be framed as such. Never invent events, operation names, or statistics.
15. Real-people bypass — when characters are based on real famous people (politicians, celebrities, military leaders), NEVER use their real name as entity name or anywhere in description, image_prompt, prompt, or video_prompt. AI image generators reject known public figures. Instead: (a) use a role-based alias as entity name (e.g. "Tổng Tư Lệnh" not "Trump", "Thủ Tướng Sắt" not "Netanyahu"), (b) describe physical appearance only — distinctive hair, face shape, build, clothing style — without naming who it is, (c) narrator_text may use real titles/roles for storytelling but real names never flow into image/video generation. Keep a real_reference mapping in the project plan file (.omc/research/) for internal tracking.
16. Review before upscale — ALWAYS run /fk-review-video (light mode) after video generation, before upscaling. Scenes scoring < 7.5 get video_prompt updated from review errors, then regen video. Max 2 review-regen cycles.