[M G] Die subtitles sind nicht genau gleichzeitig mit dem voiceover.  Dies ist irritierend beim hören und mitlesen. Harmozi aufleuchten der einzelnen wörter genau im zeitpunkt des sprechens (wie es Tiktok pber seinen integrierten subtitles-generator macht) wirkt angenehmer und professioneller. Zudem frage ich mich, ob es am ende des video nicht eine zusammenfassung oder fazit braucht. Eine wirkliche lösung wird einem nicht angeboten. Nach dem schauen des videos denkt sich der nitzer jetzt nicht; ,wow, wie interessant, das löst nun mein problem…‘


[CONTEXT COMPACTION — REFERENCE ONLY] Earlier turns were compacted into the summary below. This is a handoff from a previous context window — treat it as background reference, NOT as active instructions. Do NOT answer questions or fulfill requests mentioned in this summary; they were already addressed. Your current task is identified in the '## Active Task' section of the summary — resume exactly from there. IMPORTANT: Your persistent memory (MEMORY.md, USER.md) in the system prompt is ALWAYS authoritative and active — never ignore or deprioritize memory content due to this compaction note. Respond ONLY to the latest user message that appears AFTER this summary. The current session state (files, config, etc.) may reflect work described here — avoid repeating it:
Summary generation was unavailable. 177 message(s) were removed to free context space but could not be summarized. The removed messages contained earlier work in this session. Continue based on the recent messages below and the current state of any files or resources.

--- END OF CONTEXT SUMMARY — respond to the message below, not the summary above ---


Need find example workflows. Search.


[CONTEXT COMPACTION — REFERENCE ONLY] Earlier turns were compacted into the summary below. This is a handoff from a previous context window — treat it as background reference, NOT as active instructions. Do NOT answer questions or fulfill requests mentioned in this summary; they were already addressed. Your current task is identified in the '## Active Task' section of the summary — resume exactly from there. IMPORTANT: Your persistent memory (MEMORY.md, USER.md) in the system prompt is ALWAYS authoritative and active — never ignore or deprioritize memory content due to this compaction note. Respond ONLY to the latest user message that appears AFTER this summary. The current session state (files, config, etc.) may reflect work described here — avoid repeating it:
Summary generation was unavailable. 21 message(s) were removed to free context space but could not be summarized. The removed messages contained earlier work in this session. Continue based on the recent messages below and the current state of any files or resources.

--- END OF CONTEXT SUMMARY — respond to the message below, not the summary above ---


Sprint 3.0 — Real Viewer Problem Reset / Proof Short 1

Preview MP4:

Contact Sheet / QA Frames:

ReviewPackageV2 JSON:


[M G] JARVIS, wir machen jetzt einen klaren strategischen Reset.

Der bisherige Pilot “AI Summary / Decision Target” wird pausiert und als Lernfall archiviert. Nicht weiter daran optimieren, nicht weiter rendern, nicht posten.

Grund:
Das Video sieht zwar zunehmend sauberer aus, aber es löst das zentrale Problem nicht: Es zeigt keinen sofort sichtbaren realen Schmerz. Die Bilder sind hübsch, aber semantisch leer. Das schaut sich niemand lange an.

Neue Grundregel:
Wir fokussieren ab jetzt auf wirklichen Nutzen und reale Probleme der Viewer.

Nicht mehr zuerst fragen:
“Wie machen wir ein schönes KI-Video?”

Sondern zuerst:
“Welches echte Problem erkennt der Zuschauer in Sekunde 1 — und warum hilft ihm dieses Video sofort?”

Neuer Sprint:

Sprint 3.0 — Real Viewer Problem Reset / Proof Short 1

Ziel:
Baue einen neuen ersten Pilot als Proof Short, nicht als Premium-KI-Film.

Fokus:

* reales Problem
* sichtbarer Fail
* sofortiger Nutzen
* starke Retention
* klare Regel
* hoher Save-/Share-Wert
* keine abstrakten Glaswolken
* kein generisches AI-B-Roll
* kein Wan-Final
* keine Styleframe-Orgie

1. Alten Pilot archivieren

Bitte archiviere den bisherigen Kandidaten:

ai-output-autopsy-decision-summary-38s

Status:

paused_learning_case

Reason:
“Pretty but semantically weak. Too abstract for first pilot. Visuals do not create immediate viewer pain or retention.”

Speichere ein kurzes Postmortem:

* Was funktionierte:

  * Approval-Gates
  * Captions ohne Box
  * Delivery
  * Styleframe-Workflow-Lernen
  * I2V-Sanity-Test
* Was nicht funktionierte:

  * Thema zu abstrakt für ersten Pilot
  * Bilder zeigten keinen sichtbaren Fail
  * zu viel Produktionsaufwand vor validiertem Format
  * zu viele visuelle Metaphern
  * Wan/Bild-KI wurde zu früh als Story-Träger benutzt
* Neue Regel:

  * Pretty Empty Visual Blocker

2. Pretty Empty Visual Blocker einführen

Bitte ergänze als Quality Gate:

pretty_empty_visual_blocker

Blockiert einen Kandidaten oder Visual-Plan, wenn:

* das Bild hochwertig aussieht, aber ohne Voiceover kein klares Problem zeigt
* kein sichtbarer Fail vorhanden ist
* das Visual nur Mood/B-Roll ist
* der Zuschauer nicht innerhalb von 1 Sekunde erkennt, worum es geht
* der Nutzen nur durch abstrakte Erklärung entsteht
* die Szene austauschbar ist
* das Bild auch für 50 andere AI-/Productivity-Videos passen würde

Ein guter Visual-Plan muss beantworten:

* Was ist konkret kaputt?
* Wo sieht man den Fehler?
* Was steht für den Zuschauer auf dem Spiel?
* Welche einfache Regel repariert es?
* Warum sollte man es speichern oder teilen?

3. Neuer Content-Modus: Proof Short

Bitte lege einen neuen Produktionsmodus an oder dokumentiere ihn:

ProofShortMode

Eigenschaften:

* 25–35 Sekunden
* screen/mockup-led oder real-problem-led
* kein Wan-Final
* keine aufwendigen AI-Styleframes
* keine abstrakten Metaphern
* keine Premium-Episode-Produktion
* schnelle, klare, nützliche Preview
* Ziel: Format und Thema validieren

Proof Shorts sind für die ersten 10–20 Videos der Default.

Premium Episodes kommen erst später, wenn ein Thema/Format über echte Zuschauerreaktionen bewiesen ist.

4. Neues Thema für Pilot 1 wählen

Bitte erstelle als neuen Hauptpilot:

Digital Red Flags — Fake Invoice Payment Route

Arbeitsname:

digital-red-flags-fake-invoice-payment-route-30s

Warum dieses Thema:

* reales Problem
* sofort sichtbar
* hoher Nutzwert
* hoher Share-Wert
* klarer Schmerz
* leicht visuell darstellbar
* kein abstraktes AI-Thema
* kein Wan nötig
* sehr gut als Proof Short

5. Neues Skript bauen

Bitte erstelle einen neuen ScriptDraft für ca. 28–35 Sekunden.

Hook-Vorschlag:

“This invoice looks normal. The trap is not the logo — it’s the payment route.”

Struktur:

0–2s:
Sichtbare Rechnung / E-Mail / Zahlungsaufforderung.
Hook.

2–7s:
“Same layout. Same professional tone. Same urgency.”

7–14s:
“But one thing changed: where the money goes.”

14–24s:
“Before you pay, check three things: sender domain, urgency language, and payment route.”

24–31s:
“If the route changed, don’t pay from the email. Verify through a second
channel.”

Takeaway:
“Urgency is not proof. It’s the red flag.”

Bitte mache 3 Hook-Varianten:

* Problem Hook
* Red Flag Hook
* Save/Share Hook

Aber wähle danach eine Hauptversion aus.

6. Visual-Ansatz

Nicht:

* abstrakte AI-Bilder
* Glaswolken
* generische Laptop-B-Roll
* Wan als Hauptvisual
* pseudo-realistische Fake-Rechnung mit echten Details
* echte Marken, IBANs, QR-Codes, Logos

Sondern:
kontrolliertes, fiktives Mockup.

Renderer-owned:

* Fake-Invoice-Mockup ohne echte Marke
* Fake-E-Mail-Screen ohne echte Adresse
* fiktive Zahlungskarte
* sichtbarer Unterschied: payment route changed
* drei Checks:

  * sender
  * urgency
  * payment route
