dwroller/AGENTS.md

AGENTS.md - Codex Guide for Deathwatch Roller

This file gives Codex repo-specific context for working on Deathwatch Roller. Prefer the live code and package.json over older docs when they disagree.

Project Snapshot

Deathwatch Roller is a Create React App + Express application for running Deathwatch tabletop RPG sessions. It includes player login and character data, dice rolling, missions, simulations, a requisition shop, bestiary, rules search, weapon references, GM tools, and user-submitted error reports.

The repository is currently a single-root JavaScript app:

• Frontend: React 18 JSX under src/
• Backend: Express server under database/
• Database: MariaDB via mysql2/promise, with some legacy SQLite artifacts
• Static data: JSON and generated assets under public/, data/, database/, and database/rules/
• Tests: Jest + React Testing Library for frontend unit tests; separate integration config for root-level integration tests

High-Value Paths

• src/App.js - main React app, login/session state, tab wiring
• src/components/ - feature UI components
• src/components/DeathwatchRoller.jsx - combat dice roller, weapon mapping, attack rolls, damage, hit locations, history, presets, and tracker state
• src/components/SkillRoller.jsx - sheet-driven skill checks, manual d100 entry, target overrides, and fate-point roll modification
• src/components/rollHelpers.js - shared frontend d100, degrees of success/failure, ids, and fate application helpers used by roller components
• src/utils/diceRoller.js - mission-safe dice helpers and MISSION_ROLL_CONTEXT_KEY
• src/components/MissionTab.jsx - active mission play surface, scene reveal state, check rolling, combat state, initiative, mission roll feed, and GM progress controls
• src/components/SimulationTab.jsx - simulation report UI, run controls, difficulty/profile selection, roll feed display, and saved reports
• src/components/MissionSimTab.jsx - older/generated mission simulator UI; check current routing before extending it
• src/utils/ - shared frontend utilities such as dice and XP logic
• src/tests/ - Jest unit tests run by the default test config
• database/server.js - Express backend entrypoint and route mounting
• database/routes/ - API routes for players, sessions, shop, rules, bestiary, weapons, missions, simulations, staging, and error reports
• database/routes/missionRoutes.js - mission CRUD, active mission selection, player-safe scene projection, active-scene patching, and shared roll feed APIs
• database/routes/simulationRoutes.js - backend simulation engine and simulation CRUD/report APIs
• database/mariadb.js - MariaDB pool, schema creation, schema patching
• database/sessionModel.js - session storage helpers
• database/shop-helpers.js - requisition/shop business logic
• scripts/ - import, cleanup, validation, generation, and local CI helpers
• docs/ - user/developer docs; some structure docs are stale and still refer to non-existent backend/ and frontend/ directories

Commands

Run commands from the repository root unless noted.

npm install
npm start
npm run server:notest
npm run test:unit
npm test
npm run build

Useful variants:

npm run server        # runs tests first, then database/server.js
npm run test:integration
npm run build:fast    # skips tests, then reloads PM2
./scripts/local-ci.sh

Local ports:

• Frontend dev server: http://localhost:3000
• Backend API: http://localhost:5000
• CRA proxy points frontend API requests at http://localhost:5000

Environment And Runtime Notes

• Backend loads environment variables with dotenv from the backend process working directory. npm run server:notest runs from database/, so database/.env is relevant.
• MariaDB connection defaults are hard-coded in database/mariadb.js: host 192.168.1.113, user deathwatch, database deathwatch, port 3307, password from DB_PASSWORD or defaultpassword.
• GM upload auth checks GM_SECRET and falls back to defaultsecret.
• /api/narrate calls Ollama using OLLAMA_BASE and NARRATOR_MODEL.
• The backend can serve build/ statically when a production build exists.

Testing Guidance

• Use npm run test:unit for normal frontend changes.

• Use targeted Jest commands when iterating, for example:

  npm test -- src/tests/login.test.js
  

