scrivener-format

Scrivener 3 package format

You help the writer understand how a Scrivener 3 project is laid out on disk so the right tool and the right skill can be chosen. This is a knowledge / reference skill: it explains the package anatomy at a high level and points to deep references. It has no mutating commands — for actual reads use scrivener-inspect, for writes use the editing skills, and for validation use scrivener-integrity.

Use this skill to answer "what is this file?", "where does X live?", and "is this normal or corruption?" questions, and as the shared vocabulary the other 16 skills cite.

What a .scriv is

A Scrivener 3 project is not a single file — it is a package (a directory that macOS shows as one bundle; Windows and the synced cloud copy show it as a plain folder). The toolkit always operates on the folder regardless of platform.

The format target is Scrivener 3 only (cross-platform: Mac / Windows / iOS, Mac as reference). Scrivener 1/2 projects use a different internal layout and are detected and reported, not edited — see scrivener-integrity.

Two facts identify a v3 project:

• Files/version.txt holds the format version (e.g. 23 in the reference project).
• the <Project>.scrivx root carries Version="2.0".

High-level anatomy

Project.scriv/
├── <Project>.scrivx     # binder XML tree + project-wide settings (the spine)
├── Files/
│   ├── version.txt      # format version
│   ├── styles.xml       # named stylesheet (project styles)
│   ├── search.indexes   # regenerable plaintext index (Title/Text/Synopsis/Notes/Comments)
│   ├── writing.history  # per-day word-count history — Scrivener owns it, read-only
│   ├── binder.autosave / binder.backup   # zipped copies of .scrivx (Scrivener regenerates)
│   └── Data/
│       ├── docs.checksum         # SHA-1 of content.rtf / notes.rtf / synopsis.txt ONLY
│       └── <UUID>/               # per-document payload (not every item has one)
│           ├── content.rtf       # body text (cocoa RTF); embeds notes/styles/links/images
│           ├── synopsis.txt      # plain-text synopsis (or a synopsis image)
│           ├── notes.rtf         # document notes
│           ├── content.styles    # named styles applied in this doc
│           ├── content.comments  # linked comments + linked footnotes
│           ├── snapshots/        # captured versions of this doc
│           └── content.<ext>     # media payload for an Image/media item (e.g. content.jpeg)
├── Settings/            # compile.xml, projectpreferences.xml, ui state, sync markers
└── QuickLook/           # Preview.html, Thumbnail.jpg (macOS preview only)

Full directory tree, every file's purpose, and the regenerable-vs-authoritative split: references/package-layout.md.

The two big pieces

The .scrivx is the spine. It is the binder XML tree plus project-wide settings. Every binder entry is a <BinderItem> (UUID, Type, Title, MetaData, Children). Project siblings of <Binder> carry Collections, SectionTypes, Label/Status settings, and ProjectTargets. The full schema — BinderItem fields, the Type enum, section types and their three assignment states, collections, label/status settings — is in references/binder-and-metadata.md.

Data/<UUID>/ is the content. Each document's text, synopsis, notes, applied styles, linked comments, and snapshots live under a UUID-named directory. The binder points to these by UUID, not by title.

Absent data is normal, not corruption

This is the single most important thing to know when judging a project:

• Not every binder item has a Data/<UUID> directory. In the reference project the three special root folders (Draft, Research, Trash) have no Data dir at all.
• Not every Data/<UUID> directory has a content.rtf. Folders, empty/never-written documents, and Image items have a directory with no body file (an Image item stores content.<ext> instead).
• A "file group" is a Text item that has children — container-vs-document is decided by children, not by Type alone.

So a missing content.rtf or a missing Data directory is never corruption. Only an explicitly referenced payload that is gone counts (e.g. a docs.checksum entry, an Image item's declared content.<ext>, or a referenced snapshot/comments file).

Titles are not unique

Binder titles repeat (the reference project has two items both titled "Dont Stop To Early" — a Text and an Image). Always address a document by UUID when a title is ambiguous. Every mutating skill restates this.

docs.checksum is advisory

docs.checksum holds SHA-1 hashes of only content.rtf, notes.rtf, and synopsis.txt (never content.styles, content.comments, or media). Scrivener uses it to detect external/sync edits, not to assert integrity — real, valid projects routinely carry stale entries (≈32% mismatch in the reference project). Treat mismatches and absent entries as informational, never as corruption. scrivener-integrity can recompute them with repair --checksums.

What lives inside content.rtf

Several things are encoded in the RTF byte stream, not in side files — which is why edits must be token-preserving (see scrivener-edit / the RTF strategy in the spec):

• Linked comments/footnotes are anchored in the RTF as HYPERLINK fields targeting scrivcmt://<UUID>; their bodies live in content.comments.
• Applied named styles are marked with <$Scr_H::n>…<!$Scr_H::n> markers.
• Embedded images appear as \pict / pngblip data.
• Inline annotations/footnotes and internal Scrivener Links (HYPERLINK to a binder UUID) live inline too.

Naïvely regenerating "minimal RTF from text" would silently orphan comments, drop style ranges, break links, and delete images. That is why writes default to token-preserving edits.

How this hub is cited

Other skills point here for format facts so they can stay lean:

You're asking about…	Read this reference
Which files exist and what each is for	references/package-layout.md
BinderItem schema, Type enum, MetaData	references/binder-and-metadata.md
Section types (3 states), collections, labels/statuses	references/binder-and-metadata.md
What's embedded in content.rtf	this page + binder-and-metadata.md

Toolkit support

This skill is knowledge only — it teaches the format and has no commands of its own. The closest read commands (in other skills) are:

• ✅ outline — see the binder tree (scrivener-inspect)
• ✅ read <id> — see one document's text/synopsis/notes + construct flags (scrivener-inspect)
• ✅ verify — validate the package; checksum mismatches are advisory (scrivener-integrity)

There are no 🔜 planned commands here — format facts live in the references.

Related skills

• scrivener-inspect — open and explore a real project: outline, read, find.
• scrivener-integrity — verify, repair, backup/restore; confirms a package is valid.
• scrivener-metadata — set labels, status, section types, custom metadata defined here.
• scrivener-snapshots — work with the snapshots/ versions described here.
• scrivener-annotations — the linked/inline comments & footnotes embedded in content.rtf.