---
name: slate
description: Use when an agent needs to drive a Slate project from the CLI — brainstorm video ideas, read thumbnail entities and brainstorm/sketch/render entity-aware thumbnails, write script prompt blocks, fetch the creator's voice context, audit voice/packaging/b-roll, install the CLI, link a local folder, sync recorded media, reconcile placeholder annotations, or produce a local edit.
---

# Slate

Slate is a CLI-backed workflow for taking a planned Slate project from script and placeholder B-roll annotations to synced media, reconciled real clip annotations, and a local edit workspace.

## First Move

1. Check whether `slate` is installed: `slate version`.
2. If missing, install and authenticate from the shell yourself. The user should only need to approve browser sign-in. See `references/install-and-auth.md`.
3. Orient around the user's recorded media folder. If the current directory is not clearly the media folder, inspect likely local roots first and ask the user only when the folder or Slate project is ambiguous. See `references/local-link-and-sync.md`.
4. If the folder is not linked, run `slate link`.
5. Prefer `--json` for every command whose output you will inspect.

## Core Workflow

Use this order when the user asks you to edit a video from recorded footage:

```sh
slate link
slate edit make --yes --incremental --json
```

`slate edit make` runs the local edit orchestration from a linked folder:

1. Initialize or refresh the local `.slate/` edit workspace.
2. Sync/analyze local media, prioritizing likely A-roll footage first.
3. Assemble clean A-roll cuts from the script through Slate's A-roll engine.
4. Materialize B-roll references/downloads from the script's resolved annotations.
5. Hydrate the local edit files. For the standalone editor, the authored timeline is VML under `.slate/editor/`.

Use the smaller commands when you need granular control or a retry:

```sh
slate sync media --proxy --prioritize-a-roll --yes --wait --json
slate clips list --scope linked --processing-phase completed --limit 100 --json
slate edit recommend a-roll --json
slate sync script --yes --wait --json
# for explicit paragraph-to-A-roll assignments or retries:
slate edit assemble a-roll --paragraph-id <paragraph-id> --clip-id <clip-id> --incremental --json
slate edit reconcile b-roll --limit 5 --json
slate edit apply b-roll --file .slate/annotation-replacements.json --mode reference --yes --json
# if reference mode reports external clips and the user approves:
slate edit apply b-roll --file .slate/annotation-replacements.json --mode download --yes --json
slate edit hydrate
```

Speak to the user in workflow language, not CLI language. Good progress updates are:

- "I'll link this folder to your Slate project."
- "I'll process the footage so Slate understands the clips and make local proxies so the edit loop is faster."
- "I'll check that Slate classified the talking-head footage and B-roll correctly."
- "I'll replace the placeholder B-roll notes with the real clips you recorded."
- "I'll bring any reused Slate footage into this folder before building the edit."
- "I'll build the clean A-roll cut paragraph by paragraph, add B-roll, and render a draft."

When a command blocks, report the command's `message` and one `safeNextAction`. Do not paste raw validation blobs, GUIDs, server stack traces, or retry loops unless the user asks for debugging detail.

Before editing the local timeline, always run:

```sh
slate edit status --json
slate edit context --format md
```

For paragraph-level A-roll assembly, use Slate's edit surface:

```sh
slate edit recommend a-roll --json
slate edit assemble a-roll --paragraph-id <paragraph-id> --clip-id <clip-id> --incremental --json
```

`recommend a-roll` returns the script paragraphs each A-roll clip should cover. `assemble a-roll` calls Slate's existing A-roll assembly engine and writes the project paragraph cut data. Both commands default project and linked-folder context from `.slate/link.json`. Do not add Slate orchestration commands to the VML CLI; VML is the timeline/workspace substrate, while Slate owns project linking, media analysis, A-roll/B-roll semantics, and agent orchestration.

For B-roll reconciliation, use Slate's edit surface:

```sh
slate edit reconcile b-roll --limit 5 --json
slate edit apply b-roll --file .slate/annotation-replacements.json --mode reference --yes --json
```

`reconcile b-roll` returns candidate sets and deliberately does not choose the mapping. You choose replacements with editorial judgment, write a JSON payload, then `apply b-roll` patches Slate annotations, syncs/materializes the B-roll plan, and hydrates the local edit workspace.

If `owner` is `editor`, do not edit Slate files. Run `slate edit sync <fcp|premiere> --json` for the reported handoff editor and proceed only after ownership returns to Slate.

When `.slate/editor/main.vml` exists, edit `.vml` / `.vmlt` source files directly, validate with `slate edit validate --json`, inspect timing with `slate edit ops --at <time> --json`, render probes/drafts with `slate edit probe` and `slate edit render`, and export native editor artifacts with `slate edit export --out <file> --json`. The older `.slate/sequences/*.json` shape is legacy for the Go hydrate/render/sync path, not the standalone editor's authored contract.