• Use npm run test:integration only when backend/API behavior is touched and PM2/MariaDB are available.

• npm run build runs unit tests before react-scripts build.

• If tests fail because MariaDB, PM2, Ollama, or local services are unavailable, report that explicitly rather than masking the failure.

Implementation Conventions

• The codebase is plain JavaScript/JSX, not TypeScript. Match the surrounding style unless a broader migration is explicitly requested.
• Prefer existing React hooks/component patterns in src/components/.
• Keep state persistence keys stable; the app uses localStorage keys such as dw:shop:authedPlayer, dw:shop:sessionId, and dw:shop:playerData.
• API calls from the frontend generally use relative /api/... URLs through the CRA proxy.
• Preserve backend response shapes used by existing components and tests.
• Keep database writes parameterized through mysql2 APIs.
• Avoid broad refactors in data import scripts unless the task is specifically about those scripts.

Dice Roller, Mission, And Simulation Notes

Dice Roller

• The main dice roller lives in src/components/DeathwatchRoller.jsx.
• Shared roller primitives live in two places:
  • src/components/rollHelpers.js for UI roller and skill roller behavior.
  • src/utils/diceRoller.js for mission-safe helpers and the mission roll context storage key.
• Core roll semantics:
  • d100() returns 1-100.
  • degrees(target, roll) treats roll <= target as success and reports Degree of Success or Degree of Failure in 10-point bands.
  • Skill and combat roll targets should stay clamped to sensible d100 bounds.
• Combat helpers in DeathwatchRoller.jsx cover dice expressions, weapon normalization, RoF modes, hit counts from DoS, hit location from reversed d100, tearing/proven damage dice, and damage mitigation.
• Skill rolling is delegated to SkillRoller.jsx, which reads the logged-in player's sheet skills/characteristics, applies training modifiers, supports a manual d100 roll, and can override the target number.
• Fate handling is shared by FateControls.jsx, useFate.js, and applyFateToTest() in rollHelpers.js. Spending fate persists through POST /api/players/:name/spend-fate.
• Persistent browser state keys used by the roller include:
  • dw:presets:v3
  • dw:history:v2
  • dw:weapons:v3
  • dw:tracker:v1
  • dw:mission:rollContext

Mission Play

• MissionTab.jsx is the current mission play implementation used from App.js.
• GM users are identified in the UI with authedPlayer === 'gm'.
• GM flow:
  • Load all missions with GET /api/missions.
  • Load the current active mission with GET /api/missions/active/current.
  • Create/update/delete missions through POST/PUT/DELETE /api/missions.
  • Set the active mission with POST /api/missions/:id/active.
  • Save progress and scene edits with PUT /api/missions/:id/progress.
• Player flow:
  • Load only the player-safe active scene with GET /api/missions/active/player.
  • Hidden scene fields are stripped in playerScene() in database/routes/missionRoutes.js.
  • Player mini rollers patch only the active scene through PUT /api/missions/active/scene so they do not overwrite the full mission.
• The shared mission roll feed is backed by the mission_rolls table:
  • Read with GET /api/missions/active/rolls/feed?limit=50.
  • Create with POST /api/missions/rolls.
  • Delete with DELETE /api/missions/rolls/:id.
• Mission scenes may contain checks, objectives, complications, extra challenges, combat state, reveal state, play prompts, enemies, rewards, storyHook, secret, GM notes, and ending text. Preserve unknown scene fields when patching scenes.
• Generated missions should give every scene a GM-only storyHook that acts as a thread toward the mission's main story. Skill check rewards are the visible triggers that reveal the hook; failures should use fail-forward consequences instead of blocking the clue.
• Combat state is scene-local and includes round, initiatives, conditions, and fear rating. Initiative rolls use 1d10 + Ag bonus; fear/check rolls use the same d100 degree helpers as the roller.
• When changing mission roll behavior, verify both GM and player perspectives: the GM sees the full mission, while players only receive the active safe scene.

