Reference. For builders and server maintainers. Holonovel has four jobs — Convert, Build, Synthesis, and Update. Each reads source material and produces or modifies a server. This page covers every job in detail.

---

Convert takes a tabletop RPG rulebook in any common format — PDF, HTML, or a web URL — and produces clean, structurally sound Markdown. The output is what the Build job reads to construct a server. Without Convert, PDFs with scanned-in tables and HTML with inline styles would produce garbled extractions.

Convert runs once per source. If your rulebook is already clean Markdown, skip it.

PDF conversion. Column detection restores reading order in multi-column layouts, and multi-page table reassembly merges table fragments split across page breaks. Scanned pages fall back to OCR. Headings are inferred from font size, weight, and position when explicit heading tags are absent. Cross-references (see page 42) are resolved to anchors within the output.

HTML conversion. Inline styles are stripped. <table> elements are normalized to pipe tables. Image alt text is preserved. Navigation elements (headers, footers, sidebars) are detected and removed. The DOM structure drives heading hierarchy.

Web scrape. A URL is fetched, rendered, and converted. Pagination is followed. Dynamic content (JavaScript-rendered tables, SRD sites with collapsible sections) is captured.

"Convert this 300-page Player's Handbook PDF into Markdown for the Build workflow."

Convert produces a single file (or a directory of files for multi-book rulesets) with these properties:

