mugsy-explains

# Mugsy Explains Agent

You operate the packaged runner. Do not rebuild the renderer or invent another character.

## First question

Ask: `What should this video explain or compare?`

Ask only one question at a time. If the user asks for the included Wiggly example, use `content.json` without more creative questions.

## Run

1. Read `README.md`, the JSON contracts, and `prompts/story.md`.
2. Run `python3 runner.py smoke` before asking for a provider key.
3. For a new topic, edit only `content.json` and replace its six proof images. Never edit `runtime/build_proof.py` for content.
4. Before validation, read the fifteen sentences aloud and inspect the six proof images at phone size. Fix A/B pairs that do not answer the same viewer question, unclear labels, awkward spoken grammar, repeated lessons, whole-page screenshots, and proof that cannot be understood in one second.
5. Run `python3 runner.py validate` before voice generation.
6. Report the Fish model and estimate: `$0 on s2.1-pro-free`.
7. Ask once before generating new narration.
8. Run `python3 runner.py render` with `FISH_STUDIO_APIKEY` in the environment.
9. Run `python3 runner.py inspect` and show the contact sheet.
10. Ask the user to confirm voice identity, pronunciation, and creative fit.
11. Run `python3 runner.py finalize --human-review pass` only after approval.
12. Return the final playable MP4.
13. (Optional) Run `node runtime/publish.mjs --dry-run inputs/distribution.json goldens/wiggly-format-explainer.mp4` to validate social distribution.

Stop loudly on missing tools, keys, invalid content, failed inspection, or an unapproved voice. Do not switch providers. Do not make image- or video-generation calls.

## Multi-Platform Social Distribution (Optional)

When a Mugsy Explains video is rendered and approved, the agent can distribute it across YouTube Shorts, Instagram Reels, TikTok, and X via the packaged `runtime/publish.mjs` CLI or connected Buffer MCP tools:

1. **Author platform-tailored copy in `inputs/distribution.json`:**
   - **YouTube Shorts:** Fast, high-intrigue explainer title (≤100 chars), categoryId (`27` for Education or `28` for Tech), strictly vertical (9:16, ≤60s).
   - **Twitter/X:** Engaging educational hook with core takeaway (≤280 chars total).
   - **Instagram Reels:** Snappy caption with relevant hashtags (vertical 9:16).
   - **TikTok:** Punchy curiosity hook with trending tags (≤2200 chars).
2. **Dry-run validation:**
   ```sh
   node runtime/publish.mjs --dry-run inputs/distribution.json goldens/wiggly-format-explainer.mp4
   ```
3. **Live dispatch requires explicit human sign-off:**
   - Confirm target channels and copy with the user (`approvalRequired: true`).
   - Execute with connected Buffer MCP tools or `node runtime/publish.mjs inputs/distribution.json /path/to/final.mp4`.
   - Generates a verified distribution receipt (`<video>.distribution.json`) with zero secret leakage.

{
  "required": [
    "three clear A-versus-B lessons",
    "one proof image for each side",
    "five short narration sentences per lesson"
  ],
  "defaults": {
    "aspectRatio": "9:16",
    "durationSeconds": "25-35",
    "host": "bundled recurring pose pack",
    "voice": "authorized Fish zero-shot reference voice",
    "cuts": "hard cuts only"
  }
}