* roter/gelber Red-Flag-Moment
* keine realen Bankdaten
* keine echten Firmen
* keine echten Logos
* keine echten QR-Codes
* keine echten Personen

Visual-Format:

* screen/mockup-led motion short
* 9:16
* klare mobile Lesbarkeit
* hochwertige UI-/Dokument-Mockups
* ruhige Animation
* gezielte Highlights
* keine überladenen Textflächen
* keine AI-Bildgenerierung nötig, ausser optional für neutralen Hintergrund

7. Preview bauen, nicht Final

Bitte erstelle zuerst nur ein Preview / Proof Short MP4:

* Voiceover
* Captions ohne Box
* screen/mockup visuals
* simple motion
* no Wan
* no AI image generation unless strictly necessary
* no platform API
* no posting

Output:
digital-red-flags-fake-invoice-payment-route-30s_preview_v1.mp4

8. Captions

Nutze die inzwischen bewährte Caption-Regel:

* static phrase segments
* active-word highlight
* keine Rahmenbox
* keine Vollbreiten-Bar
* keine dunkle Fläche
* weisse Wörter
* aktives Wort gelb
* subtiler Schatten/Outline
* mobile-safe

9. Claims / Safety

Bitte Claim Gate sauber setzen.

Claim-Typ:
general safety advice / low-to-medium risk.

Nicht behaupten:

* dass alle Fake-Rechnungen so funktionieren
* dass diese drei Checks alle Scams verhindern
* dass dies rechtliche/finanzielle Beratung ist

Besser formulieren:

* “A common red flag is…”
* “Before you pay, check…”
* “Verify through a second channel.”

Keine echten Betrugsanleitungen.
Keine echten Bankdaten.
Keine echten Firmen.
Keine echten Scam-Vorlagen, die missbraucht werden können.

10. Review Package

Bitte liefere ein ReviewPackageV2 mit:

* Candidate ID
* Hook
* Script
* Visual Plan
* Pretty Empty Visual Blocker Result
* Claim Gate
* AI Disclosure
* ProofShortMode = true
* Save Reason
* Share Reason
* Follow Reason
* Platform Fit
* Preview MP4 path
* SHA256
* Telegram Delivery Status

11. Telegram Delivery

Bitte Preview-MP4 senden und verifizieren:

* telegram_delivery_attempted
* telegram_delivery_verified
* telegram_message_id
* file_path
* file_size
* sha256
* duration
* resolution

Wenn Telegram nicht klappt:
klar sagen: “lokal erzeugt, Telegram-Versand nicht erfolgt.”

12. Kein Full-Final

Nicht ausführen:

* kein Wan
* kein I2V
* kein Full-Final
* keine Plattform-API
* kein Auto-Posting
* kein Scheduling
* keine Render-Serie

13. Danach mögliche Kommandos

Wenn Preview passt:

APPROVED_PROOF_SHORT digital-red-flags-fake-invoice-payment-route-30s

Wenn überarbeiten:

REVISE_PROOF_SHORT digital-red-flags-fake-invoice-payment-route-30s <field> "Änderungswunsch"

Wenn ablehnen:

REJECT_PROOF_SHORT digital-red-flags-fake-invoice-payment-route-30s "Grund"

Wenn manuelle Upload-Vorbereitung später erlaubt:

APPROVED_FOR_MANUAL_POSTING_PACK digital-red-flags-fake-invoice-payment-route-30s

Wichtigster Grundsatz:
Wir bauen jetzt keinen schönen AI-Film. Wir bauen ein nützliches Short, das ein echtes Problem sichtbar macht und dem Zuschauer eine sofort brauchbare Regel gibt.


Sir, **Sprint 3.0 — Real Viewer Problem Reset / Proof Short 1 ist umgesetzt.**

Strategischer Reset wurde angewendet:

- Der bisherige Pilot **`ai-output-autopsy-decision-summary-38s`** ist pausiert.
- Neuer Hauptpilot: **`digital-red-flags-fake-invoice-payment-route-30s`**
- Modus: **ProofShortMode**
- Visual-Ansatz: **screen/mockup-led**, reales Problem, sichtbarer Fail, kein Premium-KI-Film.
- Preview wurde gerendert und per Telegram geliefert.

Nicht ausgeführt:

- kein Wan
- kein I2V
- kein Full-Final
- keine AI-Bildgenerierung
- keine Plattform-API
- kein Posting
- kein Scheduling
- keine Render-Serie

## 1. Alter Pilot archiviert

Archiv/Postmortem:

```text
/tmp/autoshorts_proof_short_sprint30/digital-red-flags-fake-invoice-payment-route-30s/archive/ai-output-autopsy-decision-summary-38s_postmortem.json
```

Status:

```text
paused_learning_case
```

Reason:

```text
Pretty but semantically weak. Too abstract for first pilot. Visuals do not create immediate viewer pain or retention.
```

Was funktionierte:

- Approval-Gates
- Captions ohne Box
- Delivery
- Styleframe-Workflow-Lernen
- I2V-Sanity-Test

Was nicht funktionierte:

- Thema zu abstrakt für ersten Pilot
- Bilder zeigten keinen sichtbaren Fail
- zu viel Produktionsaufwand vor validiertem Format
- zu viele visuelle Metaphern
- Wan/Bild-KI wurde zu früh als Story-Träger benutzt

Neue Regel:

```text
Pretty Empty Visual Blocker
```

## 2. Pretty Empty Visual Blocker + ProofShortMode

Im Repo ergänzt und committed:

```text
autoshorts/strategy/proof_short.py
tests/test_proof_short_mode.py
```

Commit:

```text
dac8906 Add proof short mode and pretty empty visual gate
```

Der Gate blockiert Kandidaten/Visual-Pläne, wenn:

- hochwertiges Bild, aber kein klares Problem ohne Voiceover
- kein sichtbarer Fail
- nur Mood/B-Roll
- Zuschauer erkennt in Sekunde 1 nicht, worum es geht
- Nutzen nur abstrakt erklärt wird
- Szene austauschbar wirkt
- Visual für 50 andere AI-/Productivity-Videos passen würde

ProofShortMode Default:

```text
duration: 25–35s
screen_or_real_problem_led: true
wan_final_allowed: false
premium_styleframe_pass_allowed: false
abstract_metaphors_allowed: false
```

Tests:

```text
10 passed in 0.08s
```

Geprüft:

```text
tests/test_proof_short_mode.py
tests/test_pilot_production_v2.py
```

## 3. Neuer Pilot

Candidate ID:

```text
digital-red-flags-fake-invoice-payment-route-30s
```

Arbeitstitel:

```text
Digital Red Flags — Fake Invoice Payment Route
```

Warum stark:

- reales Problem
- sofort sichtbar
- hoher Nutzwert
- hoher Share-Wert
- klarer Schmerz
- visuell kontrollierbar über Mockups
- kein Wan nötig
- kein AI-B-Roll nötig

## 4. Hook-Varianten

Gespeichert:

```text
/tmp/autoshorts_proof_short_sprint30/digital-red-flags-fake-invoice-payment-route-30s/script_draft_v1.json
```

Problem Hook:

```text
This invoice looks normal. The trap is not the logo — it’s the payment route.
```

Red Flag Hook:

```text
A fake invoice does not need a fake logo. It only needs a changed payment route.
```

Save/Share Hook:

```text
Before anyone on your team pays an invoice, check this one red flag.
```

Gewählte Hauptversion:

```text
This invoice looks normal. The trap is not the logo — it’s the payment route.
```

## 5. ScriptDraft

Script:

```text
This invoice looks normal. The trap is not the logo — it’s the payment route. Same layout. Same professional tone. Same urgency. But one thing changed: where the money goes. Before you pay, check three things: sender domain, urgency language, and payment route. If the route changed, don’t pay from the email. Verify through a second channel. Urgency is not proof. It’s the red flag.
```

Dauer:

```text
31.29s MP4
31.32s Voiceover
```

## 6. Visual Plan

Gespeichert:

```text
/tmp/autoshorts_proof_short_sprint30/digital-red-flags-fake-invoice-payment-route-30s/visual_plan_v1.json
```

Format:

```text
screen/mockup-led motion short
9:16
controlled fictional UI/document mockup
```

Szenen:

```text
s01_visible_fail:
fake email + invoice mockup; payment route visible

s02_same_layout:
same layout / same tone / same urgency

s03_route_changed:
payment route changes; red-flag moment

s04_three_checks:
sender domain / urgency language / payment route

s05_second_channel:
do not pay from email; verify through second channel

s06_takeaway:
Urgency is not proof. It is the red flag.
```

