# OpenNovelWriter — SCHEMA > **Canonical reference** for the OpenNovelWriter ecosystem. > These conventions apply to ALL authors and projects — not just a single book. > The `OpenNovelAgent` loads this document to handle structure, filenames, and data formats correctly. --- ## 1. Project Structure **Concept: one container vault, one folder per book.** A single Obsidian vault (e.g. "Novels") holds every book. Each book is a subfolder and *is* the workspace you open opencode in. The agent pack lives **once**, at the vault root, and is inherited by every book — a book never carries its own `.opencode/`. The canonical `docs/SCHEMA.md` likewise exists once, at the vault root. ``` Novels/ # the container vault (Obsidian) ├── .opencode -> /Users/Shared/NovelPack/.opencode # ONE shared agent pack ├── docs/ -> /Users/Shared/NovelPack/docs # canonical SCHEMA.md ├── AGENTS.md # house rules that apply to every book ├── Scruffy/ # a BOOK = a workspace │ ├── AGENTS.md # this book's metadata and rules │ ├── DATA/ # this book's world │ │ ├── wiki.yaml.md # world wiki (canonical) │ │ ├── timeline.yaml.md # timeline (lore history + plot) │ │ ├── glossary.yaml.md # translation glossary │ │ ├── plot.md # the story baseline: main line + side stories │ │ └── style.md # the author's writing style │ ├── 01/ # Book 1 (folder = number, title optional) │ │ ├── DE/ # language folder (ISO-639-1 code) │ │ │ ├── Kapitel 001.md │ │ │ └── ... │ │ ├── EN/ │ │ │ ├── Chapter 001.md │ │ │ └── ... │ │ └── images/ # illustrations for this book │ │ ├── prompts/ # image prompts (Markdown, one per image) │ │ └── generated/ # generated image files │ └── 02/ # Book 2 of the same series └── Kessler/ # another book — same shape, own AGENTS.md + DATA/ ``` ### Multiple books in parallel Each book is a **separate folder inside the one vault**. opencode is always started *inside* the book folder; it finds the shared pack by walking up to the vault root, so books never duplicate the agents. The `OpenNovelAgent` is identical everywhere — what makes a workspace "the Scruffy book" vs. "the Kessler book" is its own `AGENTS.md` + `DATA/`. Switch books by switching folders; never put two books in one folder. (If several books live in one vault and a book needs to be verifiable on its own, make the *book folder* a git repository — not the vault.) ## 2. Naming Conventions | Element | Rule | Example | |---------|------|---------| | **Book folder** | number (2-digit), title optional | `01` → later `01 - Der Dieb im Eulental` | | **Language folder** | ISO-639-1 code (code only) | `DE`, `EN`, `PT` | | **Chapter file** | localized chapter word + 3-digit number | `Kapitel 001.md` | | **Chapter number** | 3 digits, zero-padded | `001` … `100` | | **DATA files** | fixed English names | `wiki.yaml.md`, `timeline.yaml.md`, `glossary.yaml.md`, `plot.md` | **Chapter word per language** (defined in `.opencode/languages.yaml`): - `de` → `Kapitel` - `en` → `Chapter` - `pt` → `Capítulo` - (the community can add more languages) **Important:** language folder names are ALWAYS the code (`DE`), never spelled out. Chapter files use the *localized* word. --- ## 3. Data Format: YAML inside `.md` code blocks All DATA files are `.yaml.md` files: Markdown files whose content is a ` ```yaml ` code block. ```markdown # Title (optional, human-readable) ```yaml meta: title: "..." ``` ``` **Why:** Obsidian renders the code block cleanly; the AI assistant strips the ` ```yaml ` markers and reads the content as pure YAML. --- ## 4. Key Language: English, Values: localized **Canonical rule:** YAML **keys** are always English and stable. YAML **values** are in the author's canonical language. ```yaml # CORRECT — keys English, values German characters: - name: "Leah Kessler" role: "Hauptcharakter" ``` ```yaml # WRONG — localized keys (breaks the schema) characters: - name: "Leah Kessler" Rolle: "Hauptcharakter" ``` **Reason:** the agent parses keys reliably regardless of the canonical language. An author in Spain uses the same schema; only the values are Spanish. --- ## 5. DATA File Schemas ### 5.1 `wiki.yaml.md` — World Wiki ```yaml meta: title: "" # series title author: "" # author canonical: "" # ISO-639-1 (writing language) languages: [] # publication languages genre: "" audience: "" concept: {} # premises, series ideas (keys are free-form) characters: [] # people locations: {} # places magic: {} # magic system, spells, creatures ``` ### 5.2 `timeline.yaml.md` — Timeline ```yaml history: # lore history (world background, beyond the plot) - date: "" # ISO date OR free text (e.g. "1268-12", "long ago") event: "" story: # plot events (the fictional present) - date: "" # e.g. "2011-08" book: 1 # optional, when multiple books chapter: 13 # optional event: "" ``` **Rule:** `history` = world background (e.g. a dragon hatches in 1268). `story` = plot progression (e.g. the 2011 school year). Both live in ONE file. ### 5.3 `glossary.yaml.md` — Translation Glossary ```yaml terms: - de: "" # canonical term en: "" # translation (or missing) # pt: "" # more languages as additional keys ``` **Rule:** a term is defined ONCE and used consistently throughout the story. The `ContinuityEditor` checks translations against this glossary. --- ### 5.4 `plot.md` — the Story Baseline The one DATA file that is **prose, not YAML**. It carries the author's own telling of the story — the spine that both author and agent build around — and an explicit register of the side stories that weave around it. ```markdown # Plot — > Baseline = the author's telling. It is the *main line*, not the whole story: > side stories, subplots and new characters are expected and MUST be recorded here, > or they are invisible to the agent. ## 1. Backbone — what must happen ### Book 1 — 1. beat … 2. beat … ## 2. Side stories (register) | thread | whose story | spans | status | |---|---|---|---| | … | … | book 1–2 | planned / placed / written | ## 3. Baseline telling (verbatim, dated) Paste the transcription here, newest first. Never delete an older telling. ## 4. Deviations — where the written novel left the baseline ## 5. Open threads / unresolved questions ``` **Rules** 1. **Hierarchy:** `plot.md` is *intent* (what should happen), the manuscript is *realised* (what is written), `Notizen/`/`wiki.yaml.md` is *detail canon*. On conflict, the agent **reports** rather than silently picking; the author rules per case. 2. **The telling is verbatim material.** Spoken word transcribed by a note app is full of errors, especially in invented names. Keep it as it came — it is the author's voice — but when anything from it is *used*, normalise names against `wiki.yaml.md` and the glossary first. 3. **Side stories are first-class.** A thread that is not in the register does not exist as far as the agent is concerned. Add it the moment it is invented. 4. **Never delete a telling.** Re-recordings are appended as new dated sections; the older one is history and shows how the story grew. --- ## 6. Chapter Conventions - One `.md` file per chapter. - First line: `# [Chapter word] NNN - Title` (localized chapter word). - Prose follows `style.md` (the author's voice). - Numbers written out in prose, if `style.md` dictates it. --- ## 7. Images & Illustrations Each book has an `images/` folder for illustrations. The `Illustrator` subagent handles image generation. ``` 01/images/ ├── prompts/ # one .md per image — the prompt + metadata └── generated/ # the actual image files (png/jpg/webp) ``` **Prompt file convention** (`images/prompts/NNN - description.md`): ```markdown --- chapter: 006 # optional — which chapter the image illustrates character: "Scruffy" # optional — subject(s) status: draft # draft | approved | generated --- The image prompt (written in the author's language) that was sent to the image generator, plus a short note on why this image matters to the story. ``` **Rules:** - Prompts are derived from the **wiki** (character appearance, locations) so images stay consistent with the story. - The `Illustrator` is a *subagent* — `OpenNovelAgent` delegates image requests to it, it does not interrupt the author. - Generated files land in `images/generated/`, named to match their prompt file. --- ## 8. The Co-Authoring Cycle ``` Author: "next chapter: X should happen" ↓ Agent loads: AGENTS.md + DATA/ (wiki, timeline, glossary, style) + previous chapter summary ↓ Agent proposes a chapter draft (beats, POV, ~length) → author approves ↓ Agent writes the chapter → author reads/edits in Obsidian ↓ Agent harvests new facts (characters, events) → updates wiki.yaml.md / timeline.yaml.md ``` --- ## 8. Context-Window Strategy (long works) - **Always loaded:** `AGENTS.md`, `style.md`, the `meta:` block, current chapter outline + previous chapter summary. - **On-demand (RAG):** remaining wiki entries, specific spells/places — load only when the chapter touches them. - **Never** read the whole manuscript at once — reference it via `timeline.yaml.md` (summaries). --- ## 9. Temperature Policy (creativity vs. hallucination) Temperature is set **per agent role**, not once for the whole system. The principle: creative agents run hot (imagination), verification agents run cold (accuracy). | Agent | Role | Temp | Rationale | |-------|------|------|-----------| | `OpenNovelAgent` | Creative drafting | **0.8** | Imagination — the "write prose" brain | | `Illustrator` | Image prompt/creation | 0.7 | Creative visual, but grounded in wiki | | `PlotArchitect` | Plot structure | 0.6 | Creative but coherent | | `CharacterDeveloper` | Character depth | 0.6 | Creative | | `Translator` | Translation | 0.4 | Fidelity first, some idiom | | `StyleAnalyst` | Voice extraction | 0.2 | Pattern-finding, not inventing | | `Importer` | Migration/extraction | 0.2 | Faithful reconstruction, not invention | | `StoryReviewer` | Editorial quality review | 0.3 | Constructive critique, report-only | | `LineEditor` | Word choice / naturalness | 0.3 | Catch semantic errors grammar misses | | `ContinuityEditor` | Fact/consistency check | **0.1** | Hallucination freedom — like a code reviewer | | `Proofreader` | Grammar/spelling | 0.1 | Mechanical precision, no restyling | | `CopyrightWatchdog` | Copyright-risk check | 0.1 | Flag expression, not ideas; report-only | | `StoryRetriever` | Retrieval/search | 0.1 | Accurate lookup, no creativity | **Why this works:** the hot agent invents the prose; the cold agent verifies it (catches contradictions — changed eye color, timeline breaks). This is the same "generator hot / reviewer cold" split as code agents, applied to fiction. Each agent's temperature lives in its own frontmatter and can be tuned per author. --- ## 10. Versioning The project directory is a Git repository. Every chapter approval = a commit. This enables rollback and community collaboration.