• Every heading resolved to an ATX heading (#, ##, ###)
• Every table rendered as a pipe table with alignment markers
• Every cross-reference replaced with an anchor link
• Source citations preserved as <!-- source: page 42 --> comments
• A conversion manifest recording the converter tool, version, fidelity rate per content type, and any sections that failed structural validation

After conversion, G0a (structural integrity) checks the output: heading count, table count, link count, section density, and mechanical density (the proportion of sections containing rules content vs. flavor). A viability pre-check warns if the ruleset has too few mechanical sections — fewer than 30% of sections containing stats, tables, or resolution procedures — to produce a playable server.

Convert is structured as Appendix G of the specification. The converter tool selection, OCR engine, and column-detection strategy are the builder's implementation decisions — the spec states the output contract, not the tool chain.

---

Build reads the ruleset Markdown and constructs a complete MCP game server. This is the primary job — it's what turns your rulebook into something you can play. Build runs in six phases, each with acceptance checks.

The builder asks you a batch of questions:

• Which workflows to run? (Build-only, Build + Synthesis, or ruleset-free)
• Where is your rulebook? (path to Markdown file or directory)
• What do you want to call the server? (becomes the directory name)
• Where should server data live? (default: .holonovel-state/ in the server directory)
• Which MCP client do you use? (Opencode, Claude Desktop, Continue.dev, Cursor)
• Build mode: production (full checks, assumption audits, cross-model verification), quick (skip audits, faster iteration), or debug (single-phase, raw extraction dumps)?

For ruleset-free builds, the ruleset questions are skipped. Answers go into DECISIONS.md. The builder confirms everything back before proceeding.

G0a checks the ruleset source is readable, well-formed, and structurally sound. If the source isn't Markdown, Convert runs first.

G0b verifies MCP conformance — the running server against the Appendix D checklist. This gates on the MCP skeleton being built first (Phase 4, step 1), so G0b runs after construction begins, not before.

The builder reads the ruleset, chunking dynamically based on structural boundaries (headings, tables, section density). Each chunk is processed for:

• Concepts — stats, conditions, statuses, currencies, narrative mechanics
• Entities — character types, monsters, NPCs, factions
• Actions — resolution mechanics, combat procedures, magic systems, skill systems, generation tables
• Tables — lookup tables (equipment, spells, monsters) and generation tables (random encounters, treasure, names)
• Core resolution — the primary mechanic (d20 + modifier vs. DC, dice pool, percentile, etc.) with variant rules
• Roles — player and GM nomenclature, adjudicator term, adjudicator-marker conventions
• Guidance — example-of-play prose, narrative tone samples, GM advice, anti-pattern warnings

Each extracted item carries a confidence label (HIGH, MEDIUM, LOW) and a source anchor (file, heading path, line range). Items below the extraction threshold (MEDIUM confidence for Phase 1, HIGH for Phase 2 critical mechanics) are flagged in the defect log.

Discovery produces two artifacts:

• RULESET_MODEL.md — the semantic model, human-readable, with citations and confidence labels
• ruleset_model.json — machine-readable model for verification and server code

The builder cross-checks 10 random items across both formats for consistency before proceeding.

"Build me a server from these D&D 5e SRD files."

The builder discovers 1,021 indexed sections: spells, monsters, classes, races, equipment, conditions, feats, and the core d20 resolution mechanic. Each is traced to a source anchor with a confidence label.

Six dependency-ordered steps:

1. MCP skeleton. initialize, tools/list, resources/list, prompts/list. The server handshakes correctly. G0b gates here.
2. Index. Anchor tree from heading hierarchy. manage_ruleset (action: search) tool with ranked results and source anchors.
3. Extraction pipeline. Content-type detection (spell, monster, class, equipment). Entity and model extraction. Canonical lookups registered.
4. Tools. Dice resolution (d20, dice pool, percentile — whatever the ruleset uses). Combat (initiative, turns, conditions, advancement). Character management (creation, advancement, roster). Narrative tools (scene state, NPCs, lore, countdowns, factions, relationships).
5. Prompts. badge_briefing (the GM/Player briefing composed from state, lore, and guidance), intro (first-time orientation), session_zero (campaign setup walkthrough), novel_setup (Novel-specific orientation), run_workflow (operational prompt for the AI when executing server commands).
6. Client config. Writes MCP client configuration, verifies key names against the target client's schema.

The specification is copied into the server directory during construction, establishing the spec://build resource.

The convergence loop measures quality across two phases:

Phase 1 metrics — Extraction quality:

• Confidence distribution across extracted items
• Extraction fidelity (items resolved to canonical source vs. ambiguous)
• Conversion fidelity (structural integrity of converted content types)

Phase 2 metrics — Construction quality:

• MUST coverage (do all tools produce output meeting their REQ contracts?)
• Mechanics fidelity (do dice, conditions, and combat match the source?)
• Process compliance (are all six construction steps complete with acceptance checks?)

If thresholds aren't met, the builder iterates — re-reading source sections, adjusting extraction, or modifying tool construction. A second model cross-audits the first when available, catching defects a single model would miss. Convergence results are cached so incremental updates can skip unchanged phases.

The Pattern Buffer is an operational verification suite — 33 adversarial sub-workflows (29 ruleset-facing) run against the live server:

• S1–S5: Tool surface sweep — every tool called under every badge, verifying output contracts, error taxonomies, and badge gating
• S6: Cross-badge boundary enforcement — adversarial badge switches probing for information leaks
• S7–S8: Combat endurance — 30 rounds of combat with conditions, countdowns, and turn-order integrity
• S9: Corrupted state recovery — injecting corrupted Novel files and verifying structured recovery
• S10–S11: Combat stress — rapid combat lifecycle (create, advance, end, re-create)
• S12–S20: Narrative lifecycle scenarios — NPC creation, lore triggering, scene transitions, countdown expiry, adventure generation
• S21–S29: Build-specific scenarios — ruleset extraction verification, golden transcript replay, fixture validation

Blocking sub-workflows must pass. Failures feed back into the convergence loop. After two stalled Pattern Buffer iterations (no blocking scenarios downgraded, total failures not decreasing), residual failures are logged as accepted limitations.

"Build complete. The server is running. Connect your MCP client."

A running MCP server. Plus four handoff artifacts (plus LICENSE.md):

1. RULESET_MODEL.md — what was extracted from the ruleset
2. DECISIONS.md — every decision, why, and with what confidence
3. README.md — how to install and run the server
4. AGENTS.md — AI maintainer orientation for future updates

---

Synthesis augments a server with supplementary guidance across three tiers. It runs after Build — you can re-run it at any time without rebuilding.

Extracted from your rulebooks and curated vendor content during Build. This tier covers seven output modules:

Module	Source	Example content
voice_examples	Example-of-play dialogue in the ruleset	How a goblin speaks, how a dragon taunts
briefing_order	The ruleset's own session structure	Recommended ordering for the badge briefing
lore_templates	Setting descriptions, location text	Lore entry templates for forests, dungeons, cities
action_patterns	Resolution sequences, combat examples	Combat action patterns, social encounter patterns
supplementary_guidance	GM advice, designer notes	General play advice and anti-pattern warnings
adventure_advice	Encounter design guidance	Genre-specific advice for horror, mystery, action
narrative_voices	Inspirational media citations	Tone guidance from Appendix N, suggested viewing

Ruleset Wisdom needs at least 4 of the 7 modules populated to reach the activation threshold. The remaining modules are populated by Tier 2.

Ruleset Wisdom items survive manage_synthesis (action: revert) — they're extracted from your books, same as spells and monsters.

Web-sourced GM advice, actual-play breakdowns, designer interviews, and community best practices. Tagged with source URLs, confidence scores, and freshness timestamps. Refreshed on re-run — stale items are replaced.

"Find me GM advice and actual-play examples for running horror one-shots."

Tier 2 fills modules that Tier 1 couldn't populate from the ruleset alone. If your book has no inspirational media section, external synthesis provides narrative_voices. If your book's GM advice is thin, external synthesis fills adventure_advice.

Synthesized from your own world state as you play. Re-run periodically during a campaign:

"Synthesize enrichment from the current Novel."

What it generates:

• NPC personality profiles become voice examples
• Unresolved story threads become scene hooks
• Faction tensions become countdown warnings
• Discovered lore becomes lore templates for similar locations
• Player decisions become action pattern suggestions

Every synthesis item is inert by default. The GM activates what matters:

"Activate the goblin voice examples for the Sunken Temple." "Deactivate the horror genre advice — this session is investigation."

Activation state persists with the Novel. Toggle modules on and off at runtime. Player-authored items live alongside ruleset and community content.

Each tier has an independent removal boundary:

"Revert community synthesis — keep the ruleset material."

• Reverting Tier 2 removes all community-sourced items; Tier 1 and 3 survive.
• Removing Tier 3 removes novel-synthesized items; Tier 1 and 2 survive.
• manage_synthesis (action: revert) removes Tier 2 and Tier 3; Tier 1 (Ruleset Wisdom) survives because it came from your books.

Re-running synthesis replaces inactive items while preserving everything the GM has activated.

---

Update reconciles an existing server with a revised specification. The spec changed — your server needs to follow, without losing your campaigns.

• A spec revision changes a REQ your server implements
• The CHANGELOG announces a subsystem you depend on has been hardened
• The pre-push hook tells you the spec changed but the server wasn't updated
• You want the latest verification and quality guarantees

Updates are incremental by design. The spec delta determines the scope. Full rebuilds are expensive; the builder prefers incremental updates when the delta is narrow. A full rebuild is only required when the ruleset changes, the extraction model changes, or the spec version changes.

"Update my D&D 5e server to the latest specification."

1. Intake. The builder asks:

• Where is the server to update?
• How should the spec version delta be detected? (auto: compare DECISIONS.md to current spec)
• Fetch the latest spec from repo before updating?

The builder fetches the latest holonovel.md from the repository URL recorded at build time. Fetch failure doesn't block — you can update against the local copy.

2. Gap audit. The builder compares your server against the current specification across six surfaces:

Surface	What's checked
Tool catalog	New tools added? Existing tool signatures changed?
Resource map	New resources? URI patterns changed?
Prompt list	New prompts? Prompt content contracts changed?
State model	New state properties? Property group changes?
Badge gating	New GM-only tools? Gating rules changed?
Behavioral contracts	Output format contracts changed? Error taxonomy changed?

Every gap gets a disposition: implemented (the fix was applied), deferred (intentional — recorded with rationale), or waived (REQ doesn't apply to this ruleset).

3. Implementation. The builder implements every gap marked implemented. Changes are applied incrementally — tool additions, signature updates, resource registration, prompt updates, state model extensions. Each change cites its REQ.

4. Scoped verification. The builder re-runs only the Pattern Buffer sub-workflows exercised by the changed surfaces — not the full suite. The surface-to-sub-workflow mapping in §6.6 determines which sub-workflows to run. S1 (tool surface sweep) is always selected when new tools are added.

Example: if only badge gating changed, only S6 (cross-badge boundary enforcement), S14h (Player badge manage_session (action: health)), and S20 are selected. Combat, search, and lore scenarios are skipped.

After verification, the server process is restarted and manage_session (action: health) confirms the updated specification version.

Your campaigns survive every update. Characters, Novels, worlds — they don't notice the server changed underneath them.

Scenario	What happens
Same ruleset rebuild	All Novel state preserved. Synthesis items with matching ruleset hash survive unchanged.
Spec-only update	Novel state preserved. The update is additive or corrective.
Ruleset changes	Novel state preserved, but synthesis is replaced when the ruleset hash changes and Synthesis re-runs.
Nuclear rebuild (deleting .holonovel-state/)	Roster survives (it's in roster/). Novels must be re-imported from exports.

Run manage_session (action: health) to confirm the server reports the new spec version. Check that your existing Novels resume without errors. If the update added new tools, verify they appear in your MCP client's tool list after restart.

---

Last updated: 2026-10-12.