---
name: social-media-shorts-automation
description: Design, generate, review, publish, and optimize automated short-form social videos across YouTube Shorts, TikTok, Instagram Reels, and related channels.
version: 1.0.0
tags: [shorts, tiktok, youtube-shorts, reels, creator-monetization, content-automation, social-media]
---

# Social-Media Shorts Automation

## Reference index

- `references/dashboard-production-concept-gate-and-prepared-package.md` — Dashboard-as-source-of-truth production gate: concept proposal first, explicit `APPROVE_PRODUCTION`, prepared-package import, ready-for-review stop point, and no upload/website side effects.
- `references/autoshorts-dashboard-mobile-approval-and-package-generation.md` — AutoShorts Dashboard implementation pattern for concept-gated Generate Review Package, full dry-run idea→private-upload→website-payload tests, iPhone/mobile approval cockpit, and Tailnet preview links without private YouTube leakage.
- `references/autoshorts-dashboard-script-approval-final-render-upload-companion.md` — Corrected operational flow: script/concept approval only (no placeholder video), final Director render, Dashboard import, hash-bound private YouTube upload, audit import, and Website Companion live check.
- `references/autoshorts-dashboard-quality-gate-and-revision-flow.md` — Sprint 8.8 quality-first gate: reject/request-changes workflows, Dashboard-owned quality profile, Director skill, required quality reports, and no `MP4 exists → ready_for_review` shortcut.
- `references/tiktok-verification-recording-rehearsal.md` — guided TikTok Developer verification recording rehearsal flow: script, demo checklist, recording steps, and common failure fixes.

- `references/director-pass-cinematic-production-standard.md` — Mandatory Director Pass before every render: emotion, eye direction, pressure/relief beats, motion purpose, audio cues, first-second sheet, silent recognition, cheap-effect checks, and report fields.
- `references/private-youtube-upload-and-companion-linking.md` — After approved private YouTube uploads, validate hash/scope, upload with `youtube.upload` only, then immediately update the website companion page with the real Shorts link because the user manually makes it public.
- `references/hash-bound-private-youtube-upload-dashboard-recovery.md` — Hash-bound Dashboard upload execution/recovery: verify SHA/scope/privacy, use only `videos.insert`, avoid duplicate uploads after post-API DB failures, repair Dashboard audit rows, and keep private YouTube IDs out of visitor-facing website HTML.
- `scripts/preview_director_qa.py` — Reusable ffmpeg/Pillow QA artifact generator for first-second sheet, beat frames, and director verdict template.
- `references/pure-ai-cinematic-controlled-motion.md` — Pure-AI cinematic polish pattern: reuse existing keyframes, no renderer-built UI, no shake/vibration/wobble, controlled Z-push/crop, restrained audio, hook voice split, and QA checks.
- `references/clean-image-cut-no-overlay-pilot.md` — Pure-AI cinematic style tests: final visuals are only premium AI images; renderer adds motion/light/audio/subtitles only, with no fake UI screens, mockup boards, boxes, arrows, circles, diagrams, or instruction cards.
- `references/truetraceshorts-erf-companion-qa-pitfalls.md` — ERF companion-page QA pitfalls: Related red flags 9:16 framing, checklist-title integrity, YouTube private-upload link handoff, Google Search Console verification file placement, and required build/live checks.

- `references/tiktok-app-review-and-domain-verification.md` — TikTok Developer App review posture, public-vs-internal wording boundary, and Astro `public/` TXT domain-verification workflow.
- `references/erf-first-frame-hook-and-caption-qa.md` — TrueTraceShorts / Everyday Red Flags first-frame hook standard, consequence-drama tone, one-visual-claim-per-scene rule, and caption-overlap QA pitfalls from ERF-023.
- `references/truetraceshorts-format-family-expansion.md` — channel expansion into format families: Red Flag Shorts, Already Clicked, Spot the Trap Quiz, True Scam Story, and Scam Breakdown; planning fields, format mix, website targets, and analytics/audit metadata.
- `references/truetrace-format-family-implementation-spine.md` — concrete implementation pattern for AutoShortsBot format metadata, first 5-video test wave, `/already-clicked/` recovery hub requirements, visual rules, tests, and pitfalls.
- `references/truetrace-format-aware-premium-ai-render-discipline.md` — user-corrected next-video discipline: choose format family before topic, audit existing scripts, avoid repeating old themes by default, and treat renderer-built PowerPoint/mockup visuals as a hard blocker for review-ready TrueTraceShorts.
- `references/autoshorts-dashboard-real-data-content-library.md` — AutoShorts Dashboard sprint pattern for real YouTube CSV imports, demo-data isolation, creator-readable analytics names, package mapping, Content Library/Families, recommendation endpoint, honest placeholder pages, QA, docs, and Git hygiene.
- `references/autoshorts-dashboard-production-workflow.md` — AutoShorts Dashboard as production source of truth: Production Plan → Jarvis next item → Review → YouTube private upload/schedule → TikTok manual export → Analytics feedback; no TikTok auto/mock in main workflow.
- `references/dashboard-one-button-review-package-bridge.md` — Concept-approved `Generate review package` button pattern: package bridge behind approval gate, importer attachment by exact package folder, private-upload dry-run, Website Companion no-private-link leakage, and workflow-preview vs final Director-render distinction.
- `references/dashboard-script-approval-to-director-render-handoff.md` — User-corrected Dashboard flow: concept approval is text/script-only, no provisional video; after `APPROVE_PRODUCTION` render the final Director package, import it into Dashboard by prepared-package manifest, mark `in_review`, and deliver MP4/thumbnail/hash-bound upload command.
- `references/autoshorts-dashboard-generation-button-readiness.md` — Audit whether the Dashboard truly has one-button generation or only queue/concept approval; distinguish recommendation/concept/approval/package/publish buttons and prefer a safe “Generate review package” job that stops at Dashboard review.

- `references/pixabay-music-and-hashtag-policy.md` — user-corrected AutoShorts music policy: prefer licensed Pixabay/stock beds over homemade/generated music, handle Pixabay audio/video API quirks, and keep scam-short hashtags to 4–7 targeted tags.
- `references/jamendo-music-bed-workflow.md` — official Jamendo API workflow for licensed music beds: credential parsing, conservative CC BY filtering, license metadata, FFmpeg ducking, and hash-bound approval-package updates after mixing.

## Umbrella consolidation notes

This is the class-level umbrella for short-form social-video automation, growth-engine strategy, approval-gated rendering, manual/social posting packs, and analytics loops. Former narrow sibling skills were absorbed as support references so agents should load this one skill first, then open the relevant reference when needed:

- `references/absorbed-shortform-growth-automation.md` — earlier semi-automatic shortform growth workflow, platform strategy, human review loop, and AutoShortsBot bootstrap notes.
- `references/absorbed-social-media-shorts-growth-engine.md` — growth-engine strategy, JARVIS-operated/human-approved pipeline, deterministic implementation foundations, manual posting packs, and TrueTrace positioning notes.
- `references/absorbed-social-shorts-automation.md` — audit workflow for existing shorts bots, hook quality gates, early-account duration guidance, and initial AutoShortsBot audit reference.
- `references/absorbed-social-shorts-growth-engine.md` — concise growth-engine workflow, retention heuristics, platform monetization notes, and implementation guardrails.

