FAQ

FAQ

Reference. For players, Game Masters, and builders. Common problems and their solutions. If your question isn't here, open an issue. See Glossary for unfamiliar terms.

Setup

My MCP client doesn't see the server tools

1. Check the path in your client config. The cwd field must point to the holonovel/ directory — an absolute path, not relative.
2. Check that npm install completed without errors.
3. Restart your MCP client. The server logs handshake details on startup — check your client's connection logs.
4. Verify the server starts: cd holonovel && npx tsx src/index.ts. It should print connection info.

"Cannot find module" or import errors

Run npm install in the holonovel/ directory. All dependencies are listed in package.json.

I get "command not found: npx" or "command not found: tsx"

You need Node.js 20 or newer. node --version to check. Get it at nodejs.org. npx ships with Node. tsx is installed by npm install.

Playing

My character disappeared

Characters in the roster are permanent. Characters imported into a Novel live in that Novel. If you started a new Novel, import your character again:

"Import my fighter from the roster."

If you ended the Novel without exporting, the Novel file is in .trash/ with a configurable retention period (default: 30 days). Move it back to restore.

I can't switch badges

Badges require an active Novel. If you haven't created one:

"Start a new game called My Campaign."

If a workflow is pending (e.g., character creation), complete or cancel it first:

"Cancel character creation."

My dice roll seems wrong

Every roll shows its work — die faces, modifiers, target. Check the output. If the modifier looks wrong, check your character sheet:

"Show me my character sheet."

If the seed is deterministic (same seed = same result), verify you're not reusing a seed from an earlier roll.

The AI narrated something mechanically impossible

This shouldn't happen — the pre-narration validation gate intercepts mechanically impossible narration before you see it. If you do see one, it's a spec violation. Report it as a bug. The engine should have rejected it.

How do I export my campaign?

"Export my Novel."

Your Novel exports as JSON or Markdown. Export creates a complete snapshot — characters, NPCs, scenes, lore, combat state, world model, story journal. Import it on another machine with manage_novel (action: import). See Novels for the full lifecycle.

I'm in observer mode. What can I do?

The observer badge lets the AI play both Player and Game Master while you watch. You have read-only access to the Novel. You can step in for mechanical decisions at your configured autonomy level. See Badges for the four badges and what each enables.

Game Mastering

My lore entry isn't triggering

1. Check the triggers match the scene text exactly (case-insensitive, word boundaries respected).
2. Check the entry is enabled: manage_lore (action: toggle) may have disabled it.
3. Check the token budget: if lore entries exceed TTRPG_MAX_LORE_TOKENS, low-priority entries are omitted. manage_session (action: health) reports suppression counts.
4. Check badge scope: game_master entries don't appear in Player badge briefing.

Combat state was lost after restart

Combat state should survive restarts. If it didn't:

1. Check that TTRPG_NOVEL is set to the correct Novel slug.
2. Check manage_session (action: health) for corruption warnings — a corrupt state file triggers structured recovery (auto-restore from .bak).
3. If both primary and backup are corrupt, the server reports which keys could not be parsed. Export what you can, start a fresh Novel, and re-import.

Source: REQ-065, REQ-092.

My countdown didn't fire

Check the countdown direction and tick type. Round countdowns only decrement on manage_combat (action: advance). Narrative countdowns decrement on scene transitions (if on_scene_transition is set) or on manage_countdown (action: advance).

Expired countdowns are removed from the active set — they don't tick again. Create a fresh countdown with the same name.

Source: REQ-073, REQ-125.

How does World in Motion work?

The engine autonomously advances faction agendas and NPC goals between scenes. You see proposed changes in the World in Motion section of your GM briefing. Accept them all, modify individual proposals, or defer everything. The engine never changes state without your approval — it proposes, you decide.

Source: REQ-233a.

How does Campaign Memory differ from lore?

Campaign Memory is automatic — the engine records facts from your tool calls (creating NPCs, setting scenes, advancing combat) without you doing anything. Lore is manual — you create entries with specific triggers for specific moments. Campaign Memory gives you a searchable record of "what actually happened." Lore gives you "what you want to remember at key moments."

Source: REQ-310, REQ-083.

I want to reuse an NPC from another campaign

Capture them to the Codex — a server-level library that survives all Novels:

"Save this NPC to the Codex."

Then import them into any Novel:

"Import the Thieves Guild from the Codex."

Codex entries carry ruleset tags so a D&D NPC won't accidentally load into the wrong system. See Codex for the full reference.

How do I get GM advice for my campaign?

Synthesis adds community GM advice, lore templates, and action patterns to your server. Inert by default — you activate it:

"Run Synthesis. Focus on dungeon design."

Three tiers: Ruleset Wisdom (vendor content), External Synthesis (web research), Internal Synthesis (generated from your Novel state). Each tier independently removable. See Synthesis.

I want to add an enemy mid-combat

"A third goblin bursts through the door. Add them to combat."

Participants can join and leave combat without ending the encounter. The turn order adjusts automatically. See Combat for running encounters.

Building

The build keeps failing in the convergence loop

1. Check RULESET_MODEL.md for defect log entries — low-confidence extractions are flagged there.
2. The viability pre-check may have warned about low mechanical density (below 30% of sections). Try a different source or a more structured ruleset.
3. Check DECISIONS.md for the specific convergence metrics that failed. Each failure maps to a metric — the Pattern Buffer handshake sends failures back into Phase 2 for targeted correction.
4. If production mode is struggling, try quick mode for inner-loop iteration. It skips assumption audits and cross-model audits but still gates on the Pattern Buffer.

Source: spec §6.3, §6.5, §6.6.

The Pattern Buffer fails with "no improvement"

After two stalled Pattern Buffer iterations (total failures not decreasing, no blocking scenario downgraded), the builder stops. Residual failures are logged in DECISIONS.md. Blocking failures must be resolved — the build is incomplete until they pass. Non-blocking failures are accepted limitations.

Source: spec §6.6 (exit criteria).

See also

• Getting Started — setup walkthrough
• Badges — the four badges explained
• Combat — running combat encounters
• Glossary — every Holonovel term defined
• Character Creation — building your character

Last updated: 2026-10-12.