# UGC Swarm content pipeline: guide for agents

You can make AI personas (consistent fictional characters) and remix short vertical videos with them. You work through
`remixctl`, a one-file Python 3 command-line tool with no dependencies. Everything you start shows up in the team's web
app (http://hermes-content.tail7d831b.ts.net:8765), where people watch the work and approve it.

## Set up

```
curl -fsSL https://hermes-content.tail7d831b.ts.net/cli/remixctl.py -o remixctl && chmod +x remixctl
./remixctl login --server https://hermes-content.tail7d831b.ts.net --name "<who you are, e.g. Lena's Claude Code>"
```

`login` prints a link and a code, then waits. Give the link to your person: a teammate approves you in the web app,
and then you're signed in. `./remixctl whoami` shows what you may do:

- **Always:** test runs (free; every step runs with placeholder images), uploads, reading results.
- **`runs:real`:** paid real runs, which call Nano Banana, Claude, ElevenLabs and MiniMax.
- **`jobs:approve`:** approving steps yourself, including confirming a paid shoot.

Put `--json` before the command for machine-readable output (`./remixctl --json jobs wait JOB`). Never print or share
your key: remixctl keeps it in `~/.config/remixctl/config.json` (mode 600).

## How a job works

A job runs step by step and stops at approval steps ("gates"). `./remixctl jobs wait JOB` waits until the job needs a
decision or is finished. It then says what is waiting, what to look at and which decisions it takes, plus the job's
web link. Long text to review, such as the script, is in `pending_approval.options.previews` in the `--json` output.
Images and videos are easiest to review in the web app.

If you don't have `jobs:approve`, give your person the web link: they approve in the web app, and you keep waiting.
Approve with `./remixctl jobs approve JOB -d DECISION [-c "notes"]`. A `redo` always needs notes saying what to change.

## Make a persona

**Your own character**, from a description and photos of one person (20 or more photos is best):

```
./remixctl persona create --name "Nova Lind" --prompt "late-20s baker in Copenhagen, warm, direct" \
    --photo a.jpg --photo b.jpg --md persona.md --rights [--real]
```

**Remix a persona** from a creator's profile. Persona Scout studies the profile and drafts 10 original characters for
the same niche. They are never lookalikes of the creator.

```
./remixctl persona remix https://www.instagram.com/handle/ --rights [--real]
./remixctl jobs wait JOB                                  # waits at phase1_lock: 10 options
./remixctl persona pick JOB --option C --name "Remy Cole" [--changes "shorter hair"]
./remixctl persona pick JOB --none                        # none fit: 10 new ones
```

Both kinds then stop at:
- `sheet_check`: approve the character from every angle (`-d pass`), or `-d redo -c "what to change"`.
- `voice_pick`: list the account's ElevenLabs voices with `./remixctl voices`, then
  `./remixctl persona voice JOB --voice-id ID`.

The finished persona appears in `./remixctl personas list` (its slug is what remixes use).

## Remix a video

The persona performs a new script in the source video's style: same structure, pacing and look.

```
./remixctl personas list
./remixctl remix --persona SLUG --url https://www.instagram.com/reel/XYZ/ \
    --prompt "this week's biggest AI launches, for people who build with AI" --rights [--real]
```

- **The source** is one of: a video link with `--url`, your own file with `--video clip.mp4`, or a saved template with
  `--template ID` (see `./remixctl templates list`).
- **From a profile:** `./remixctl sources list https://www.instagram.com/handle/` lists its latest videos. Then run
  `./remixctl sources pick LIST N --persona SLUG --prompt "..." --rights`.
- **The words:** `--prompt` is what the new video is about. The script is researched on the web, and every fact cites its
  source. `--script-file words.txt` uses your exact words instead.

The steps it stops at, in order:

| Gate | What it is | Decisions |
|---|---|---|
| `script_approval` | Every word the persona says, with sources | `pass`, `redo -c` |
| `frames_approval` | The persona in each keyframe of the source | `pass`, `redo -c` |
| `shoot_confirm` | **Paid** filming; `options.packet.est_usd` is the cost | `confirm`, `hold` |
| `clip_approval` | The filmed clips | `pass`, `redo -c` |
| `final_approval` | The edited video | `pass`, `redo -c` |

When it's finished, download the video with `./remixctl jobs download JOB --to out/`. Save a remix you like as a template
with `./remixctl jobs template JOB`, to make it again with another persona.

## Rules

- Only remix videos your team has the rights to. `--rights` says you do.
- Personas are fictional adults (21+), never copies of a real person who didn't agree.
- Real runs cost money. A test run is free and walks every step, so try a flow as a test run first.
- If a step fails, `./remixctl jobs retry JOB` carries on from where it stopped. Finished steps and anything already
  paid for are kept.

## Other commands

`./remixctl jobs list`, `jobs status JOB`, `jobs audit JOB`, `jobs cancel JOB`, `approvals list`, `notifications`.
Everything the tool does is plain HTTPS: see https://hermes-content.tail7d831b.ts.net/docs for the API.