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.

1. 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.

1. 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:

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

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.