Reference note: for the current main AutoShorts/TrueTraceShorts direction, first use `references/everyday-red-flags-clean-ai-strategy.md`: Everyday Red Flags / digital self-defense for normal people, common scams, simple English, high-quality realistic AI images only, subtitles only, no visual overlays, first image must show the concrete scam instantly, and for current gallery consistency the scam name appears inside the first visible screen in readable red text only on that first keyframe unless explicitly requested otherwise; every video needs red flag + safe action + takeaway. For the repeatable production/render workflow, use `references/everyday-red-flags-clean-ai-render-recipe.md`: 6 concrete AI keyframes, EdgeTTS WordBoundary subtitles, no caption boxes/progress bars, contact-sheet + frame + ffprobe QA, and regenerate if the first frame is not self-explanatory. For thumbnail/cover assets, always use `references/thumbnail-cover-workflow.md`: strong first frame and separate 9:16 thumbnail A/B are both required, `thumbnail_passed != first_frame_passed`, thumbnail text is renderer-owned, max 2 variants, no clickbait, and ReviewPackage fields must include thumbnail paths/hashes/scores/recommendation. For publishing new videos to the TrueTraceShorts website, use `references/truetrace-website-companion-screen-ux.md`: direct scam-screen visuals, `screenImage`/`screenImageAlt`/`visualBrief`, no odd `Start frame` labels, no artificial visible-screen mock panels, and Common Screens carousel must be mouse-button + swipe/trackpad usable. Use `templates/manual-posting-pack-with-thumbnails.md` when producing upload-ready packages so video, cover assets, copy blocks, gates, and artifact reports stay consistent. For YouTube platform integration, use `references/youtube-upload-only-manual-analytics-policy.md`: upload-only OAuth scope, private-draft uploads only after exact hash-bound approval, no read scopes, no comments, no Analytics API, and manual CSV-only learning reports. For this user's AutoShorts approval requests, include the Telegram-playable MP4 attachment, proposed title, engaging YouTube description, TikTok caption/description text (without uploading to TikTok), and exact hash-bound approval command in one review message. See `references/truetraceshorts-review-upload-reporting.md` for the review/upload report bundle, recovery no-shame wording, and natural-language private-upload approval handling. For this user, every newly delivered AutoShorts/TrueTraceShorts video must include the exact hash-bound `APPROVED_FOR_PRIVATE_YOUTUBE_UPLOAD ...` command in the review message so the user can return it unchanged for private-draft approval. Place the video duration immediately after the approval-code block at the end of the message. For future YouTube approval/review packages, always attach/send the proposed thumbnail or cover image as a chat image alongside the MP4, title, description, approval command, and duration. The user still sets thumbnails manually in YouTube Studio unless a separate thumbnail-upload workflow is explicitly approved. For headless OAuth where the user pastes a localhost callback URL into chat, use `references/youtube-manual-pkce-callback-token-exchange.md`: verify state + redirect URI + exact scope + matching PKCE verifier before token exchange, write token only after scope validation, chmod `0600`, delete temporary state, and never echo codes/tokens/secrets. For approved-video Drive staging, use `references/upload-freigabe-drive-workflow.md`: upload the MP4 plus thumbnail assets/contact sheet plus a matching DOCX with YouTube/TikTok copy blocks to Google Drive `AutoShortsBot/Upload Freigabe`. If a hash-bound YouTube private-upload package exists and the exact approval command was returned, but the repo-specific upload CLI is unavailable or has moved, use `references/youtube-private-upload-direct-fallback.md`: validate package approval, privacy, video SHA256, and exact upload-only OAuth scope, then call only `videos.insert` and write an audit; do not attempt thumbnails when the user sets them manually. If the package was saved beside the render artifact rather than the repo default package directory, set `AUTOSHORTS_YOUTUBE_PACKAGE_DIR` for dry-run and execute. If the user replies with natural-language approval immediately after one review package, proceed only by reusing the saved package's exact `approval_command` that was just delivered and after a valid dry-run; otherwise ask for the exact command.  See `references/controlled-pilot-production-v2.md` for the controlled first-video workflow: resource tiers, media-generation gates, pilot package shape, Wan prompt planning without generation, and no auto-posting. See `references/pilot-preview-render-v2.md` for the next approval step: `APPROVED_FOR_PREVIEW_RENDER`, EdgeTTS preview audio, time/word cue generation, deterministic 9:16 animatic MP4, checksums, and Telegram media delivery without Wan/AI-image/platform side effects. See `references/static-active-word-captions-and-final-pilot-render.md` for the corrected caption style and controlled final pilot render pattern: static 3–7 word phrase segments with only the active spoken word highlighted, hash-bound final render gates, one Wan text-free background layer, deterministic overlays, and draft-only manual posting packages. For the current accepted TrueTrace proof-short postpreview standard — detailed AI-generated UI/screen keyframes with readable concrete text, no focus lines/arrows/boxes, active-word subtitles, sentence-boundary caption segmentation, and explicit 9:16 export QA — use `references/detailed-ai-screen-postpreview-pattern.md`. For the current TrueTraceShorts strategic repositioning, use `references/digital-red-flags-scam-self-defense-strategy.md`: Scam Self-Defense for normal people, `One screen. One red flag. One safer move.`, screen/mockup-led scam self-defense pillars, simple English, deterministic scam mockups, and review packages before rendering. For selecting the next topic and choosing the correct video length, use `references/everyday-red-flags-topic-database-and-duration-policy.md`: normalized 12-category / 185-topic idea database paths, already-produced topic hints, status update pattern, duration-by-understanding ranges, and the early goal of shares/saves/followers/trust over ad monetization. For the concrete “next video from prior renderer” workflow, use `references/next-erf-video-render-from-prior-script.md` and actively avoid near-duplicate mechanics/visual grammar; the user expects variety across scam families, not only new slugs. For production QA corrections learned from ERF-021/022 — surgical keyframe replacement, product-shape brand safety, CAPTCHA/browser-permission premium AI visual requirements, first-frame in-image title gate, forced-alignment word fixes, voice/text/background sentence-beat alignment after visual replacement, and PDF/print checklist pitfalls — use `references/truetrace-erf-production-qa-corrections.md`. If a final render is rejected as preview-overlay-dominated or not visual-first, follow `references/visual-first-final-render-repair.md`: mark the render rejected/not-postable, fix Wan output parsing, enforce final overlay limits, produce only a short visual proof under `APPROVED_FOR_VISUAL_PROOF`, and do not run another full final until the visual direction is accepted. If even the visual proof is rejected as abstract/generic/dark or “blind T2V”, switch to `references/keyframe-first-final-visuals.md`: plan and approve start/end/style keyframes first, then run only a short I2V/first-last-frame proof with minimal renderer-owned overlays. If the user says the production method itself is wrong, keyframes are not I2V-ready, or an animatic was incorrectly substituted for a failed Wan proof, follow `references/visual-production-reset-i2v-first.md`: reject/audit the proof, stop content rendering, run technical I2V sanity first, then generate at most three styleframes for direction review. If deterministic layout proofs are useful as composition blueprints but rejected as too wireframe/PowerPoint for final style, switch to `references/premium-ai-styleframe-direction.md`: use the layouts only as mechanism blueprints, generate at most 3 tightly briefed premium text-free AI styleframes, deliver a contact sheet with verified media metadata, and keep Wan/I2V/endframes/full-final blocked until style direction approval. If those premium styleframes are better quality but still too abstract, switch to `references/real-life-premium-styleframes.md`: anchor the mechanism in a realistic work/meeting/desk scene, keep all readable overlays renderer-owned, generate at most 3 new real-life styleframes plus contact sheet, and still block Wan/I2V/endframes/full-final until explicit approval. If the user approves one or more real-life styleframe directions but wants to compare A/B/C before Wan, use `references/prerelease-animatic-preview.md`: build only a small AI-keyframe + deterministic-motion animatic per approved direction, reuse existing voiceover/captions, deliver MP4/contact/QA sheets with metadata, and keep Wan/I2V/final/posting blocked. If the user then rejects the renderer-added circles/arrows/labels/boxes/decision-target markers as destroying the premium look, switch to `references/clean-image-cut-no-overlay-pilot.md`: render only AI images + voiceover + clean subtitles, with a hard subtitles-only NoOverlayPolicy and no Wan/I2V/full-final/posting. If the user performs a strategic reset because the pilot is pretty but semantically weak, stop optimizing that candidate and follow `references/proof-short-real-problem-reset.md`: archive the old pilot as a learning case, enforce the Pretty Empty Visual Blocker, and build a screen/mockup-led Proof Short around an immediately visible real viewer problem before any premium/Wan production. If the next review focuses on image provider quality/provenance or subtitles running off-screen, follow `references/image-provider-audit-and-caption-safezone.md`: audit the configured image provider/model/tier from config + provider registry + cache metadata, run at most one neutral capability test, keep UI/invoice mockups deterministic, and add tested caption layout safe-zone bounds before re-rendering. If an approved Proof Short feels too visually flat and the user asks why no AI images were used, follow `references/proof-short-ai-visual-upgrade.md`: use AI images as a controlled text-free atmosphere/background/keyframe layer while keeping invoices, emails, payment routes, labels, facts, and captions deterministic renderer-owned. For the concrete rendering/QA pattern — small 2–3 keyframe pass, contact-sheet inspection, discard pseudo-text frames, blur/darken/subordinate AI backgrounds, and report used/discarded keyframes — see `references/proof-short-ai-background-rendering-qa.md`. If the user accepts the detailed KI-screen-image direction as “new standard,” follow `references/detailed-ai-screen-proof-shorts.md`: use detailed AI-generated real UI/screen images with readable concrete text (e.g. Outlook-style invite/login/calendar), no focus lines/arrows/boxes, active-word subtitles, and verified 9:16 SAR/DAR export before delivery. For the follow-up A/B test where the user asks whether pure KI images can match or beat hybrid mockups, see `references/clean-ai-cut-vs-hybrid-mechanism.md`: compare clean image-only premium feel against mechanism clarity, keep word-aligned subtitles, and consider `90% clean AI images + 10% minimal deterministic mechanism` as the likely next style. When the user explicitly corrects the workflow to “keine Render overlays” and wants the content entirely in detailed AI images, follow `references/clean-ai-image-cut-production-qa.md`: detailed AI screen-image keyframes carry the story, renderer adds only text-only active-word subtitles, no progress bars/cards/boxes/arrows/focus lines, and QA catches EdgeTTS punctuation-stripping subtitle chunks. For local Chatterbox TTS over Tailscale, use `references/chatterbox-tts-candidate-provider.md`: test only Chatterbox when asked, save WAV + metadata, deliver Telegram voice proposals as media-cache Ogg, keep it as candidate_provider until explicitly promoted, and if voices sound metallic retry standard voices/presets before further tuning. If the user rejects a render because it looks like deterministic mockups/PowerPoint and asks to use high-quality AI images again, use `references/high-quality-ai-image-repair-after-mockup-rejection.md`: treat it as a hard visual-style correction, keep the topic/script if possible, replace the main visual layer with well-prompted premium AI keyframes, rerender, rebuild hashes/approval package, QA contact sheet and frames, and never reuse the old approval command. For CAPTCHA/browser-permission scenes specifically, do not solve brand safety by shipping self-built CAPTCHA cards as the main visual layer; regenerate AI keyframes with strict negative prompts for reCAPTCHA/Google/browser logos/real domains, and use deterministic elements only as hidden blueprints or small controlled layers.