{
  "steps": [
    "choose-topic",
    "write-three-comparisons",
    "collect-six-proof-images",
    "smoke",
    "validate",
    "approve-voice",
    "render",
    "inspect",
    "human-review",
    "distribute",
    "finalize"
  ],
  "stages": [
    {
      "id": "choose-topic",
      "output": "Select one A-versus-B topic with three clear comparison lessons"
    },
    {
      "id": "write-three-comparisons",
      "output": "Fifteen snappy sentences with tight spoken phrasing"
    },
    {
      "id": "collect-six-proof-images",
      "output": "Six curated proof screenshots or diagrams"
    },
    {
      "id": "smoke",
      "output": "Deterministic local smoke test"
    },
    {
      "id": "validate",
      "output": "Verify timing, character poses, and handwritten captions"
    },
    {
      "id": "approve-voice",
      "approvalRequired": true,
      "output": "Confirm narrator voice model and audio direction"
    },
    {
      "id": "render",
      "output": "Local deterministic assembly of 9:16 vertical MP4"
    },
    {
      "id": "inspect",
      "output": "Inspect video stream, audio intelligibility, and contact sheet"
    },
    {
      "id": "human-review",
      "approvalRequired": true,
      "output": "Explicit human sign-off on the rendered vertical video"
    },
    {
      "id": "distribute",
      "approvalRequired": true,
      "output": "Simultaneous multi-platform publishing receipt (YouTube Shorts, Instagram Reels, TikTok, X) with zero secret leakage"
    },
    {
      "id": "finalize",
      "output": "Final packaging and receipt generation"
    }
  ]
}

# Story Prompt

Write three short A-versus-B explanations about the user's topic.

Choose three different buyer-relevant decisions or reveals. In every comparison, A and B must answer the same viewer question: build versus buy, old versus new, myth versus reality, problem versus solution, or one output versus a reusable system. The labels must name that contrast clearly; do not pair two concepts merely because both appeared in the research.

For each comparison, return exactly five sentences:

1. `This is [A].`
2. `This is [B].`
3. `What's the difference?`
4. One plain sentence explaining A.
5. One plain sentence explaining B and landing the useful takeaway.

Read all fifteen sentences aloud before approval. Every sentence must sound like natural spoken English. Use `a`, `an`, or `the` before common nouns when needed; do not write fragments such as `This is separate integration.`

Every sentence must have a visible proof image or a reusable character pose. Each proof image must communicate one point at phone size in under one second. Use a tight crop of the relevant product, diagram, number, or sentence; never use a whole webpage screenshot. Keep each rolling caption to one short phrase. Use the same bundled pose pack repeatedly; do not design a new character, animate lips, or turn the character into the narrator.

Before returning the script, reject it if:

- the two sides do not answer the same viewer question;
- two comparisons make substantially the same point;
- a sentence sounds incomplete when spoken;
- a proof image would need zooming or reading a paragraph to understand;
- the useful takeaway is not clear to a first-time buyer.

The visual grammar is fixed: white 9:16 canvas, one or two proof images at the top, handwritten label and caption, recurring non-speaking demonstrator below, hard cuts, continuous omniscient narration.

{
  "automatic": {
    "width": 1080,
    "height": 1920,
    "fps": 30,
    "durationSeconds": {"min": 25, "max": 35},
    "audioStreams": 1,
    "maxSilenceGapSeconds": 0.25
  },
  "human": [
    "Each A-versus-B pair answers one clear viewer question, and its labels name the contrast.",
    "All fifteen sentences sound complete and natural when read aloud.",
    "Each spoken line has a matching visual proof.",
    "Each proof image is a tight crop that communicates one point at phone size in under one second.",
    "The same bundled character pose pack is reused throughout.",
    "The character never lip-syncs or acts as the narrator.",
    "Proof images stay at the top on a plain white canvas.",
    "Handwritten captions are short and readable.",
    "The voice resembles the authorized source and pronounces every word correctly."
  ]
}

{
  "localTools": ["python3", "ffmpeg", "ffprobe"],
  "pythonPackages": ["Pillow", "numpy", "ormsgpack"],
  "providers": [
    {
      "name": "Fish Audio",
      "environmentVariable": "FISH_STUDIO_APIKEY",
      "model": "s2.1-pro-free",
      "estimatedCost": "$0 on the free developer model",
      "approval": "Ask before generating a new narration"
    },
    {
      "name": "Social Publisher (Buffer MCP or API)",
      "purpose": "Simultaneous multi-platform publishing to YouTube Shorts, Instagram Reels, TikTok, and X.",
      "optional": true,
      "environmentVariables": ["BUFFER_API_KEY"],
      "pricingSource": "https://buffer.com/pricing"
    }
  ],
  "paidImageOrVideoProviders": []
}