# Edit Workspace

The standalone editor writes local edit state under `.slate/editor/`. VML source files are the authored contract for Claude/Codex agents and the GUI.

Before hydration, make sure required reused footage has been materialized:

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

Run reference mode first. If it reports clips to download, ask the user for permission before downloading them into `External Media`. Do not hydrate and then delete missing-media overlays as a workaround; missing media should be fixed before the timeline is built.

## Files

- `.slate/editor/main.vml`: authored VML sequence.
- `.slate/editor/transcripts/*.vmlt`: prose transcript sources with `<Segment>` spans.
- `.slate/editor/main.vml.json`: host facts for media duration, transcript words, silences, and other deterministic media facts.
- `.slate/editor/.vml/project.json`: local VML project settings when present.
- `.slate/editor/.vml/cache/**`: generated cache. Do not edit this by hand.
- `.slate/proxies/*`: optional local proxy cache generated by `slate sync media --proxy` for faster probes/renders. Do not treat these as source media or editor handoff truth.
- `.slate/project.json` and `.slate/sequences/*.json`: legacy Go local edit engine files used by the older hydrate/render/native-sync path. Do not choose these for new standalone-editor work when VML files exist.

## Editing Loop

1. Inspect status:

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

If status reports `owner: "editor"`, stop. Resume with `slate edit sync <editor> --json` and only continue after ownership returns to Slate.

2. Read `.slate/editor/main.vml`, relevant `.vmlt` files, and `main.vml.json` facts.

3. Make the smallest useful timeline edits:

- Keep A-roll as the primary spine unless the user asks for a different structure.
- Preserve transcript-backed prose in `.vmlt` files; cut by moving/wrapping segments instead of flattening prose into generated objects.
- Adjust VML attributes deliberately: `range`, `on`, `offset`, `class`, and authored text. Timeline rows are derived from overlap by the compiler — never author a row.
- Use connected clips, scenes, and titles only when they make the edit better. For when and how, follow the folder's `vml-edit` skill.
- Do not edit generated cache or compiled plan artifacts.

4. Validate after every meaningful batch:

```sh
slate edit validate --json
slate edit plan --json
```

Validation errors block the edit. Warnings are the compiler's measurements of your
placements on the compiled timeline — B-roll or a scene that ends or starts within a
second of an A-roll cut, a sliver of face between two of them — each with the edit that would fix
it. A scene `cue` that isn't spoken while the scene plays is warned too (no automatic fix:
choose a phrase from the transcript). Read them; when the proposed edits are what you meant, apply them all with
`slate edit validate --fix --json`, which re-checks until nothing fixable is left.

5. Probe important moments before rendering the full draft:

```sh
slate edit ops --at 12.345 --json
slate edit probe --at 12.345s --out .slate/editor/export/probe-12.345s.png --json
slate edit render --from 12s --duration 3s --out .slate/editor/export/region.mp4 --json
```

6. Export native editor artifacts from VML:

```sh
slate edit export --out .slate/editor/export/main.fcpxml --target fcpxml --json
```

If validation reports missing or ambiguous media, fix VML asset declarations or host facts before editing timing.

## Common VML Shapes

```xml
<Asset id="host" file="./media/host.mov" note="talking head" />

<Sequence id="main">
  <Storyline>
    <Clip ref="host" range="12.4s..18.2s" />
  </Storyline>
</Sequence>
```

```xml
<Segment id="hook">
  This is the transcript-backed sentence Claude can edit as prose.
</Segment>
```

Run `slate edit catalog --json` for the full current VML contract.

## Final Cut / Premiere Handoff

Minimal supported flow:

```sh
# agent edits Slate
slate edit status --json
slate edit validate --json

# user takes over in an editor
slate edit sync fcp --handoff --json
# or
slate edit sync premiere --handoff --json

# use the returned nativeProject in the requested desktop editor, then stop editing Slate

# user edits in the editor, then asks the agent to continue
slate edit sync fcp --json
# or
slate edit sync premiere --json
```

While `owner` is `editor`, do not run `hydrate`, `validate`, `plan`, `ops`, `probe`, or `render`, and do not edit authored timeline files. The user should save the native editor project normally; the next `slate edit sync <editor> --json` automatically captures that saved `.fcpbundle` or `.prproj` back into Slate's hidden XML return artifact. If capture fails, fix Slate's native project adapter or Premiere UXP plugin and rerun sync instead of asking the user to export XML manually. Do not automate editor UI to force an export or click menus.