Use this skill when building or operating systems that generate short-form social videos, especially faceless or semi-automated pipelines for YouTube Shorts, TikTok, Instagram Reels, Facebook Reels, Pinterest video pins, X video, or LinkedIn video.

For Chatterbox voice experiments and candidate voiceovers, use `references/chatterbox-tts-tailscale-candidate-provider.md`: local Chatterbox over Tailscale; for the user's accepted ERF/AutoShorts voice standard use Gianna premium female reference clone v1 (`voice_mode=clone`, `reference_audio_filename=Gianna.wav`, warm chunks, ~500ms pauses, speed 1.0, temp .80/exagg .52/cfg .50). Use performance-script chunking and punctuation to fix sentence-end prosody; do not slow/stretch audio. For final-near AutoShorts/TrueTraceShorts renders with Chatterbox, use `references/chatterbox-forced-alignment-shorts-render-pattern.md`: render the WAV first, extract word timestamps with faster-whisper, group captions by source-script punctuation/phrase breakers, use stable two-line active-word subtitles, omit thumbnails by default, and deliver a hash-bound Telegram review package. If captions are too fast or fragmented for mute/silent viewing, use `references/silent-viewer-caption-pacing.md`: rewrite into short complete sentences, add sentence-level pauses, build caption pages from source sentence boundaries, avoid orphan-word pages, and extend duration when needed for comprehension. For duration selection and early growth optimization, use `references/dynamic-duration-and-growth-goals.md`: length is chosen by viewer understanding, default Proof Shorts are 35–45s, and early optimization is shares/saves/followers/trust rather than direct ad monetization. For large user-supplied Everyday Red Flags topic lists or next-batch planning, use `references/everyday-red-flags-topic-database.md`: preserve the user's category/series taxonomy, store it as a structured backlog with topic IDs/slugs/status/priority, mark produced topics to avoid duplicates, and validate topic counts/unique IDs before reporting success.

## Core principle

For this user's AutoShorts Dashboard work, treat the Dashboard as the production source of truth, not a platform-demo surface. Before producing “the next Short,” read the locked/approved Production Plan item via the Dashboard agent API; do not infer the next topic from chat context. TikTok is manual export unless explicitly reopened; YouTube automation is private-upload only with explicit confirmation or a token-free Jarvis-uploader request when Dashboard OAuth is not configured. See `references/autoshorts-dashboard-production-workflow.md`.

For AutoShorts concept approval, do **not** generate provisional/placeholder preview videos for the user. The user explicitly prefers a text/script concept package for approval: hook rationale, full voiceover/drehbuch, storyboard/director beats, visual hook plan, Director plan, and social metadata. Video generation belongs to the final Director render/review package only, after concept approval. See `references/dashboard-one-button-review-package-bridge.md`.

