Book Filesystem Layout

Scritorio books are ordinary local folders. Markdown and YAML front matter are the source of truth; databases and generated files are supporting state. This page describes the intended v1 book layout. Scritorio can import or tolerate older shapes, but new projects and repaired projects should converge on this contract.

Book Root

A typical book project looks like this:

MyBook/
  book.md
  story.yml
  scritorio.project.json
  manuscript/
    act-a552eb2e.md
    act-a552eb2e/
      chapter-c3960842.md
      chapter-c3960842.notes.md
      chapter-c3960842.beat-sheet.md
    dedication.md
    prologue.md
    page.md
  codex/
    characters/
    locations/
    organizations/
    items/
    concepts/
    events/
    style/
  notes/
  assets/
  exports/
  state/
  .scritorio/

Not every folder is required on day one. book.md, story.yml, scritorio.project.json, manuscript/, codex/, and .scritorio/ are the core shape for a Scritorio-managed book. If the manifest is missing, Scritorio should be able to repair it from the readable project files where possible.

File Classes

Different files have different durability expectations:

Class	Examples	Upgrade rule
Author source	`book.md`, `manuscript/*/.md`, `codex/*/.md`, `notes/*/.md`	Preserve body text and unknown front matter. Do not rewrite prose during repair unless the author explicitly asks.
App metadata	`story.yml`, `scritorio.project.json`, `.scritorio/settings.json`, `.scritorio/layout-settings.json`	Keep relative-path based. Repair from source files where possible.
Repairable manifest	`scritorio.project.json`	Treat as app-maintained state that can be regenerated or patched when it drifts from disk.
Generated cache	`.scritorio/index.sqlite`, `.scritorio/manuscript-intelligence/`	Never canonical manuscript state. Safe to rebuild from author source and app metadata.
Export artifact	`exports/`	User-visible output of a workflow. Safe to regenerate, but do not delete user-visible exports without confirmation.
Build intermediate	`.scritorio/build/`	App-owned preview and export intermediates. Safe to regenerate.
Legacy/transitional	`.colophon/`, older `state/` files	Preserve when opening older projects unless a migration explicitly knows how to replace or retire it.
Unknown author file	Any unrecognized local file	Preserve by default. Unknown files are not errors unless they conflict with a Scritorio-owned path.

Root Files

Path	Owner	Purpose
`book.md`	Author and app	Book overview, metadata, genre, audience, point of view, and working notes.
`story.yml`	App with readable author-facing structure	Manuscript assembly order and other project-level source lists.
`scritorio.project.json`	App	Project manifest, stable document ids, roots, status, asset records, and sidebar sort metadata.

story.yml keeps a readable manuscript order list:

schema_version: 1
manuscript_order:
  - manuscript/act-a552eb2e.md
  - manuscript/act-a552eb2e/chapter-c3960842.md
  - manuscript/act-a552eb2e/chapter-5599394a.md

scritorio.project.json is the app manifest. It should stay relative-path based so the book folder remains movable.

Metadata Precedence

When metadata disagrees, Scritorio should use the most author-facing source that can safely answer the question:

Question	Preferred source
What is this manuscript unit?	The Markdown file’s YAML front matter: `id`, `type`, `unit_type`, `title`, `include_in_manuscript`, and `order`.
What is the manuscript display and assembly sequence?	Manuscript front matter `order`, with `story.yml` and manifest sort metadata repaired to agree.
What is the chapter number?	Derived at runtime by sorting included chapters by `order`; never stored as canonical YAML.
What files exist in the project?	Disk, then `scritorio.project.json` repaired to match.
What is searchable/indexed state?	`.scritorio/index.sqlite`, rebuilt from Markdown and metadata.
What are generated intelligence summaries?	`.scritorio/manuscript-intelligence/`, rebuilt from source evidence when needed.

story.yml is readable assembly/reference state. It should agree with manuscript front matter but should not require prose rewrites to repair. scritorio.project.json is app-maintained manifest metadata. It should preserve stable document ids when possible, but it is not the only source of manuscript truth.

Manuscript

manuscript/ contains first-class manuscript units. Every printable unit should use front matter like this:

---
type: manuscript_unit
unit_type: chapter
order: 2000
include_in_manuscript: true
id: 39608427-8650-476a-90f8-335fbebf5932
---

order means display and assembly sequence. It is not a chapter number. Chapter numbers are derived at runtime by sorting included manuscript units by order and counting only units where unit_type: chapter. A dedication, prologue, quotation, or page can appear anywhere in the manuscript without consuming a chapter number. Chapter filenames are stable storage ids:

manuscript/act-a552eb2e/chapter-c3960842.md

The filename should not be renamed when the chapter becomes Chapter 2, Chapter 7, or moves between acts. The left panel and preview should derive labels such as Chapter 1 or Chapter 1: The Signal from current manuscript order. For chapters, title is reserved for a real author-supplied title:

---
type: manuscript_unit
unit_type: chapter
title: "The Signal"
order: 3000
include_in_manuscript: true
id: 5c34c771-2c9e-4f5b-b2cb-f6777979c28f
---

Untitled chapters should omit title. They should not store title: "Chapter N" as placeholder metadata.

Manuscript Units

The current author-facing v1 units are:

Unit type	Typical path	Notes
`act`	`manuscript/act-a552eb2e.md`	Structural grouping with stable id filenames. Acts may have companion folders such as `manuscript/act-a552eb2e/`.
`chapter`	`manuscript/act-a552eb2e/chapter-c3960842.md`	Stable id filename, derived chapter number, optional author title.
`section`	`manuscript/act-a552eb2e/sections/section-1/index.md`	Nested subdivision where useful.
`note`	`manuscript/note-1.md`	Manuscript-adjacent note, not normal assembled prose.
`prologue`	`manuscript/prologue.md`	Printable book-level unit, title-only chrome.
`dedication`	`manuscript/dedication.md`	Printable book-level unit, title-only chrome.
`page`	`manuscript/page.md`	Generic printable page for custom book matter.
`quotation`	`manuscript/quotation.md`	Recognized printable quotation or epigraph-style unit. UI creation support may lag behind recognition.