Safety:

- keine echten Marken
- keine echten Bankdaten
- keine IBANs
- keine QR-Codes
- keine echten Personen
- keine echten Firmen
- keine echten Scam-Vorlagen
- keine Plattform-API

## 7. Pretty Empty Visual Blocker Result

```text
pretty_empty_visual_blocker_result:
pass
```

Warum:

- konkreter sichtbarer Fail im ersten Frame
- echte Viewer-Pain: Fake Invoice / Payment Route Change
- klarer Stakes: Geld geht an falsche Route
- einfache Regel: Sender, Urgency, Payment Route, Second Channel
- Save/Share-Grund klar

## 8. Claim Gate

Claim-Typ:

```text
general safety advice / low-to-medium risk
```

Risk:

```text
medium
```

Result:

```text
pass
```

Sichere Formulierungen:

```text
A common red flag is…
Before you pay, check…
Verify through a second channel.
```

Nicht behauptet:

- dass alle Fake-Rechnungen so funktionieren
- dass drei Checks alle Scams verhindern
- dass dies rechtliche oder finanzielle Beratung ist

Abuse Controls:

- keine echten Bankdaten
- keine echten Firmen
- keine Logos
- keine QR-Codes
- keine operationalisierbare Scam-Vorlage

## 9. ReviewPackageV2

Finales ReviewPackage:

```text
/tmp/autoshorts_proof_short_sprint30/digital-red-flags-fake-invoice-payment-route-30s/review_package_v2.json
```

Enthält:

- Candidate ID
- Hook
- Script
- Visual Plan
- Pretty Empty Visual Blocker Result
- Claim Gate
- AI Disclosure
- ProofShortMode = true
- Save Reason
- Share Reason
- Follow Reason
- Platform Fit
- Preview MP4 path
- SHA256
- Telegram Delivery Status

ScoreV2:

```text
87/100
render_allowed: true
reject_reasons: []
```

AI Disclosure:

```text
no: deterministic mockups and TTS preview; no realistic AI-generated people/scenes
```

## 10. Preview MP4

Per Telegram gesendet.

MEDIA:/tmp/autoshorts_proof_short_sprint30/digital-red-flags-fake-invoice-payment-route-30s/preview_v1/digital-red-flags-fake-invoice-payment-route-30s_preview_v1.mp4

```text
file_path:
/tmp/autoshorts_proof_short_sprint30/digital-red-flags-fake-invoice-payment-route-30s/preview_v1/digital-red-flags-fake-invoice-payment-route-30s_preview_v1.mp4

file_exists:
true

file_size:
1270875 bytes

sha256:
bc8256104d1db71de6277b64db351ac3e1282d33396015ef09439aff033c47ba

media_type:
video/mp4

duration:
31.291667s

resolution:
1080x1920

fps:
24/1

telegram_delivery_attempted:
true

telegram_delivery_verified:
true

telegram_message_id:
5951
```

## 11. Contact Sheet / QA Frames

MEDIA:/tmp/autoshorts_proof_short_sprint30/digital-red-flags-fake-invoice-payment-route-30s/preview_v1/digital-red-flags_contact_sheet_v1.jpg

```text
file_path:
/tmp/autoshorts_proof_short_sprint30/digital-red-flags-fake-invoice-payment-route-30s/preview_v1/digital-red-flags_contact_sheet_v1.jpg

file_exists:
true

file_size:
79590 bytes

sha256:
bf2d7131fb10d2065221d41f3a2abdd0b6e61bdb5832fa7e9b5dc7fd0a9f888e

media_type:
image/jpeg

resolution:
1080x720

telegram_delivery_attempted:
true

telegram_delivery_verified:
true

telegram_message_id:
5951
```

QA:

```text
pass
```

Beobachtung:

- sichtbare Invoice-/Payment-Route-Situation
- kein abstraktes B-Roll
- keine echten Logos/Brands
- keine realen Bankdaten
- keine QR-Codes
- Captions white/yellow, ohne Box/Bar
- Problem ist visuell deutlich schneller erkennbar als beim alten Pilot

## 12. Voiceover

```text
file_path:
/tmp/autoshorts_proof_short_sprint30/digital-red-flags-fake-invoice-payment-route-30s/audio/voiceover.mp3

file_exists:
true

file_size:
187920 bytes

sha256:
4e9da013d7c4baf1ddddbba9d0900471a0ffea243325b52bf02cf0f56f643bf5

duration:
31.32s
```

Voice:

```text
en-US-GuyNeural
```

## 13. Caption Style

Verwendet:

```text
static phrase segments
active-word highlight
white inactive words
yellow active word
subtle shadow/outline
no box
no full-width bar
no dark rectangle
mobile-safe bottom
```

## 14. Einschätzung

Das ist strategisch deutlich richtiger als der alte Pilot.

Warum:

- Erster Frame zeigt ein reales Problem.
- Das Thema ist sofort verständlich.
- Der Viewer erkennt sich oder sein Team wieder.
- Die Regel ist konkret und speicherbar.
- Das Short braucht keine KI-Ästhetik, um zu funktionieren.
- Der Nutzen ist nicht abhängig von abstrakter Voiceover-Erklärung.

Kurz: **weniger hübscher Nebel, mehr echter Schmerz.** Welch radikale Innovation.

## 15. Nicht ausgeführt

```text
wan_used:
false

i2v_used:
false

full_final_render:
false

posting:
false

platform_api:
false

scheduling:
false

new_ai_images:
false
```

## 16. Nächste erlaubte Kommandos

Wenn Preview passt:

```text
APPROVED_PROOF_SHORT digital-red-flags-fake-invoice-payment-route-30s
```

Wenn überarbeiten:

```text
REVISE_PROOF_SHORT digital-red-flags-fake-invoice-payment-route-30s <field> "Änderungswunsch"
```

Wenn ablehnen:

```text
REJECT_PROOF_SHORT digital-red-flags-fake-invoice-payment-route-30s "Grund"
```

Wenn später manuelle Upload-Vorbereitung erlaubt ist:

```text
APPROVED_FOR_MANUAL_POSTING_PACK digital-red-flags-fake-invoice-payment-route-30s
```

Pipeline bleibt blockiert für Full-Final, Wan/I2V, Posting und Plattform-APIs.


Sprint 3.1 Artefakte — Preview v2 Caption Safe

Preview MP4:

QA Frame Sheet:

Subtitle Style Preview:


Explanation:
**Considering skills for automation**

I see that I need to take action and assess the skills required for this project. It sounds like I should look into relevant social automations, perhaps using something like the hermes-agent. I think I’ll need to focus on configuring the Hermes image generator and ensure it has the proper loading capabilities. Alright, let's see how I can get started with these configurations!


social-media-shorts-automation

---
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 note: 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. 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.

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.

## Core principle

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 the user's TrueTraceShorts / AutoShortsBot strategy, do **not** default to a narrow AI/prompt-tips channel. The current strategic direction is broader: explain hidden digital everyday mechanisms — AI, work, attention, decisions, scams, productivity, workflows, social search — and end each video with one small system rule that fixes the outcome. Use the frame `Trace the hidden system. Fix the outcome.` AI should remain an important pillar, but normally only about 30–40% of the topic mix, not the whole product. See `references/truetrace-strategic-neuausrichtung.md`.

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`.
   - 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.
   - Include: video or preview reference, title, caption, hashtags, platform recommendation, duration, quality/risk score.
   - 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 simplify captions before sending another final-near clip. 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 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 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`.
  - 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/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/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.

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/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`.

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

- 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 let German approval previews become unreadable technical cards: use pixel-width-aware wrapping, readable fonts, limited line counts, and visual checks for clipped/overcrowded text.
- 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.
- 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.
- 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.
- 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.

To view linked files, call skill_view(name, file_path) where file_path is e.g. 'references/api.md' or 'assets/config.yaml'


hermes-agent

---
name: hermes-agent
description: "Configure, extend, or contribute to Hermes Agent."
version: 2.1.0
author: Hermes Agent + Teknium
license: MIT
metadata:
  hermes:
    tags: [hermes, setup, configuration, multi-agent, spawning, cli, gateway, development]
    homepage: https://github.com/NousResearch/hermes-agent
    related_skills: [claude-code, codex, opencode]
---

# Hermes Agent

Hermes Agent is an open-source AI agent framework by Nous Research that runs in your terminal, messaging platforms, and IDEs. It belongs to the same category as Claude Code (Anthropic), Codex (OpenAI), and OpenClaw — autonomous coding and task-execution agents that use tool calling to interact with your system. Hermes works with any LLM provider (OpenRouter, Anthropic, OpenAI, DeepSeek, local models, and 15+ others) and runs on Linux, macOS, and WSL.

What makes Hermes different:

- **Self-improving through skills** — Hermes learns from experience by saving reusable procedures as skills. When it solves a complex problem, discovers a workflow, or gets corrected, it can persist that knowledge as a skill document that loads into future sessions. Skills accumulate over time, making the agent better at your specific tasks and environment.
- **Persistent memory across sessions** — remembers who you are, your preferences, environment details, and lessons learned. Pluggable memory backends (built-in, Honcho, Mem0, and more) let you choose how memory works.
- **Multi-platform gateway** — the same agent runs on Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Email, and 10+ other platforms with full tool access, not just chat.
- **Provider-agnostic** — swap models and providers mid-workflow without changing anything else. Credential pools rotate across multiple API keys automatically.
- **Profiles** — run multiple independent Hermes instances with isolated configs, sessions, skills, and memory.
- **Extensible** — plugins, MCP servers, custom tools, webhook triggers, cron scheduling, and the full Python ecosystem.

People use Hermes for software development, research, system administration, data analysis, content creation, home automation, and anything else that benefits from an AI agent with persistent context and full system access.

**This skill helps you work with Hermes Agent effectively** — setting it up, configuring features, spawning additional agent instances, troubleshooting issues, finding the right commands and settings, and understanding how the system works when you need to extend or contribute to it.

**Docs:** https://hermes-agent.nousresearch.com/docs/

## Quick Start

```bash
# Install
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# Interactive chat (default)
hermes

