OpenWriterControle/novel/docs/SCHEMA.md

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.

# 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"

# 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

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

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

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.

# Plot — <series title>

> 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 — <title>
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):

---
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.