Simulation

• SimulationTab.jsx is the current simulation report and control UI.
• database/routes/simulationRoutes.js contains the backend simulation engine. It loads mission/player data, builds temporary player combat state from tabInfo, runs scenes, and saves reports through simulationHelpers.
• Simulation endpoints:
  • POST /api/simulations runs and saves a new simulation.
  • GET /api/simulations?limit=50 lists saved simulation summaries.
  • GET /api/simulations/:id returns a full saved report.
  • DELETE /api/simulations/:id removes a saved report.
• Simulation request inputs include mission_id, player_names, difficulty, per-player combat_profiles, and enemy_profile.
• Difficulty levels are 1-5 and affect wounds, enemy BS, check modifiers, fear, extra enemies, recovery, and max combat rounds.
• Combat profiles include auto, balanced, ranged, and melee; they affect weapon choice, grenade use, and enemy attack style.
• The simulation engine normalizes weapons from player tabInfo.weapons, infers ammo/clip defaults for common Deathwatch weapons, tracks ammo spend, resolves single/semi/full-auto hit counts, rolls initiative each combat round, applies conditions, performs fear tests, spends fate once when useful, and builds roll feeds/player report cards.
• Saved simulation reports include result, earned XP, total rounds, total rolls, overall success rate, combat success rate, puzzle/check success rate, scene results, player cards, roll feed, story hooks, findings, difficulty_level, and enemy_profile.
• Because simulations use Math.random() directly and are not seeded, tests and docs should avoid assuming deterministic exact roll output.

App Tabs

Tabs are selected in src/App.js with the tab state. Login/session state is owned by App.js and passed to tabs as authedPlayer and sessionId where needed. Navigation actions are logged with logUserAction().

Mission

• Component: src/components/MissionTab.jsx
• Default tab: mission
• Availability: all logged-in states, but GM and player views differ.
• Backend: /api/missions, /api/missions/active/current, /api/missions/active/player, /api/missions/active/scene, and mission roll feed endpoints.
• Notes: GM sees full mission state; players receive only the active safe scene. Preserve unknown scene fields and avoid replacing the full scene array from player-facing actions.

Dice Roller

• Component: src/components/DeathwatchRoller.jsx
• Tab key: roller
• Availability: visible to all users.
• Backend: player sheet/fate endpoints, bestiary enemy data where loaded, and mission roll context when launched from mission play.
• Notes: Depends on SkillRoller.jsx, FateControls.jsx, useFate.js, rollHelpers.js, and src/utils/diceRoller.js. Keep d100/DoS behavior aligned across mission, skill, and combat rolls.

Requisition Shop

• Component: src/components/RequisitionShop.jsx
• Tab key: shop
• Availability: visible to all users; GM controls appear for authedPlayer === 'gm'.
• Backend: GET /api/shop, POST /api/shop/purchase, GET /api/players/:name, GET /api/players, POST /api/players/gm/set-rp, and POST /api/players/gm/set-renown.
• Data source: public/deathwatch-armoury.json through shopRoutes.js.
• Notes: Purchases deduct tabInfo.rp and append/update tabInfo.gear. Renown gating uses the local rank order in the component.

Character Sheet

• Component: src/components/PlayerTab.jsx
• Tab key: fallback branch when no other tab matches; nav label is Character Sheet.
• Availability: visible to all users; GM edit tools are enabled only when the logged-in user is gm.
• Backend: GET /api/players, GET /api/players/:name, PUT /api/players/:name, avatar upload under POST /api/players/:name/avatar if present, and GM player endpoints.
• Local state: caches player data under dw:shop:players:v1 and also consumes dw:shop:playerData as a fallback.
• Notes: Character data is stored primarily in tabInfo and includes characteristics, skills, weapons, armour, gear, wounds, fate, XP, XP spent, renown, movement, insanity, corruption, notes, and avatar/picture data. Preserve tabInfo shape because the roller and simulator read it directly.

