# 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.
- Use connected clips and titles only when they make the edit better. For when and how, see `references/cinematography.md`.
- Do not edit generated cache or compiled plan artifacts.

4. Validate after every meaningful batch:

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

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.