auto-vlog-editor: Instructions file for Codex

AGENTS.md — working in this codebase

Operational rules and non-obvious gotchas for anyone (human or AI agent) editing this repo. Architecture and feature explanations live in docs/.

Rule of thumb: info needed to NOT break things → here. Info to understand how it works → docs/.

Knowledge map

Hard rules

• Never publish without approval. Only a day in the approved state can create posts; the single gate is publishing.publish_day(). Don't add publish paths anywhere else.
• Never call the Claude CLI outside app/claude_cli.py. It's the swappable reasoning layer (CLAUDE_CODE_COMMAND): serialized, schema-validated, read-only tools. Everything that needs the model goes through run_structured.
• Secrets never go into prompts or git. Real keys live only in .env (which is gitignored). .env.example documents the variables with placeholders.

Critical gotchas

Subtitles/beats: ASR gives TIMING, the script gives TEXT

Word timings (words_v{N}_{lang}.json, which drive BOTH subtitles and beats) come from app/services/align.py: faster-whisper transcribes the mp3, wav2vec2 refines per-word timing. The transcription's TEXT is often mis-heard, so retext_to_script re-maps the timed words onto the KNOWN script (difflib) and emits the script tokens verbatim — the subtitle word TEXT is ALWAYS the script, never the ASR. This runs on every path, including fallbacks (WhisperX align → free-form faster-whisper → char alignment). Don't remove the re-text step or let any path set word text from ASR. torch is CPU-only and lives in the Dockerfile prod stage (the dev image has none → exercises the fallback). See docs/architecture/rendering.md.