# Scrivener Sync

> When the user wants to edit a Scrivener Draft as plain text in an external folder and re-sync the changes back — the agent-native round-trip that avoids RTF surgery. Use when the user says "sync to a folder," "edit as plain text and sync back," "export the draft so I can edit it elsewhere," "external folder sync," "set up a Dropbox sync folder," or "is this project in a sync conflict." For converting content out without the round-trip, see scrivener-extract. For bringing edited text back into a document today, see scrivener-edit. For detecting and resolving sync conflicts, see scrivener-integrity.

- Skill: `donnfelker/scrivener-sync` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add donnfelker/scrivener-sync`
- Raw SKILL.md: https://api.skillmd.com/api/skills/donnfelker/scrivener-sync/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: donnfelker (https://skillmd.com/u/donnfelker)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/donnfelker/scrivener-sync

---


# Scrivener Sync

You help the writer (or an agent) edit a Scrivener Draft as **plain text in an
ordinary folder** and bring the edits back into the `.scriv` — Scrivener's
**Sync with External Folder** round-trip. This is the agent-native edit loop:
plain `.txt`/`.rtf`/Fountain files an agent can read and rewrite directly,
with no RTF byte surgery.

> **Heads up: the dedicated `sync-folder` command is not in the CLI yet.** It is
> on the v0.1.0 roadmap (see **Toolkit support**). Today you reproduce the
> round-trip with `extract`/`compile` to get text out and `set-text` to bring
> edits back. Be honest with the user about which path you are taking.

## When to use this skill

- "Export my draft to a folder so I can edit it in another app, then sync it back."
- "Set up an external sync folder for this project."
- "I edited the text files in the sync folder — pull my changes in."
- "Edit chapter 4 as plain text and sync the result back."
- "Is this project in a sync conflict?" → route to **scrivener-integrity** for
  detection; this skill explains how conflicts arise and how to avoid them.

## What the round-trip is (and is not)

Sync with External Folder mirrors binder documents to flat files on disk so you
can edit them anywhere, then reconciles changes in both directions:

1. **Export** — write each Draft document to a file in a sync folder, named with
   a `[number]` prefix that links the file back to its binder item.
2. **Edit externally** — open the files in any plain-text/RTF/Fountain editor (or
   have an agent rewrite them). Add a new file and it becomes a new binder item on
   import; the prefix number is how the linkage survives a round-trip.
3. **Import** — read the files back, diff each against the binder by **modified
   date**, and update only the documents that actually changed.

It is **not** a live sync daemon and it is **not** a full document round-trip. It
moves **content text only**.

## Constraints (tell the user up front)

External-folder sync deliberately moves a *reduced* form of each document:

- **Content only.** Synopsis, notes, labels, status, keywords, custom metadata,
  and snapshots are **not** in the synced files — they stay in the project.
- **Strips embedded images.** Inline `\pict` images are dropped from the synced
  text; they remain in the project's `content.rtf`.
- **Wraps inline notes.** Inline annotations and footnotes are wrapped in plain
  markers in the file so they survive editing and re-import.
- **Plain formatting.** `.txt` and Fountain carry no rich formatting; `.rtf`
  preserves basic character/paragraph formatting only.

Because of this, sync is ideal for **prose editing** (rewrite the words) and a
poor fit for documents that are mostly tables, heavy styling, or images.

## The round-trip today (available now)

Until `sync-folder` ships, do the round-trip with the existing commands:

```bash
SCRIV="<path.scriv>"
CLI="python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py"

# 1. EXPORT — get the text out. Per-document:
$CLI extract <uuid> --to txt --project "$SCRIV"
# …or the whole Draft as one assembled, structured file:
$CLI compile --to md --project "$SCRIV"

# 2. EDIT the text (you, or the user, in any editor).