Rules

• Component: src/components/RulesTab.jsx
• Tab key: rules
• Availability: visible to all users.
• Backend: GET /api/rules/categories, GET /api/rules/search, GET /api/rules/rule/:id, and GET /api/rules/random.
• Local state: recent searches are stored as dw:rules:recent.
• Notes: Results include structured fields such as summary, examples, category, source, page, aliases, tags, and midgame priority. Keep highlighting and compact/full rendering behavior when changing rule result shapes.

Weapons

• Component: src/components/WeaponsTab.jsx
• Tab key: weapons
• Availability: visible to all users.
• Backend: GET /api/weapons.
• Data source: MariaDB weapons when available, with fallback to public/deathwatch-armoury.json.
• Notes: The tab normalizes displayed categories into ranged, melee, grenade, armour, and other. Ranged stat strings may be parsed from semicolon-separated fields in stats.damage.

Error Reports

• Component: src/components/ErrorReports.jsx
• Tab key: errors
• Availability: visible to all logged-in users; GM sees all reports and can resolve/delete.
• Backend: GET /api/errors, POST /api/errors, PUT /api/errors/:id/resolve, PUT /api/errors/:id/status, and DELETE /api/errors/:id.
• Auth: requires x-session-id; backend uses requireSession.
• Notes: Non-GM users should only see their own reports. Form submissions default pageUrl to the current browser path when not provided.

Bestiary

• Component: src/components/BestiaryTab.jsx
• Tab key: bestiary
• Availability: GM-only in App.js; non-GM users see an access denied panel.
• Backend: GET /api/bestiary/full, POST /api/bestiary/reload, and GET /api/bestiary/enemies for dice roller enemy format.
• Local state: caches entries under dw:enemies:v1; DB-down warning dismissal uses dw:warning-dismiss-until:v1.
• Data source: MariaDB bestiary rows with fallback to public/deathwatch-bestiary-extracted.json.
• Notes: normalizeEntry() handles multiple imported statblock shapes. Keep fallback/cache behavior intact so the tab remains useful when the DB is down.

Player Management

• Component: src/components/PlayerManagement.jsx
• Tab key: players
• Availability: GM-only nav item. The component also expects GM context.
• Backend: GET /api/players, POST /api/players/gm/add-or-update, POST /api/players/gm/set-xp, POST /api/players/gm/set-xp-spent, POST /api/players/gm/set-rp, POST /api/players/gm/set-renown, POST /api/players/gm/reset-password, and DELETE /api/players/gm/delete/:name.
• Auth: sends x-session-id and x-gm-secret where available; backend GM secret defaults are defined in playerRoutes.js.
• Notes: Bulk XP/RP operations update each player in sequence. The component expects player economic and progression values in tabInfo.

GM Kit

• Component: src/components/GMKit.jsx
• Tab key: gmkit
• Availability: GM-only nav item and component-level access check.
• Backend: none for the current table UI; App.js separately uses GET /api/gmkit/list to choose the players-tab background.
• Notes: Current GM Kit is static reference tables inside the component: difficulty modifiers, hit locations, combat actions, weapons, armour, critical hits, weapon qualities, cover, renown, and related GM references. There are older GMKit_old.jsx and GMKit_new.jsx files; check routing before editing them.

Simulation Lab

• Component: src/components/SimulationTab.jsx
• Tab key: simulation
• Availability: GM-only nav item in App.js.
• Backend: /api/simulations endpoints and mission/player data loaded by the backend simulation route.
• Notes: Reports include roll feeds, scene logs, player report cards, story hooks, findings, difficulty, and enemy profile. Simulation output is non-deterministic.

External Utility Pages

