> ## Documentation Index
> Fetch the complete documentation index at: https://ralphy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Templates

> Vibe-reference and vibe-style templates, organized into five segment-persona categories.

A template is a pre-built scaffold for a kind of video. Ralphy ships 54 templates across five segment-persona categories. Two kinds exist: **vibe-reference** (full-stack production templates with a composition.md, a reference example, and a manifest) and **vibe-style** (prompt cookbooks with hooks, camera vocab, and worked example prompts). The agent's first move on any new brief is `ralphy template suggest "<the user's brief>"` — if the top hit scores ≥ 0.5, use the template instead of improvising (AGENTS.md hard invariant #10, surfaced in [`docs/playbooks/meta.md`](https://github.com/alecs5am/ralphy/blob/main/docs/playbooks/meta.md) rule 3).

## The two kinds

**Vibe-reference (5 in repo).** A complete production template — `composition.md` describing scene-by-scene structure, `model-stack.md` naming the image / video / VO / music picks, `reference-example.md` linking to a rendered mp4 that exemplifies the format, `fragments.md` of reusable prompt fragments, and a `template.json` manifest. The five today:

* `before-after-product` (DTC) — 5s pain → 1s reveal → 9s demo
* `talking-head-rant` (creator) — deadpan 15-22s monolog
* `podcast-clip` (creator) — long-form podcast → 15-60s viral cut
* `ai-vegetables` (entertainment) — surrealist POV of an anthropomorphic vegetable
* `ai-drama` (entertainment) — Pixar-3D fruit / object / animal mini-soap-opera

**Vibe-style (49 in repo).** A prompt cookbook — `hooks.md` (validated opener patterns), `prompt-cookbook.md` (camera vocabulary, lighting, color grades, worked example prompts), and a `template.json`. No baked composition. The art-director playbook reads the cookbook before drafting prompts. Examples: `pov-first-person`, `grwm`, `yap-talking-head`, `italian-brainrot`, `cinematic`, `analog-horror-psa`.

The split is intentional: when a format has a *load-bearing structural pattern* (5s + 1s + 9s, or 7 × 8s clips with one music drop), it earns a vibe-reference template. When the format is a *register* (cinematic, anime-action, ASMR), it stays vibe-style.

## The five categories

Templates are organized by **segment × persona** — who is watching the content and why. Pick the category that matches the audience archetype.

| Category               | Count | Audience                                                | Goal                                    | Tone                                          |
| ---------------------- | ----- | ------------------------------------------------------- | --------------------------------------- | --------------------------------------------- |
| `b2b-saas/`            | 7     | Decision-makers, ops, marketers, founders               | Educate, build authority, drive demo    | Confident, didactic, ROI-aware                |
| `dtc-commerce/`        | 12    | Online shoppers (apparel, beauty, nutra, gadgets, food) | Conversion                              | Aspirational, peer-evidence, demo-led         |
| `creator-lifestyle/`   | 10    | Scroll-feed lifestyle / personality-driven              | Parasocial connection, native placement | Relatable, first-person, unpolished-by-design |
| `entertainment-viral/` | 15    | Passive scroll-feed / meme / brainrot                   | Pure attention, share, dwell            | Punchy, surreal, AI-native                    |
| `cinematic-narrative/` | 11    | Aesthetics-first / film-quality                         | Brand prestige, emotional resonance     | Directorial, deliberate                       |

