Switch the active badge to player, game_master, observer, or none (Editor), gating tool access server-side for the active Novel; always callable. The badge is per Novel and switching re-filters tools/list immediately, 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.

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.

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 (for example manage_story), because only the most recent mutation is stacked.

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; Novel mutations persist, are audited, and are undoable via manage_history (action: undo). 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/talents/equipment; a top-level value overrides its grouped alias. stage and roster_remove are exact inverses on the roster; remove deletes the Novel entity and is undoable. Use when: creating or importing a PC, staging or activating one for play, editing its sheet or voice, or handling player feedback. Do NOT use when: managing an NPC — use manage_npc.

Run the spatial parser: execute a parsed command, resolve a movement outcome, or map an intent to tool calls. execute accepts free-form text, mutates world and entity state, persists, and is audited; a mistaken move is reversed by issuing the inverse command because no undo snapshot is taken. resolve computes the same movement without mutating, and suggest returns recommended calls without executing them; source and target apply only to perception queries. On a ruleset-bound Novel the parser is GM-only for navigation and mutation, while the Player badge keeps read-only perception commands. Use when: a player or narrator takes a physical action, needs a movement outcome without mutating, or wants intent mapped to tools. Do NOT use when: the GM creates or edits the model — use manage_world; durable world facts — use manage_lore.

Manage the world model — rooms, things, exits, and their spatial properties. create and update mutate in place and persist to the Novel; all mutations are audited; remove is permanent and requires re-creation; convert replaces the described subtree; generate creates rooms from installed table pools bounded by TTRPG_WORLD_GEN_MAX_ROOMS. 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_command (action: execute); proposing objective-state transitions — use manage_causality; recording what an entity believes — use manage_belief.

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 objective causal state and transition proposals. causal_propose records a proposal without applying it; causal_admit applies the proposal and causal_reject discards it; causal_expected_version guards optimistic concurrency and causal_from records the expected prior value; causal_ingress admits an external event without a proposal. Proposals persist and are audited; list and state are read-only. Use when: proposing, admitting, rejecting, listing, or inspecting causal transitions, or ingressing an external event. Do NOT use when: changing rooms, things, or exits — use manage_world. Revert with manage_history (action: undo).

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 overwrites the scene's description and metadata and derives the description from location only when description is omitted; directive replaces the active directive; choices replaces the offered 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 a directive, offering choices, or consulting the oracle. Do NOT use when: recording a story beat — use manage_story (action: record); staging presence or autonomy — use manage_staging.

Manage non-player characters in the active Novel. create requires a name; ruleset_reference links a stat block without copying it; mind is GM-only and never returned to the Player badge; remove deletes the NPC permanently. create, update, and remove require the GM or Editor badge, persist to the Novel, are audited, and are undoable via manage_history (action: undo); 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 scene presence, autonomy, and social-cast staging. presence replaces the present set; cast sets the multi-NPC speaker strategy with mute/unmute adjusting its pool; next_speaker runs manual, forced, or pooled selection, where force overrides select; autonomy changes apply to the current scene only. Presence, autonomy, and cast state persist to the Novel and are audited. Use when: setting who is present, adjusting scene autonomy, choosing a speaker strategy, or selecting the next speaker. Do NOT use when: setting the scene, issuing a directive, offering choices, or consulting the oracle — use manage_scene. Revert the most recent mutation with manage_history (action: undo).

Manage countdown timers in the active Novel. set accepts a starting tick count and optional total; advance fires the configured world_effect when the countdown reaches its threshold, and on_scene_transition advances it automatically; direction shifts NPC dispositions only when scope is also set. Mutating actions persist to the Novel and are audited; list is read-only. Use when: starting, advancing, removing, or listing clocks. Do NOT use when: tracking a vow's progress — use manage_vow (action: milestone). Revert with manage_history (action: undo).

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, removing, toggling, grouping, suggesting, listing, exporting, or importing lore, or controlling what an entity knows. Do NOT use when: recording one entity's beliefs or perceptions — use manage_belief; handling cold-reference corpus documents — use manage_corpus.

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 (action: init/advance).

