Reference. For Game Masters and players. A Novel is your entire campaign in one file — party, NPCs, scenes, lore, combat state, world model, story journal, factions, secrets, everything. This page covers the full Novel lifecycle.

---

A Novel is a structured save file at .holonovel-state/novels/<slug>.json. It is not a chat log — every property group is typed, validated, and checksummed against corruption. A Novel survives server restarts, process crashes, and full rebuilds. You can export it, share it, clone it, and import it into a different machine.

Multiple Novels coexist on one server. One is active per connection. Novels are isolated — state from one Novel never leaks into another.

"Start a new game called the Dragon Tomb." "Switch to my Ravenloft campaign." "Resume the Sunken Temple game."

---

"Start a new game called the Dragon Tomb."

Creates a Novel file on disk. The Novel starts in the Editor badge — full access to all tools. You can create characters, load an adventure, build the world, and set up lore before the story begins.

The Novel slug is derived from the name (lowercased, whitespace to hyphens, punctuation stripped). You'll use this slug with manage_novel (action: resume) and manage_novel (action: switch).

"Resume the Dragon Tomb game."

Loads a previously created Novel from disk. The Novel resumes in whatever state it was in — same badge, same scene, same combat round, same conditions. If a Novel was paused via manage_novel (action: save_context), resume returns exactly the pause context:

"You were in round 4 of combat with the goblins. Sister Mora was about to reveal the High Priest's betrayal."

"Switch to my Ravenloft campaign."

Changes the active Novel for the current connection. The previous Novel's state is saved to disk. The new Novel loads. Badge state carries over — if you were in the Player badge, you remain in the Player badge after switching.

"What game are we in?" "Switch to Dragon Tomb." "Switch back to Ravenloft."

"Clone the Dragon Tomb as 'Dragon Tomb — Branch'."

Creates an identical copy of the Novel under a new slug. Use this to test story branches without corrupting the main campaign. The clone starts in the Editor badge — activate a badge when ready.

"End the Dragon Tomb game."

Ending a Novel moves the save file to .holonovel-state/.trash/<slug>.json with a configurable retention period (default: 30 days). Nothing is permanently deleted unless you want it to be. Move the file back to .holonovel-state/novels/ to restore it before the retention period expires.

"Are you sure? Type 'yes, end the Dragon Tomb' to confirm."

Ending requires explicit confirmation. Accidental ending is guarded against.

---

"Export the entire campaign as Markdown." "Export the campaign as JSON."

Export produces a single file containing every character, NPC, scene, lore entry, countdown, faction, relationship, and combat state. Two formats:

• JSON — machine-readable, complete. Every field present.
• Markdown — human-readable, round-trippable. Metadata embedded in HTML comments. Suitable for reading, sharing, and re-importing.

Round-trip fidelity is guaranteed: manage_novel (action: export) → manage_novel (action: import) produces a Novel indistinguishable from the source.

"Import this campaign." (paste exported content)

Three modes:

Mode	Behavior
dry-run	Validate the import without changing state. Reports conflicts, duplicates, what would change.
merge	Add entries. Skip conflicts (entries with matching keys). Existing entries unchanged.
replace	Overwrite the entire Novel. All existing state is replaced.

Import auto-detects JSON vs. Markdown format.

"Export the lorebook as Markdown." "Import this lorebook into the Dragon Tomb."

Lorebooks are keyword-triggered lore collections — the worldbuilding you carry between campaigns. Export produces a portable file of lore entries without mechanical state (no HP, conditions, or combat position). Import with dry-run, merge, or replace. See spec Appendix L for the full format reference.

---

Checkpoints let you save the Novel's state before a pivotal moment and restore it if things go wrong.

"Set a checkpoint: before the vault door." "List checkpoints." "Restore checkpoint: before the vault door." "Delete checkpoint: before the vault door."

Multiple checkpoints per Novel. Each checkpoint is a named snapshot. Restoring a checkpoint replaces the current Novel state with the checkpoint's state — the current state is lost. Checkpoints survive server restarts.

---

Notes attach GM-scoped text to the Novel. They are key-value pairs — a label and content. Notes survive restarts and rebuilds.

"Make a note: the High Priest's weakness is silver. The party hasn't discovered this yet." "Show me my notes." "Remove the note about the High Priest."

Notes are badge-scoped per REQ-242: GM-only notes are invisible to the Player badge. Server notes (REQ-285) are a separate key-value store that survives Novels and rebuilds — use those for cross-campaign information.

---

Pause mid-session and return to the exact same state:

"Save my place for later."

The engine records the current scene, active badge, combat round and turn, active conditions, pending countdowns, and the pause timestamp. The Novel sleeps until you return.

"Resume my game."

The AI greets you with the pause context — where you were, what was happening, what was about to happen. You're back in the same moment.

---

Every state change is recorded in the Novel's audit log — a timestamped, sequenced history of every mutation. The audit log is the Novel's forensic record.

Entries include:

• Badge switches (when and to which badge)
• Scene changes (description, location, time of day, atmosphere)
• NPC creation, updates, and removal
• Lore entry creation, updates, and toggling
• Combat lifecycle (init, participant changes, advance, end)
• Countdown creation, advancement, and expiry
• Character creation, import, and export
• Checkpoint operations
• Errors (state conflicts, corruption events, recovery actions)
• Tool calls with parameters and outcomes

The audit log is compressed periodically to keep it manageable:

"Summarize the audit log."

Compression produces a condensed narrative of the last N entries, preserving critical events (character death, major discoveries, faction standing changes) while collapsing routine operations (condition expiry, countdown ticks).

---

"How's the Dragon Tomb looking?"

Reports per-Novel metrics:

Metric	What it measures
NPC count	Total named NPCs in the Novel
Lore count	Total lore entries (enabled + disabled)
Audit log size	Number of uncompressed audit entries
Snapshot depth	Undo stack levels per badge
File size	Size of the Novel file on disk
Corruption status	Whether the file passed integrity checks
Healthy flag	true if all checks pass

If corruption is detected, manage_session (action: health) reports which property groups failed validation and whether auto-recovery from .bak succeeded.

---

A Novel is designed to survive everything.

Server restarts. All Novel state is on disk. Restart the server, resume the Novel — same scene, same combat round, same conditions.

Server rebuilds. Rebuilding the server (new spec version, new extraction) doesn't touch Novel files. The Novel loads into the new server. State that references ruleset content (conditions, spells) is validated against the new index — mismatches are reported but don't block loading.

Corrupted files. Every save operation writes atomically — the new state is written to a .bak file, validated, then atomically renamed over the primary. If validation fails, the .bak is discarded and the primary is untouched. On load, if the primary fails validation, the engine falls back to the .bak. If both are corrupt, the engine reports which keys could not be parsed and offers structured recovery — export what you can.

---

Last updated: 2026-10-12.