Browse the full roster on the public [Library](https://www.alecs5am.com/library), or run `ralphy template list -p`.

## Where templates live

Two tiers, both read by the same loader.

```
public content library            # Supabase template blocks (hosted)
                                   # served by /library + read via cli/lib/library/client.ts

.ralphy/workspaces/<ws>/templates/              # user-local, gitignored
├── my-internal-template/
└── ...
```

The **public content library** holds the shipped catalog (the same library the `/library` landing serves). The user-local `.ralphy/workspaces/<ws>/templates/` stays flat. The repo-public `templates/<category>/<slug>/` folder was retired in #084 — templates are no longer committed to git here. **The loader resolves by slug across both tiers** — `ralphy template use before-after-product --project <id>` works whether the slug is a public-library template or lives at `.ralphy/workspaces/<ws>/templates/before-after-product/`.

**Workspace overrides the public tier on id collision.** If you `ralphy template extract` a project into `.ralphy/workspaces/<ws>/templates/<slug>/` and edit it, the local version wins. The public tier degrades gracefully when the library is unreachable — the CLI lists workspace templates only and prints a warning.

## The slug system

A slug is a kebab-case identifier — `before-after-product`, `pov-first-person`, `italian-brainrot`. Slugs are unique across the entire template set (repo + workspace).

```bash theme={"dark"}
ralphy template list                          # every slug, with category and kind
ralphy template list --category dtc-commerce  # filter by category
ralphy template list --kind vibe-reference    # filter by kind
ralphy template show <slug>                   # the raw TEMPLATE.md (pipe-friendly)
ralphy template suggest "<utterance>"          # rank by user-brief
ralphy template use <slug> --project <id>      # scaffold a project from the template
ralphy template register <slug>                # add a new template to the registry
```

`ralphy template suggest` is the most important verb of the set. It takes a user utterance ("I want a TikTok about my coffee shop's pastry") and ranks templates by a composite of slug-keyword-match, tag-overlap, and category-fit. A score ≥ 0.5 means "use this template." A score \< 0.3 means "no template fits — fall through to a generic generation flow."

The suggest verb is *the* gate against improvisation. 54 templates ship; the chance that a "new" brief is actually a known format is high.

## Example slug roster

Here is a representative slice — browse the full roster on the public [Library](https://www.alecs5am.com/library) or run `ralphy template list -p`.

### `b2b-saas/`

* `yap-talking-head` — Hormozi / Codie raw-energy single-idea education
* `tutorial-how-to` — Hoyos-method 3-step search-first tutorial
* `listicle` — "Top N X" with big counter and #1 cliffhanger
* `faceless-voiceover` — AI / live VO over b-roll
* `interview-dialog` — two-person dialog with two voice IDs

### `dtc-commerce/`

* `before-after-product` (vibe-reference) — most reliably converting UGC pattern
* `doctor-authority` — white-coat authority + mechanism explainer
* `try-on` — virtual try-on with mirror-flash multi-variant
* `multi-scene-product-launch` — 27-shot identity-locked branded-hardware launch (derived from `nothing-hp1-001`)
* `ugc-selfie-product-review` — handheld 9:16 UGC selfie (derived from `glitter-cream-001`)

### `creator-lifestyle/`

* `pov-first-person` — "POV: you just…" — highest share-rate format
* `grwm` — Get Ready With Me, dual-layer storytime + visual
* `storytime` — selfie talking-head with rising tension + pattern-interrupts
* `noski-deadpan-2hander` — `@americanbaron` deadpan register (derived from `noski-people-001`)
* `podcast-clip` (vibe-reference) — long-form → 15-60s viral cuts

### `entertainment-viral/`

* `italian-brainrot` — single-character AI-meme with Italian gibberish VO (uses the 33-character canonical pool)
* `brainrot-ai-meme` — split-screen AI VO + Subway Surfers / Minecraft Parkour loop
* `analog-horror-psa` — 30s EBS-style emergency-broadcast PSA (derived from `analog-horror-fridge-001`)
* `broadcast-caught-on-tv-square` — 1:1 square caught-on-live-broadcast realism (derived from `kbo-broadcast-001`)
* `found-footage-mockumentary` — first-person handheld occult mockumentary (derived from `occult-mockumentary-001`)

### `cinematic-narrative/`

* `cinematic` — blockbuster film-look, 12 hooks, 16-move camera vocab
* `tokyo-y2k-cinematic` — long-form 75s locked-off-tripod neon-Asian-metropolis (derived from `tokyo-y2k-001`)
* `pixel-art-product-reveal` — photoreal hero device as only chroma in duotone world (derived from `playdate-pixel-001`)
* `comic-spiderverse-action` — painterly action duel in Spider-Verse / Arcane register
* `japanese-hypermotion-product-ad` — 15s 8-hard-cut hyperpop product ad

## Templates derived from shipped projects

Eleven templates in the catalog were extracted from shipped projects — the agent finished a video, the postmortem identified a reusable pattern, and the team promoted the structure into a template. These ship under a unified schema (structured `slots`, `sourceProject` pointer, `doNotCopyLiterally` rationale) so the next user gets the *structure* without inheriting the *specific brief*. The roster:

| Template                          | Source project             |
| --------------------------------- | -------------------------- |
| `broadcast-caught-on-tv-square`   | `kbo-broadcast-001`        |
| `analog-horror-psa`               | `analog-horror-fridge-001` |
| `noski-deadpan-2hander`           | `noski-people-001`         |
| `tokyo-y2k-cinematic`             | `tokyo-y2k-001`            |
| `pixel-art-product-reveal`        | `playdate-pixel-001`       |
| `japanese-hypermotion-product-ad` | `flipper-hypermotion-001`  |
| `comic-spiderverse-action`        | `skater-spiderverse-001`   |
| `found-footage-mockumentary`      | `occult-mockumentary-001`  |
| `anthropomorphic-object-drama`    | `fruit-drama-001`          |
| `ugc-selfie-product-review`       | `glitter-cream-001`        |
| `multi-scene-product-launch`      | `nothing-hp1-001`          |

The `sourceProject` pointer means the agent can re-read the original project's postmortem (`.ralphy/workspaces/<ws>/projects/<source>/postmortem/02-lessons.md`) before scaffolding a new project from the template. Per [`meta.md`](https://github.com/alecs5am/ralphy/blob/main/docs/playbooks/meta.md) rule 1, this is the "highest-leverage 10 minutes" of a session.

## The scaffold flow

```bash theme={"dark"}
# 1. Suggest a template from the brief.
ralphy template suggest "I want a TikTok about my coffee shop's new pastry"
# → before-after-product (score 0.61, dtc-commerce, vibe-reference)
# → food-beverage (score 0.42, dtc-commerce, vibe-style)
# → pov-first-person (score 0.29, creator-lifestyle, vibe-style)

# 2. Read the template doc (raw TEMPLATE.md).
ralphy template show before-after-product

# 3. Scaffold a project.
ralphy template use before-after-product \
  --project coffee-shop-001 \
  --brief "Lumen Coffee's new croissant — 15s ad"

# 4. The template pulls any required assets from the companion repo
#    automatically (e.g. brainrot-ai-meme pulls cs-surf-loop.mp4).
```

After `template use`, the project has a `BRIEF.md`, a draft `STORYBOARD.md`, and a `prompts.json` skeleton. The agent then chains scenarist → art-director → editor to fill in the rest.

## Adding a new template

Author a template into your user-local workspace tier, then publish it onward to the public library.

```bash theme={"dark"}
# 1. Extract a finished project into .ralphy/workspaces/<ws>/templates/<slug>/ (or hand-author the folder there).
ralphy template extract <project-id> --slug <slug> --category <category>

# 2. Register.
ralphy template register <slug>

# 3. Verify suggest finds it with score ≥ 0.5 for the canonical utterance.
ralphy template suggest "<the brief that should land on this template>"
```

To make it discoverable in the public Library, publish it via the `templater` / `dev-publish-template` path (Supabase + the open-source `published.ts`).

## Related

* [Library](https://www.alecs5am.com/library) — browse every published template + unit
* [Asset catalog](/concepts/asset-catalog) — `ralphy template use` pulls required assets from the companion repo
* [Projects](/concepts/projects) — what a scaffolded project looks like on disk
* [Asset catalog](/concepts/asset-catalog) — `ralphy template use` pulls required assets from the companion repo
* [Projects](/concepts/projects) — what a scaffolded project looks like on disk
* [`/advanced/template-format`](/advanced/template-format) — the YAML / JSON schema for `template.json`