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:

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.