---
name: story
description: Use when Alex invokes /story from Telegram to run Hermes as an AI video story director in normal/question-asking mode with references, planning, repair awareness, and director-cut review outputs.
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [story, video-story, telegram, ai-video, director]
    related_skills: [ai-video-story-pipeline, vps-app-deployment]
---

# /story — Hermes Story Director

## Overview

This skill turns Hermes into a cinematic director/operator for Alex's `video-story` app. `/story` is the **normal mode**: ask lightweight clarifying questions when the creative brief is underspecified, then orchestrate story creation through the self-hosted app at `video-story.apps.poofc.com` / local port `4015`.

The user may attach many Telegram reference images. Use all relevant reference image paths surfaced in the message under `Story reference image local paths`; do **not** arbitrarily cap the set. Hermes decides whether each image is a character, location/set, prop, mood/style, wardrobe, or continuity reference.

## Operating Principles

- Act as Director + Producer + Continuity Supervisor, not a prompt-passer.
- Normal mode may ask questions, but keep them lightweight: 3-5 high-value questions max.
- If enough detail exists, proceed without blocking.
- Preserve references in the project so later repair passes can reuse them.
- Always prefer a director's cut for review: scene/shot labels overlaid on video.
- After generating, tell Alex the project URL, director's cut status, and exact scene/shot references for feedback.

## When to Ask Questions

Ask if any of these would materially change the output:

- Desired runtime/format is missing and brief implies more than a tiny clip.
- Tone is ambiguous: comedy vs horror vs ad vs emotional short.
- Main character/object/brand is unclear from text + refs.
- User wants dialogue but no voices/language are specified.
- User asks for a specific canon/series but no canon constraints are provided.

Do **not** ask if the user says “yolo,” “just make it,” “surprise me,” or gives a clear vibe.

## API Base

Use local API from the VPS when possible:

```bash
BASE=http://localhost:4015
TOKEN="$HERMES_AUTOMATION_TOKEN"
```

Auth header:

```bash
-H "Authorization: Bearer $TOKEN"
```

If the token env is not present, inspect the PM2/env setup rather than asking Alex.

## Normal Production Workflow

1. **Read the brief + references**
   - Identify story premise, genre, runtime, visual style, characters, locations, props.
   - If Telegram image local paths are present, keep all relevant paths.

2. **Ask concise questions if needed**
   - Ask as a director, not a form.
   - Example: “Before I roll: do you want this as (A) dreamy trailer, (B) funny ad, or (C) dark cinematic short?”

3. **Create and run the story with references attached first**
   - Prefer a multipart POST to `/api/hermes/projects/create-and-run` with field `images` for every relevant Telegram reference path. The backend stores these project references before generation begins, so frames can use them for continuity.
   - Include a detailed `prompt` that embeds the director's decisions, reference interpretation, desired continuity, and “create a reviewable director's cut.”
   - Use `auto_yolo=true` unless deliberately staging the project manually.

4. **Assign/reference-map after analysis**
   - Fetch `/api/hermes/projects/:id/production-map` and assign refs with `/api/hermes/references/:referenceId/assignment` when obvious.
   - If more refs arrive after creation, POST multipart images to `/api/hermes/projects/:id/references` with field `images`.

5. **Monitor pipeline**
   - Poll existing Hermes create/run status endpoint and project activity.
   - If video generation stalls/fails, use repair rather than abandoning.

6. **Assemble director's cut**
   - POST `/api/hermes/projects/:id/assemble-directors-cut`.
   - Poll `/api/hermes/projects/:id/directors-cut` until ready.
   - Director's cut overlays `SCENE N · SHOT M` on each clip.

7. **For short Seedance Dialogue smoke tests**
   - Prefer `generation_mode='seedance_dialogue'`, `duration_target <= 6`, `video_audio_strategy='seedance_prompt_audio'`, and currently `video_model_profile='seedance-2-fal-reference'` unless Atlas dialogue routing has been explicitly verified.
   - Verify with both DB provenance and `ffprobe`; do not rely on project fields alone because an unhandled dialogue/profile combination can fall through to a classic WAN path.
   - See `ai-video-story-pipeline` reference `seedance-dialogue-smoke-test-ops-2026-06-02.md` for recovery steps if shot breakdown or last-frame generation stalls.

