loreweaver: Instructions file for Codex

AGENTS.md — contributor & AI-agent guide

Loreweaver is a self-hosted AI Game Master / Keeper for tabletop RPGs: a world/story-first engine (structured world + module + rules + persistent state), not a persona-chat frontend. Terminal-first over Iroh p2p, system-agnostic (D&D 5e SRD + CoC 7e), English-first with runtime en/zh i18n, MIT. This file orients humans and AI coding agents working in the repo — it is the single source of truth (CLAUDE.md just imports it). User-facing docs live in README.md; the open client protocol in docs/protocol.md; the extensibility contract in docs/plugins.md. The formats themselves are specified in docs/lwf/ (LWF, CC BY 4.0): a change to a pack/card/rulepack/hook/panel format updates the matching docs/lwf/formats/*.md in the same commit.

Architecture (layers, each with one job)

• core/ — deterministic engine (never AI-generated), rule-AGNOSTIC since M16: dice, resolution (pack-compiled check ladders + the QuickJS rules_script lane), sheets (pack-declared sheet shapes: canonical-name bridges, derived DAG — derived values are NEVER persisted — vitals, wire resources), character_rules (pack-constraint validation on every stat write path), clock, rulepacks (data-driven rule systems: resolution/sheet/subsystems/commands/expertise all pack data; tests/architecture/ pins agent/ to zero system tokens), skills (SKILL.md loader), deterministic relationship tracks, modvars (deterministic module-variable trackers), worldbook, charcard (SillyTavern-card parser), table_habits — the M20 E procedural-memory type (how THIS table plays; keeper-side only, player projection returns None, index-only residency), chronicle — the M18 campaign-history types (chronicle/campaign_summary/thread: projections keep keeper annotations out of every player-grade view) plus the deterministic fold policy (0.60 trigger / 0.40 floor / 0.85 emergency, 4-turn no-future lag window), and documents — the M17 meta-type: ALL room content (lore/NPCs/sheets/pregens/modvars/MVU tree/notes/pools) is a Document in one table, and every type's project(doc, viewer) is THE single wire chokepoint for iron rule #3.
• infra/ — plumbing: SQLite store (documents + room_state + kv tables — content documents, room-scoped runtime state, non-room leftovers), pydantic-settings config + hot runtime overrides/credential book, i18n, llm/embeddings (each with a Fake* offline double), vector, providers (multi-vendor LLM factory).
• agent/ — the AI-KP brain: AgentCtx, tools (@tool schema-gen + gating), kp_tools* (the Keeper tools), forge (self-extension generators: skill/rulepack/module from a description), prompt_builder, loop (function-calling loop), services (the wiring bundle), chronicle (the M18 fold flow: batch-fold old chronicle records into the rolling campaign_summary when the usage meter crosses the trigger; folded records join the embedding index for topical recall — records themselves are AUTO-WRITTEN since M21 by the Scribe, one player-grade line per material turn at zero extra model calls, so durable memory and the history trim that rides on it never depend on the Keeper remembering record_chronicle; the keeper spoiler margin stays exclusive to that voluntary tool), knowledge-scoped npc/companion actors, and the three model-driven prep lanes that used to sit in core/ — module_initializer (full-text module analysis into the keeper/player pools), document_manager (chunking + RAG answers), char_from_persona (persona → rule-legal sheet; the validation half stays in core.character_rules).
• gateway/ — platform-independent: session/events/turn/member/room state, commands/ (dual-dialect + slash — a package: router owns the spec table and dispatch, each domain is a mixin module checks/sheet/rules/rooms/cast/world/panels/media/llm/forge; a new command lands in its domain module plus one spec row, never in the turn pipeline), ops (rate-limit/censor/permissions), hub (the cross-transport RoomHub), director.
• net/ — session (transport-agnostic SessionCore), iroh_server (p2p QUIC, the DEFAULT carrier), tui_server (WebSocket, offline-test/loopback only), keystore, admin, room_backup.
• adapters/ — cli only (the local operator REPL). The five chat-platform adapters (Discord/QQ/Telegram/Feishu/OneBot) were REMOVED 2026-07-30: the UI direction is protocol clients with a deeply customizable UI extension layer (ui frames, panels), which text-chat platforms structurally cannot render. Don't re-add platform adapters; build against docs/protocol.md instead. The QQ path is a protocol client, the terminal client's bridge mode (official Bot API first, OneBot second).
• clients/ — TypeScript: protocol (shared types + WsClient; published to npm as loreweaver-protocol, whose major.minor tracks the wire-protocol version), tui (OpenTUI terminal client; IrohClient and the one-click host live here). Both speak docs/protocol.md. The DESKTOP client — Loreweaver Studio, Tauri (Rust transport + React UI), play mode with tier-1/tier-2 panels and the keeper screens plus the card/pack studio — lives in the separate loreweaver-studio repo and is the recommended player client; it consumes loreweaver-protocol from npm and pins itself to the engine with a cross-repo round-trip gate (bun run roundtrip there). Changing the protocol or a pack format here means that gate must be rerun there. Bumping the protocol means bumping it in all five places at once — net/session.py (the authority), protocol/src/types.ts, the npm manifest's version + description, protocol/README.md, docs/protocol.md — pinned by tests/architecture/test_protocol_version_sync.py.