Holonovel

Manage player characters: create (quick or step-by-step), stage to roster, import, render a sheet, set the active entity, set personality/voice, patch mechanical stats, send player signals, remove, or list roster characters. sheet and roster_list are read-only; every other action mutates the Novel and persists the change. update merges provided fields in place (stats shallow-merge; omitted fields are preserved) so one sheet field can change without re-creating the character. The personality{} object aliases description/voice/background/goals, and details{} aliases ability_scores/skills/feats/t…

Manage the server-level codex library of reusable, cross-Novel content (NPCs, characters, scenes, encounters, lore, factions, rooms, things, templates, voice profiles, adventures). Entries persist to `.holonovel-state/codex.json` outside every Novel and survive restarts; mutations are audited. Out-of-play and badge-free: requires the Editor or Game Master badge, a Player mid-adventure gets `[FORBIDDEN]`, and reads are not badge-filtered. When no Novel is active, the codex is the default store; `import` and `capture` require an active Novel. `set` needs `kind` + `name` (the id derives from them…

Manage combat encounters in the active Novel — encounter turn order, participants, and lifecycle, not per-entity conditions. Mutating actions persist to the Novel and are audited; read-only actions do not mutate state. Revert the most recent mutation with manage_history (action: undo). init's seed only reorders the danger set; participants keep their given order. Use when: starting, advancing, ending a fight, or changing its participants. Do NOT use when: applying a status effect — use manage_condition (action: apply).

Manage mechanical or narrative conditions on entities. apply attaches a named condition to one entity; rounds is a positive round count, and omitting it (or passing 0) leaves the condition without an expiry. Re-applying an active condition warns instead of duplicating it, and remove deletes the condition and its round counter. apply and remove require the GM or Editor badge, persist to the Novel, and are undoable via manage_history (action: undo); list is read-only. Use when: applying, removing, or listing conditions. Do NOT use when: recording damage or combat state — use manage_combat (actio…

Manage the cold-reference knowledge corpus. Use when: registering, listing, reading, routing, granting, denying, accessing, consuming, or inspecting acquisitions of corpus documents (corpus_register, corpus_list, corpus_get, corpus_route, corpus_grant, corpus_deny, corpus_access, corpus_consume, corpus_acquisitions). Do NOT use when: writing Novel lore entries or secrets — use manage_lore. corpus_register, corpus_route, corpus_grant, and corpus_deny persist access state; revert with manage_history (action: undo); corpus_list, corpus_get, corpus_access, and corpus_acquisitions are read-only; co…

Manage countdown timers in the active Novel. Mutating actions persist to the Novel and are audited; read-only actions do not mutate state. Revert the most recent mutation with manage_history (action: undo). set's direction shifts NPC dispositions only when scope is also set. Use when: starting, advancing, removing, or listing clocks. Do NOT use when: tracking a vow's progress — use manage_vow (action: milestone).

Manage session diagnostics and maintenance surfaces separate from play-facing session controls. Use when: reporting server health (health), summarizing or compacting the audit log (compress, compact), subscribing to notifications (subscribe), reassigning a tool category (category), or appending and reading the Novel event log (event, history). Do NOT use when: recapping play, setting verbosity, or reordering the briefing — use manage_session. compact is GM-only and irreversible; category, event, and compact persist; health, compress, subscribe, and history are read-only.

Manage organizations in the active Novel: create, update, remove, or list factions, each carrying a name, description, goals, resources, and optional territory room names. name is required to create and faction_id targets an existing faction; the progress clock is Novel-internal and not set directly. create, update, and remove require the GM or Editor badge, persist to the Novel, and are undoable via manage_history (action: undo); remove deletes the faction permanently unless undone, and list is read-only. Use when: creating, revising, removing, or listing factions. Do NOT use when: tracking a…

Undo or redo the most recent state mutation for the active badge, restoring the prior per-badge snapshot and clearing the redo stack on a new mutation. Both directions mutate Novel state and persist immediately (readOnlyHint false). The stack is per badge and capped by TTRPG_MAX_SNAPSHOT_DEPTH, and a pending workflow decision blocks both until resolved with respond_decision. Use when: reverting the last mutation (undo) or restoring an undone one (redo). Do NOT use when: an older change is the target — re-run the owning tool (e.g. manage_lore, manage_story, manage_world), because only the most …

Manage a roster character's durable identity: staged candidates, accepted facets, and the versioned compiled kernel. stage imports or authors identity material, accept replaces a facet and bumps the identity version, and reject marks that candidate rejected without touching accepted facets; bootstrap seeds from a character card, and an accepted facet's prior value is not retained. accept's perspective defaults to the candidate's stored perspective. Mutation persists the roster and is audited; list and snapshot are read-only; identity changes are not reversible via manage_history, so reject a b…

Manage derived, in-memory knowledge over Novel sources: a semantic index for advisory text ranking and a typed knowledge graph. index_build and graph_build replace the prior in-memory projection, are audited, and are safe to rebuild from the authoritative Novel file, which is never modified. The read actions (index_status, graph_status, index_list, index_search, index_relations, graph_get, graph_nodes, graph_edges, graph_neighbors) are read-only and do not mutate state. Use when: building or rebuilding the index or graph, checking staleness, listing or ranking indexed items, or reading relatio…

Manage the active Novel's lore entries — shared, durable world facts every caller recalls. set/update writes a keyed entry with recall triggers, priority, sticky weight, and a badge_scope (game_master hides it from the Player badge); set_secret, reveal, secret_list, and knowledge control Player-visible knowledge. import defaults to a non-mutating dry-run, while merge and replace write. Lore mutations require the GM or Editor badge, persist to the Novel, and are undoable via manage_history (action: undo); list, get, export, secret_list, and knowledge are read-only. Use when: creating, revising,…

Manage Novel-scoped scratch notes, badge-scoped to game_master (default), player, or shared. Mutating actions persist to the Novel and are audited; read-only actions do not mutate state. Revert the most recent mutation with manage_history (action: undo). set's badge_scope defaults to game_master. Use when: storing scratch state the caller will reuse. Do NOT use when: recording durable world facts — use manage_lore (action: set).

Manage Novel save files: lifecycle (create, resume, switch, end, rename, description, info, genre, complete_session_zero, save_context, get_context) and listing. list returns one line per Novel unless detail is set, and filter selects active, archived, or all. create and save_context persist to the Novel; list, info, and get_context are read-only. Lifecycle changes are not reversible via manage_history; clone a Novel with manage_archive before a risky change. Use when: handling a campaign's lifecycle or returning to saved context. Do NOT use when: managing content inside the Novel — use the en…

Manage non-player characters in the active Novel. create requires a name; update, remove, and get target an existing npc_id; ruleset_reference links an optional stat block; mind is GM-only and never returned to the Player badge. create, update, and remove require the GM or Editor badge, persist to the Novel, are audited, and are undoable via manage_history (action: undo); remove deletes the NPC, while list and get are read-only. Use when: introducing, revising, removing, listing, or reading NPCs. Do NOT use when: managing player characters — use manage_character (action: create/import/sheet).

Manage directed relationships between entities, NPCs, or factions. set is keyed by the ordered (entity_a, entity_b) pair and updates type, value, or description in place rather than duplicating; type is one of ally, rival, neutral, mentor, dependent, or suspicious, and value is an optional numeric strength. get returns outgoing and incoming edges separately. set requires the GM or Editor badge, persists to the Novel, and is undoable via manage_history (action: undo); get is read-only. Use when: setting or reading how two parties relate. Do NOT use when: tracking faction standing or progress — …

Manage ruleset packages: search an installed ruleset's index, install or remove a package, list installed packages, bind a Novel to a ruleset, or import/remove supplementary Wisdom. search accepts an optional slug, works with no active Novel, and is read-only; install, remove, import_supplementary, and remove_supplementary mutate state, are audited, and are reversible via the paired action. install of an existing slug conflicts, and remove refuses while a Novel is bound to that slug. binding scopes only Novel-dependent features; import_supplementary uses inline wisdom when present and reads so…

Manage the active scene and its narrative framing — scene description, directive, choices, and oracle rolls, distinct from the world model's rooms and things. set writes the description, location, type, time, and atmosphere, deriving the description from location only when description is omitted; directive sets the narrative directive; choices offers player options; oracle resolves a chance question and records the roll. set and directive require the GM or Editor badge, persist to the Novel, are audited, and are undoable via manage_history (action: undo). Use when: setting scene state, issuing…

Manage play-facing session controls: recap, verbosity, briefing_order, and tool discovery, distinct from story content and Novel lifecycle. recap summarizes recent activity and accepts session_id, gm_notes, and a history window; discover searches the tool catalog by name, description, or title. verbosity sets normal or terse output; briefing_order reorders briefing sections and requires the GM or Editor badge. verbosity is session-scoped; briefing_order persists to the Novel. recap and discover are read-only, and a setting is restored by setting it again (no undo snapshot is taken). Use when: …

Manage scene presence and autonomy staging. Use when: setting which entities are present (presence) or adjusting NPC and world autonomy for the scene (autonomy). Do NOT use when: setting the scene, issuing a directive, offering choices, or consulting the oracle — use manage_scene. presence and autonomy persist to the Novel and are audited; revert with manage_history (action: undo).

Manage the story journal — typed narrative memories (decision, moment, revelation, bond, consequence). record appends an entry and consumes the turn_handle minted by take_turn; update edits a mutable entry; decision and consequence entries are immutable and refuse update or promotion; remove deletes an entry by index; promote copies an entry into lore under a derived or supplied key. list filters by type and paginates with offset and limit, returning previews unless detail is set. Mutations require the GM or Editor badge, persist to the Novel, and are undoable via manage_history (action: undo)…

Manage synthesis content (voice examples, lore templates, action patterns, and other Ruleset Wisdom). Mutating actions persist to the Novel and are audited; read-only actions do not mutate state. Revert the most recent mutation with manage_history (action: undo). activate/deactivate with key omitted act on the whole module. Use when: running, reverting, listing, activating, deactivating, toggling, or player-authoring synthesis items. Do NOT use when: browsing the codex — use manage_codex (action: list).

Track narrative vows, quests, and obligations with milestones. set creates a vow and links a countdown whose ticks follow the difficulty rank track (scope defaults to shared); milestone advances progress; resolve and forsake close the vow with distinct outcomes (fulfilled vs abandoned). Mutations require the GM or Editor badge and persist to the Novel; list is read-only. Vow changes are not reversible via manage_history; resolve and forsake are terminal choices. Use when: setting, advancing, resolving, forsaking, or listing vows. Do NOT use when: starting a clock timer — use manage_countdown (…

Manage the world model — rooms, things, exits, and their spatial properties. create, update, remove, convert, and generate mutate the model and persist to the Novel; removing a room or thing is permanent — re-create it to restore the model. create_exit links both directions; create_thing honors location_type only when location is set, and kind forces property defaults. There are no read-only actions here; inspect state with run_command (action: execute). Use when: creating, updating, removing, bulk-converting, or generating locations and objects. Do NOT use when: navigating the world — use run…

Open a play session by resuming a Novel, activating a badge, and returning a recap. Use when: starting or resuming a session (open_session), especially after a restart. Do NOT use when: creating a Novel — use manage_novel (action: create); running a turn — use take_turn. Resume and badge changes persist and are audited; revert with manage_history (action: undo).

Orphan info. Use when: test. Do NOT use when: real — use core_mechanic.

Look up. Use when: looking. Do NOT use when: not — use core_mechanic.

Return a single stat for a player and season, with qualifiers.

Resolve Fate-style actions with Fudge dice, aspects, Fate points, and stress. Rolls and state changes (points, stress, momentum, progress) persist to the Novel; a roll with no following write is flagged as an uncommitted roll. stress with neither track nor consequence clears all tracks and consequences. Rolls and their state writes are recorded and are not individually reversible. Use when: rolling 4dF against a difficulty, invoking or compelling aspects, spending or refreshing Fate points, or marking stress and consequences. Do NOT use when: resolving a d20 skill check — use the bound ruleset…

Resolve Blades in the Dark-style actions: action rolls with position and effect, stress and trauma with resistance, and downtime recovery. Rolls and state changes (points, stress, momentum, progress) persist to the Novel; a roll with no following write is flagged as an uncommitted roll. action_roll with dice 0 rolls the lower of two d6; stress name labels the resist consequence or the trauma mark. Rolls and their state writes are recorded and are not individually reversible. Use when: rolling an action against the highest die, marking or resisting stress, or recovering during downtime. Do NOT …

Resolve Ironsworn-style actions: momentum, the action-roll move framework, and progress tracks. Rolls and state changes (points, stress, momentum, progress) persist to the Novel; a roll with no following write is flagged as an uncommitted roll. move's burn replaces the action die with momentum and ignores adds; progress rank defaults to dangerous. Rolls and their state writes are recorded and are not individually reversible. Use when: setting or burning momentum, rolling a move against two challenge dice, or marking and testing a progress track. Do NOT use when: managing vows — use manage_vow …

Resolve uncertain actions across the host's base mechanics: Fate Fudge dice, aspects, Fate points, and stress; Ironsworn momentum, moves, and progress; Forged action rolls, stress, trauma, and downtime; and generic ruleset table rolls. Rolls and state changes persist to the Novel and are audited; a roll with no following write is flagged as an uncommitted roll. Revert the most recent mutation with manage_history (action: undo). fate_roll uses dF, ironsworn_move compares an action die against two challenge dice, and forged_action_roll takes the highest of a d6 pool. Use when: resolving a Fate, …

Answer a pending workflow decision, atomically draining it and persisting the outcome to the Novel. option must match one of the emitted choices; 'cancel' aborts the workflow and restores its pre-workflow snapshot, while any applied outcome is not reversible. The drain is mutating and audited, and a second call with no pending decision returns STATE_CONFLICT. Use when: the server emitted a [NEED_INPUT] prompt and the caller must choose. Do NOT use when: no decision is pending — use set_badge or a state tool instead.

Roll a dice check with an optional skill label. Use when: you need to resolve a skill or ability check. Do NOT use when: you need spell text — use lookup_spell.

Roll on a fixture table. Use when: resolving a table. Do NOT use when: looking up a thing — use lookup_thing.

Execute a parser command, resolve a spatial intent, or map intent to tool calls. execute runs a parsed verb-and-noun command (for example 'take lamp' or 'go north') against the world model, mutates world/entity state, persists to the Novel, and is audited; a mistaken move is reversed by issuing the inverse command because no undo snapshot is taken. resolve computes a movement outcome without mutating, and suggest returns recommended tool calls for an intent. On a ruleset-bound Novel the parser is GM-only for navigation and mutation, while the Player badge keeps read-only perception commands. U…

Search the fixture. Use when: term unknown. Do NOT use when: type known — use lookup_thing.

Switch the active badge to player, game_master, observer, or none (Editor), gating tool access server-side for the active Novel; always callable. Switching immediately re-filters tools/list, so a narrower badge can revoke tools mid-task and switching back restores them; badge changes are mutating session state, audited, and reversible by switching back. Use when: entering the story, spectating, or stepping away to edit. Do NOT use when: answering a pending workflow decision — use respond_decision.

Resolve a player intent through the parser and mint a turn handle for the story record. Use when: taking a turn (take_turn) before recording the outcome with manage_story (action: record). Do NOT use when: resolving a specific combat round — use manage_combat (action: advance); rolling a ruleset check — use resolve_mechanic (action: roll). The turn is read-only and non-persistent: no Novel state is mutated; the handle is session-scoped and expires.