Treat the system as a **Shorts Growth Engine** / **semi-automatic Retention Studio**, not merely a renderer. A working video generator can still fail if it produces generic, low-retention, AI-slop content. Optimize for audience identity, hook quality, retention mechanics, visual mechanism reveals, platform fit, and analytics feedback. For the user's strongest strategic direction, see `references/retention-studio-strategy.md`.

For this user's AutoShorts workflows, approval previews should be German for concept comprehension, while final social-media videos should remain English unless explicitly changed. Treat preview legibility as a quality gate: readable font sizes, pixel-width-aware line wrapping, no clipped words, and no overcrowded cards. For Dashboard Production Queue concept approval, do not create a provisional/placeholder video: show a text/script concept package with hook rationale, storyboard/Director beats, visual hook plan, Director plan, and social metadata. When the user replies `APPROVE_PRODUCTION <id>`, render/import the final Director package rather than a workflow-preview MP4.

For this user's TrueTraceShorts / AutoShortsBot strategy, do **not** default to an AI/prompt/workflow channel. The official current positioning is **Digital Red Flags / Scam Self-Defense for Normal People** with the core line `One screen. One red flag. One safer move.` The channel promise is: `I show you the one red flag before you click, pay, scan, or log in.` AI/workflow content is now a secondary/legacy specialist format, not the main feed. Use simple B1/B2 English, normal screens, visible red flags, one safer action, and family/share/save value. See `references/digital-red-flags-scam-self-defense-strategy.md` for the current strategy and `references/truetrace-strategic-neuausrichtung.md` for the older broader mechanism-reveal context. For deterministic phone/SMS scam renders such as Delivery SMS Trap, use `references/deterministic-delivery-sms-proof-render.md`: renderer-owned SMS mockup, short safe fake URL, manual caption-timing fallback when TTS word boundaries are unavailable, and frame-level subtitle/aspect QA before delivery. For broader controlled UI/screen Proof Shorts where critical scam text must remain exact — invoices, payment-detail changes, emails, logins, support popups, marketplace chats — use `references/deterministic-premium-screen-mockup-rendering.md`: deterministic premium 1080x1920 screen mockups, Chatterbox/forced captions, contact-sheet + real-frame QA, stale-keyframe regeneration, and hash-bound review package delivery.

When the user asks to start implementation work on this strategy, especially “Sprint 1: Strategic Spine Refactor”, follow `references/truetrace-strategic-spine-refactor-v2.md`: implement a side-effect-free V2 spine in parallel to existing V1 models, with mandatory strategic fields, hard quality gates, anti-AI-slop blockers, hash/version-bound ReviewPackageV2, and tests before integration with renderers or platform workflows.

When the user asks for “Sprint 1.5” or to make the V2 spine operational without production, follow `references/truetrace-v2-operational-bridge.md`: first secure/commit the Sprint-1 baseline, then add only minimal side-effect-free bridges (`to_candidate_v2`, `workflow_v2`, `demo_review_batch_v2`), deterministic ReviewPackageV2 JSON, strict approval parsing, calibrated non-generous scoring, anti-example/human-texture gates, minimal manual claim/disclosure stubs, LinkedIn manual metadata, and a Remotion-as-later-spike note. Keep it capped at 3 demo candidates and avoid rendering, platform APIs, dashboards, auto-posting, or 30-day batches.

## Retention-Studio / Mechanism-Reveal Pipeline

For quality-first automated Shorts, especially Hidden Money & AI Systems concepts, prefer the pipeline documented in `references/retention-studio-pipeline-pattern.md`:

```text
strategy → scored ideas → mechanism explainer → shot plan → keyframe/I2V prompt plan → seeded clip jobs → clip review → deterministic final renderer
```

When implementing a new repo or core pipeline, first scaffold the approval-first typed artifact chain in `references/approval-first-retention-studio-core.md`:

```text
ContentPillar → ContentBrief → ScriptDraft → VideoCandidate → TestBatch → ReviewBatch → Telegram ReviewDelivery → ShotPlan
```

Hard rule for this class: AI-video clips provide photorealistic texture and motion only. Captions, numbers, labels, arrows, UI text, price/risk/margin layers, and factual claims are renderer-owned. Final content should keep `static_card_limit = 0`, use visual changes every 1–2 seconds, and reject technically successful clips that do not serve the retention beat.

Before video generation, build an inspectable content-to-review spine: `ContentBrief → ScriptDraft → CandidateDraft → VideoCandidate → TestBatch → ReviewBatch → Telegram ReviewDelivery`. Keep it deterministic, side-effect free, and human-approval-first so hooks, retention beats, visual concepts, policy notes, and review copy can be optimized before spending GPU/API time. See `references/content-to-review-pipeline.md` for the implementation pattern and guardrails.

Hard rule for this class: AI-video clips provide photorealistic texture and motion only. Captions, numbers, labels, arrows, UI text, price/risk/margin layers, and factual claims are renderer-owned. Final content should keep `static_card_limit = 0`, use visual changes every 1–2 seconds, and reject technically successful clips that do not serve the retention beat.

## Recommended workflow

1. **Define channel position**
   - Niche(s): e.g. life optimization, AI life systems, Christian faith/FaithTok.
   - Target audience and emotional problem.
   - Language and tone.
   - Whether the brand is faceless, AI-persona-led, or creator-led.
   - No-go topics and theological/ethical boundaries if faith-related.

2. **Generate test ideas before code-heavy automation**
   - Create 20–30 candidate ideas across 2–4 content pillars.
   - For each: hook, script kernel, visual concept, caption, CTA, risk/quality score.
   - Select a small first batch (e.g. 3 per pillar) for real testing.
   - Before renderers or external AI APIs, add a deterministic content-development core: `ContentPillar → ContentBrief → ScriptDraft → CandidateDraft → VideoCandidate`. See `references/content-development-core.md`.

3. **Use hook-first, retention-led scripting**
   - First 1–2 seconds must contain a clear tension, identity statement, pain point, contrarian line, or immediate self-recognition.
   - Prefer one idea per video over generic “4 tips” unless the list format is the explicit series.
   - Avoid generic advice viewers have already heard unless framed with a new angle, concrete payoff, or strong story.
   - For TrueTraceShorts, prefer the structure `visible fail → identification → mechanism → fix → before/after → memorable takeaway` over generic AI-tip narration. Every video must answer: what goes wrong, why it happens, what rule fixes it, what sentence sticks, why viewers save/share it, and why they follow the series.
   - For unvalidated first pilots, apply the `Pretty Empty Visual Blocker`: if the first frame is beautiful but does not show a concrete viewer pain without voiceover, block the concept and switch to a Proof Short. Do not keep polishing abstract AI visuals, glass metaphors, or generic laptop B-roll before validating the real problem. See `references/proof-short-real-problem-reset.md`.
   - After a Proof Short concept is approved for usefulness/clarity, do not interpret `ProofShortMode` as a permanent ban on AI images. If the user wants the video “aufgepeppt”, add a controlled AI visual-upgrade layer: 2–3 text-free premium backgrounds/keyframes, while all invoice/email/UI/payment-route text, labels, facts, captions, claims, and red-flag overlays remain deterministic renderer-owned. See `references/proof-short-ai-visual-upgrade.md`.
   - Reward hooks with direct address, specificity, open loops, tension, and a visible payoff; reject slow intros such as “In this video...”.
   - See `references/retention-led-shorts.md` for scoring signals, penalties, and voiceover finalization rules.