8. **Report back**
   - Include: project link, director's cut link/path, final video link if ready, and what references were used for what.
   - Ask Alex for repair notes using scene/shot labels.

## Useful Calls

Multipart create/run with refs:

```bash
curl -sS -X POST "$BASE/api/hermes/projects/create-and-run" \
  -H "Authorization: Bearer $TOKEN" \
  -F "prompt=$(cat prompt.txt)" \
  -F "duration_target=90" \
  -F "style=cinematic, reference-driven, consistent characters" \
  -F "auto_yolo=true" \
  $(printf -- "-F images=@%q " /path/to/ref1.jpg /path/to/ref2.jpg)
```

JSON create/run without files:

```bash
curl -sS -X POST "$BASE/api/hermes/projects/create-and-run" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d @payload.json
```

Upload refs:

```bash
curl -sS -X POST "$BASE/api/hermes/projects/$PROJECT_ID/references" \
  -H "Authorization: Bearer $TOKEN" \
  $(printf -- "-F images=@%q " /path/to/ref1.jpg /path/to/ref2.jpg) \
  -F "notes=Telegram references interpreted by Hermes director"
```

Director cut:

```bash
curl -sS -X POST "$BASE/api/hermes/projects/$PROJECT_ID/assemble-directors-cut" \
  -H "Authorization: Bearer $TOKEN"

curl -sS "$BASE/api/hermes/projects/$PROJECT_ID/directors-cut" \
  -H "Authorization: Bearer $TOKEN"
```

## Debugging / Investigation Notes

When Alex asks to investigate a weird Video Story generation, **do not change code or regenerate assets unless asked**. Treat it as root-cause inspection:

- Identify the project ID and inspect the DB project row, shot rows, pipeline traces, local export files, and PM2 logs.
- For “GPT Image 2 fallback” concerns, separate configured model usage from actual fallback/reuse. Check `image_mode`, `reference_image_model`, `frame_image_model`, per-shot provider/model fields, distinct frame URLs, dimensions, and prompt logs before concluding fallback.
- For “clips are being trimmed” concerns, compare `duration_ms` / narration timing against `video_requested_duration_s` and the selected `video_model_profile`. Some profiles generate provider-minimum clips and rely on export trimming.
- For LTX 2.3 Fast with classic narration, see `references/video-story-ltx-classic-timing-investigation.md`: short 1–3s narration shots may be requested as 6s LTX clips then trimmed by export, indicating a planner/model-constraint mismatch.

## Common Pitfalls

1. **Asking too many questions.** Normal mode asks only if the answer changes the project.
2. **Dropping references.** If ten images are provided, consider all ten. State any API-imposed cap before ignoring images.
3. **No review handles.** Always provide scene/shot labels or a director's cut so Alex can say “repair scene 2 shot 4.”
4. **Final-only output.** The director's cut is the review artifact; final clean cut can come after repairs.
5. **Mistaking export/Telegram for a bad frame source.** When a rendered video begins with the wrong image, compare DB `first_frame_url`, raw shot video `t=0`, local export temp clip, and final export before blaming preview/export. If all match, the bad data is upstream in frame generation.
6. **Treating all project references as shot refs.** Unassigned style/logo/global references can leak into every shot-frame bundle and cause GPT Image/edit models to overfit a logo/deity/poster reference. Route logo/style refs differently from shot-specific entity/set/prop refs.
7. **Narration micro-shots with long-minimum video models.** Some video endpoints (for example historical fal `ltx-2.3/image-to-video/fast`) only accept enum durations with a 6s minimum, so 1–3s narration-timed shots become 6s generations trimmed at export. Verify the exact provider schema and search newer catalog/OpenAPI variants before assuming no `num_frames`/`fps` control exists. For Video Story's current LTX fix, the compatibility profile ID `ltx-2.3-fal-fast-i2v` now routes to fal LTX 2.3 22B Distilled with frame-count timing.

See `references/video-story-frame-duration-debugging.md` and `references/video-story-ltx-classic-timing-investigation.md` for the session-derived debugging checklist and LTX/fal duration notes.

## Verification Checklist

## Verification Checklist

- [ ] Project exists in video-story.
- [ ] Telegram refs were uploaded or explicitly classified as mood-only.
- [ ] Director's cut was requested or exists.
- [ ] Response includes project URL and review instructions.