holonovel

<!--
README DESIGN:

  Product principle.
    The README answers three questions for three readers, each in under
    60 seconds: an operator gets a running server, an evaluator
    understands what it does and how it differs, a contributor finds how
    to help. It is a design document, not an afterthought. Every section
    earns its place.

  Scannability.
    Engineers scan, don't read. Consistent heading hierarchy (ATX only,
    no setext). No wall of prose — every section is broken into
    digestible paragraphs. One story vector per section.

  Voice.
    Punchy, reserved, grounded in fact. Direct address ("you"). No
    first-person ("we", "I", "our"). Professional without being cold.
    No "obvious to me" assumptions — every sentence survives a reader
    who knows nothing about the project.

  Plain English (Standing Rule 10).
    Describe what the user does, not what the tool is called. Write as
    if instructing a person, not documenting an API. Tool names,
    parameter shapes, and technical syntax SHALL NOT appear in prose.
    The validator enforces this.

  Structure.
    Orientation → Table of contents → Run a server (§1) → How it works
    (§2) → How it compares (§3) → Footer. No other
    ordering. Section headings use canonical numbering (§1–§3) matching
    the TOC and cross-reference links. The TOC is a bulleted list of
    every h2 and h3 heading with Markdown anchor links, each h2 entry
    tagged by audience. It does not link to itself or the Orientation.

  Audience split.
    §1 is for operators who want a server now — one copy-paste
    quick-start sequence, plus installing rulesets. §2
    describes capabilities to an evaluator. §3 is the competitive
    landscape — one row per competitor category.

  Orientation.
    Exactly four elements: h1 heading, bold tagline on its own line,
    the MCP server card badges (below the tagline), one prose paragraph
    (≤80 words). The paragraph defines "holonovel"
    as a Star Trek holodeck program. States what Holonovel builds (the
    server, the Holodeck), what a campaign becomes (the program, the
    Novel), and what rulebooks become (the engine). Names D&D 5e and
    Starfinder as example rulesets the spec can build. Closes with
    "Your books. Your server. Your Holodeck."

  Table of contents.
    Bulleted list of every h2 and h3 heading with Markdown anchor links.
    Appears between the Orientation and §1. Each h2 entry carries a
    trailing audience tag — operators or evaluators —
    outside the link. h3 entries are untagged. No prose, no descriptions.
    The validator enforces TOC-to-heading consistency.

  Run a server (§1).
    Two h3 subsections. No introductory prose under the h2.
    Install: one descriptive sentence, prerequisite (Node.js 24+), shell
    code block for install, and copy-paste JSON config block with
    `<path>` placeholder.
    Install a ruleset: drop-in packages, lazy loading, and the
    state-directory location.
    Config blocks use `json` language tag. Shell blocks use `sh`.
    No blockquotes, no tool names in prose.

  How it works (§2).
    One introductory h2 sentence (≤50 words) naming the pipeline, then
    five stages — Convert → Build → World → Novel → Synthesis. Each
    stage follows this format:
      1. What-it-is paragraph — defines the capability conceptually.
      2. What-you-can-do paragraph — describes player/GM capabilities.
      3. Demo blockquote — 2–5 natural-language prompts, each a
         self-contained sentence valid on the holonovel MCP server.
      4. Closing takeaway — one factual sentence, not a slogan.
    Badge enforcement is not a stage — it is a cross-cutting runtime
    layer, described once inside Novel. No forward references between
    stages. Each stage is readable independently.

  Five stages (§2).
    Convert (rulebooks → clean Markdown) and Build (Markdown → a
    declarative ruleset package) carry the Convert/Build claims.
    World (the spatial model) covers rooms, things, exits, containment.
    Mentions Inform exactly once.
    Novel (the campaign object) covers scenes, NPCs, lore, factions,
    secrets, journal, and the badge settings Player / Game Master /
    Observer / Editor. Badges are Novel-scoped; enforcement runs
    server-side.
    Synthesis (the game evolving) distinguishes Ruleset Wisdom from
    external research.

  Badge terminology.
    The canonical term is "badge," not "hat." Badges are Novel-scoped:
    each Novel has its own active badge. Enforcement runs server-side.
    Four settings: Player, Game Master, Observer, Editor. Player and GM
    are "in the story." Observer is in the story. Editor (none) is out
    of the story.

  Comparison table (§3).
    h2 heading, no introductory prose. Three columns (Category | What
    you're used to | How Holonovel differs). Three rows, one per
    competitor category — AI storytelling apps, generic LLM chat, and
    first-generation rules MCP servers. Never individual products. One
    closing prose paragraph (≤80 words) states the gap and names D&D 5e
    and Starfinder.

  Refrain contract.
    "Your books. Your server. Your Holodeck." appears once, in the
    Orientation paragraph. The word "Holodeck" appears in the tagline
    and the refrain as the product's central metaphor. Additional prose
    uses are permissible where the metaphor drives meaning.

  License footer.
    Canonical-origin line, project-wiki link, then three attribution
    lines: MIT, sources (Inform, four narrative
    frameworks), Inform credit. RSS link. "Last updated: YYYY-MM-DD."
    Date matches package.json version date. Update both or neither.

  Demo prompt maintenance.
    Every prompt in a demo blockquote SHALL be a valid natural-language
    command on the holonovel MCP server. The author SHALL verify all
    prompts after any tool or capability change. Broken prompts are a
    README defect.

  Blockquote convention.
    Blockquotes appear only in §2 stage subsections. No other section
    uses blockquotes. Each blockquote contains 2–5 natural-language
    prompts, each a self-contained sentence. No tool names, no parameter
    shapes, no function signatures — exactly what the user would say
    or type.

  Table convention.
    Exactly one table: the comparison table (§3). No other tables. No
    tables in prose. Pipe-delimited Markdown. No inline formatting beyond
    bold. Column widths are author-managed.

  No repetition.
    One story vector per section. Don't explain the same concept in two
    different places. The validator detects near-duplicate sentences.
    No bullet lists of features in prose. No tables for feature
    descriptions.

  Future targets.
    The Orientation and §3 closing prose name D&D 5e and Starfinder as
    example rulesets. No Mothership appears anywhere in the document.

  Non-goals.
    The README is not an API reference, a tool catalog, a spec document,
    or a changelog. It does not enumerate tools or parameters. It does
    not describe implementation details. It does not repeat information
    found in CHANGELOG.md, AGENTS.md, or holonovel.md.

  Word budget.
    Total prose ≤ 1,500 words (excludes code blocks, config JSON,
    tables, blockquotes, TOC, and footer). Orientation ≤ 80 words. §3
    closing prose ≤ 80 words. The validator enforces the 1,500-word cap.

  Validator.
    All rules marked "The validator enforces" SHALL be checked by
    scripts/validate-readme.ts. Rules without mechanical enforcement
    are maintained by author discipline. Adding an enforceable rule
    requires a corresponding validator check.

  Readme-driven development.
    The README is the first artifact of the repo. Changes that affect
    the README's claims SHALL update the README before or alongside the
    code change. A README that promises something the server does not
    deliver is a defect.
-->

# Holonovel

**The Holodeck for your rulebooks — rules enforced, worlds remembered.**

[![holonovel MCP server](https://glama.ai/mcp/servers/flukeatzerocool/holonovel/badges/card.svg)](https://glama.ai/mcp/servers/flukeatzerocool/holonovel)

[![M8ven Live Monitored](https://m8ven.ai/badge/mcp/flukeatzerocool-holonovel-1n5aoa)](https://m8ven.ai/mcp/flukeatzerocool-holonovel-1n5aoa)

A *holonovel* is a Star Trek holodeck program — an interactive story where you
step inside as a character and the rules govern. Holonovel builds the server (the
Holodeck). Your campaign is the program (the Novel). Your rulebooks become the
engine — D&D 5e, Starfinder, or the game on your shelf. Your books. Your server.
Your Holodeck.

## Table of contents

- [Run a server](#run-a-server) — operators
  - [Install](#install)
  - [Install a ruleset](#install-a-ruleset)
- [How it works](#how-it-works) — evaluators
  - [Convert](#convert)
  - [Build](#build)
  - [World](#world)
  - [Novel](#novel)
  - [Synthesis](#synthesis)
- [How it compares](#how-it-compares) — evaluators

## Run a server

### Install

The base server — a world-model MCP with rooms, things, exits, parser commands,
narrative tools, and out-of-the-box mechanics from Fate, Ironsworn, and Blades in
the Dark (Fudge dice, momentum, and stress tracks, no ruleset required). Install
it, then install any number of ruleset packages — each drops in alongside the
base and never modifies it. Node.js 24+ required.

```sh
cd holonovel
npm install
npm run start
```

On first start the server seeds a ruleset-free tutorial Novel, **Torre Nosferatu**,
so a fresh install is immediately playable with no ruleset; set
`TTRPG_STARTER_NOVEL=off` to skip it.

Add to your MCP client:

```json
"holonovel": {
  "type": "local",
  "command": ["npx", "tsx", "src/index.ts"],
  "cwd": "<path>/holonovel",
  "environment": {
    "TTRPG_NOVEL": "default"
  },
  "enabled": true
}
```

### Install a ruleset

The Build workflow turns a rulebook into a declarative package. Drop the package
into the server's ruleset install directory and the running server registers it.
That di