4. **Quality gate before rendering**
   Score drafts on:
   - hook strength
   - novelty
   - emotional pull
   - clarity
   - retention risk
   - comment/share potential
   - AI-slop risk
   - platform/policy risk
   - first-frame clarity
   - mechanism value
   - practical payoff
   - save/share/follow reason
   - trust/human texture
   - series fit and saturation defense
   Render only drafts above the chosen threshold, e.g. 8/10.
   For TrueTraceShorts, use the 100-point scoring and hard blockers in `references/truetrace-strategic-neuausrichtung.md`: block generic AI hooks, pure text first frames, unsourced claims, missing before/after, missing human texture, unclear AI disclosure, and candidates too similar to recent videos.

5. **Visual strategy**
   - Avoid obvious AI artifacts, fake UI text, illegible generated lettering, generic charts, and soulless stock visuals.
   - Prefer high-contrast kinetic captions, visible hook text in first seconds, relatable B-roll, screen recordings for AI/tutorial content, phone/screen close-ups, before/after transformations, cards, and timer visuals.
   - Use pattern interrupts every 2–3 seconds for retention.
   - Before rendering, generate a shot plan from the finalized voiceover: first-frame hook, pattern interrupt, core explanation, screen/card visual, CTA, caption beats, and asset type.
   - Before writing a renderer, convert shot plans into deterministic render manifests: machine-readable timeline items, asset placeholders, caption tracks, style constraints, and approval constraints. See `references/render-manifest-pipeline.md`.
   - Treat this as a deterministic intermediate artifact, not optional prose. See `references/retention-render-planning.md` for the five-scene shot-plan pattern and renderer-facing fields.
   - For the first video output, build a manifest-driven preview renderer before any AI-video or polished asset pipeline: first create a side-effect-free local preview plan, then write deterministic PNG scene cards, then build a side-effect-free FFmpeg concat plan, and only then call FFmpeg from an explicit renderer boundary. The boundary should report side effects such as `write_png`, `write_concat`, `call_ffmpeg`, and `write_mp4`; keep generated PNG/MP4 artifacts out of Git. See `references/manifest-preview-renderer.md`.
   - When the user rejects static/slideshow output, add an `asset_plan.v2` layer that maps each scene to motion-led local asset modes such as `cinematic_ai_video`, `screen_recording_simulation`, `mechanism_animation`, or `kinetic_text_overlay` with no baked text. If the user requires a free workflow, do not depend on paid video-credit tools; use local procedural motion and optional free NVIDIA LLM text refinement. See `references/ai-video-asset-planning.md`.
   - For hybrid workflows, add an imported-clip assembly layer: provider handoff prompts create short manual AI-video clips, humans drop them into deterministic `data/imported_ai_clips/<slug>/scene_XX.mp4` paths, and the final renderer combines imported clips with local mechanism animations/captions. See `references/imported-ai-clip-assembly.md`.
   - For local Wan2.2 quality workflows, prefer keyframe/image-to-video over raw text-to-video: generate/select a clean keyframe, run native Wan2.2 I2V variants, review clips bluntly for subject clarity/motion/artifacts, then add all labels/numbers/captions via deterministic renderer. See `references/wan-i2v-retention-studio.md`.
   - For final renders, Wan must carry the visual scene, not merely provide a blurred/looped background underneath preview cards. Use full-bleed, scene-specific Wan clips, minimal renderer-owned overlays, and a final overlay policy that blocks preview frames, large UI cards/textboxes, debug bars, and overlay overload. If architecture is rejected, create a short visual proof first; see `references/visual-first-final-render-repair.md`.
   - If a visual proof still looks like blind text-to-video or random abstract AI output, stop T2V and move to a keyframe-first workflow: generate/approve 1–2 text-free start/end/style keyframes for the scene, then attempt only a short Wan I2V/first-last-frame proof. See `references/keyframe-first-final-visuals.md`.
   - When using NVIDIA Build/API Catalog for keyframes, prefer hosted `ai.api.nvidia.com` calls before considering self-hosted NIM deployment; implement a configurable model fallback chain, store the key as a runtime secret, and inspect/clean logos, emblems, license plates, and fake text before I2V. See `references/nvidia-keyframe-generation.md`.

6. **Social-media draft and content-preview approval packages before TTS/rendering polish**
   - Before TTS, platform APIs, or polished video generation, build a typed `SocialMediaDraft` from the approved candidate plus render manifest/preview.
   - Include platform targets, title variants, caption, hashtags, CTA, hook, duration, quality/risk summary, and preview reference.
   - Render this into a Telegram-safe approval message and wrap it in a side-effect-free delivery plan with `requires_human_approval=True` and `side_effects=()`.
   - After a local MP4 timing preview exists, combine the MP4 path plus social draft review into a side-effect-free content preview approval package. This package should carry `approval_language=de`, `final_video_language=en`, explicit approval commands, no external calls, and no side effects.
   - Add local demo CLIs that print metadata first, then review text; draft-only CLIs must not write files, call renderers, call Telegram, or access credentials. MP4 preview CLIs may write local artifacts and call FFmpeg only at explicit renderer boundaries that report side effects.
   - See `references/social-draft-approval-package.md` and `references/content-automation-patterns.md` for concrete artifact sequence, user-specific language rules, and external workflow patterns.

7. **Human approval loop before posting**
   - Send preview to the user through the requested channel, usually Telegram.
   - For AutoShorts/TrueTraceShorts YouTube approval requests, the review message must include all four items together:
     1. the actual MP4 as a Telegram-playable media attachment, not only a filesystem path;
     2. a proposed title;
     3. a proposed engaging description, optionally with tasteful emojis and hashtags;
     4. the exact `APPROVED_FOR_PRIVATE_YOUTUBE_UPLOAD ...` command the user can return.
   - If a `MEDIA:/path/to/video.mp4` line does not appear as an inline Telegram player, copy the MP4 into a Hermes media cache/allowed media directory and resend from there before asking for approval. A path in text is not sufficient for this user.
   - Include: video or preview reference, title, caption, hashtags, platform recommendation, duration, quality/risk score.
   - For AutoShorts/TrueTraceShorts videos that are upload-package ready, include the exact hash-bound YouTube private-draft approval command in a copyable code block with every delivery. The user expects to be able to return that command unchanged for release.
   - When sending multiple preview videos, verify and label distinct artifacts before delivery: candidate ID/title, absolute path, duration, and preferably checksum/hash. If several previews are visually similar timing cards, do not spam them as separate unlabeled media; send a concise indexed list first or bundle with clear labels so the user can tell them apart.
   - Wait for explicit approval such as `Freigabe alle`, `Freigabe YouTube`, `Freigabe TikTok`, `Ablehnen`, or `Ändern: ...`.
   - Do not publish automatically unless the user has explicitly authorized that workflow.

