# Local Link And Sync

Run link from the local folder that contains the user's recorded media:

```sh
slate link
```

If the user says something like "I plugged in my SD card; edit my Slate video" and does not give a folder, first orient yourself:

```sh
pwd
ls
ls /Volumes
find /Volumes -maxdepth 3 -type f \( -iname '*.mov' -o -iname '*.mp4' -o -iname '*.m4v' \) 2>/dev/null | head -50
slate projects list --json
```

Choose the obvious media folder and Slate project when there is only one plausible match. If several folders or projects are plausible, ask the user one short question to choose between them.

For non-interactive agents:

```sh
slate link --project-id <project-id> --yes --json
```

Slate writes `.slate/link.json`. After that, commands can usually infer `projectId`, `linkedFolderId`, and the local media root from the current folder.

The agent should run these commands directly after auth. Do not ask the user to learn CLI flags.

## Sync Recorded Media

After recording:

```sh
slate sync media --proxy --yes --wait --json
```

This preprocesses local files concurrently, creates Slate clips, uploads transient analysis artifacts, enqueues processing, generates local proxy footage for faster Slate probes/renders, and waits for the clips it synced to reach a terminal processing phase.

Suggest `--proxy` when the user is preparing a local Slate edit from recorded video, especially for large or high-resolution footage, or when a previous edit loop felt slow. Proxies are local cache files for Slate `probe` and `render`; they are not uploaded, do not affect server analysis, and are not used for FCP/Premiere handoff.

`sync media` runs a preflight before creating or mutating clips. If the Slate app is reachable but media processing is not running, stop and tell the user:

```text
Slate can see your project and footage, but media processing is not running yet. Start Slate's media services, then I'll continue.
```

Then use the command's `safeNextAction`. Do not keep creating clips, retrying blindly, or asking the user to understand queue internals.

Large local talking-head/A-roll videos are common. Slate may skip raw Gemini video upload for those files and let the media worker analyze local preprocessed audio/frames instead. Treat `geminiSkipped.reason: "large_local_video"` as expected progress, not as a failure.

Useful inspection commands:

```sh
slate status --local --json
slate clips list --scope linked --processing-phase completed --limit 100 --json
slate clips search "hands typing at laptop" --linked-folder-id <folder-id> --type b_roll --limit 10 --json
```

After media analysis, verify clip categorization before building A-roll:

```sh
slate clips list --scope linked --processing-phase completed --limit 100 --json
slate clips set-type <clip-id> a_roll --yes --json
slate clips set-type <clip-id> b_roll --yes --json
```

Only recategorize when the analyzed metadata clearly disagrees with the user's footage: A-roll should be primary narration/talking-head material; B-roll should be supplemental visuals.

If the reconciled script uses clips from outside this linked folder, materialize them before edit hydration:

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

Ask the user before the download step because it may copy real media files into `External Media`.

Cloud-linked folders can still use folder sync:

```sh
slate sync folder --yes --json
```

Local folders do not use cloud folder sync.