{
  "markdown": "<!--\nREADME DESIGN:\n\n  Product principle.\n    The README answers three questions for three readers, each in under\n    60 seconds: an operator gets a running server, an evaluator\n    understands what it does and how it differs, a contributor finds how\n    to help. It is a design document, not an afterthought. Every section\n    earns its place.\n\n  Scannability.\n    Engineers scan, don't read. Consistent heading hierarchy (ATX only,\n    no setext). No wall of prose — every section is broken into\n    digestible paragraphs. One story vector per section.\n\n  Voice.\n    Punchy, reserved, grounded in fact. Direct address (\"you\"). No\n    first-person (\"we\", \"I\", \"our\"). Professional without being cold.\n    No \"obvious to me\" assumptions — every sentence survives a reader\n    who knows nothing about the project.\n\n  Plain English (Standing Rule 10).\n    Describe what the user does, not what the tool is called. Write as\n    if instructing a person, not documenting an API. Tool names,\n    parameter shapes, and technical syntax SHALL NOT appear in prose.\n    The validator enforces this.\n\n  Structure.\n    Orientation → Table of contents → Run a server (§1) → How it works\n    (§2) → How it compares (§3) → Contribute (§4) → Footer. No other\n    ordering. Section headings use canonical numbering (§1–§4) matching\n    the TOC and cross-reference links. The TOC is a bulleted list of\n    every h2 and h3 heading with Markdown anchor links, each h2 entry\n    tagged by audience. It does not link to itself or the Orientation.\n\n  Audience split.\n    §1 is for operators who want a server now — one copy-paste\n    quick-start sequence, plus installing and building rulesets. §2\n    describes capabilities to an evaluator. §3 is the competitive\n    landscape — one row per competitor category. §4 is for contributors.\n\n  Orientation.\n    Exactly four elements: h1 heading, bold tagline on its own line,\n    the MCP server card badge (below the tagline), one prose paragraph\n    (≤80 words). The paragraph defines \"holonovel\"\n    as a Star Trek holodeck program. States what Holonovel builds (the\n    server, the Holodeck), what a campaign becomes (the program, the\n    Novel), and what rulebooks become (the engine). Names D&D 5e and\n    Starfinder as example rulesets the spec can build. Closes with\n    \"Your books. Your server. Your Holodeck.\"\n\n  Table of contents.\n    Bulleted list of every h2 and h3 heading with Markdown anchor links.\n    Appears between the Orientation and §1. Each h2 entry carries a\n    trailing audience tag — operators, evaluators, or contributors —\n    outside the link. h3 entries are untagged. No prose, no descriptions.\n    The validator enforces TOC-to-heading consistency.\n\n  Run a server (§1).\n    Three h3 subsections. No introductory prose under the h2.\n    Install: one descriptive sentence, prerequisite (Node.js 20+), shell\n    code block for install, and copy-paste JSON config block with\n    `<path>` placeholder.\n    Install a ruleset: drop-in packages, lazy loading, and the\n    `.holonovel-state/` location.\n    Build your own rulebook: the build-ruleset entry point.\n    Config blocks use `json` language tag. Shell blocks use `sh`.\n    No blockquotes, no tool names in prose.\n\n  How it works (§2).\n    One introductory h2 sentence (≤50 words) naming the pipeline, then\n    five stages — Convert → Build → World → Novel → Synthesis. Each\n    stage follows this format:\n      1. What-it-is paragraph — defines the capability conceptually.\n      2. What-you-can-do paragraph — describes player/GM capabilities.\n      3. Demo blockquote — 2–5 natural-language prompts, each a\n         self-contained sentence valid on the holonovel MCP server.\n      4. Closing takeaway — one factual sentence, not a slogan.\n    Badge enforcement is not a stage — it is a cross-cutting runtime\n    layer, described once inside Novel. No forward references between\n    stages. Each stage is readable independently.\n\n  Five stages (§2).\n    Convert (rulebooks → clean Markdown) and Build (Markdown → a\n    declarative ruleset package) carry the Convert/Build claims.\n    World (the spatial model) covers rooms, things, exits, containment.\n    Mentions Inform exactly once.\n    Novel (the campaign object) covers scenes, NPCs, lore, factions,\n    secrets, journal, and the badge settings Player / Game Master /\n    Observer / Editor. Badges are Novel-scoped; enforcement runs\n    server-side.\n    Synthesis (the game evolving) distinguishes Ruleset Wisdom from\n    external research.\n\n  Badge terminology.\n    The canonical term is \"badge,\" not \"hat.\" Badges are Novel-scoped:\n    each Novel has its own active badge. Enforcement runs server-side.\n    Four settings: Player, Game Master, Observer, Editor. Player and GM\n    are \"in the story.\" Observer is in the story. Editor (none) is out\n    of the story.\n\n  Comparison table (§3).\n    h2 heading, no introductory prose. Three columns (Category | What\n    you're used to | How Holonovel differs). Three rows, one per\n    competitor category — AI storytelling apps, generic LLM chat, and\n    first-generation rules MCP servers. Never individual products. One\n    closing prose paragraph (≤80 words) states the gap and names D&D 5e\n    and Starfinder.\n\n  Refrain contract.\n    \"Your books. Your server. Your Holodeck.\" appears once, in the\n    Orientation paragraph. The word \"Holodeck\" appears in the tagline\n    and the refrain as the product's central metaphor. Additional prose\n    uses are permissible where the metaphor drives meaning.\n\n  Contribute (§4).\n    One h3 subsection — Improve the spec. No introductory prose under\n    the h2. Prerequisite sentence, four-row commands table, closing\n    assemble sentence, canonical-origin note, project-wiki link. No\n    duplicated instructions from §1. License footer follows immediately\n    — no heading.\n\n  License footer.\n    Three attribution lines: MIT, sources (Inform, four narrative\n    frameworks), Inform credit. RSS link. \"Last updated: YYYY-MM-DD.\"\n    Date matches package.json version date. Update both or neither.\n\n  Demo prompt maintenance.\n    Every prompt in a demo blockquote SHALL be a valid natural-language\n    command on the holonovel MCP server. The author SHALL verify all\n    prompts after any tool or capability change. Broken prompts are a\n    README defect.\n\n  Blockquote convention.\n    Blockquotes appear only in §2 stage subsections. No other section\n    uses blockquotes. Each blockquote contains 2–5 natural-language\n    prompts, each a self-contained sentence. No tool names, no parameter\n    shapes, no function signatures — exactly what the user would say\n    or type.\n\n  Table convention.\n    Exactly two tables: the comparison table (§3) and the Contribute\n    commands table (§4). No other tables. No tables in prose.\n    Pipe-delimited Markdown. No inline formatting beyond bold. Column\n    widths are author-managed.\n\n  No repetition.\n    One story vector per section. Don't explain the same concept in two\n    different places. The validator detects near-duplicate sentences.\n    No bullet lists of features in prose. No tables for feature\n    descriptions.\n\n  Future targets.\n    The Orientation and §3 closing prose name D&D 5e and Starfinder as\n    example rulesets. No Mothership appears anywhere in the document.\n\n  Non-goals.\n    The README is not an API reference, a tool catalog, a spec document,\n    or a changelog. It does not enumerate tools or parameters. It does\n    not describe implementation details. It does not repeat information\n    found in CHANGELOG.md, AGENTS.md, or holonovel.md.\n\n  Word budget.\n    Total prose ≤ 1,500 words (excludes code blocks, config JSON,\n    tables, blockquotes, TOC, and footer). Orientation ≤ 80 words. §3\n    closing prose ≤ 80 words.\n\n  Validator.\n    All rules marked \"The validator enforces\" SHALL be checked by\n    scripts/validate-readme.ts. Rules without mechanical enforcement\n    are maintained by author discipline. Adding an enforceable rule\n    requires a corresponding validator check.\n\n  Readme-driven development.\n    The README is the first artifact of the repo. Changes that affect\n    the README's claims SHALL update the README before or alongside the\n    code change. A README that promises something the server does not\n    deliver is a defect.\n-->\n\n# Holonovel\n\n**Build the Holodeck. Load your campaign.**\n\n[![holonovel MCP server](https://glama.ai/mcp/servers/flukeatzerocool/holonovel/badges/card.svg)](https://glama.ai/mcp/servers/flukeatzerocool/holonovel)\n\nA *holonovel* is a Star Trek holodeck program — an interactive story where you\nstep inside as a character and the rules govern. Holonovel builds the server (the\nHolodeck). Your campaign is the program (the Novel). Your rulebooks become the\nengine — D&D 5e, Starfinder, or the game on your shelf. Your books. Your server.\nYour Holodeck.\n\n## Table of contents\n\n- [Run a server](#run-a-server) — operators\n  - [Install](#install)\n  - [Install a ruleset](#install-a-ruleset)\n  - [Build your own rulebook](#build-your-own-rulebook)\n- [How it works](#how-it-works) — evaluators\n  - [Convert](#convert)\n  - [Build](#build)\n  - [World](#world)\n  - [Novel](#novel)\n  - [Synthesis](#synthesis)\n- [How it compares](#how-it-compares) — evaluators\n- [Contribute](#contribute) — contributors\n  - [Improve the spec](#improve-the-spec)\n\n## Run a server\n\n### Install\n\nThe base server — a world-model MCP with rooms, things, exits, parser commands,\nnarrative tools, and out-of-the-box mechanics from Fate, Ironsworn, and Blades in\nthe Dark (Fudge dice, momentum, and stress tracks, no ruleset required). Install\nit, then install any number of ruleset packages — each drops in alongside the\nbase and never modifies it. Node.js 20+ required.\n\n```sh\ncd holonovel\nnpm install\nnpm run start\n```\n\nAdd to your MCP client:\n\n```json\n\"holonovel\": {\n  \"type\": \"local\",\n  \"command\": [\"npx\", \"tsx\", \"src/index.ts\"],\n  \"cwd\": \"<path>/holonovel\",\n  \"environment\": {\n    \"TTRPG_NOVEL\": \"default\"\n  },\n  \"enabled\": true\n}\n```\n\n### Install a ruleset\n\nThe Build workflow turns a rulebook into a declarative package. Drop the package\ninto the install directory — `.holonovel-state/rulesets/<slug>/` by default — and\nthe running server registers it. Packages load lazily: a ruleset's tools and index\nhydrate only when you open a campaign bound to that ruleset, so stacking many\npackages costs you nothing up front. Install, remove, and list packages from the\nserver tools, or just move files and restart.\n\nYour campaign data and installed packages live under `.holonovel-state/`, outside\nthe server tree — updating holonovel never touches them.\n\n### Build your own rulebook\n\nTo start a build, run the entry point — it records the intake and prints the\nworkflow to follow (see the spec's Workflow Runbooks appendix for the full happy\npath):\n\n```sh\nnpm run build-ruleset dnd5e=ruleset/dnd5e/\n```\n\n## How it works\n\nHolonovel is one pipeline — Convert, Build, World, Novel, Synthesis — that turns\na rulebook into a running table. Badge enforcement runs across all of it,\nserver-side.\n\n### Convert\n\nConvert takes PDFs, HTML, and web scrapes and turns them into clean Markdown.\nColumn detection reassembles tables across page breaks. OCR catches text\nembedded in images. The output is structurally sound — every heading resolved,\nevery reference traced.\n\n> \"Take the Dungeon Master's Guide — every chapter, every table, every sidebar —\n> and make it a clean source file the server can build from.\"\n> \"Convert this PDF to Markdown, and reassemble the tables that break across\n> pages.\"\n\nClean Markdown, ready to build.\n\n### Build\n\nBuild reads that Markdown and extracts every mechanic. Dice procedures, combat\nsystems, spell catalogues, equipment tables, condition tracks — every structured\nelement becomes a tool, resource, or prompt in a declarative ruleset package.\nGuidance prose becomes narrative material. The discovery engine samples the\nsource, measures extraction confidence, and iterates until every mechanical\nsection is accounted for. What can't be modeled stays searchable — nothing is\nfabricated to fill a gap.\n\n> \"Build me a ruleset package from these files.\"\n> \"Extract every mechanic from this rulebook — the dice, the combat, the spells —\n> into a ruleset package.\"\n\nOne spec. Any rulebook. Zero code.\n\n### World\n\nThe world model is a spatial simulation layer — rooms, exits, containers,\nsupports, doors. Every object knows where it is and what it contains. The server\nmaintains a real containment graph, not a paragraph of prose it hopes the AI\nremembers. The world model is powered by the Inform programming language — the\nsame engine behind decades of interactive fiction classics.\n\nParser commands navigate the world with real containment logic. Go north. The\nroom is there. Take the lantern. It moves from the sarcophagus to your\ninventory. Open containers, lock doors, examine surroundings. Exits connect\nautomatically in both directions. Most AI RPG tools have no spatial model — the\nAI pretends to remember where things are.\n\n> \"Go north.\"\n> \"Take the lantern from the sarcophagus.\"\n> \"Look around.\"\n> \"Open the iron door.\"\n> \"Examine the runes carved into the altar.\"\n\nYour map is real.\n\n### Novel\n\nA Novel is your entire campaign — party, NPCs, scenes, lore, combat state, world\nmodel, story journal, factions, secrets, everything. The narrative model gives\nyour world depth: scenes set the stage, NPCs carry personality profiles and\ndialogue voice, lore entries fire automatically when keywords match, factions\ntrack standing, secrets gate knowledge, vows bind quests, countdowns escalate on\nschedule. The story journal records decisions, moments, and consequences — a\nnarrative memory that survives every rebuild.\n\nA Novel lives on the server. It survives restarts, rebuilds, and session breaks.\nExport as JSON or Markdown. Import with merge, replace, or dry-run modes. Clone\nto test a story branch. Set checkpoints before pivotal moments. Undo any\nmutation. A Novel is not a chat log — it is a structured save file. Other tools\nask the AI to remember your world. Holonovel writes it to the server —\nstructured, queryable, permanent.\n\nEvery Novel has four badge settings. Player. Game Master. Observer. Editor.\nSwitch between them at any time — no restart, no reload. The AI takes the\nopposite role automatically: when you're the player, the AI is your GM. Badge\ngating is not a prompt instruction. It is enforced server-side — the GM's\nsecrets, lore entries, and narrative directives never leak to the Player badge.\n\n> \"Set the scene: a flooded ossuary beneath the old cathedral. The air is thick\n> with stale incense and something older.\"\n> \"A figure emerges from the shadows — Sister Mora, an acolyte of the buried\n> order. She's terrified, not hostile.\"\n> \"I swear a vow to recover the Saint's Reliquary before the next full moon.\"\n> \"Switch to the Game Master badge. I need to set up the next scene.\"\n> \"Pace: I want things to move faster.\"\n\nYour campaign. On the server. Forever.\n\n### Synthesis\n\nSynthesis deepens your campaign through two source categories. Ruleset Wisdom is\nextracted from your rulebooks during Build — voice examples from example-of-play\ndialogue, lore templates from setting descriptions, action patterns from\nresolution sequences, narrative voice profiles from inspirational media\ncitations. It persists as first-class server behavior — the Holodeck renders\nyour rulebook's own genre conventions mechanically. Ruleset Wisdom survives\nevery rebuild and synthesis reversion.\n\nExternal research runs on demand — web-sourced GM advice, actual-play\nbreakdowns, designer notes. Tagged with source URLs, confidence scores, and\nfreshness timestamps. Every synthesis item is inert by default. The GM toggles\nwhat matters on and off at runtime. Re-running synthesis replaces inactive items\nwhile preserving everything the GM has activated. Revert synthesis removes\nexternal research — Ruleset Wisdom persists.\n\n> \"Find me GM advice and play examples for running horror one-shots.\"\n> \"Research how other tables handle horror pacing, and tag what you find with\n> sources.\"\n\nThe game evolves without losing what you've built.\n\n## How it compares\n\n| Category | What you're used to | How Holonovel differs |\n|----------|---------------------|-----------------------|\n| AI storytelling apps | Freeform AI storytellers — invent rules, forget consequences | Your rulebooks. Real dice. Real conditions. Not AI improv. |\n| Generic LLM chat | Forgets conditions mid-combat, invents spells, drifts from the ruleset | The server remembers every rule you gave it. Deterministic dice. Conditions that don't vanish mid-fight. |\n| First-generation rules MCP servers | Hand-built for one edition of one game. Rules lookup and nothing else. | Not locked to one system. One spec reads any rulebook — D&D 5e, Starfinder, or whatever's on your shelf. |\n\nEvery tool in this space asks you to pick. Rules engines serve one system and\nstop there. AI storytellers improvise mechanics as they go. Holonovel doesn't\npick. The server enforces every mechanic. The AI narrates. The Novel preserves\neverything — D&D 5e, Starfinder, or your own rulebook.\n\n## Contribute\n\n### Improve the spec\n\n```sh\nnpm install && npm run check   # lint + validate + assumption audit + ambiguity\n                                # scan + cross-ref check + dupe detection\n```\n\n| Command | What it checks |\n|---------|---------------|\n| `npm run fmea` | REQ-level failure mode and effects |\n| `npm run validate --traceability` | Full REQ↔test↔workflow traceability |\n| `npm run graph-deps` | REQ dependency graph (DOT/Graphviz) |\n\nEdit files in `spec/`. Run `npm run assemble` before committing. Do not edit\n`holonovel.md` directly — it is generated from `spec/` source files.\n\nCanonical origin: [git.gay/flukeatzerocool/Holonovel](https://git.gay/flukeatzerocool/Holonovel). This GitHub repository is a push-only mirror (synced by `scripts/push-pipeline.sh`) that also hosts the npm and MCP-registry publish workflow (`.github/workflows/publish.yml`).\n\nGuides for players, Game Masters, and builders live in the [project wiki](https://git.gay/flukeatzerocool/Holonovel/wiki).\n\nLicense: MIT. Built from: Graham Nelson's Inform (Artistic License 2.0),\nif-craft-corpus (CC BY 4.0), dmcp (MIT, Shawn Rushefsky), lonelog (CC BY-SA 4.0),\nBitD SRD (CC BY 3.0, John Harper), Ironsworn SRD (CC BY 4.0, Shawn Tomkin),\nFate SRD (CC BY 3.0, Evil Hat Productions).\n[RSS](https://git.gay/flukeatzerocool/Holonovel.rss). Last updated: <!-- @spec:date -->2026-09-07.\n",
  "bytes": 18500,
  "sha": "811b445eb38dcd950aa71259d15aa444f3fed78184275f220018471db7b49292",
  "repo_slug": "flukeatzerocool/holonovel",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_flukeatzerocool_holonovel_baa2e110/readme"
}