8. **TTS / voice layer after draft approval**
   - Treat TTS as a later layer, not the starting point for a first post draft.
   - Decide voice, final voiceover script, words-per-second, scene timing, caption sync, audio format, provider, and separate voice approval only after the social draft package is reviewable.
   - This avoids spending TTS/rendering effort on unapproved hooks, captions, or platform positioning.
  - For final-near previews, keep one copy source of truth: final voiceover → script draft/retention beats → shot plan → top card text → scene captions → subtitle track → TTS audio. Do not mix old approval-card text with new spoken/subtitle text.
  - If the user says the result is too abstract/abgehoben, rewrite around a concrete beginner-friendly everyday failure example before polishing visuals. Prefer “one weird email arrives” / missing field / unclear request / wrong confident action over jargon such as `exception path`, `input boundary`, or `output standard`. See `references/beginner-friendly-audio-caption-alignment.md`.
  - If the user says subtitles are irritating or not simultaneous with voiceover, treat this as a blocking quality issue: use forced alignment or provider word-boundary events before sending another final-near clip. For EdgeTTS previews, request `boundary='WordBoundary'` and render active-word highlights from those offsets; do not merely distribute words evenly over sentence SRT durations. For this user's AutoShorts/TrueTraceShorts default, do **not** show one word alone and do **not** slide a changing word-window every word. Use static phrase segments: keep 3–7 words fixed on screen while only the currently spoken word highlights/pulses left-to-right; replace the full segment only at a sentence/phrase boundary. See `references/static-active-word-captions-and-final-pilot-render.md`.
  - If the user says the ending is confusing, rushed, or does not offer a real solution, treat this as a content-blocking issue, not a minor copy tweak. Rewrite the final third so non-technical viewers are explicitly walked through the concrete action: what to close/avoid, what to open/check instead, how they know it worked, and the memorable rule/fazit. Avoid vague imperatives like “open the service yourself” unless immediately unpacked with a concrete example such as “close the invite; open the calendar/work app from the normal icon or bookmark; if the meeting is real, it will still be there.”
  - If deterministic layouts explain the mechanism but look like wireframes/PowerPoint, do not promote them to final style.
  - If deterministic layouts explain the mechanism but look like wireframes/PowerPoint, do not promote them to final style. Treat them as composition blueprints and run a small, tightly prompted premium AI styleframe pass instead: AI supplies glassmorphism/product-film quality and atmosphere; the renderer still owns labels, arrows, captions, facts, and final assembly. See `references/premium-ai-styleframe-direction.md`.
  - If premium AI styleframes improve quality but still feel like abstract SaaS symbolism, do not continue iterating abstract funnels/rings. Move to real-life anchored work scenes: desk/laptop, empty meeting room/glass board, or project table/work evidence, with only subtle glass/holographic mechanism overlays. See `references/real-life-premium-styleframes.md`.
  - If real-life styleframe directions are accepted but the user has not approved Wan/I2V yet, insert a pre-release animatic comparison step rather than jumping to endframes or video generation. Create small per-direction AI keyframe sets, deterministic push-ins/crossfades, existing voiceover, static active-word captions, contact sheets, and QA frame sheets; report Telegram delivery metadata. See `references/prerelease-animatic-preview.md`.
If the user rejects the added visual explanation overlays as making the result look like a technical explainer board, treat this as a hard style failure. For the clean pilot, use only AI images, voiceover, and clean subtitles; block circles, arrows, labels, boxes, connector lines, decision-target markers, debug/diagram elements, and caption boxes/bars. See `references/clean-image-cut-no-overlay-pilot.md`. If the user then asks whether pure KI-Bilder can achieve the same or better effect, run an A/B proof against the hybrid version and assess premium look vs mechanism clarity; the likely final style may be `90% clean AI images + 10% minimal renderer-owned mechanism`. See `references/clean-ai-cut-vs-hybrid-mechanism.md`.
  - For mechanism-reveal final renders, use the hybrid pattern in `references/final-motion-hybrid-rendering.md`: ChatGPT Image/Codex or similar tools create text-free scene backgrounds only; deterministic renderer owns cards, labels, arrows, subtitles, and FFmpeg assembly. Use compact phrase-boundary subtitle cues before 1080 export.

9. **Publish and measure**
   Track at minimum:
   - platform, video id/url, niche, format, hook, duration
   - views at 2h/24h/7d
   - likes, comments, shares, saves, follows
   - retention metrics if available
   Use results to generate the next batch.

## Platform duration/monetization notes

See `references/preview-media-delivery-guardrails.md` for avoiding duplicate-looking/unlabeled preview-video spam in Telegram review workflows.

See `references/truetrace-strategic-spine-refactor-v2.md` for implementing the new TrueTraceShorts strategy in code: V2 strategic models, hard gates, anti-AI-slop blockers, SeriesRegistry, 100-point scoring, hash-bound ReviewPackageV2, and deterministic five-candidate examples without rendering or platform side effects. See `references/truetrace-v2-operational-bridge.md` for the next implementation step: secure the Sprint-1 commit, add minimal side-effect-free bridge/workflow/CLI modules, deterministic ReviewPackageV2 JSON, strict approval parsing, calibrated scoring, anti-example/human-texture gates, manual claim/disclosure stubs, LinkedIn manual metadata, and Remotion-as-later-spike documentation without production expansion.

See `references/audio-caption-preview-pipeline.md` for the approval-first EdgeTTS + ASS subtitles + FFmpeg review-MP4 pipeline, including actual-audio-duration probing and the explicit `preserve_video` vs `trim_to_audio` duration-mode guardrail. See `references/mobile-vertical-aspect-qa.md` for the mobile 9:16 export QA/repair pattern: probe final MP4 SAR/DAR, extract a frame, and re-export full-bleed 1080x1920 with `setsar=1,setdar=9/16` when Telegram/Shorts previews show black bars or squeezed height. See `references/pilot-preview-render-v2.md` for the stricter first-pilot preview pattern: preview-only approval state, EdgeTTS sentence SRT to preview word cues when forced alignment is unavailable, deterministic card/diagram animatic rendering, SHA256/duration verification, and Telegram media delivery while Wan/AI-image/platform calls remain blocked. See `references/static-active-word-captions-and-final-pilot-render.md` for the corrected Hormozi-style caption behaviour and the one-render final pilot review-package checklist. See `references/word-boundary-caption-sync-and-solution-gate.md` for the stronger EdgeTTS `WordBoundary` timing pattern and the explicit solution/fazit gate for Proof Shorts.

See `references/final-motion-hybrid-rendering.md` for the final-near hybrid renderer pattern: ChatGPT Image/Codex or other AI tools provide text-free background/keyframe texture while deterministic renderer overlays own text, arrows, labels, captions, and final assembly. For quick prototypes, prefer ChatGPT Image/Codex backgrounds before local Qwen/ComfyUI unless privacy/cost/local-only constraints dominate. After a 1080 export, create a side-effect-free final approval package with media path, SHA256, platform metadata, social copy, quality notes, and approval commands before any delivery or platform step. If Telegram/mobile playback shows black bars, squeezed height, wrong aspect metadata, clipped UI text, or cramped active-word captions, follow `references/mobile-safe-vertical-export-and-caption-qa.md`: normalize to 1080x1920 square pixels with explicit `setsar=1,setdar=9/16`, verify with ffprobe, and inspect QA frames before sending again.

