io.github.flukeatzerocool/holonovel

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. With no novel and no active Novel, it resumes the only Novel on the server (on a fresh install, the seeded starter), and refuses naming the available slugs when several exist. resume closes the current session window, switches the active Novel, and increments its session count; a badge change persists, is audited, and re-filters tools/list immediately; neither deletes prior Novel state. Session and badge changes are not undoable via manage_history. 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.

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).

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.

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.

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.

Resolve a player intent through the parser and mint a turn handle for the story record. intent is free text parsed by the command resolver; entity_id optionally scopes the parse to the acting entity. 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. Repeated calls mint fresh handles rather than resuming the prior one. 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).