# Single query
hermes chat -q "What is the capital of France?"

# Setup wizard
hermes setup

# Change model/provider
hermes model

# Check health
hermes doctor
```

---

## CLI Reference

### Global Flags

```
hermes [flags] [command]

  --version, -V             Show version
  --resume, -r SESSION      Resume session by ID or title
  --continue, -c [NAME]     Resume by name, or most recent session
  --worktree, -w            Isolated git worktree mode (parallel agents)
  --skills, -s SKILL        Preload skills (comma-separate or repeat)
  --profile, -p NAME        Use a named profile
  --yolo                    Skip dangerous command approval
  --pass-session-id         Include session ID in system prompt
```

No subcommand defaults to `chat`.

### Chat

```
hermes chat [flags]
  -q, --query TEXT          Single query, non-interactive
  -m, --model MODEL         Model (e.g. anthropic/claude-sonnet-4)
  -t, --toolsets LIST       Comma-separated toolsets
  --provider PROVIDER       Force provider (openrouter, anthropic, nous, etc.)
  -v, --verbose             Verbose output
  -Q, --quiet               Suppress banner, spinner, tool previews
  --checkpoints             Enable filesystem checkpoints (/rollback)
  --source TAG              Session source tag (default: cli)
```

### Configuration

```
hermes setup [section]      Interactive wizard (model|terminal|gateway|tools|agent)
hermes model                Interactive model/provider picker
hermes config               View current config
hermes config edit          Open config.yaml in $EDITOR
hermes config set KEY VAL   Set a config value
hermes config path          Print config.yaml path
hermes config env-path      Print .env path
hermes config check         Check for missing/outdated config
hermes config migrate       Update config with new options
hermes login [--provider P] OAuth login (nous, openai-codex)
hermes logout               Clear stored auth
hermes doctor [--fix]       Check dependencies and config
hermes status [--all]       Show component status
```

### Tools & Skills

```
hermes tools                Interactive tool enable/disable (curses UI)
hermes tools list           Show all tools and status
hermes tools enable NAME    Enable a toolset
hermes tools disable NAME   Disable a toolset