See `references/visual-first-final-render-repair.md` for the repaired final-render architecture after a rejected pilot: mark rejected renders as not-postable, avoid preview-board overlays, enforce `FinalOverlayPolicy`, validate ComfyUI/Wan output histories robustly, and use `APPROVED_FOR_VISUAL_PROOF` for one short visual proof before any second full final.

See `references/hybrid-scene-backgrounds-codex.md` for the concrete ChatGPT Image/Codex scene-background workflow: side-effect-free `SceneBackgroundPlan`, per-scene text-free backgrounds, renderer-owned overlays, and visual QA before review delivery. Prefer this over local Qwen/ComfyUI when the user allows Codex image generation and local GPU should be reserved for video/model work.

See `references/monetization-and-approval-notes.md` for current working notes captured from official YouTube/TikTok docs and the recommended approval/posting setup. See `references/monetization-map-description-checklists.md` for the accepted current monetization pattern: no newsletter or 30-day learning program for now, use topic-specific 3-bullet YouTube checklist blocks, short TikTok/Reels checklist captions, and cautious affiliate partner fit/claim guardrails. See `references/retention-led-shorts.md` for retention scoring signals, no-faith/adjacent-pillar handling, and voiceover finalization rules. See `references/render-manifest-pipeline.md` for the script → shot plan → render manifest → renderer sequence that prevents generic AI slideshow output. See `references/manifest-preview-renderer.md` for the first deterministic Pillow/FFmpeg preview-renderer pattern. See `references/local-preview-frame-writer.md` for the staged `LocalPreviewPlan → PNG scene cards → FFmpeg concat plan` boundary before MP4 rendering. See `references/social-draft-approval-package.md` for the typed first-post approval package to build before TTS or platform APIs. See `references/content-automation-patterns.md` for public workflow patterns, queue/status/cost tracking, versioned approval, synthetic-content disclosure, originality gates, and the user's German-preview/English-final rule. See `references/ai-video-asset-planning.md` for motion-led final-render asset planning with Kling/Hailuo/Runway-style clips and screen simulations. See `references/imported-ai-clip-assembly.md` for hybrid assembly where manually generated provider clips are imported into a deterministic local renderer. See `references/nvidia-keyframe-generation.md` for NVIDIA-hosted keyframe generation, model fallback, secret handling, and pre-I2V logo/plate cleanup. Re-check official docs before making business-critical decisions because platform programs change often.

## Project/repo hygiene for automated video bots

- Keep source code in Git; keep generated videos, assets, `.env`, OAuth tokens, API keys, and downloaded secrets out of Git.
- Use `.gitignore` aggressively for outputs, media caches, local credentials, and temp files.
- Store platform credentials as runtime secrets; never print raw tokens.
- Build the repo as modular components: idea generation, scripting, rendering, review, publishing, analytics.
- For approval-first Retention Studio implementations, use a typed side-effect-free core before real I/O: `ContentBrief`, `ScriptDraft`, `VideoCandidate`, review batches, Telegram delivery plans, then shot plans. See `references/approval-first-retention-studio-core.md`.
- When cleaning/consolidating this user's AutoShortsBot runtime folders, use `references/autoshortsbot-runtime-cleanup-and-canonical-path.md`: prefer `/home/agent/jarvis_runtime/autoshortsbot/AutoShortsBot` as the canonical future repo, treat `/home/agent/jarvis_runtime/AutoShortsBot` as a divergent older/production-artifact copy to inspect before removal, and prefer rename-and-test over immediate deletion.

## Sensitive-content positioning

When AI/productivity automation is the primary brand, be cautious about mixing in religious/FaithTok, health, finance, or other high-trust themes. If the user flags the combination as sensitive, pause that pillar rather than forcing it into the same testbatch. Replace it with a safer adjacent pillar (for example `attention_design`) and document the paused pillar in config so it can be revisited only with explicit approval and a separate brand strategy.

## Pitfalls