Manage the cold-reference knowledge corpus. corpus_register indexes a document; route derives its domain from a trusted source profile; grant and deny set per-entity access with the latest decision winning; consume records a read; access checks an entity against the recorded grants. Mutating actions persist access state and are audited; list, get, access, and acquisitions are read-only. Use when: registering, listing, reading, routing, granting/denying access, consuming, or inspecting acquisitions of corpus documents. Do NOT use when: writing Novel lore entries or secrets — use manage_lore. Revert the most recent mutation with manage_history (action: undo).

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 faction's territory rooms — use manage_world (action: create_room).

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 — use manage_faction (action: update).

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, persist to the Novel, and are undoable via manage_history (action: undo); resolve and forsake are terminal in the forward direction. Use when: setting, advancing, resolving, forsaking, or listing vows. Do NOT use when: starting a clock timer — use manage_countdown (action: set).

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, Ironsworn, or Forged mechanic, or rolling on a ruleset generation table. Do NOT use when: resolving a ruleset skill check — use the bound ruleset's roll tools; managing vows — use manage_vow (action: set).

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); list is read-only. Use when: recording, editing, removing, listing, or promoting story beats. Do NOT use when: recording a durable world fact — use manage_lore (action: set).

Manage Novel-scoped scratch notes, badge-scoped to game_master (default), player, or shared. set replaces the note content; badge_scope defaults to game_master and controls which badge can read it; set_server stores a server-level note with an optional narrative_tag, and list_server returns summaries unless detail is set. Mutations persist to the Novel and are audited. Use when: storing scratch state the caller will reuse. Do NOT use when: recording durable world facts — use manage_lore (action: set). Revert with manage_history (action: undo).

Manage per-entity evidence, reconciled belief stances, the perception ledger, and a one-entity knowledge query. admit records a subject/predicate/object proposition with a 0..1 weight and does not change a stance until reconcile recomputes it; retract removes the cited evidence and reconciles; the perception ledger is append-only, so correct a mistaken perception with a new record. Mutating actions persist to the Novel; reads are read-only. knowledge_query returns perceptions, beliefs, and known secrets with event provenance, optionally filtered by topic. Use when: inspecting or recording what an entity learned or believes. Do NOT use when: recording objective truth — use manage_causality; recording shared lore — use manage_lore.

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, retains the displaced value in an internal history, and bumps the identity version; reject marks a candidate rejected without touching accepted facets; revert restores the most recently displaced facet. bootstrap seeds from a character card; accept's perspective defaults to the candidate's stored perspective. Mutation persists the roster and is audited; list and snapshot are read-only and report current facets only. Use when: staging, accepting, rejecting, reverting, or reading identity material. Do NOT use when: recording what a character knows or believes — use manage_belief; editing narrative personality — use manage_character (action: personality).

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 are audited, replace the prior projection in one step, and do not persist a separate copy; they are safe to rebuild from the authoritative Novel file, which is never modified. The read actions never mutate state. Use when: building or rebuilding the index or graph, checking staleness, ranking indexed items, or reading relations and graph structure. Do NOT use when: searching a bound ruleset's index — use manage_ruleset (action: search); recording knowledge — use manage_corpus; recording a relationship — use manage_relationship.

Manage durable NPC/agent tasks and their action lifecycle. create reads goal and optional source_goal; advance appends description; complete, fail, and cancel settle the task and terminal tasks are immutable; autonomy defaults to TTRPG_AGENT_AUTONOMY. Mutating actions persist to the Novel and are audited; list/get are read-only. Use when: creating, starting, advancing, settling, or inspecting tasks. Do NOT use when: surfacing an advisory suggestion — use manage_scene (action: oracle); managing NPC identity — use manage_npc. Revert with manage_history (action: undo).

Manage play-facing session controls: recap, verbosity, briefing_order, and tool discovery, distinct from story content and Novel lifecycle. recap accepts an archived session_id, GM-only gm_notes, and an optional compression tier; gm_notes are never returned to a non-GM badge. discover searches names, descriptions, and titles, and detail schema requires query. verbosity is session-scoped; briefing_order persists to the Novel and requires the GM or Editor badge. recap and discover are read-only; a setting is restored by setting it again (no undo snapshot is taken). Use when: recapping play, tuning output verbosity, reordering the briefing, or finding a tool. Do NOT use when: health, audit compaction, event-log, or category operations — use manage_diagnostics; recording story content — use manage_story (action: record).