Scritorio may still recognize older or imported manuscript types such as part, appendix, front_matter, and back_matter. Those should be treated as compatibility/import concepts unless they are reintroduced as v1 creation targets. Scenes are usually headings inside chapter Markdown:

## Scene: Arrival At The Station

That keeps scene structure portable without requiring every scene to become a separate file.

Planning Sidecars

Planning sidecars are Markdown files linked to manuscript prose but excluded from normal manuscript assembly. For a standalone manuscript file, the sidecar sits next to the prose file:

manuscript/act-a552eb2e/
  chapter-c3960842.md
  chapter-c3960842.notes.md
  chapter-c3960842.beat-sheet.md

Their front matter points back to the manuscript unit:

---
type: chapter_notes
for: manuscript/act-a552eb2e/chapter-c3960842.md
id: chapter_notes.5ae1227a-e08d-4c1f-bbb2-d27e2d5b2307
---

---
type: beat_sheet
for: manuscript/act-a552eb2e/chapter-c3960842.md
id: beat_sheet.eb0972b6-bbbc-46fb-b657-fd231a222d11
---

Folder-style manuscript units can use:

manuscript/chapter-folder/
  prose.md
  notes.md
  beat-sheet.md

notes.md and beat-sheet.md are sidecars for prose.md in that shape. Sidecars should be indexed, searchable, available to advisor context, and repairable by project health checks. They should not print unless the author explicitly turns them into manuscript units. Chapter-note sidecars may also have a sibling note collection directory:

manuscript/act-a552eb2e/
  chapter-c3960842.notes.md
  chapter-c3960842.notes/
    embedded-ai-bonding-worldbuilding-approval.md
    note-2.md

The .notes.md file is the chapter-notes index. The .notes/ directory stores captured Editorial Board notes, related note cards, and other chapter-specific planning artifacts. These collection files remain author-readable Markdown and should move with their chapter notes sidecar when the manuscript unit moves. When a manuscript unit moves or is renamed, Scritorio should update known references that it owns or can safely patch:

sidecar front matter such as for, target, and target_path
note front matter such as linked_chapter
generated or legacy state references such as source_path
story.yml manuscript order entries
scritorio.project.json manifest paths and sort metadata
Scritorio-managed Markdown links that point to the moved file

If Scritorio cannot confidently rewrite a reference, it should leave the author text untouched and surface a repair warning instead of guessing.

Codex

codex/ stores local canon and style knowledge:

codex/
  characters/
  locations/
  organizations/
  items/
  concepts/
  events/
  style/

Most Codex entries are single Markdown files:

codex/items/skim-pod.md
codex/locations/vespera.md
codex/style/series-style-guide.md

Character creation can also use a folder shape when a character soul is present:

codex/characters/mara-vale/
  dossier.md
  soul.md

soul.md is voice and stance grounding for character chat. It is not a place for unreconciled canon that should contradict the dossier.

Supporting Folders

Path	Owner	Purpose
`notes/`	Author and app	General project notes and captured notes not tied to one manuscript unit.
`assets/`	Author and app	Images, references, generated assets, and local media.
`exports/`	App and author	User-facing export results such as preview PDFs.
`.scritorio/build/`	App	Generated preview/build intermediates. Safe to regenerate.
`state/`	Legacy/transitional	Older generated chapter or character state may appear in migrated projects. Current live context should prefer source manuscript and Codex files.

App Internals

.scritorio/ is app-owned local state:

.scritorio/
  index.sqlite
  ai-chat.sqlite
  settings.json
  layout-settings.json
  logs/
    app.jsonl
    ai-provider-requests.jsonl
  ai/
    provenance.jsonl
    usage.jsonl
  build/
    book-preview/
  manuscript-intelligence/

index.sqlite is rebuildable from Markdown and front matter. Chat databases, usage logs, provenance logs, provider request traces, and local settings are app state; they should not become the only copy of author manuscript content. Older migrated projects may also contain .colophon/. Scritorio can preserve and read legacy state where supported, but new app-owned state should live in .scritorio/.

Portability Rules

Use relative paths in front matter, manifests, links, and sidecars.
Preserve manuscript body text during repairs and migrations unless the author explicitly asks for prose edits.
Repair ordering and references by patching metadata first.
Keep generated caches rebuildable.
Keep author-facing content readable in any Markdown editor.

Compatibility And Upgrade Rules

Future Scritorio versions should be conservative with existing projects:

Preserve unknown files, folders, front matter keys, Markdown links, and manuscript body text.
Prefer additive metadata changes over structural rewrites.
Keep stable chapter id filenames through reorders and renumbering.
Use relative paths so projects can move between machines and folders.
Repair story.yml, manifest entries, and sidecar references from manuscript front matter where possible.
Require explicit author confirmation for destructive cleanup, broad renames, or migrations that rewrite many author-owned files.
Reject or warn on newer unsupported schema versions instead of guessing.
Record path mappings during migrations so open documents, sidecars, notes, and manifests can be remapped consistently.
Treat .scritorio/index.sqlite, generated intelligence files, and .scritorio/build/ output as rebuildable, not canonical author content.

Scritorio

​Book Filesystem Layout

​Book Root

​File Classes

​Root Files

​Metadata Precedence

​Manuscript

​Manuscript Units

​Planning Sidecars

​Codex

​Supporting Folders

​App Internals

​Portability Rules

​Compatibility And Upgrade Rules