First Commit

README.md

@@ -0,0 +1,44 @@
+# RQ3 Story Tool
+
+A solo web app for narrative-driven play using RuneQuest 3rd Edition rules with a custom fiction layer.
+
+## Setup
+
+```bash
+npm install
+```
+
+The first time you run the app, the SQLite database is created automatically at `data/story-tool.db` from `db.js`'s schema.
+
+### Importing the table files
+
+`tables/*.md` are converted into the database once, then the database is authoritative (the `.md` files can be deleted afterward):
+
+```bash
+npm run import-tables
+```
+
+Re-running this command wipes and rebuilds the imported table tree, NPC-field detection, and the Norse Layer 1→2 table links - safe to re-run any time the `.md` files change.
+
+## Run
+
+```bash
+npm start
+```
+
+Then open `http://localhost:3000`.
+
+## Project layout
+
+- `db.js` - SQLite schema and all query helpers (npcs, enemies, log, combat state, imported tables, spell mappings).
+- `rq3.js` - the RuneQuest 3rd Edition rules engine. Pure functions only, no DB/HTTP dependencies.
+- `server.js` - Express routes. All state changes go through `/api/*` and are logged.
+- `lib/markdownTableParser.js` - parses the heading/table structure out of `tables/*.md`.
+- `scripts/import-tables.js` - one-time markdown → SQLite conversion (see above).
+- `public/` - the frontend (`index.html`, `app.js`, `style.css`). Plain JS, no framework, no rules logic - everything goes through the API.
+
+## Notes
+
+- The fiction layer (NPC names, encounter flavor text, custom spell names) lives entirely in the database (originally seeded from `tables/*.md`) and never touches the RQ3 rules engine in `rq3.js`.
+- Spell name → mechanic mappings are managed via `/api/spell-mappings` rather than markdown, since the table content has already moved into the database.
+- Closing the tab while there are unexported changes triggers an export reminder; data is also safely persisted in SQLite regardless.