For the local edit loop and VML source shape, read `references/edit-workspace.md`. When you are shaping the edit itself — pacing, B-roll, punch-ins, J-cuts, music, captions — and not just fixing syntax, read `references/cinematography.md`.

## Content Production (ideation, thumbnails, script, audits)

Beyond editing recorded footage, the CLI drives Slate's AI production operations so an external agent can take a project from idea to packaged, scripted, audited content. These run the SAME server operations as the Slate webapp/agent (creator context, metering, and persistence included). Use `--json`; they are slow synchronous AI calls (the CLI imposes no client timeout by default).

### Ideation

```sh
slate ideate --yes --json   # brainstorm video ideas grounded in the linked channel + vault; returns scored candidates
```

### YouTube research

```sh
slate youtube search "productivity systems" --max-results 20 --json
slate youtube outliers "productivity systems" --top 5 --json
slate videos search "productivity systems" --json
slate videos search "productivity systems" --platform youtube,tiktok --max-results 10 --json
slate videos inspect "https://www.youtube.com/watch?v=<video-id>" --json
slate videos ask "https://www.youtube.com/watch?v=<video-id>" "How does the opening hook work?" --json
```

`youtube search` returns ordinary YouTube matches. `youtube outliers` evaluates a wider result set against each video's channel baseline and ranks the strongest breakouts. `videos search` uses the same unified discovery path as Slate's agent and searches YouTube, YouTube Shorts, TikTok, and Instagram by default; repeat or comma-separate `--platform` to narrow it. Scored YouTube rows include `outlierScore`, `outlierScoreVersion`, `outlierTier`, `outlierConfidence`, `baselineViews`, and `comparisonCount`; rows without enough channel evidence omit those fields. `videos inspect` accepts a YouTube URL or id and returns video details, the raw transcript, a shot-by-shot visual breakdown, and the reconstructed edit timeline. `videos ask` runs Slate's grounded video-question operation against the YouTube video feed.

### Thumbnails — entity-aware

Thumbnail concepts reference **thumbnail entities** — the creator's face and custom subjects — as inline tokens `[label](attachment:att-e-<entityId>)` (YouTube refs use `att-y-<videoId>`). Those tokens are what make the render composite the REAL creator face; without them the render is generic. The canonical, entity-aware flow:

```sh
slate thumbnails entities --json                               # read entity ids (e.g. entityType creators_face + custom subjects)
slate thumbnails brainstorm --project-id <id> --json           # concepts WITH att-e-* entity tokens already embedded
slate thumbnails brainstorm --project-id <id> --json | slate thumbnails add --project-id <id> --file - --yes --json
```

`thumbnails add` runs the SAME `addThumbnails` executor the webapp/routine use: it persists each concept, parses its `att-e-*`/`att-y-*` tokens, resolves your `thumbnail_entities` (with creator-face self-heal), and renders entity-aware photorealistic thumbnails with the real creator face. **Prefer `thumbnails add`** — it is the canonical entity-aware path. It accepts the `thumbnails brainstorm` output directly (a concepts/thumbnails array).

If you author a concept description yourself instead of using brainstorm output, first run `slate thumbnails entities` to get the ids, then embed `[the creator](attachment:att-e-<id>)` in the description so the face is composited.

Lower-level, **entity-blind** commands for an explicit single-thumbnail re-render (they only forward what you pass — include `entities` in `--data` if you need the face):

```sh
slate thumbnails sketch <packaging-id> --thumbnail-id <id> --concept "..." --yes --json
slate thumbnails render <packaging-id> --thumbnail-id <id> --instructions "..." --yes --json
```

### Script voice + prompt blocks

```sh
slate scripts voice-context --json                                       # the user's blended voice profile, to author in-voice
slate scripts prompt-block --project-id <id> --block-id <id> --yes --json
```

### Audits (read-only quality gates)

```sh
slate audit voice --project-id <id> --json        # voice & tone vs the user's past videos
slate audit packaging --project-id <id> --json    # titles/thumbnails (long-form only)
slate audit broll --project-id <id> --json        # b-roll annotation coverage
```

### Generic

Any capability can also be called by name: `slate capability call <name> --data '<json>' --yes --json`.

## Editor Handoff

When the user asks to open or take over the edit in Final Cut Pro or Premiere:

```sh
slate edit sync fcp --handoff --json
slate edit sync premiere --handoff --json
```

