TechShorts: Instructions file for Codex

Repository Structure

TechShorts/ is the Git root. It currently contains the README, and license; inspect all files again once source or an archive is added. Keep concerns separated as the application grows: configuration/model routing, content and AI logic, persistence, media processing, scheduling/workers, platform adapters, dashboard, tests, and editable assets such as the Style Bible. Avoid a monolithic module and keep generated media, exports, secrets, and local databases out of Git.

Core Product Constraints

• Target approximately 12-second, 9:16 videos; validate finished media with FFprobe.
• Generate 6–10 hooks, rank them, retain candidates and judgments, then write around the winner.
• Run factual and quality gates before paid rendering. Never invent citations, measured SEO data, or API capabilities.
• Centralize configurable OpenAI model routing and verify current official API documentation before model-specific work.
• Keep TikTok and YouTube metadata and publishing adapters separate.
• Enforce OFFLINE, APPROVAL_REQUIRED, and AUTOMATIC modes in backend workers. Offline mode must make publication technically impossible.
• Use explicit, observable, idempotent job transitions; bounded retries; persistent error history; and duplicate-dispatch protection.
• Package offline exports with video.mp4, metadata.json, youtube.txt, tiktok.txt, and genuine sources.json, plus ZIP output.

Development and Verification

No application toolchain exists yet. Add exact commands to TechShorts/README.md only when implemented. The expected Python quality baseline is Ruff/formatting, type checking where practical, pytest, and compilation/import checks. Tests must mock paid/external APIs and cover model routing, publishing-mode safety, exports, filename sanitization, state transitions, retries, scheduling races, configuration, Style Bible loading, metadata mapping, and persistence. Never report a check as passing unless it was run; distinguish mocked tests from live integrations.