feat(rules): Rifts rules engine — attributes, dice, LLW O.C.C., combat, skills

.gitignore

@@ -0,0 +1,34 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/settings.json
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# AI agent worktrees
+.claude/worktrees/
+
+# Session memory (local only)
+.remember/
+
+# Source rulebook — copyrighted (Palladium Books); kept local, never committed
+docs/rules/*.pdf

CLAUDE.md

@@ -0,0 +1,16 @@
+<!--VITE PLUS START-->
+
+# Using Vite+, the Unified Toolchain for the Web
+
+This project is using Vite+, a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task. Vite+ wraps runtime management, package management, and frontend tooling in a single global CLI called `vp`. Vite+ is distinct from Vite, and it invokes Vite through `vp dev` and `vp build`. Run `vp help` to print a list of commands and `vp <command> --help` for information about a specific command.
+
+Docs are local at `node_modules/vite-plus/docs` or online at https://viteplus.dev/guide/.
+
+## Review Checklist
+
+- [ ] Run `vp install` after pulling remote changes and before getting started.
+- [ ] Run `vp check` and `vp test` to format, lint, type check and test changes.
+- [ ] Check if there are `vite.config.ts` tasks or `package.json` scripts necessary for validation, run via `vp run <script>`.
+- [ ] If setup, runtime, or package-manager behavior looks wrong, run `vp env doctor` and include its output when asking for help.
+
+<!--VITE PLUS END-->

README.md

@@ -1 +1,48 @@
-# RiftForge
+# RiftForge
+
+A smart character builder and interactive character sheet for the **Rifts®** TTRPG
+(Palladium Books, _Rifts Ultimate Edition_) — think "D&D Beyond, but for Rifts."
+
+Two halves:
+
+1. **Guided builder** — a step-by-step wizard that walks you from a blank slate to a
+   rules-legal character, enforcing the rules as you go.
+2. **Live character sheet** — roll saves, attacks, skill checks, and damage with every
+   modifier already derived from the build.
+
+## Architecture
+
+The hard part isn't the web app — it's encoding the game rules. Those live in a
+standalone, framework-agnostic package so they can be validated and tested in isolation:
+
+```
+packages/rules/
+  src/content/   rules as page-stamped JSON (transcribed from the rulebook)
+  src/schema/    Zod schemas that validate the content at load
+  src/engine/    pure TypeScript that derives every number (no backend, no UI)
+```
+
+A Convex backend (planned) will seed and serve the validated content; the runtime never
+parses the source book.
+
+### Current status
+
+First vertical slice — the **Ley Line Walker** O.C.C. — end to end: attributes → O.C.C. →
+P.P.E. → combat/HP → skills. Magic + spells and the Convex backend are next.
+
+## Development
+
+Tooling is [Vite+](https://viteplus.dev) (`vp`) over a pnpm workspace.
+
+```bash
+vp install            # install dependencies
+vp run rules#test     # run the rules-engine tests
+vp run rules#check    # format + lint + typecheck
+vp run ready          # check + test + build across the workspace
+```
+
+## Source material
+
+The `Rifts Ultimate Edition` rulebook PDF is **not** committed (it's copyrighted by
+Palladium Books); it lives locally under `docs/rules/` and is git-ignored.
+`docs/rules/PAGE_MAP.md` indexes where each rule is transcribed from.

docs/rules/PAGE_MAP.md

@@ -0,0 +1,104 @@
+# Rifts Ultimate Edition — Page Map
+
+Index of where each rule lives, built by reading the book's Table of Contents.
+Source: `Rifts-Ultimate-Edition-Main-Book.pdf` (382 pages, scanned images — no text layer).
+
+**Page offset:** `PDF page index (0-based) = printed page number + 2`.
+(e.g. printed p.113 → PDF index 115. Verified against front matter.)
+
+The PDF has no extractable text; all content is transcribed from page images via
+vision extraction (`scratchpad/extract_pages.py` renders a page to PNG for reading).
+
+---
+
+## Character Creation spine (`Game Rules`, printed 274+)
+
+| Section                                                            | Printed pp. | PDF idx |
+| ------------------------------------------------------------------ | ----------- | ------- |
+| Character Creation (overview)                                      | 279         | 281     |
+| Step 1: The Eight Attributes                                       | 279         | 281     |
+| — Attribute Bonus Chart                                            | 281         | 283     |
+| — Speed Chart                                                      | 281         | 283     |
+| — Attributes Below Average                                         | 281         | 283     |
+| — Attributes Beyond Thirty (Augmented/Robot/Supernatural PS)       | 284–286     | 286–288 |
+| Step 2: Understanding Damage Ratings (Physical S.D.C., Hit Points) | 286–288     | 288–290 |
+| Step 3: Understanding Mega-Damage & M.D.C.                         | 288         | 290     |
+| Step 4: Determine Psionics                                         | 289         | 291     |
+| Step 5: Pick an O.C.C. & Skills                                    | 289         | 291     |
+| Step 6: Pick an Alignment                                          | 289         | 291     |
+| Step 7: Character Advancement / Experience Level System            | 292–295     | 294–297 |
+| — O.C.C. Experience Tables                                         | 295         | 297     |
+| Step 8: Rounding out the Character                                 | 296         | 298     |
+
+## Skills (printed 298+)
+
+| Section                                                               | Printed pp. | PDF idx |
+| --------------------------------------------------------------------- | ----------- | ------- |
+| Skill Rules (Selecting, Bonuses, Penalties)                           | 298–301     | 300–303 |
+| — O.C.C. / O.C.C.-Related / Secondary Skills                          | 299–300     | 301–302 |
+| Skill List                                                            | 302         | 304     |
+| Skill Descriptions (all categories)                                   | 304–329     | 306–331 |
+| — Communication 304 · Domestic 307 · Electrical 308 · Espionage 308   |             |         |
+| — Mechanical 312 · Medical 313 · Physical 316 · Pilot 318 · Rogue 320 |             |         |
+| — Science 321 · Technical 323 · W.P. 326 · Wilderness 329             |             |         |
+
+## Combat & Saving Throws (printed 339+)
+
+| Section                                                      | Printed pp. | PDF idx |
+| ------------------------------------------------------------ | ----------- | ------- |
+| Combat Rules (Hand to Hand, Sequence, Terms & Moves)         | 339–346     | 341–348 |
+| Hand to Hand Combat Skills (Basic/Expert/MA/Assassin tables) | 347         | 349     |
+| Battle Injuries & Recovery / Surviving Coma & Death          | 354         | 356     |
+| Mega-Damage & M.D.C.                                         | 355–359     | 357–361 |
+| Ranged Combat (Modern WP, Dodging, Missiles)                 | 360–365     | 362–367 |
+| Psychic Combat / Horror Factor / Perception Rolls            | 366–367     | 368–369 |
+
+## Magic (printed 185+) — needed for Ley Line Walker
+
+| Section                                                                          | Printed pp. | PDF idx |
+| -------------------------------------------------------------------------------- | ----------- | ------- |
+| Principles of Magic (Building/Recovering P.P.E., Saving Throw vs Magic, Casting) | 185–190     | 187–192 |
+| Ley Lines & Rifts                                                                | 191–196     | 193–198 |
+| Magic Spells by level (1–15)                                                     | 197–225     | 199–227 |
+| — Level One 198 · Two 199 · Three 202 · Four 204 · Five 206 …                    |             |         |
+
+## Psionics (printed 164+)
+
+| Section                                              | Printed pp. | PDF idx |
+| ---------------------------------------------------- | ----------- | ------- |
+| Psionic Powers (Healing, Physical, Sensitive, Super) | 164–184     | 166–186 |
+
+## O.C.C.s — Practitioners of Magic (printed 100+)
+
+| O.C.C.                                             | Printed pp. | PDF idx     |
+| -------------------------------------------------- | ----------- | ----------- |
+| **Ley Line Walker** (Body Armor, Abilities, Stats) | **113–116** | **115–118** |
+| Ley Line Rifter                                    | 116–117     | 118–119     |
+| Mystic                                             | 118–119     | 120–121     |
+| Shifter                                            | 120–125     | 122–127     |
+| Techno-Wizard                                      | 126–137     | 128–139     |
+| Elemental Fusionist                                | 100–104     | 102–106     |
+
+Full O.C.C. roster spans printed 45–99 (men-at-arms, adventurers/scholars) and
+100–137 (practitioners of magic), plus psychics 138–163 and Coalition 231–237.
+
+---
+
+## Slice #1 target — Ley Line Walker (pages to extract)
+
+Foundation (needed by every character):
+
+- Attribute Bonus Chart + Speed Chart — printed 281 (PDF 283)
+- S.D.C. / Hit Points rules — printed 286–288 (PDF 288–290)
+- Alignment — printed 289 (PDF 291)
+- Combat: attacks per melee + strike/parry/dodge + saving throw table — printed 339–346 (PDF 341–348)
+- HTH Combat Skills table — printed 347 (PDF 349)
+
+Ley Line Walker specifics:
+
+- LLW O.C.C. entry (abilities, bonuses, skills granted, P.P.E., equipment, stats) — printed 113–116 (PDF 115–118)
+
+Magic subsystem:
+
+- Principles of Magic / P.P.E. / Saving Throw vs Magic — printed 185–190 (PDF 187–192)
+- A handful of low-level spells for the sheet — printed 198–202 (PDF 200–204)

package.json

@@ -0,0 +1,22 @@
+{
+  "name": "riftforge",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "ready": "vp check && vp run -r test && vp run -r build"
+  },
+  "devDependencies": {
+    "vite-plus": "catalog:"
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "11.9.0",
+      "onFail": "download"
+    }
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  }
+}

packages/rules/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@riftforge/rules",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Rifts Ultimate Edition rules: page-stamped content, Zod schemas, and a pure derivation engine.",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "test": "vp test",
+    "check": "vp check",
+    "build": "vp pack"
+  },
+  "dependencies": {
+    "zod": "^4"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "typescript": "catalog:",
+    "vite-plus": "catalog:"
+  }
+}