Manage session diagnostics and maintenance surfaces separate from play-facing session controls. compress summarizes the audit log while compact prunes it irreversibly; verify compares live state with recorded hashes and replay reads the retained log, and both are read-only; visibility_check records its decision in the audit log while visibility_audit reads recent decisions; health, subscribe, and category reassignment do not change Novel content. compact is GM-only. Use when: reporting health, summarizing or compacting the audit log, subscribing, reassigning a category, appending/reading the event log, verifying or replaying state, or scanning a draft for GM-only disclosure. Do NOT use when: recapping play, setting verbosity, or reordering the briefing — use manage_session.

Generate, load, or list adventure content. generate writes an adventure scaffold into the target store (novel by default when one is active; a !force prefix bypasses the guard) and generate_encounter writes one encounter; both persist to the Novel, appear in the audit log, and the most recent write is undoable via manage_history (action: undo). load and list are read-only, and list accepts an optional genre filter. Use when: the GM wants a new adventure scaffold, a single encounter, or to load a prepared module. Do NOT use when: recording a story beat — use manage_story (action: record).

Manage Novel save files: create, resume, switch, end, rename, description, info, genre, complete_session_zero, save_context, get_context, and list. 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, so 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 entity tools; use manage_archive for export, import, archive/unarchive, clone/branch, and checkpoints.

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 source only when absent. Table rolls are resolve_mechanic (action: roll). Use when: searching rules content, managing packages, binding a Novel, or adding/removing supplementary Wisdom. Do NOT use when: the ruleset name is unknown — use manage_session (action: discover).

Manage Novel archival and checkpoint surfaces. Export writes a file; import writes Novel state and mode selects dry-run (validate only), merge (keep existing entries), or replace (discard current Novel state), while strict aborts on unresolved references. archive is reversible with unarchive; checkpoint_restore replaces the live Novel with the stored checkpoint and is itself undoable; checkpoint subscriptions persist. Use when: exporting or importing a Novel, archiving/unarchiving, cloning/branching, or managing checkpoints. Do NOT use when: creating, resuming, renaming, or ending a Novel — use manage_novel. Revert the most recent mutation with manage_history (action: undo); checkpoint_list is read-only.

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); merge=true shallow-merges content. Revert the most recent mutation with manage_history (action: undo). Use when: storing reusable content for later import, or enumerating/reading/deleting it. Do NOT use when: storing Novel-scoped content — use manage_lore (action: set) or manage_note (action: set).

Manage synthesis content (voice examples, lore templates, action patterns, and other Ruleset Wisdom). Mutating actions (run, revert, activate, deactivate, toggle, toggle_action, player_add, player_remove, record_ruling, revert_ruling) persist to the Novel and are audited; read-only actions (list, player_list, verify) do not mutate state. verify checks each item's stored citation locally and reports pass/weak/unsupported; it never fetches and never changes state. record_ruling writes a ruling and its verified citations to the GM-only ruling ledger; revert_ruling marks a ledger entry reverted; ruling_list reads the ledger newest-first. Undo the latest mutation with manage_history. activate/deactivate with key omitted act on the whole module. Use when: running, reverting, listing, activating, deactivating, toggling, verifying, recording or reading rulings, or player-authoring items. Do NOT use when: browsing the codex — use manage_codex (action: list).

Open a play session by resuming a Novel, activating a badge, and returning a recap. novel selects the slug and badge the seat; both are optional and fall back to the active Novel and current badge; resume and badge changes persist and are audited. Use when: starting or resuming a session, especially after a restart. Do NOT use when: creating a Novel — use manage_novel (action: create); running a turn — use take_turn. Revert with manage_history (action: undo).

Close a play session by returning a recap and saving the current context. The close seals the session's recap and saved context but does not archive or export the Novel; resume it later with open_session. Context and recap state persist and are audited; revert with manage_history (action: undo). Use when: ending a session or checkpointing the narrative context. Do NOT use when: archiving or exporting a Novel — use manage_archive.

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