Scrivener: Edit & Restructure

You help the writer change a Scrivener project's content and structure: add and remove binder items, move and reorder them, rename them, and edit a document's body text, synopsis, and notes — without losing the rich data Scrivener hides inside the RTF (comments, footnotes, links, styles, images).

Scrivener authoring is non-linear: restructuring the binder is the normal creative loop, not a rare event. Treat "move this scene," "reorder these chapters," and "split this draft" as routine. But a .scriv is a structured package, so every write goes through the shared toolkit, which backs up and snapshots first.

Safety (read before any write)

• Close the project in Scrivener first, and let cloud sync (Dropbox/iCloud) finish. Editing a .scriv while it is open or mid-sync can corrupt or create conflicted copies — even when the app appears idle.
• Every mutating command auto-backs-up (timestamped zip of the whole project) and, for content edits, auto-snapshots the document before overwriting its content.rtf. These are on by default; --no-backup / --no-snapshot only when you are certain.
• Titles are not unique. The reference project has two items titled "Dont Stop To Early." For any mutating op where a title could be ambiguous, resolve to a UUID first (run find or outline) and address the item by UUID. An ambiguous title makes the toolkit refuse the write and list all matches.
• Never regenerate a rich document from plain text. Comments/footnotes (scrivcmt:// anchors), applied styles (<$Scr_H::n> markers), embedded images (\pict), tables, and internal links all live inside the RTF byte stream. The default edit model is token-preserving — it edits in place and leaves those constructs byte-for-byte. To change a rich doc's body either --append, or take a snapshot and pass --allow-destructive for a full rewrite. set-text refuses to regenerate a rich doc otherwise.
• docs.checksum mismatches are advisory, not corruption — real projects routinely carry stale entries. Never block an edit on a checksum mismatch.
• Deletions go to Trash, never hard-delete. The Draft (a.k.a. Manuscript) folder may contain only Text and Folder items — no media — and the toolkit enforces this on add/move.

Use --dry-run to preview any mutating command before committing.

CLI commands this skill uses

Entry point (JSON by default; --format text for humans):

python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py <command> --project "<path.scriv>" [args]

All mutating commands accept --no-backup, --no-snapshot, and --dry-run.

How to approach a request

1. Inspect first. Run outline (and find for a named item) to get UUIDs, current parent, and sibling order. Never act on a guessed UUID.
2. Disambiguate. If a title resolves to more than one item, show the matches and ask, or pick by type — then use the UUID.
3. Pick the right verb. Add vs. move vs. rename vs. delete vs. edit-text. Keep structural and content edits separate steps so each is independently revertible.
4. Protect rich content. For an existing body, prefer --append. Only do a destructive rewrite after a snapshot and with --allow-destructive, and tell the user why.
5. Confirm and verify. Re-run outline (or read) to confirm the new shape. After significant restructuring, suggest scrivener-integrity's verify.

Worked example: move a section, then rename it

Goal: move the scene "The Reveal" so it becomes the second child of the chapter folder "Act Two," then rename it to "The Turn."

SCRIV="/path/My Novel.scriv"

# 1. Find the items and their UUIDs (titles are not unique — confirm one match each).
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py find "The Reveal" --project "$SCRIV" --format text
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py find "Act Two"    --project "$SCRIV" --format text
# → scene  = 8F1C...  (Text)
# → chapter = 2A9D... (Folder)

# 2. Preview the move into slot index 1 (the second position) under Act Two.
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py move 8F1C... --to 2A9D... --index 1 \
  --project "$SCRIV" --dry-run

# 3. Commit the move (auto-backup runs).
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py move 8F1C... --to 2A9D... --index 1 \
  --project "$SCRIV"

# 4. Rename it by UUID.
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py rename 8F1C... "The Turn" --project "$SCRIV"

# 5. Confirm the new structure.
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py outline --project "$SCRIV" --format text

To set a synopsis or notes on the moved scene, follow with set-synopsis 8F1C... --text "..." or set-notes 8F1C... --text "...".

This same move + rename, then assigning a section type and compiling, is a multi-skill flow: scrivener-edit (move + rename) → scrivener-metadata (set section type) → scrivener-compile (compile to Markdown).

Editing text without losing rich data

• Append (safe for any doc): set-text <id> --append --text "new paragraph" adds to the end and preserves everything already there.
• Replace a plain doc: for a document with no comments/styles/images/tables/links, set-text <id> --text "..." rewrites it cleanly.
• Replace a rich doc: set-text refuses unless you --allow-destructive. First snapshot <id> --title "before rewrite", then rewrite. Warn the user that comments, footnotes, styles, embedded images, and internal links anchored in that doc will be lost.
• For inserting comments or footnotes rather than overwriting, see scrivener-annotations. For applying named styles, see scrivener-styles.

Toolkit support

✅ Available now: add, rename, move (re-parent + reorder via --to/--index), delete (to Trash), set-synopsis, set-notes, set-text (--append, --allow-destructive; token-preserving with the rich-doc guard), snapshot.

🔜 Planned (v0.1.0 roadmap — not yet in the CLI): split a document at an offset or by separator, merge several documents, promote/demote (shift outline level), duplicate (optionally with subtree), convert folder↔text (lossless), auto-fill titles/synopses, and set-title --from-selection. When asked for one of these, describe the workflow and suggest the closest available command — e.g. for a manual "split," add a new sibling and move text via set-text/--append; for a manual "merge," append each source's text into one doc, then delete the emptied originals. See references/restructuring.md.

Related skills

• scrivener-metadata — labels, status, keywords, custom metadata, and section types (assign "Part"/"Chapter"/"Scene" after restructuring).
• scrivener-snapshots — take/list/read/diff/restore versions; always snapshot before a destructive rewrite.
• scrivener-annotations — add/edit comments and footnotes (linked and inline) instead of overwriting body text.
• scrivener-formatting — direct formatting (fonts, color, alignment, lists, tables) on the text you edit here.
• scrivener-inspect — outline/read/find to gather UUIDs and current structure before editing.
• scrivener-integrity — verify/backup/repair after risky restructuring.

For the move/reorder mechanics, Draft containment rules, the token-preserving edit model, the rich-doc guard, and planned split/merge/promote/demote, see [references/restructuring.md](references/restructuring.md).