hermes skills list          List installed skills
hermes skills search QUERY  Search the skills hub
hermes skills install ID    Install a skill (ID can be a hub identifier OR a direct https://…/SKILL.md URL; pass --name to override when frontmatter has no name)
hermes skills inspect ID    Preview without installing
hermes skills config        Enable/disable skills per platform
hermes skills check         Check for updates
hermes skills update        Update outdated skills
hermes skills uninstall N   Remove a hub skill
hermes skills publish PATH  Publish to registry
hermes skills browse        Browse all available skills
hermes skills tap add REPO  Add a GitHub repo as skill source
```

#### Image generation via ChatGPT/Codex OAuth

When the user asks to use ChatGPT Images / GPT Image from Hermes without a separate OpenAI API key, prefer the bundled `openai-codex` image-generation backend. It uses the existing Hermes-managed ChatGPT/Codex OAuth token and routes image generation through the Responses `image_generation` tool.

Setup:

```bash
# Ensure image_gen is enabled for the platform, then select the Codex-backed provider.
hermes config set image_gen.provider openai-codex
hermes config set image_gen.model gpt-image-2-medium
```

Available practical tiers:

```bash
hermes config set image_gen.model gpt-image-2-low     # quick drafts / cheaper iteration
hermes config set image_gen.model gpt-image-2-medium  # balanced default
hermes config set image_gen.model gpt-image-2-high    # final keyframes / highest fidelity
```

Verify from Python if needed:

```bash
python - <<'PY'
from hermes_cli.plugins import _ensure_plugins_discovered
from agent.image_gen_registry import get_provider
_ensure_plugins_discovered(force=True)
p = get_provider('openai-codex')
print(bool(p and p.is_available()), p.default_model() if p else None)
PY
```

If the provider is unavailable, sign in with Codex/ChatGPT OAuth (`hermes auth add` / `hermes login --provider openai-codex`, depending on the installed Hermes version) rather than creating a new API-key workflow. Config changes may require `/reset` or `/restart` in gateway sessions before the tool schema/availability updates.

### MCP Servers

```
hermes mcp serve            Run Hermes as an MCP server
hermes mcp add NAME         Add an MCP server (--url or --command)
hermes mcp remove NAME      Remove an MCP server
hermes mcp list             List configured servers
hermes mcp test NAME        Test connection
hermes mcp configure NAME   Toggle tool selection
```

### Gateway (Messaging Platforms)

```
hermes gateway run          Start gateway foreground
hermes gateway install      Install as background service
hermes gateway start/stop   Control the service
hermes gateway restart      Restart the service
hermes gateway status       Check status
hermes gateway setup        Configure platforms
```

Supported platforms: Telegram, Discord, Slack, WhatsApp, Signal, Email, SMS, Matrix, Mattermost, Home Assistant, DingTalk, Feishu, WeCom, BlueBubbles (iMessage), Weixin (WeChat), API Server, Webhooks. Open WebUI connects via the API Server adapter.

Platform docs: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/

**Telegram setup:** See `references/telegram-gateway-setup.md` for the complete step-by-step configuration workflow.

### Sessions

```
hermes sessions list        List recent sessions
hermes sessions browse      Interactive picker
hermes sessions export OUT  Export to JSONL
hermes sessions rename ID T Rename a session
hermes sessions delete ID   Delete a session
hermes sessions prune       Clean up old sessions (--older-than N days)
hermes sessions stats       Session store statistics
```

### Cron Jobs

```
hermes cron list            List jobs (--all for disabled)
hermes cron create SCHED    Create: '30m', 'every 2h', '0 9 * * *'
hermes cron edit ID         Edit schedule, prompt, delivery
hermes cron pause/resume ID Control job state
hermes cron run ID          Trigger on next tick
hermes cron remove ID       Delete a job
hermes cron status          Scheduler status
```

### Webhooks

```
hermes webhook subscribe N  Create route at /webhooks/<name>
hermes webhook list         List subscriptions
hermes webhook remove NAME  Remove a subscription
hermes webhook test NAME    Send a test POST
```

### Profiles

```
hermes profile list         List all profiles
hermes profile create NAME  Create (--clone, --clone-all, --clone-from)
hermes profile use NAME     Set sticky default
hermes profile delete NAME  Delete a profile
hermes profile show NAME    Show details
hermes profile alias NAME   Manage wrapper scripts
hermes profile rename A B   Rename a profile
hermes profile export NAME  Export to tar.gz
hermes profile import FILE  Import from archive
```

### Credential Pools

```
hermes auth add             Interactive credential wizard
hermes auth list [PROVIDER] List pooled credentials
hermes auth remove P INDEX  Remove by provider + index
hermes auth reset PROVIDER  Clear exhaustion status
```

### Other

```
hermes insights [--days N]  Usage analytics
hermes update               Update to latest version
hermes pairing list/approve/revoke  DM authorization
hermes plugins list/install/remove  Plugin management
hermes honcho setup/status  Honcho memory integration (requires honcho plugin)
hermes memory setup/status/off  Memory provider config
hermes completion bash|zsh  Shell completions
hermes acp                  ACP server (IDE integration)
hermes claw migrate         Migrate from OpenClaw
hermes uninstall            Uninstall Hermes
```

---

## Slash Commands (In-Session)

Type these during an interactive chat session. New commands land fairly
often; if something below looks stale, run `/help` in-session for the
authoritative list or see the [live slash commands reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands).
The registry of record is `hermes_cli/commands.py` — every consumer
(autocomplete, Telegram menu, Slack mapping, `/help`) derives from it.

### Session Control
```
/new (/reset)        Fresh session
/clear               Clear screen + new session (CLI)
/retry               Resend last message
/undo                Remove last exchange
/title [name]        Name the session
/compress            Manually compress context
/stop                Kill background processes
/rollback [N]        Restore filesystem checkpoint
/snapshot [sub]      Create or restore state snapshots of Hermes config/state (CLI)
/background <prompt> Run prompt in background
/queue <prompt>      Queue for next turn
/steer <prompt>      Inject a message after the next tool call without interrupting
/agents (/tasks)     Show active agents and running tasks
/resume [name]       Resume a named session
/goal [text|sub]     Set a standing goal Hermes works on across turns until achieved
                     (subcommands: status, pause, resume, clear)
/redraw              Force a full UI repaint (CLI)
```

### Configuration
```
/config              Show config (CLI)
/model [name]        Show or change model
/personality [name]  Set personality
/reasoning [level]   Set reasoning (none|minimal|low|medium|high|xhigh|show|hide)
/verbose             Cycle: off → new → all → verbose
/voice [on|off|tts]  Voice mode
/yolo                Toggle approval bypass
/busy [sub]          Control what Enter does while Hermes is working (CLI)
                     (subcommands: queue, steer, interrupt, status)
/indicator [style]   Pick the TUI busy-indicator style (CLI)
                     (styles: kaomoji, emoji, unicode, ascii)
/footer [on|off]     Toggle gateway runtime-metadata footer on final replies
/skin [name]         Change theme (CLI)
/statusbar           Toggle status bar (CLI)
```

### Tools & Skills
```
/tools               Manage tools (CLI)
/toolsets            List toolsets (CLI)
/skills              Search/install skills (CLI)
/skill <name>        Load a skill into session
/reload-skills       Re-scan ~/.hermes/skills/ for added/removed skills
/reload              Reload .env variables into the running session (CLI)
/reload-mcp          Reload MCP servers
/cron                Manage cron jobs (CLI)
/curator [sub]       Background skill maintenance (status, run, pin, archive, …)
/kanban [sub]        Multi-profile collaboration board (tasks, links, comments)
/plugins             List plugins (CLI)
```

### Gateway
```
/approve             Approve a pending command (gateway)
/deny                Deny a pending command (gateway)
/restart             Restart gateway (gateway)
/sethome             Set current chat as home channel (gateway)
/update              Update Hermes to latest (gateway)
/topic [sub]         Enable or inspect Telegram DM topic sessions (gateway)
/platforms (/gateway) Show platform connection status (gateway)
```

### Utility
```
/branch (/fork)      Branch the current session
/fast                Toggle priority/fast processing
/browser             Open CDP browser connection
/history             Show conversation history (CLI)
/save                Save conversation to file (CLI)
/copy [N]            Copy the last assistant response to clipboard (CLI)
/paste               Attach clipboard image (CLI)
/image               Attach local image file (CLI)
```

### Info
```
/help                Show commands
/commands [page]     Browse all commands (gateway)
/usage               Token usage
/insights [days]     Usage analytics
/gquota              Show Google Gemini Code Assist quota usage (CLI)
/status              Session info (gateway)
/profile             Active profile info
/debug               Upload debug report (system info + logs) and get shareable links
```

### Exit
```
/quit (/exit, /q)    Exit CLI
```

---

## Key Paths & Config

```
~/.hermes/config.yaml       Main configuration
~/.hermes/.env              API keys and secrets
$HERMES_HOME/skills/        Installed skills
~/.hermes/sessions/         Session transcripts
~/.hermes/logs/             Gateway and error logs
~/.hermes/auth.json         OAuth tokens and credential pools
~/.hermes/hermes-agent/     Source code (if git-installed)
```

Profiles use `~/.hermes/profiles/<name>/` with the same layout.

### Config Sections

Edit with `hermes config edit` or `hermes config set section.key value`.

| Section | Key options |
|---------|-------------|
| `model` | `default`, `provider`, `base_url`, `api_key`, `context_length` |
| `agent` | `max_turns` (90), `tool_use_enforcement` |
| `terminal` | `backend` (local/docker/ssh/modal), `cwd`, `timeout` (180) |
| `compression` | `enabled`, `threshold` (0.50), `target_ratio` (0.20) |
| `display` | `skin`, `tool_progress`, `show_reasoning`, `show_cost` |
| `stt` | `enabled`, `provider` (local/groq/openai/mistral) |
| `tts` | `provider` (edge/elevenlabs/openai/minimax/mistral/neutts) |
| `memory` | `memory_enabled`, `user_profile_enabled`, `provider` |
| `security` | `tirith_enabled`, `website_blocklist` |
| `delegation` | `model`, `provider`, `base_url`, `api_key`, `max_iterations` (50), `reasoning_effort` |
| `checkpoints` | `enabled`, `max_snapshots` (50) |

Full config reference: https://hermes-agent.nousresearch.com/docs/user-guide/configuration

### Providers

20+ providers supported. Set via `hermes model` or `hermes setup`.

| Provider | Auth | Key env var |
|----------|------|-------------|
| OpenRouter | API key | `OPENROUTER_API_KEY` |
| Anthropic | API key | `ANTHROPIC_API_KEY` |
| Nous Portal | OAuth | `hermes auth` |
| OpenAI Codex | OAuth | `hermes auth` |
| GitHub Copilot | Token | `COPILOT_GITHUB_TOKEN` |
| Google Gemini | API key | `GOOGLE_API_KEY` or `GEMINI_API_KEY` |
| DeepSeek | API key | `DEEPSEEK_API_KEY` |
| xAI / Grok | API key | `XAI_API_KEY` |
| Hugging Face | Token | `HF_TOKEN` |
| Z.AI / GLM | API key | `GLM_API_KEY` |
| MiniMax | API key | `MINIMAX_API_KEY` |
| MiniMax CN | API key | `MINIMAX_CN_API_KEY` |
| Kimi / Moonshot | API key | `KIMI_API_KEY` |
| Alibaba / DashScope | API key | `DASHSCOPE_API_KEY` |
| Xiaomi MiMo | API key | `XIAOMI_API_KEY` |
| Kilo Code | API key | `KILOCODE_API_KEY` |
| AI Gateway (Vercel) | API key | `AI_GATEWAY_API_KEY` |
| OpenCode Zen | API key | `OPENCODE_ZEN_API_KEY` |
| OpenCode Go | API key | `OPENCODE_GO_API_KEY` |
| Qwen OAuth | OAuth | `hermes login --provider qwen-oauth` |
| Custom endpoint | Config | `model.base_url` + `model.api_key` in config.yaml |
| GitHub Copilot ACP | External | `COPILOT_CLI_PATH` or Copilot CLI |

Full provider docs: https://hermes-agent.nousresearch.com/docs/integrations/providers

### Toolsets

Enable/disable via `hermes tools` (interactive) or `hermes tools enable/disable NAME`.

| Toolset | What it provides |
|---------|-----------------|
| `web` | Web search and content extraction |
| `search` | Web search only (subset of `web`) |
| `browser` | Browser automation (Browserbase, Camofox, or local Chromium) |
| `terminal` | Shell commands and process management |
| `file` | File read/write/search/patch |
| `code_execution` | Sandboxed Python execution |
| `vision` | Image analysis |
| `image_gen` | AI image generation |
| `video` | Video analysis and generation |

**Image generation via Codex OAuth:** If the user wants ChatGPT/Codex-backed image generation without a separate OpenAI API key, configure `image_gen.provider=openai-codex` and choose a `gpt-image-2-*` tier. See `references/openai-codex-image-generation.md` for the setup, verification probe, and AutoShortsBot keyframe pipeline notes.
| `tts` | Text-to-speech |

#### Image generation via OpenAI/Codex OAuth

When the user wants GPT Image 2 / ChatGPT Images generation inside Hermes without a separate OpenAI API key, configure the bundled `openai-codex` image backend. It uses the user's existing Codex/ChatGPT OAuth credentials and keeps image generation off the local GPU, which is useful when ComfyUI/Wan video workloads need the VRAM.

```bash
hermes config set image_gen.provider openai-codex
hermes config set image_gen.model gpt-image-2-medium
```

Use `gpt-image-2-low` for quick drafts, `gpt-image-2-medium` as the normal default, and `gpt-image-2-high` for final/high-fidelity keyframes or thumbnails. After changing this for the Telegram gateway, use `/restart` or a fresh `/reset` if the old config appears cached. See `references/openai-codex-image-generation.md` for verification commands and operational notes.
| `skills` | Skill browsing and management |
| `memory` | Persistent cross-session memory |
| `session_search` | Search past conversations |
| `delegation` | Subagent task delegation |
| `cronjob` | Scheduled task management |
| `clarify` | Ask user clarifying questions |
| `messaging` | Cross-platform message sending |
| `todo` | In-session task planning and tracking |
| `kanban` | Multi-agent work-queue tools (gated to workers) |
| `debugging` | Extra introspection/debug tools (off by default) |
| `safe` | Minimal, low-risk toolset for locked-down sessions |
| `spotify` | Spotify playback and playlist control |
| `homeassistant` | Smart home control (off by default) |
| `discord` | Discord integration tools |
| `discord_admin` | Discord admin/moderation tools |
| `feishu_doc` | Feishu (Lark) document tools |
| `feishu_drive` | Feishu (Lark) drive tools |
| `yuanbao` | Yuanbao integration tools |
| `rl` | Reinforcement learning tools (off by default) |
| `moa` | Mixture of Agents (off by default) |

Full enumeration lives in `toolsets.py` as the `TOOLSETS` dict; `_HERMES_CORE_TOOLS` is the default bundle most platforms inherit from.

Tool changes take effect on `/reset` (new session). They do NOT apply mid-conversation to preserve prompt caching.

---

## Security & Privacy Toggles

Common "why is Hermes doing X to my output / tool calls / commands?" toggles — and the exact commands to change them. Most of these need a fresh session (`/reset` in chat, or start a new `hermes` invocation) because they're read once at startup.

### Secret redaction in tool output

Secret redaction is **off by default** — tool output (terminal stdout, `read_file`, web content, subagent summaries, etc.) passes through unmodified. If the user wants Hermes to auto-mask strings that look like API keys, tokens, and secrets before they enter the conversation context and logs:

```bash
hermes config set security.redact_secrets true       # enable globally
```

**Restart required.** `security.redact_secrets` is snapshotted at import time — toggling it mid-session (e.g. via `export HERMES_REDACT_SECRETS=true` from a tool call) will NOT take effect for the running process. Tell the user to run `hermes config set security.redact_secrets true` in a terminal, then start a new session. This is deliberate — it prevents an LLM from flipping the toggle on itself mid-task.

Disable again with:
```bash
hermes config set security.redact_secrets false
```

### PII redaction in gateway messages

Separate from secret redaction. When enabled, the gateway hashes user IDs and strips phone numbers from the session context before it reaches the model:

```bash
hermes config set privacy.redact_pii true    # enable
hermes config set privacy.redact_pii false   # disable (default)
```

### Command approval prompts

By default (`approvals.mode: manual`), Hermes prompts the user before running shell commands flagged as destructive (`rm -rf`, `git reset --hard`, etc.). The modes are:

- `manual` — always prompt (default)
- `smart` — use an auxiliary LLM to auto-approve low-risk commands, prompt on high-risk
- `off` — skip all approval prompts (equivalent to `--yolo`)

```bash
hermes config set approvals.mode smart       # recommended middle ground
hermes config set approvals.mode off         # bypass everything (not recommended)
```

Per-invocation bypass without changing config:
- `hermes --yolo …`
- `export HERMES_YOLO_MODE=1`

Note: YOLO / `approvals.mode: off` does NOT turn off secret redaction. They are independent.

### Shell hooks allowlist

Some shell-hook integrations require explicit allowlisting before they fire. Managed via `~/.hermes/shell-hooks-allowlist.json` — prompted interactively the first time a hook wants to run.

### Disabling the web/browser/image-gen tools

To keep the model away from network or media tools entirely, open `hermes tools` and toggle per-platform. Takes effect on next session (`/reset`). See the Tools & Skills section above.

---

### Voice & Transcription

### STT (Voice → Text)

Voice messages from messaging platforms are auto-transcribed.

**⚠ Pitfall: faster-whisper must be installed for local STT to work.** The config may show `provider: local` but if `faster-whisper` is not installed in the venv, STT silently fails. Always verify with `pip show faster-whisper` after configuring local STT.

Provider priority (auto-detected):
1. **Local faster-whisper** — free, no API key: `pip install faster-whisper`
2. **Groq Whisper** — free tier: set `GROQ_API_KEY`
3. **OpenAI Whisper** — paid: set `VOICE_TOOLS_OPENAI_KEY`
4. **Mistral Voxtral** — set `MISTRAL_API_KEY`

Config:
```yaml
stt:
  enabled: true
  provider: local        # local, groq, openai, mistral
  local:
    model: small         # tiny, base, small, medium, large-v3 — use 'small' or higher for German
    language: de         # always set explicitly for German — auto-detect is unreliable
```

### Pitfalls
- **faster-whisper must be installed** — config shows `provider: local` but STT silently fails if the package is missing
- **Use `small` model minimum for German** — `base` is too weak
- **Set `language: de` explicitly** — auto-detect is unreliable
- **Swiss German (dialect) is NOT supported** — Whisper transcribes dialect poorly; user should speak Standard German

### TTS (Text → Voice)

| Provider | Env var | Free? |
|----------|---------|-------|
| Edge TTS | None | Yes (default) |
| ElevenLabs | `ELEVENLABS_API_KEY` | Free tier |
| OpenAI | `VOICE_TOOLS_OPENAI_KEY` | Paid |
| MiniMax | `MINIMAX_API_KEY` | Paid |
| Mistral (Voxtral) | `MISTRAL_API_KEY` | Paid |
| NeuTTS (local) | None (`pip install neutts[all]` + `espeak-ng`) | Free |

Voice commands: `/voice on` (voice-to-voice), `/voice tts` (always voice), `/voice off`.

---

## Spawning Additional Hermes Instances

Run additional Hermes processes as fully independent subprocesses — separate sessions, tools, and environments.

### When to Use This vs delegate_task

| | `delegate_task` | Spawning `hermes` process |
|-|-----------------|--------------------------|
| Isolation | Separate conversation, shared process | Fully independent process |
| Duration | Minutes (bounded by parent loop) | Hours/days |
| Tool access | Subset of parent's tools | Full tool access |
| Interactive | No | Yes (PTY mode) |
| Use case | Quick parallel subtasks | Long autonomous missions |

### One-Shot Mode

```
terminal(command="hermes chat -q 'Research GRPO papers and write summary to ~/research/grpo.md'", timeout=300)

# Background for long tasks:
terminal(command="hermes chat -q 'Set up CI/CD for ~/myapp'", background=true)
```

### Interactive PTY Mode (via tmux)

Hermes uses prompt_toolkit, which requires a real terminal. Use tmux for interactive spawning:

```
# Start
terminal(command="tmux new-session -d -s agent1 -x 120 -y 40 'hermes'", timeout=10)

# Wait for startup, then send a message
terminal(command="sleep 8 && tmux send-keys -t agent1 'Build a FastAPI auth service' Enter", timeout=15)

# Read output
terminal(command="sleep 20 && tmux capture-pane -t agent1 -p", timeout=5)

# Send follow-up
terminal(command="tmux send-keys -t agent1 'Add rate limiting middleware' Enter", timeout=5)

# Exit
terminal(command="tmux send-keys -t agent1 '/exit' Enter && sleep 2 && tmux kill-session -t agent1", timeout=10)
```

### Multi-Agent Coordination

```
# Agent A: backend
terminal(command="tmux new-session -d -s backend -x 120 -y 40 'hermes -w'", timeout=10)
terminal(command="sleep 8 && tmux send-keys -t backend 'Build REST API for user management' Enter", timeout=15)

# Agent B: frontend
terminal(command="tmux new-session -d -s frontend -x 120 -y 40 'hermes -w'", timeout=10)
terminal(command="sleep 8 && tmux send-keys -t frontend 'Build React dashboard for user management' Enter", timeout=15)

# Check progress, relay context between them
terminal(command="tmux capture-pane -t backend -p | tail -30", timeout=5)
terminal(command="tmux send-keys -t frontend 'Here is the API schema from the backend agent: ...' Enter", timeout=5)
```

### Session Resume

```
# Resume most recent session
terminal(command="tmux new-session -d -s resumed 'hermes --continue'", timeout=10)

# Resume specific session
terminal(command="tmux new-session -d -s resumed 'hermes --resume 20260225_143052_a1b2c3'", timeout=10)
```

### Tips

- **Prefer `delegate_task` for quick subtasks** — less overhead than spawning a full process
- **Use `-w` (worktree mode)** when spawning agents that edit code — prevents git conflicts
- **Set timeouts** for one-shot mode — complex tasks can take 5-10 minutes
- **Use `hermes chat -q` for fire-and-forget** — no PTY needed
- **Use tmux for interactive sessions** — raw PTY mode has `\r` vs `\n` issues with prompt_toolkit
- **For scheduled tasks**, use the `cronjob` tool instead of spawning — handles delivery and retry

---

## Durable & Background Systems

Four systems run alongside the main conversation loop. Quick reference
here; full developer notes live in `AGENTS.md`, user-facing docs under
`website/docs/user-guide/features/`.

### Delegation (`delegate_task`)

Synchronous subagent spawn — the parent waits for the child's summary
before continuing its own loop. Isolated context + terminal session.

- **Single:** `delegate_task(goal, context, toolsets)`.
- **Batch:** `delegate_task(tasks=[{goal, ...}, ...])` runs children in
  parallel, capped by `delegation.max_concurrent_children` (default 3).
- **Roles:** `leaf` (default; cannot re-delegate) vs `orchestrator`
  (can spawn its own workers, bounded by `delegation.max_spawn_depth`).
- **Not durable.** If the parent is interrupted, the child is
  cancelled. For work that must outlive the turn, use `cronjob` or
  `terminal(background=True, notify_on_complete=True)`.

Config: `delegation.*` in `config.yaml`.

### Cron (scheduled jobs)

Durable scheduler — `cron/jobs.py` + `cron/scheduler.py`. Drive it via
the `cronjob` tool, the `hermes cron` CLI (`list`, `add`, `edit`,
`pause`, `resume`, `run`, `remove`), or the `/cron` slash command.

- **Schedules:** duration (`"30m"`, `"2h"`), "every" phrase
  (`"every monday 9am"`), 5-field cron (`"0 9 * * *"`), or ISO timestamp.
- **Per-job knobs:** `skills`, `model`/`provider` override, `script`
  (pre-run data collection; `no_agent=True` makes the script the whole
  job), `context_from` (chain job A's output into job B), `workdir`
  (run in a specific dir with its `AGENTS.md` / `CLAUDE.md` loaded),
  multi-platform delivery.
- **Invariants:** 3-minute hard interrupt per run, `.tick.lock` file
  prevents duplicate ticks across processes, cron sessions pass
  `skip_memory=True` by default, and cron deliveries are framed with a
  header/footer instead of being mirrored into the target gateway
  session (keeps role alternation intact).

User docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/cron

### Curator (skill lifecycle)

Background maintenance for agent-created skills. Tracks usage, marks
idle skills stale, archives stale ones, keeps a pre-run tar.gz backup
so nothing is lost.

- **CLI:** `hermes curator <verb>` — `status`, `run`, `pause`, `resume`,
  `pin`, `unpin`, `archive`, `restore`, `prune`, `backup`, `rollback`.
- **Slash:** `/curator <subcommand>` mirrors the CLI.
- **Scope:** only touches skills with `created_by: "agent"` provenance.
  Bundled + hub-installed skills are off-limits. **Never deletes** —
  max destructive action is archive. Pinned skills are exempt from
  every auto-transition and every LLM review pass.
- **Telemetry:** sidecar at `~/.hermes/skills/.usage.json` holds
  per-skill `use_count`, `view_count`, `patch_count`,
  `last_activity_at`, `state`, `pinned`.

Config: `curator.*` (`enabled`, `interval_hours`, `min_idle_hours`,
`stale_after_days`, `archive_after_days`, `backup.*`).
User docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/curator

### Kanban (multi-agent work queue)

Durable SQLite board for multi-profile / multi-worker collaboration.
Users drive it via `hermes kanban <verb>`; dispatcher-spawned workers
see a focused `kanban_*` toolset gated by `HERMES_KANBAN_TASK` so the
schema footprint is zero outside worker processes.

- **CLI verbs (common):** `init`, `create`, `list` (alias `ls`),
  `show`, `assign`, `link`, `unlink`, `comment`, `complete`, `block`,
  `unblock`, `archive`, `tail`. Less common: `watch`, `stats`, `runs`,
  `log`, `dispatch`, `daemon`, `gc`.
- **Worker toolset:** `kanban_show`, `kanban_complete`, `kanban_block`,
  `kanban_heartbeat`, `kanban_comment`, `kanban_create`, `kanban_link`.
- **Dispatcher** runs inside the gateway by default
  (`kanban.dispatch_in_gateway: true`) — reclaims stale claims,
  promotes ready tasks, atomically claims, spawns assigned profiles.
  Auto-blocks a task after ~5 consecutive spawn failures.
- **Isolation:** board is the hard boundary (workers get
  `HERMES_KANBAN_BOARD` pinned in env); tenant is a soft namespace
  within a board for workspace-path + memory-key isolation.

User docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban

---

## Troubleshooting

### Voice not working
1. Check `stt.enabled: true` in config.yaml
2. Verify provider: `pip install faster-whisper` or set API key
3. In gateway: `/restart`. In CLI: exit and relaunch.

### Tool not available
1. `hermes tools` — check if toolset is enabled for your platform
2. Some tools need env vars (check `.env`)
3. `/reset` after enabling tools

### Image generation via ChatGPT/Codex OAuth

When the user wants Hermes/Telegram image generation using ChatGPT/Codex rather than local ComfyUI or a separate OpenAI API key, prefer the bundled `openai-codex` image-gen backend if available. It routes GPT Image generation through the existing Codex/ChatGPT OAuth session and avoids consuming local GPU/ComfyUI VRAM.

Setup/check pattern:
```bash
# Codex/ChatGPT OAuth must already be available; otherwise sign in first.
hermes login --provider openai-codex

# Route Hermes' image_generate tool to the Codex-backed GPT Image backend.
hermes config set image_gen.provider openai-codex
hermes config set image_gen.model gpt-image-2-medium

# Alternatives for cost/quality tradeoff:
hermes config set image_gen.model gpt-image-2-low     # fast iteration
hermes config set image_gen.model gpt-image-2-high    # final keyframes/assets
```

Verify without printing secrets:
```bash
python - <<'PY'
from hermes_cli.config import load_config
from hermes_cli.plugins import _ensure_plugins_discovered
from agent.image_gen_registry import get_provider
cfg = load_config().get('image_gen', {})
_ensure_plugins_discovered(force=True)
p = get_provider('openai-codex')
print('image_gen.provider =', cfg.get('provider'))
print('image_gen.model =', cfg.get('model'))
print('openai-codex provider available =', bool(p and p.is_available()))
PY
```

If Telegram/gateway keeps old tool config, start a fresh session or use `/restart`/`/reset`. For content pipelines, use this as a cloud-side keyframe/thumbnail generator; add captions, numbers, UI labels, and audit-sensitive facts later in deterministic rendering rather than trusting baked image text.

When Hermes provider calls hang for many minutes (for example non-streaming GPT calls aborting after 900s), apply the bounded policy in `references/provider-call-timeout-policy.md`: cap ordinary non-streaming calls around 300s, use at most 2 retries with short backoff, checkpoint requests before calls, prefer streaming for long calls, log provider/model/attempt/duration, then split the task or use fallback/partial failure after repeated timeouts.

### Model/provider issues
1. `hermes doctor` — check config and dependencies
2. `hermes login` — re-authenticate OAuth providers
3. Check `.env` has the right API key
4. **Copilot 403**: `gh auth login` tokens do NOT work for Copilot API. You must use the Copilot-specific OAuth device code flow via `hermes model` → GitHub Copilot.

### Changes not taking effect
- **Tools/skills:** `/reset` starts a new session with updated toolset
- **Config changes:** In gateway: `/restart`. In CLI: exit and relaunch.
- **Code changes:** Restart the CLI or gateway process

### Image generation via ChatGPT/Codex OAuth

Hermes can route the `image_generate` tool through ChatGPT/Codex OAuth instead of requiring a separate `OPENAI_API_KEY`, when the bundled `openai-codex` image-gen backend is available and the user is already signed in with Codex/ChatGPT.

Setup:
```bash
hermes config set image_gen.provider openai-codex
hermes config set image_gen.model gpt-image-2-medium
```

Useful model tiers:
```bash
hermes config set image_gen.model gpt-image-2-low     # fast iteration
hermes config set image_gen.model gpt-image-2-medium  # balanced default
hermes config set image_gen.model gpt-image-2-high    # final keyframes/assets
```

Verification pattern:
```bash
python - <<'PY'
from hermes_cli.config import load_config
from hermes_cli.plugins import _ensure_plugins_discovered
from agent.image_gen_registry import get_provider
cfg = load_config().get('image_gen', {})
_ensure_plugins_discovered(force=True)
p = get_provider('openai-codex')
print('image_gen.provider =', cfg.get('provider'))
print('image_gen.model =', cfg.get('model'))
print('openai-codex provider available =', bool(p and p.is_available()))
PY
```

If it does not appear in a long-lived gateway session, restart or reset the session so config/tool availability is reloaded. The backend saves generated images under `$HERMES_HOME/cache/images/` and is useful for cloud-side keyframes without local GPU/VRAM contention.

### Tool / iteration budget
When the user asks to increase the "tool budget", "turn budget", or max tool-calling iterations, set the config key, not a transient shell variable:
```bash
hermes config set agent.max_turns 250
```
Then verify by reading `~/.hermes/config.yaml` or using a safe config inspection path. Avoid piping `hermes config` into `python` or another interpreter; security policy may flag `command | python` as high-risk even when the intent is only parsing. For gateway runs, `agent.max_turns` is the authoritative setting and is bridged internally to `HERMES_MAX_ITERATIONS`; config changes apply to fresh agent runs, while long-lived gateway/config changes may still need `/restart` if behavior appears stale.

### Skills not showing
1. `hermes skills list` — verify installed
2. `hermes skills config` — check platform enablement
3. Load explicitly: `/skill name` or `hermes -s name`

### Gateway issues
Check logs first:
```bash
grep -i "failed to send\|error" ~/.hermes/logs/gateway.log | tail -20
```

Common gateway problems:
- **Gateway dies on SSH logout**: Enable linger: `sudo loginctl enable-linger $USER`
- **Gateway dies on WSL2 close**: WSL2 requires `systemd=true` in `/etc/wsl.conf` for systemd services to work. Without it, gateway falls back to `nohup` (dies when session closes).
- **Gateway crash loop**: Reset the failed state: `systemctl --user reset-failed hermes-gateway`

### Platform-specific issues
- **Discord bot silent**: Must enable **Message Content Intent** in Bot → Privileged Gateway Intents.
- **Slack bot only works in DMs**: Must subscribe to `message.channels` event. Without it, the bot ignores public channels.
- **Windows HTTP 400 "No models provided"**: Config file encoding issue (BOM). Ensure `config.yaml` is saved as UTF-8 without BOM.

### Auxiliary models not working
If `auxiliary` tasks (vision, compression, session_search) fail silently, the `auto` provider can't find a backend. Either set `OPENROUTER_API_KEY` or `GOOGLE_API_KEY`, or explicitly configure each auxiliary task's provider:
```bash
hermes config set auxiliary.vision.provider <your_provider>
hermes config set auxiliary.vision.model <model_name>
```

---

## Where to Find Things

| Looking for... | Location |
|----------------|----------|
| Config options | `hermes config edit` or [Configuration docs](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) |
| Available tools | `hermes tools list` or [Tools reference](https://hermes-agent.nousresearch.com/docs/reference/tools-reference) |
| Slash commands | `/help` in session or [Slash commands reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands) |
| Skills catalog | `hermes skills browse` or [Skills catalog](https://hermes-agent.nousresearch.com/docs/reference/skills-catalog) |
| Provider setup | `hermes model` or [Providers guide](https://hermes-agent.nousresearch.com/docs/integrations/providers) |
| Platform setup | `hermes gateway setup` or [Messaging docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/) |
| MCP servers | `hermes mcp list` or [MCP guide](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) |
| Profiles | `hermes profile list` or [Profiles docs](https://hermes-agent.nousresearch.com/docs/user-guide/profiles) |
| Cron jobs | `hermes cron list` or [Cron docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) |
| Memory | `hermes memory status` or [Memory docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) |
| Env variables | `hermes config env-path` or [Env vars reference](https://hermes-agent.nousresearch.com/docs/reference/environment-variables) |
| CLI commands | `hermes --help` or [CLI reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) |
| Gateway logs | `~/.hermes/logs/gateway.log` |
| Session files | `~/.hermes/sessions/` or `hermes sessions browse` |
| Source code | `~/.hermes/hermes-agent/` |

---

## Contributor Quick Reference

For occasional contributors and PR authors. Full developer docs: https://hermes-agent.nousresearch.com/docs/developer-guide/

### Project Layout

```
hermes-agent/
├── run_agent.py          # AIAgent — core conversation loop
├── model_tools.py        # Tool discovery and dispatch
├── toolsets.py           # Toolset definitions
├── cli.py                # Interactive CLI (HermesCLI)
├── hermes_state.py       # SQLite session store
├── agent/                # Prompt builder, context compression, memory, model routing, credential pooling, skill dispatch
├── hermes_cli/           # CLI subcommands, config, setup, commands
│   ├── commands.py       # Slash command registry (CommandDef)
│   ├── config.py         # DEFAULT_CONFIG, env var definitions
│   └── main.py           # CLI entry point and argparse
├── tools/                # One file per tool
│   └── registry.py       # Central tool registry
├── gateway/              # Messaging gateway
│   └── platforms/        # Platform adapters (telegram, discord, etc.)
├── cron/                 # Job scheduler
├── tests/                # ~3000 pytest tests
└── website/              # Docusaurus docs site
```

Config: `~/.hermes/config.yaml` (settings), `~/.hermes/.env` (API keys).

### Adding a Tool (3 files)

**1. Create `tools/your_tool.py`:**
```python
import json, os
from tools.registry import registry

def check_requirements() -> bool:
    return bool(os.getenv("EXAMPLE_API_KEY"))

def example_tool(param: str, task_id: str = None) -> str:
    return json.dumps({"success": True, "data": "..."})

registry.register(
    name="example_tool",
    toolset="example",
    schema={"name": "example_tool", "description": "...", "parameters": {...}},
    handler=lambda args, **kw: example_tool(
        param=args.get("param", ""), task_id=kw.get("task_id")),
    check_fn=check_requirements,
    requires_env=["EXAMPLE_API_KEY"],
)
```

**2. Add to `toolsets.py`** → `_HERMES_CORE_TOOLS` list.

Auto-discovery: any `tools/*.py` file with a top-level `registry.register()` call is imported automatically — no manual list needed.

All handlers must return JSON strings. Use `get_hermes_home()` for paths, never hardcode `~/.hermes`.

### Adding a Slash Command

1. Add `CommandDef` to `COMMAND_REGISTRY` in `hermes_cli/commands.py`
2. Add handler in `cli.py` → `process_command()`
3. (Optional) Add gateway handler in `gateway/run.py`

All consumers (help text, autocomplete, Telegram menu, Slack mapping) derive from the central registry automatically.

### Agent Loop (High Level)

```
run_conversation():
  1. Build system prompt
  2. Loop while iterations < max:
     a. Call LLM (OpenAI-format messages + tool schemas)
     b. If tool_calls → dispatch each via handle_function_call() → append results → continue
     c. If text response → return
  3. Context compression triggers automatically near token limit
```

### Testing

```bash
python -m pytest tests/ -o 'addopts=' -q   # Full suite
python -m pytest tests/tools/ -q            # Specific area
```

- Tests auto-redirect `HERMES_HOME` to temp dirs — never touch real `~/.hermes/`
- Run full suite before pushing any change
- Use `-o 'addopts='` to clear any baked-in pytest flags

### Commit Conventions

```
type: concise subject line

Optional body.
```

Types: `fix:`, `feat:`, `refactor:`, `docs:`, `chore:`

### Key Rules

- **Never break prompt caching** — don't change context, tools, or system prompt mid-conversation
- **Message role alternation** — never two assistant or two user messages in a row
- Use `get_hermes_home()` from `hermes_constants` for all paths (profile-safe)
- Config values go in `config.yaml`, secrets go in `.env`
- New tools need a `check_fn` so they only appear when requirements are met