• public/cards.html is linked from nav as Kort and opens in a new tab. It is a printable card-sheet view and fetches app/static data directly from the served public site.
• public/print.html is linked from nav as Print and opens in a new tab. It is a printable quick-reference sheet.
• These are not React tabs. They are static public pages served by CRA/dev server or by Express static serving in production.

Deathwatch RPG Domain Notes

Use these notes when changing the app's roller, mission, simulation, shop, rules, bestiary, and character-sheet flows. They are summarized from the local rules database and app data, not copied from rulebook text. Do not paste long rulebook passages into UI or docs; link/search the local rules DB and summarize mechanics in original wording.

Source Data In This Repo

• Rules index: database/rules/rules-database.json
  • Categories include actions, combat, damage, conditions, requisition, renown, cohesion, squad_mode, psychic, hordes, gm_tables, mission, skills, talents, and traits.
• Skill import/reference data: database/deathwatch_skills_p94_107.csv
• Armoury/shop data: public/deathwatch-armoury.json
  • Major groups include ranged weapons, melee weapons, grenades, other weapons, power armour, helmets, carapace/natural/primitive/xenos armour, shields, and other armour.
• Bestiary data: public/deathwatch-bestiary-extracted.json and database/deathwatch-bestiary-extracted.json
  • Entries generally include profile, movement, wounds, toughness, skills, talents, traits, armour, book, page, and snippets.
• Backend may load rules, weapons, and bestiary from MariaDB first, then fall back to the JSON files above.

Core Resolution Model

• Deathwatch uses percentile tests: roll d100 and succeed when the roll is equal to or under the effective target.
• Effective target is normally characteristic + skill/training + situational modifiers. The app generally clamps practical targets to d100 bounds.
• Degrees of Success/Failure are 10-point bands from the target/roll margin. The app's shared helper returns 1 base degree plus one per full 10 points.
• Basic skills can be attempted broadly; untrained advanced skills should be treated as unavailable or heavily constrained unless the app explicitly allows an override.
• Common characteristics:
  • WS Weapon Skill for melee attacks and parries.
  • BS Ballistic Skill for ranged attacks.
  • S, T, Ag, Int, Per, Wp, Fel for strength, toughness, agility, intelligence, perception, willpower, and fellowship checks.
• When making UI for tests, expose the final target, roll, success/failure, DoS/DoF, and the source of modifiers. This is more useful at the table than only showing pass/fail.

Combat Flow

• Combat is round-based and action-based. Common action concepts include Aim, Charge, Standard Attack, Semi-Auto Burst, Full Auto Burst, Overwatch, Suppressing Fire, Dodge, Parry, Ready, Reload, Move, Run, and Disengage.
• Initiative is relevant to combat order. In the simulator, each combat round currently rolls player Agility Bonus + d10 and enemy agBonus + d10, then resolves actors from highest to lowest.
• Attack flow for app purposes:
  • Choose WS or BS based on melee/ranged attack.
  • Apply attack-mode and situation modifiers.
  • Roll d100 against target.
  • On a hit, derive hit count from fire mode and DoS.
  • Determine hit location from the reversed d100 attack roll where needed.
  • Roll damage, apply weapon qualities such as Tearing/Proven where supported.
  • Reduce damage by armour and Toughness Bonus/Penetration handling as the app model supports.
  • Track wounds, critical damage threshold, defeat/downed status, and notable events.
• Semi-auto and full-auto are not just labels. They change the attack modifier and how additional hits scale with DoS. Keep roller and simulator hit-count formulas aligned.
• Dodge and Parry are reactions that negate hits when allowed. Dodge is usually the generic ranged/melee avoidance reaction; Parry is melee and WS-based.
• Suppressing fire and pinning matter in Deathwatch combat. Pinned targets are constrained and should be represented as a condition when simulation or mission play needs battlefield pressure.
• Righteous Fury is a special high-damage/exploding-damage style event on successful attacks. The simulator currently records "critical hit"/hero moments for high DoS, while the roller has damage dice mechanics; be explicit if changing this behavior to match a stricter table interpretation.