# 3. IMPORT — bring an edited document back in.
#    Prefer --append for rich docs; only overwrite a known-plain doc.
$CLI set-text <uuid> --text-file edited.txt --project "$SCRIV"
$CLI set-text <uuid> --text-file addition.txt --append --project "$SCRIV"
```

Key differences from real sync, which you must surface:

- There is no `[number]`↔binder linking yet — **you** track which file maps to
  which UUID (resolve titles via `find`/`outline` in scrivener-inspect).
- There is no automatic mod-date diff — decide yourself which documents changed.
- `set-text` is **token-preserving** and **refuses to regenerate a rich document**
  (comments, footnotes, styles, links, tables, images) unless you pass
  `--allow-destructive`. For a rich document, **append** the new text or take a
  snapshot first — do not blow away its constructs. Inspect a doc's `constructs`
  with `read` (scrivener-inspect) before overwriting.

## Cloud-sync HAZARD (read before touching the file)

Sync with External Folder is unrelated to cloud sync — but the two collide
dangerously:

- **Editing a `.scriv` while Dropbox or iCloud is mid-sync can corrupt or
  conflict the project — even when Scrivener is closed.** A half-uploaded package
  is an inconsistent package.
- Before any export or import: **close the project in Scrivener** *and* **wait for
  cloud sync to fully finish** (no spinning sync badge / "uploading…" indicator).
- Put the **external sync folder somewhere stable**. If both the `.scriv` and the
  sync folder live inside the same cloud-synced directory, you can get duplicate
  conflicted copies on either side.

**Conflict detection.** A conflict shows up as a "(Conflicted Copy)" file, a
Conflicts folder, or Synced/Updated collections in the project. If the user asks
"is this in a conflict?", route to **scrivener-integrity** (`conflicts`, planned)
to detect it, and refuse risky bulk writes until it is resolved.

## Safety

Restate before any write:

- **Close the project in Scrivener AND let cloud sync finish first.**
- Writes auto-**backup** (zip) and auto-**snapshot** a document before overwriting
  its text; `--no-backup` / `--no-snapshot` skip these (don't, unless asked).
- `docs.checksum` mismatches are **advisory** — Scrivener uses them to flag
  externally edited files; they are never corruption and never block a write.
- **Titles are not unique** — address mutating commands by **UUID** when a title
  is ambiguous.
- **Never regenerate a rich document from plain text.** Append, or snapshot and
  pass `--allow-destructive`.

## Toolkit support

| Capability | Status |
|---|---|
| `extract <id\|all\|draft> [--to md\|txt]` (export text out) | ✅ available now |
| `compile [--to md\|txt]` (assembled Draft out) | ✅ available now |
| `set-text <id> (--text\|--text-file) [--append] [--allow-destructive]` (bring edits back) | ✅ available now |
| `read <id>` → `constructs` (check if a doc is rich before overwriting) | ✅ available now |
| `sync-folder export --folder <dir> [--format rtf\|txt\|fountain]` | 🔜 planned |
| `sync-folder status --folder <dir>` (mod-date diff vs binder) | 🔜 planned |
| `sync-folder import --folder <dir>` (`[number]`↔binder linking, new files → new items) | 🔜 planned |
| Draft/Notes/Trashed subdir layout + `.fdx`/Fountain formats | 🔜 planned |

When asked for a planned capability, say `sync-folder` isn't in the CLI yet and
offer the manual round-trip above (`extract`/`compile` out, `set-text` back),
plus this honest caveat: you lose the automatic `[number]` linking and mod-date
diffing, so you must track file↔UUID mapping and which files changed yourself.

See `references/external-folder-sync.md` for the folder layout, linking and
mod-date diffing rules, the full constraint list, the planned `sync-folder`
command shapes, and the cloud-sync hazard in depth.

## Related skills

- **scrivener-integrity** — `conflicts` (detect sync/cloud conflicts), `verify`,
  `backup`/`restore`; the place to check before and after a risky round-trip.
- **scrivener-extract** — convert `content.rtf` to Markdown/plain text; the
  "export" half of the round-trip today.
- **scrivener-edit** — `set-text` (token-preserving append/overwrite), the write
  model and `--allow-destructive` guard; the "import" half today.
- **scrivener-compile** — assembled, structured Draft output (titles → headings,
  binder order) when you want one file instead of per-document text.
- **scrivener-format** — how content, inline notes, and images are stored on disk,
  which explains what sync keeps and what it strips.