- If Telegram/mobile playback shows top/bottom black bars or a visibly squeezed vertical image, do not hand-wave it as a player quirk. Re-export through an explicit mobile-safe normalization boundary (`scale=1080:1920:force_original_aspect_ratio=increase,crop=1080:1920,setsar=1,setdar=9/16,format=yuv420p`), verify SAR/DAR with ffprobe, and inspect extracted frames before redelivery; see `references/mobile-safe-vertical-export-and-caption-qa.md`.
- Do not let active-word captions become unreadable compounds. In uppercase/bold 1080-wide renders, even 3–7 word phrase chunks can merge visually; use shorter 1–3 word chunks or larger spacing/font shrink, then QA a real frame after rendering. EdgeTTS word-boundary events may strip punctuation, so do not group caption chunks only by `WordBoundary` token punctuation; align back to source-script token punctuation or use phrase breakers to avoid cross-sentence chunks like “SPOTS THIRD GIVE”.
- Do not send several generated preview videos as unlabeled media attachments just because they are distinct files. Telegram/mobile previews can make timing-card MP4s look identical. Verify uniqueness (path + title + hash/duration) and provide labels or an indexed summary; if the user complains about duplicate-looking media, stop resending, verify artifacts, and continue the pipeline.
- Do not let final-near preview layers drift apart: if the top field, voiceover, and subtitles do not say the same thing, rebuild the render plan from one final script source before sending another clip.
- Do not make broad-audience AI-system shorts sound like architecture lectures. For early-AI users, convert abstract workflow concepts into concrete everyday failures first, then reveal the principle.
- Do not over-optimize renderer quality before testing whether the content format earns retention.
- Do not keep iterating a polished pilot when the user identifies the core failure as “pretty but semantically weak.” Archive it as a learning case, preserve what worked, and restart with a Proof Short whose first second shows a real visible fail and an immediately useful rule.
- Do not overcorrect from “validate with Proof Shorts” into “never use AI images.” Once the real problem/rule is approved, AI images can legitimately improve perceived quality as text-free atmosphere, backgrounds, keyframes, or thumbnails. Keep factual UI/document/payment layers deterministic; use AI for polish, not truth.
- Do not let German approval previews become unreadable technical cards: use pixel-width-aware wrapping, readable fonts, limited line counts, visual checks for clipped/overcrowded text, and hard mobile safe-zone tests for captions/highlights before delivery.
- Do not deliver final-near Shorts/Reels/TikTok MP4s based only on nominal render dimensions. Probe `width,height,sample_aspect_ratio,display_aspect_ratio`, extract QA frames, and repair black bars or squeezed-height playback with a full-bleed 1080x1920 square-pixel export (`setsar=1,setdar=9/16`) before resending.
- Do not confuse approval language with final audience language. For this user, approval previews are German by default; final social videos remain English unless explicitly changed.
- Do not copy public automation workflows wholesale: keep their queue/status/cost tracking and template structure, but remove blind auto-publishing until a human approval/version lock exists.
- Do not mass-generate repetitive shorts without originality/inauthentic-content gates; this can harm monetization/account health and create AI slop.
- Do not jump directly from a script idea to ComfyUI/Wan/Qwen/Image/video generation. First build and inspect the content-to-review spine so weak hooks, generic scripts, policy issues, and static visual concepts are killed before render time.
- Do not assume local Qwen/ComfyUI is the best first image step for every final-near short. If the user permits ChatGPT Image/Codex, use it for text-free scene backgrounds/keyframes when the deterministic renderer owns labels/captions and local GPU should be saved for video/model work. When provider quality matters, verify the actual `image_gen.provider`/model from config and the image cache filenames/metadata rather than guessing; for premium styleframes prefer the highest available reasonable GPT Image tier, but keep fake invoice/email/UI/payment-route mockups deterministic.
- Do not create a parallel candidate path for content experiments; convert content artifacts into the existing candidate factory input so IDs, hashtags, duration classes, quality gates, and pillar/platform validation stay centralized.
- Do not use `x or default` for optional content/script overrides in factories; explicit blank strings and zero durations must pass through to validation so tests can catch them.
- For Chatterbox/Taylor voiceovers, do not slow speech with `speed` or `speed_factor` if the user is judging quality; it can make the voice metallic/blechern. Keep speed at `1.0` and control pacing through punctuation, shorter sentence chunks, and pauses.
- Do not assume TikTok monetization rules match YouTube: TikTok Creator Rewards emphasizes 1min+ eligible videos, while shorter videos may still be better for growth.
- Do not treat a keyframe animatic as a successful Wan/I2V proof. If ComfyUI/Wan I2V fails or history contains no valid video output, label any fallback MP4 as `not_wan` / composition-review-only and block full-final progression.
- Do not treat deterministic layout proofs as the final premium visual style when the user asked for a high-end social-video look. Layouts are for mechanism composition; after approval, use a tightly scoped premium AI styleframe pass with strict negative prompts and verified delivery before endframes/Wan.
- Do not mistake premium abstract glassmorphism for an approved final direction if the user wants a credible everyday work scene. When the user says the motif is still too abstract, switch to real-life work-scene styleframes with laptop/tablet/meeting-room/project-table anchors; keep motion graphics subtle and renderer-owned.
- If the user rejects the production method itself, do not keep iterating content visuals. Reject/audit the proof, run a technical I2V sanity test with a trivial non-content image, and only after it passes generate a small set of styleframes for direction review; see `references/visual-production-reset-i2v-first.md`.
- Do not keep trying blind text-to-video after the user rejects a proof as abstract, dark, generic, or semantically ungrounded. Move to keyframe-first planning, review the keyframes, then run at most one short I2V/first-last-frame proof.
- For TrueTraceShorts after the Digital Red Flags repositioning, do not suggest AI/workflow/prompt topics as the default next post. Start from normal-person scam self-defense: delivery texts, fake support popups, marketplace buyer scams, fake QR/login pages, invoice/payment route changes, password reuse, or family/emotion scams. Each candidate must show one normal screen, one visible red flag, and one safer move before any render.
- Do not call the audience “Boomers” externally even when designing boomer-safe content. Use “Digital self-defense for normal people”; keep language simple, readable, and shareable without being patronizing.
- Do not use AI image generation to invent critical scam-screen text/data when a deterministic mockup is safer. AI can add premium atmosphere; renderer-owned mockups should control SMS, invoices, bank/login pages, payment routes, QR situations, marketplace chats, popups, captions, and checklist cards.
- For this user's TrueTraceShorts visual standard, do not fall back to plain deterministic mockup/PowerPoint-looking videos when the user asked for the polished clean-AI-image direction. If deterministic UI is needed for factual control, integrate it with high-quality AI-generated scene/keyframe visuals so the final feels premium, not like a renderer demo.
- For Chatterbox/Taylor-standard AutoShorts renders, do not silently treat EdgeTTS or another provider as an equivalent final voice if the Chatterbox endpoint temporarily fails. First run a short Chatterbox connectivity/Taylor speech probe; if still down, label any alternate voice render as a temporary fallback and make the package/version/hash reflect that actual voice. If Chatterbox comes back, rerender the same candidate with Chatterbox, regenerate forced alignment/captions and package hashes, and deliver a fresh approval command; never reuse the fallback approval command.
- For deterministic SMS/phone proof shorts, do not let fake URLs or UI strings run off the card. Use short reserved-domain text such as `example.com/hold`, then inspect an extracted hook frame before delivery.
- Do not assume TTS word-boundary events were emitted just because TTS audio rendered. Check the word-boundary count; if it is zero, regenerate active-word ASS subtitles from a manual sentence-start timing fallback and QA a real subtitle frame.
- When creating the next numbered Everyday Red Flags video by adapting the previous render script, update every candidate-specific identifier, not only the visible title/script: `CANDIDATE_ID`, output/post-candidate slug, VERSION if policy changed, audio/word/metadata filenames, final MP4 filename, image/keyframe names, package title/description/hashtags/tags, topic-database `topic_id` and `existing_artifact_hint`, media-cache path, and any stale comments/placeholders. Stale IDs in approval packages or topic DB make later upload/dry-run approval brittle — tedious, yes, but so is explaining to YouTube that `erf-010` is secretly `erf-013`. For the repeatable “next video” workflow from a prior known-good renderer, see `references/next-erf-video-render-from-prior-script.md`: choose topic, generate 5–6 premium keyframes, clone/rename the prior script carefully, run end-to-end, QA contact sheet + hook/final frames, update topic DB, and deliver a media-cache MP4 with hash-bound approval command.
- Do not remove old AI/workflow pillars abruptly when refactoring AutoShortsBot. Keep them as legacy/secondary compatibility entries while making Digital Red Flags the primary strategy, otherwise broad existing tests/pipelines may break unnecessarily.
- Do not send AutoShorts approval requests that only contain a local MP4 path or a non-clickable `MEDIA:` reference from a runtime directory. The user expects the video to be directly playable in Telegram; if delivery fails, stage/copy the MP4 into an allowed Hermes media cache and resend the review package with the playable video plus title, description, and approval command.
- Do not rerun a YouTube private upload after the API has returned a video ID just because local Dashboard bookkeeping failed. First recover the video ID from the audit/API response, then repair `VideoAsset`, `PostDraft`, `UploadRequest`, and `YouTubeUploadAudit` rows; mark duplicate older upload requests superseded to prevent a second private upload. See `references/hash-bound-private-youtube-upload-dashboard-recovery.md`.
- Do not expose a private YouTube Short as a visitor-facing website button/link. After private upload, store the ID/URL only in source metadata with `website_link_allowed: false`, set `videoUrl: null`, build the site, and grep dist HTML/JS to verify the private ID is absent.
- Do not rerun a YouTube private upload immediately after a thumbnail-setting failure. If `videos.insert` succeeded and `thumbnails.set` returned 403/no custom-thumbnail permission, a private video may already exist; report the Studio link/video ID, create a partial audit, and have the user set the thumbnail manually rather than creating a duplicate upload.
- Do not publish religious or health-adjacent content with overconfident claims; preserve humility, nuance, and platform safety.
- Do not rely on platform payout as the only monetization path; plan indirect monetization such as newsletter, templates, affiliates, digital products, or services.
- Do not confuse Pixabay API scopes: this user stores the Pixabay key at `~/.hermes/secrets/pixabay_api_key` in `.env` form (`PIXABAY_API=...`), and it has been verified for `https://pixabay.com/api/videos/` stock-video search. Do not invent or assume a documented music/audio API when Pixabay docs only cover image/video; strip the env-var prefix, use the video endpoint for B-roll where useful, and for music ask for a licensed MP3/URL or another approved music source instead of falling back to homemade/generated music.