Weapons, Damage, Armour, And Qualities

• Weapon data often appears as compact strings like range, RoF, damage, penetration, clip, reload, and qualities. Prefer structured parsing helpers over ad hoc display-only splitting when adding behavior.
• Damage expressions use dice notation such as 1d10+9, 2d10+2, or 3d10+4, with a damage type marker in source data (E, I, R, X, etc.) for energy, impact, rending, explosive, and related categories.
• Important weapon qualities represented in app data include Tearing, Reliable, Accurate, Blast, Flame, Power Field, Razor Sharp, Unbalanced, Unwieldy, Volatile, Scatter, Storm, Smoke, Toxic, and others.
• Tearing usually means roll extra damage dice and keep the better result for supported dice. Proven sets a floor on supported damage dice. Only apply qualities that the code explicitly models.
• Armour can be whole-body or location-based. Bestiary and armoury entries may use different shapes for protection values, so normalize before using in combat calculations.
• Penetration should reduce armour effectiveness, not Toughness, unless a local helper intentionally abstracts damage.

Missions, Requisition, Renown, And Economy

• Deathwatch missions are framed around a kill-team selecting mission gear, entering an operation, resolving scenes, earning XP/renown, and returning equipment.
• Requisition Points are mission equipment budget, not ordinary money. The shop stores purchases as gear and deducts tabInfo.rp.
• Renown gates access to more prestigious or restricted equipment. The app rank order is None, Respected, Distinguished, Famed, Hero; keep that order consistent in shop and player-management flows.
• Mission scenes in this app can include objectives, complications, checks, enemies, combat state, reveal state, extra challenges, rewards, and ending text.
• Good mission UI should separate GM-only information from player-safe scene information. The backend playerScene() projection strips hidden/GM fields.

Skills And Scene Checks

• Useful scene-check skills from the local skill data include Awareness, Command, Tactics, Tech-Use, Medicae, Scrutiny, Search, Logic, Inquiry, Intimidate, Demolition, Tracking, Survival, Security, Psyniscience, and relevant Lore skills.
• Tactics is an Intelligence skill and should be used for battlefield doctrine, priority targets, ambush reads, deployments, or tactical approach. It should not automatically grant Squad Mode abilities or Cohesion benefits unless a mission rule explicitly says so.
• Awareness/Search/Tracking are good for threat and clue discovery.
• Tech-Use/Security/Demolition are good for machines, locks, traps, explosives, and sabotage.
• Medicae/Chem-Use are good for injuries, toxins, infection, biology, and field treatment.
• Command/Charm/Intimidate/Scrutiny/Deceive support social or morale scenes.
• Puzzle scenes should usually produce multiple checks with assigned best-fit players, visible targets, complications on high DoF, and rewards on success.

Cohesion, Squad Mode, Solo Mode, And Fate

• Cohesion is the kill-team resource around coordination and Squad Mode. Existing app coverage is mostly reference/rules-search level; do not invent persistent Cohesion behavior without adding explicit state and tests.
• Squad Mode and Solo Mode are distinct from ordinary skill checks. A successful Tactics or Command roll should not silently toggle Squad Mode.
• Fate points can be spent to improve outcomes. In this app:
  • The roller exposes re-roll, +10, and +DoS style fate actions.
  • useFate.js reads and persists fate through player endpoints.
  • The simulator may spend fate once on severe failed checks.
• Keep fate changes persistent and visible because players track remaining fate across scenes/sessions.

Psychic Powers And Warp Risk

• Psychic rules involve Focus Power tests, Psy Rating, and risk modes such as safer/fettered use versus riskier high-output use.
• Psychic Phenomena and Perils of the Warp are significant consequences. If adding psychic automation, model risk and output separately and expose the roll trail clearly.
• Avoid treating psychic powers as generic skills unless the feature explicitly asks for a simplified helper.