After a successful handoff, use the reported `nativeProject` as the user-facing editor project (`.fcpbundle` for Final Cut Pro, `.prproj` for Premiere), then stop editing Slate. The XML `editorProject` is Slate's hidden reconciliation artifact, not the file the user should manage.

When the user asks you to keep editing after using Final Cut or Premiere, resume first:

```sh
slate edit sync fcp --json
slate edit sync premiere --json
```

Only continue once the report says `owner: "slate"` and `roundTripVerified: true` or the clean no-change equivalent. Do not ask the user to export XML manually. A normal save in Final Cut Pro or Premiere is enough; the next `slate edit sync <editor> --json` captures the saved native project through Slate's native project adapter. Never automate editor UI to force an export or click menus; fix the `.fcpbundle` adapter or Premiere UXP bridge/plugin and rerun sync.

If the user explicitly wants to abandon editor changes:

```sh
slate edit sync fcp --discard-editor-changes --yes --json
slate edit sync premiere --discard-editor-changes --yes --json
```

## Critical Checkpoint: After Recording

After the user records A-roll and B-roll, Slate's script can still contain placeholder annotations: instructions like what to record, not the clips that were actually recorded.

When the user is syncing recorded video for a local Slate edit, suggest proxy generation unless they explicitly want the fastest possible sync with no extra local transcoding. Use `slate sync media --proxy --yes --wait --json` for large, high-resolution, or previously slow footage. Proxies speed up Slate `probe` and `render`; they do not change server analysis and are not used for FCP/Premiere handoff.

For a full local edit, prefer `slate edit make --yes --incremental --json`. If running phases manually, use `slate sync media --proxy --prioritize-a-roll --yes --wait --json` so likely talking-head footage is analyzed first and A-roll assembly can start while B-roll indexing continues.

Do not skip classification review or reconciliation. Before edit hydration:

- Read the newly synced clip inventory with `slate clips list --scope linked --processing-phase completed --limit 100 --json`.
- Check that clips classified as `a_roll` look like the user's primary talking-head/narration footage, and that clips classified as `b_roll` look like supplemental visuals. Use titles, descriptions, transcript availability, duration, filenames, and local folder placement together; do not trust a single field blindly.
- If a clip is miscategorized, explain the correction in plain language and update it with `slate clips set-type <clip-id> a_roll --yes --json` or `slate clips set-type <clip-id> b_roll --yes --json`.

Then reconcile script placeholders:

- Read current blocks with `slate scripts blocks list --json`.
- Read the newly synced clip inventory with `slate clips list --scope linked --processing-phase completed --type b_roll --limit 100 --json`.
- Retrieve per-placeholder candidates with `slate edit reconcile b-roll --limit 5 --json`. This is the canonical recorded-footage reconciliation surface for local edits.
- Use LLM judgment to match placeholder intent to the analyzed real clips. Candidate embeddings are generated from each placeholder annotation's label/description and are scoped to the linked media folder; the CLI must not choose the mapping by itself.
- Before applying, ask the user to confirm the project update: "I’m about to update your Slate project by replacing placeholder B-roll notes with the actual footage clips. This is what lets Slate generate the edit timeline accurately. Should I apply these replacements?"
- Apply the chosen replacements with `slate edit apply b-roll --file .slate/annotation-replacements.json --yes --json` only after the user confirms.
- Preserve script block text unless the user explicitly asks you to rewrite the script.
- Do not use broad `slate clips search` for recorded-footage reconciliation unless the user explicitly asks to source clips outside this folder.

The browser Slate project agent can do the same task with `getScriptBlocksState`, `searchClips`, `listProjectClips`, and `setBlockAnnotations`. External coding agents should use the CLI path.

## Critical Checkpoint: External Media

After annotation reconciliation and before `slate sync script` / `slate edit hydrate`, check whether the timeline will need reused clips from other Slate projects:

```sh
slate sync b-roll --mode reference --yes --json
```

If the plan has items, ask the user before downloading: "This edit uses reused footage from your Slate library that is not in this local folder yet. Is it okay if I download those clips into `External Media` so the draft can render?"

Only after the user confirms, run:

```sh
slate sync b-roll --mode download --yes --json
```

Do not delete missing-media overlays from authored timeline files as a workaround. Missing reused clips should be materialized into `External Media` before hydration/render. If download fails, report the failed clip count and stop before editing the timeline.

## References

- Install/auth details: `references/install-and-auth.md`
- Local folder linking and sync: `references/local-link-and-sync.md`
- Post-recording annotation reconciliation: `references/post-recording-reconciliation.md`
- Local edit workspace: `references/edit-workspace.md`
- Cinematographic / editorial craft for the edit loop: `references/cinematography.md`
- Full CLI reference: `references/cli-reference.md`