Hordes And Large Enemy Groups

• Hordes are a special combat abstraction for many lesser enemies. They should not be treated as a single normal NPC unless the app is intentionally using a simplified profile.
• Horde-relevant UI should track magnitude/remaining threat, area effects, full-auto/multi-hit attacks, Blast, Flame, and morale/breaking behavior.
• Current simulation uses simplified enemy lists and wounds, not a full horde engine.

Bestiary And Enemy Modeling

• Bestiary entries vary by source and import quality. Normalize names, profile stats, wounds, armour, movement, talents, traits, and attacks before using them in roller/simulation logic.
• Common enemy themes in app code include Tyranids, Chaos, Xenos/Tau, Orks, and servitor/Imperial profiles.
• For combat simulation, prefer clear approximations and visible findings over opaque precision. If a stat is missing, surface the fallback rather than pretending it came from the book.

Simulation Design Guidance

• Simulation is a balance/design tool, not an authoritative rules engine.
• Keep simulated rolls categorized. Current categories include:
  • combat for attacks and combat-scene tactical checks.
  • puzzle for non-combat scene checks.
  • fear for fear tests.
• Reports should show overall success %, combat %, puzzle/check %, XP, rounds, roll count, scene results, player report cards, ammo/fate use, conditions, initiative events, and findings.
• Findings are scripted threshold notes, not AI. They do not use OpenAI/Ollama tokens unless a future feature explicitly calls an AI endpoint.
• Story hooks are scripted from mission scene data. Mission generation stores a GM-only storyHook/secret on each scene; simulation reports which checks or combat outcomes revealed, partially revealed, or escalated those hooks.
• Scripted findings should give the GM actionable mission edits grounded in the rules model: reduce or increase enemy pressure, add cover/Aim/Dodge/Parry prompts, add non-attack combat objectives, tune puzzle difficulty, allow assists/alternate skills, prevent single-roll clue bottlenecks, add recovery beats for conditions/fear, and match player roles to checks.
• Evaluate combat and puzzle/skill pressure separately. A good sim report should make it clear whether the mission is too lethal, too easy, too attack-only, too clue-blocked, or mismatched to the party's stats.
• Because simulation uses Math.random() and is unseeded, never make exact roll totals a test expectation. Test shape, categories, persistence, and visible report fields instead.

Copyright And Wording

• The repo contains local summaries, OCR, PDFs, and extracted data for gameplay support. When writing UI/help/docs, use short summaries in original wording.
• Do not reproduce long rulebook sections, tables, or copyrighted passages in new docs or UI. Prefer links/search into local rule entries and cite source title/page metadata where helpful.
• If a requested feature needs exact rules text, build a lookup/display path from the existing rules database instead of embedding copied text in code.

API Surface

Mounted API prefixes in database/server.js include:

• /api/players
• /api/sessions
• /api/shop
• /api/rules
• /api/weapons
• /api/bestiary
• /api/rules/staging
• /api/missions
• /api/simulations
• /api/errors
• /api/gmkit/list
• /api/gmkit/upload
• /api/copy-bestiary
• /api/narrate

Static serving includes /gmkit, /weapon-images, and /avatars.

Files To Treat Carefully

• Do not commit or churn runtime logs such as database/backend.log or database/server.log.
• Do not overwrite database files, backups, generated JSON, PDFs, OCR output, or imported rulebook data unless the user specifically asks for data work.
• public/ and database/ contain generated/reference JSON used by the app; update paired files intentionally when scripts require it.
• There may be unrelated local changes. Inspect git status --short before editing and avoid reverting user work.

Documentation Notes

• README.md and DEVELOPMENT_GUIDE.md are useful, but several docs under docs/ and CLAUDE.md mention an older split backend/ + frontend/ structure. The current live structure is root CRA frontend plus database/server.js backend.
• When updating docs, prefer correcting stale structure references rather than propagating them.