ttrpg-engine-dnd 0.1.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+Notable changes to this project. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). The bump policy and pre-release roadmap are documented in [VERSIONING.md](VERSIONING.md).
+
+## 0.1.0-alpha.0 (2026-05-12)
+
+First alpha. All six phases of the roadmap are complete except the optional `ttrpg-engine-core` extraction. Forty-six slices shipped across engine mechanics, state schemas, combat fill-in, adoption surface, and 2024 content.
+
+### Engine architecture (Phase A, Slices 1-16)
+
+- Event-sourced state machine. `apply(state, event) -> state` is pure; `replay(events)` reconstructs state byte-for-byte.
+- Plan/commit split: all RNG is consumed inside `engine.plan.*` planners; resolution events carry baked rolls. `apply()` never touches RNG. Tested via `ThrowOnCallRNG` on every golden scenario.
+- Branded IDs (`CharacterId`, `EncounterId`, etc.) backed by ULIDs. Normalized state. Immer internally, immutable externally.
+- Twenty-five effect primitives plus a `CustomEffect` code-handler hook.
+- `PendingChoice` protocol for deferred player decisions.
+- Combat resolution chain (`AttackDeclared` -> `AttackRolled` -> `DamageRolled` -> `DamageApplied`), full encounter lifecycle, level-up flow with HP rolls, ability checks and saves, spellcasting with cantrip scaling and ritual casting and area shapes, concentration enforcement, OnEvent triggers (Sneak Attack), action economy (Action Surge, Extra Attack, Bonus Action), reactions (opportunity attacks, off-hand strikes, flat damage reduction), movement and positioning, damage mitigation order of operations, inventory equip/attune with 3-slot cap, creature as combatant with multiattack, environmental hazards (falling, cover), all 15 2024 conditions.
+
+### State schemas (Phase B, Slices 17-20)
+
+- Parties + shared inventory + currency + treasure ledger.
+- Sessions + journal entries (player / DM / character visibility) + in-game clock formatted as `Day NN HH:MM`.
+- Locations + maps (normal / difficult / impassable / water cells) + doors (open / closed / locked) + Bresenham line-of-sight and line-of-effect.
+- Quests + objectives + rewards + milestone XP.
+
+### Combat fill-in (Phase C, Slices 21-30)
+
+- Grapple, shove, hide (2024 unarmed save-DC model).
+- Counterspell, Dispel Magic, Identify.
+- Weapon Mastery effects: Sap, Vex, Slow, Topple, Push, Graze.
+- Mounts and vehicles (land / water / air, with HP, AC, capacity, occupants).
+- Travel + forage + navigation + forced-march exhaustion.
+- NPCs as first-class with attitude (hostile / unfriendly / indifferent / friendly / helpful) and morale.
+- Downtime + crafting + training + tool proficiency tracking.
+- Magic item charges + recharge cadence + sentient items.
+- Resurrection variants: Revivify, Raise Dead, Reincarnate, Resurrection, True Resurrection.
+- Wild Shape, Polymorph, Simulacrum, Wish.
+
+### Adoption surface (Phase D, Slices 31-37)
+
+- Starter content pack bundled with the package. `loadStarterPack()` returns a fully-populated `ContentPack`.
+- `examples/` directory with three runnable apps: character-sheet printer, encounter + replay demo, save/load round-trip. CI executes them to catch public-API regressions.
+- Getting-started doc and API reference under `docs/`.
+- Public API conveniences: `engine.do(campaign, intent)`, `serializeCampaign(c)` / `loadCampaign(json)`, `createPC({...})`.
+- Per-engine derivation memoization keyed on `CampaignState.version`. Repeated `engine.derive.*` calls return the same object reference until the next commit.
+- npm publish prep. Package ships ESM + CJS + `.d.ts`. `prepublishOnly` runs the full CI gate. `publishConfig: public`.
+- Content pack validator with path-pointed Zod failures and Levenshtein "Did you mean X?" suggestions on cross-reference errors.
+
+### 2024 content (Phase E, Slices 38-46)
+
+- All 12 PHB classes in the starter pack with 1-20 level tables and signature features at landmark levels.
+- ~31 spells across cantrip + level 1-3 tiers covering the common archetypes.
+- 7 species, 8 backgrounds, 22 feats (origin + general + all six fighting styles), 25+ items including armor variety, 5 tools, 7 adventuring-gear items.
+- 9 magic items across all rarity tiers (common Bag of Holding through legendary Deck of Many Things) including a charged Wand of Magic Missiles.
+- 6 monster statblocks (Goblin, Orc, Wolf, Skeleton, Ogre, Young Red Dragon).
+- 2024 Bastion stronghold system: facilities, hirelings, turn orders, damage and level-up.
+- 9 epic boons under the `epic-boon` feat category.
+- Variant rule toggles on `CampaignState.settings`: gritty rest, hero points, sanity, mass combat, custom houserules.
+
+### Testing
+
+- 475 tests across 87 files. Replay-equivalence and RNG-capture invariants asserted on every golden scenario. 80% line coverage gate on `src/engine/`, `src/derive/`, `src/effects/`.
+- Showcase scenario "The Stoneheart Saga" exercises 46 distinct mechanical surfaces in one coherent campaign narrative.
+
+### Not yet done
+
+- Phase F: optional `ttrpg-engine-core` extraction for multi-system support.
+- Subclass mechanics for individual classes (the level tables ship; specific subclass features are consumer territory).
+- The full ~370 spell catalog (representative sample ships; bulk content is for consumers to fill out from the 2024 SRD).
+- Specific scenario content (specific NPCs, adventures, named magic items beyond the starter set).

package/CONTRIBUTING.md

@@ -0,0 +1,98 @@
+# Contributing to ttrpg-engine-dnd
+
+Thanks for your interest. This engine is built to be the foundation that other D&D 5.5e tools rely on, so contributions are held to a higher bar than typical app code.
+
+## Before you start
+
+- Read [README.md](README.md) for the goal and roadmap.
+- Read [CLAUDE.md](CLAUDE.md) for architecture (locked) and conventions.
+- Read [DEVELOPMENT.md](DEVELOPMENT.md) for the dev workflow and house rules.
+
+## Scope: what this engine does and does not do
+
+**Does**: model every printed mechanic in the 2024 PHB, DMG, and Monster Manual. Provide a schema-only library that consumers extend with their own content packs. Run an event-sourced state machine with deterministic replay.
+
+**Does not**: ship any D&D content. Adjudicate situations the rules text delegates to the DM (improvised actions, table houserules, ambiguous spell interactions). Replace a human DM.
+
+If a contribution would put copyrighted Wizards of the Coast text or stat blocks into this repo, it does not belong here. Content goes in separate, consumer-owned content packs.
+
+## Architecture is locked
+
+The decisions in [CLAUDE.md](CLAUDE.md) under "Architecture (locked)" are not up for debate as part of a contribution:
+
+- Event-sourced with `apply(state, event) -> state` pure.
+- Plan/commit split: RNG only inside planners, resolution events carry baked rolls, replay is deterministic.
+- Effect-primitive vocabulary plus code-handler escape hatch.
+- Branded IDs with ULIDs. Normalized state. Immer internally, immutable externally. Zod schemas.
+- `PendingChoice` protocol for deferred decisions.
+
+If you think one of these needs to change, open an issue first and discuss before coding.
+
+## How to add a slice or feature
+
+Most contributions touch the same set of layers:
+
+1. **Event schemas** in [src/schemas/events/](src/schemas/events/). Intent / resolution / notification events as appropriate. Resolution events carry baked RNG.
+2. **Reducers** in [src/engine/reducers/](src/engine/reducers/), one file per event category. Wire into [src/engine/apply.ts](src/engine/apply.ts) (both the import and the switch case).
+3. **Planners** in [src/engine/plan/](src/engine/plan/). RNG-consuming logic lives here, never in reducers.
+4. **Public API** in [src/engine/index.ts](src/engine/index.ts) and re-exports in [src/index.ts](src/index.ts).
+5. **Tests**: see Testing standard below.
+
+## Testing standard
+
+Held to the standard documented in [CLAUDE.md](CLAUDE.md). Summary:
+
+**Required**:
+
+- Reducer unit tests in [tests/unit/reducers/](tests/unit/reducers/) for every new event type. Happy path, every rulebook edge case, invalid-input rejection.
+- At least one golden scenario in [tests/golden/](tests/golden/) per new gameplay flow. Asserts replay equivalence.
+- Each golden scenario must emit a human-readable transcript via `formatTranscript()` from [tests/transcript.ts](tests/transcript.ts) and assert it against a snapshot in [tests/golden/transcripts/](tests/golden/transcripts/). PRs show the transcript diff. Update intentionally with `npx vitest run -u`.
+- **Naming convention.** Slice-aligned golden tests are named `s<N>-<short-name>.test.ts` (for example `s4-checks.test.ts`, `s8-action-economy.test.ts`) and their transcript snapshots share the same prefix (`s4-checks.transcript.md`). Architectural-invariant tests (`replay-equivalence.test.ts`, `rng-capture.test.ts`) and the multi-slice narrative (`showcase.test.ts`) stay un-prefixed. A directory listing then reveals slice progression at a glance.
+- For RNG-consuming planners: a `ThrowOnCallRNG` test confirming `apply()` never calls the RNG.
+- Derivation tests: table-driven against rulebook tables (proficiency bonus, ability modifier, etc.), branch-tested for derived values that compose.
+- New event type: extend [tests/transcript.ts](tests/transcript.ts) `formatEvent` with a case so the rendering stays readable.
+
+**Not required** (and discouraged unless they catch a real bug):
+
+- Coverage chasing past 80% on core directories.
+- Public API contract snapshot tests.
+- Schema round-trip tests (Zod already guarantees this).
+
+If you cannot name a bug a test would prevent, do not write it.
+
+CI gates: typecheck, 80% line coverage on `src/engine/`, `src/derive/`, `src/effects/`, replay equivalence on every golden scenario, RNG capture proof.
+
+## Code style
+
+- TypeScript strict mode. Enforced in [tsconfig.json](tsconfig.json).
+- No magic numbers or strings. Extract to named module-scope constants.
+- No defensive error handling for impossible cases. Use `invariant()` for genuine boundary checks.
+- Small functions. Reducers should read as a sequence of named operations.
+- No em dashes or en dashes in code, comments, docs, or error messages. Use commas, parentheses, colons, or separate sentences.
+- File references in markdown as `[label](path)`, not backticks.
+
+## Commit and PR style
+
+- One coherent change per PR. Big features land as a series of merged-quickly slices.
+- Commit messages: imperative mood, summary line under 72 chars, optional paragraph for the why.
+- PRs should include: what changed, why, what tests cover it, anything reviewers should look at closely.
+
+## Reporting bugs
+
+Open an issue with:
+
+- A minimal reproduction: ideally a failing test or a short script that triggers the bug.
+- Expected vs actual behavior.
+- The rulebook citation if the bug is about rules correctness (PHB page, errata).
+
+## Reporting rules-correctness bugs
+
+These are different from code bugs. The engine aims for 95%+ correctness against the printed 2024 rules. If you believe a mechanic is implemented incorrectly:
+
+1. Cite the rulebook (PHB chapter / page) or official errata / Sage Advice.
+2. Show a test case that demonstrates the discrepancy.
+3. If the rules are genuinely ambiguous, that is a candidate for the `CustomEffect` escape hatch, not for the core engine.
+
+## License
+
+By contributing, you agree your contributions are licensed under the MIT License (see [LICENSE](LICENSE)).

package/DEVELOPMENT.md

@@ -0,0 +1,70 @@
+# Development
+
+## Branches
+
+- `main`: releasable, tagged.
+- `dev`: daily work, merges to `main` on release.
+
+## Commands
+
+```
+npm install            # install deps
+npm run typecheck      # tsc --noEmit
+npm test               # vitest run
+npm run test:watch     # vitest in watch mode
+npm run test:coverage  # vitest with coverage gates
+npm run build          # vite build + .d.ts emit
+npm run ci             # typecheck + coverage + build (full gate)
+```
+
+## Adding a new effect primitive
+
+1. Add the discriminated-union variant in [src/schemas/effects.ts](src/schemas/effects.ts) (both the `Effect` type and the `EffectSchema` Zod definition).
+2. Add the `EFFECT_KINDS` entry.
+3. Add interpretation in [src/effects/builder.ts](src/effects/builder.ts) `applyEffectToBuilder` if the primitive contributes statically to the effect stack. Triggered primitives (`OnEvent`) are handled by the trigger system instead.
+4. Add reducer tests for any features that exercise the new primitive end to end (via a golden scenario).
+
+## Adding a new event type
+
+1. Add schema in [src/schemas/events/](src/schemas/events/) and re-export from [src/schemas/events/index.ts](src/schemas/events/index.ts) (including `EVENT_TYPES` and the discriminated union).
+2. Add reducer in [src/engine/reducers/](src/engine/reducers/).
+3. Wire into [src/engine/apply.ts](src/engine/apply.ts): both the import at the top and the switch case in `apply()`. Both edits are easy to forget, the resulting bug surfaces only at runtime as `Unhandled event`.
+4. Reducer unit test in [tests/unit/reducers/](tests/unit/reducers/).
+5. At least one golden scenario in [tests/golden/](tests/golden/) emits the event so the replay-equivalence gate covers it.
+6. If the event involves RNG, the resolution event must carry the baked roll. Verify by including the new flow in a `ThrowOnCallRNG` test (apply with a no-RNG must not throw).
+
+## Adding a new planner
+
+1. Add `src/engine/plan/<thing>.ts` with the intent type and the `plan*` function.
+2. Re-export from [src/engine/plan/index.ts](src/engine/plan/index.ts).
+3. Add to the `Engine['plan']` type in [src/engine/index.ts](src/engine/index.ts) and to `planNs` in `createEngine`.
+4. Re-export from the public barrel [src/index.ts](src/index.ts).
+5. Planner test: deterministic for fixed seed, different seeds produce different rolls, applied events do not call RNG.
+
+## Versioning
+
+Bump policy, pre-release tag meanings (alpha / beta / rc), promotion criteria, and the roadmap to 1.0.0 are in [VERSIONING.md](VERSIONING.md). Short version: don't bump on every PR, treat ambiguous changes as breaking, update CHANGELOG with every release.
+
+## Schema migrations
+
+Bump `SCHEMA_VERSION` in [src/version.ts](src/version.ts) and add a migration function in [src/migrations/](src/migrations/) in the same PR as the breaking schema change. Migration test accompanies it. `SCHEMA_VERSION` is independent of the package version, see [VERSIONING.md](VERSIONING.md) for the contract.
+
+## Consumer integration
+
+For local development from a consumer app (e.g. `dndbnb`):
+
+```jsonc
+// in the consumer's package.json
+"dependencies": {
+  "ttrpg-engine-dnd": "file:../dnd-engine"
+}
+```
+
+Or use `npm link` for tighter iteration loops.
+
+## House rules
+
+- No em dashes or en dashes anywhere (code, comments, docs, error messages). Use commas, parentheses, colons, or separate sentences.
+- No magic numbers or strings. Extract to named module-scope constants. The 5.5e rules contain many of these (hit die averages, death save thresholds, exhaustion cap, ability score range). Each gets a name.
+- Reducers stay small. If `applyFoo` grows past about 30 lines, extract named helpers. The reducer reads as a sequence of named operations.
+- No defensive error handling for impossible cases. Trust types. Use `invariant()` only for genuine preconditions on incoming events.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Greg Carr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,247 @@
+# ttrpg-engine-dnd
+
+[![CI](https://github.com/greghcarr/ttrpg-engine-dnd/actions/workflows/ci.yml/badge.svg)](https://github.com/greghcarr/ttrpg-engine-dnd/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)](tsconfig.json)
+[![Status](https://img.shields.io/badge/status-alpha-yellow)](README.md#status)
+
+A standalone, event-sourced TypeScript domain engine for Dungeons & Dragons 5.5e (the 2024 rules update). Schema-only. Bring your own content pack (a starter SRD-shaped pack ships in the box).
+
+The package is named `ttrpg-engine-dnd` because the long-term plan extracts the system-agnostic core (event sourcing, plan/commit, branded IDs, content packs, sessions, party, predicate / formula DSL) into a future `ttrpg-engine-core` package, with `ttrpg-engine-dnd` becoming the 5.5e adapter. See [VERSIONING.md](VERSIONING.md) and the Phase F slice in the roadmap below.
+
+If you are building a D&D character sheet, encounter tracker, virtual tabletop, automation tool, or AI dungeon master and you do not want to reimplement the rules engine from scratch, this is for you.
+
+## Quick start
+
+```sh
+npm install ttrpg-engine-dnd@alpha
+```
+
+```ts
+import {
+  createEngine, loadStarterPack, createPC, commit,
+  seededRNG, newEventId,
+} from 'ttrpg-engine-dnd';
+
+const engine = createEngine({ contentPacks: [loadStarterPack()], rng: seededRNG(42) });
+const alyx = createPC({
+  name: 'Alyx', speciesId: 'human', backgroundId: 'soldier',
+  classId: 'fighter', level: 3, hpMax: 26,
+  abilityScores: { STR: 16, DEX: 14, CON: 14, INT: 10, WIS: 12, CHA: 8 },
+});
+
+let campaign = engine.createCampaign({ name: 'demo' });
+campaign = commit(campaign, [
+  { id: newEventId(), at: new Date().toISOString(), type: 'CharacterCreated', snapshot: alyx },
+]);
+
+const sheet = engine.derive.character(campaign.state, alyx.id);
+console.log(`${alyx.name}: AC ${sheet.ac.total}, HP ${sheet.hp.current}/${sheet.hp.max}`);
+```
+
+## Documentation
+
+Pick the doc that matches what you want:
+
+| You want to... | Read this |
+|---|---|
+| Try the smallest possible working example | [examples/00-quickstart](examples/00-quickstart/) |
+| Walk through your first character, attack, and save/load | [docs/getting-started.md](docs/getting-started.md) |
+| Understand the mental model (events, plan/commit, content packs) | [docs/concepts.md](docs/concepts.md) |
+| Look up a specific public symbol | [docs/api-overview.md](docs/api-overview.md) |
+| See common patterns (save, undo, houserules, multiplayer sync) | [docs/recipes.md](docs/recipes.md) |
+| Watch a full multi-act campaign run | [the showcase transcript](tests/golden/transcripts/showcase.transcript.md) |
+| Know what each version means (alpha / beta / rc / 1.0) | [VERSIONING.md](VERSIONING.md) |
+| Read the change history | [CHANGELOG.md](CHANGELOG.md) |
+
+## Why this engine
+
+- **Built for accuracy first.** Full mechanical coverage of the 2024 Player's Handbook, Dungeon Master's Guide, and Monster Manual is the explicit goal. Every printed class, subclass, species, background, feat, spell, weapon, armor, magic item, condition, and monster statblock can be expressed.
+- **No content, no IP problems.** The library ships schemas and an engine. It does not ship any rulebook text or statblocks. You bring your own content packs (built from the SRD 5.2 or your own homebrew), and the engine validates and runs them.
+- **Event-sourced, fully deterministic replay.** Every state change is an event. A captured event log replays to byte-identical state across machines. Undo and redo are free.
+- **Plan/commit split.** All randomness is consumed inside `engine.plan(intent)` and baked into resolution events. `apply()` is pure and replay never re-rolls dice. This is the architectural foundation that makes multiplayer sync, save files, and audit logs work correctly.
+- **Effect-primitive vocabulary plus escape hatch.** About 25 declarative primitives express the bulk of 5.5e features as pure data; a `CustomEffect` code-handler hook covers genuinely-procedural exotica (Wild Shape, Wish, Simulacrum) and table-specific houserules.
+- **Solid foundations.** TypeScript strict mode. Zod validation at boundaries. Immer-backed reducers, immutable externally. ESM and CJS builds. Zero peer-dependency conflicts.
+- **Living transcripts.** Every golden test emits a human-readable markdown transcript of its event log, checked into [tests/golden/transcripts/](tests/golden/transcripts/). Every PR that changes engine behavior shows the transcript diff alongside the code. See [the showcase transcript](tests/golden/transcripts/showcase.transcript.md) for "The Stoneheart Saga": a multi-act campaign that exercises sessions and journals, party currency and bastion management, locations + doors + terrain, NPC reaction rolls, mounts and a supply wagon, travel and forage, two combat encounters (goblin scouts then a young red dragon) covering attack chains with advantage and counterspell and weapon mastery and concentration breakage, action surge, off-hand strikes, sneak attack, opportunity attacks, falling, polymorph (Alyx into a giant ape), multiattack creatures, fire-mitigation, death save plus revivify, quest objectives plus milestone plus XP plus reward claim, magic-item charges plus dawn recharge, downtime training plus crafting, and replay-equivalence plus RNG-capture invariants over the whole 339-line transcript.
+
+## Architecture
+
+- **Event-sourced.** State changes are events. `apply(state, event) -> state` is pure. Replay any campaign from its event log.
+- **Plan/commit split.** RNG is consumed only inside `engine.plan(intent)`. Resolution events carry baked rolls, so `apply()` is deterministic. Replay never re-rolls.
+- **Effect-primitive vocabulary.** Features (class features, feats, magic item powers, conditions) are described via a fixed vocabulary of about 25 effect primitives. Wild Shape, Polymorph, Wish, Simulacrum and a handful of others drop to code handlers.
+- **Schema-only.** The library ships shapes (`Character`, `Spell`, `MagicItem`, `MonsterStatblock`, etc.) and the engine that operates on them. Consumers load rules content from their own JSON content packs. This keeps the IP story clean.
+- **Branded IDs + ULIDs.** `CharacterId`, `SpellId`, `ItemDefinitionId` versus `ItemInstanceId`, etc. Backed by ULIDs (lexicographically sortable by time).
+- **PendingChoice protocol.** Deferred player decisions (ASI vs feat, fighting style selection, spell target selection) are first-class events in the log.
+- **Zod for validation, Immer for clean reducers, Vitest for tests.**
+
+## Status
+
+**Alpha-ready.** Forty-six slices complete (Phases A through E done), 475 tests across 87 files. The engine compiles, builds (ESM + CJS + `.d.ts`), the architectural invariants (event-sourcing, plan/commit, RNG capture, replay equivalence, branded IDs, effect primitives) are locked and proven by the test suite, the adoption surface is in place (starter pack, examples, getting-started doc, `engine.do()` convenience, derivation memoization, npm-publish-ready package, content validator with suggestions), and the content layer covers every 2024 PHB shape: all 12 classes with 1-20 level tables, ~31 representative spells across the common archetypes, 7 species, 8 backgrounds, ~31 feats including all fighting styles and 9 epic boons, 25+ items with armor variety and 9 magic items, 6 monster statblocks from CR 1/4 to CR 10, the full 2024 Bastion stronghold system, and toggles for the common DMG variant rules.
+
+What remains is the optional Phase F (`ttrpg-engine-core` extraction) if multi-system support becomes a real goal. Otherwise the library is ready for alpha consumers.
+
+## Roadmap
+
+Six phases. The slice catalog below is the canonical list; ✓ marks done, blank marks pending. Phases A through E are complete (46 slices). Only the optional Phase F (core extraction) remains.
+
+### Phase A: Engine mechanics (16 slices, all done)
+
+Each slice landed a load-bearing combat or rules mechanic. Order was dependency-driven.
+
+- ✓ **Slice 1.** Character creation, HP, damage, healing, temp HP, hit dice, short / long rest, exhaustion, conditions, death saves, stabilize.
+- ✓ **Slice 2.** Combat resolution chain (`AttackDeclared` -> `AttackRolled` -> `DamageRolled` -> `DamageApplied`) with RNG-captured d20 + damage dice, advantage / disadvantage, critical hits, full encounter lifecycle (create, roll initiative, start, turn / round, end), item acquisition.
+- ✓ **Slice 3.** Level-up flow with RNG-captured HP rolls (roll or average strategy), `PendingChoice` resolution protocol for deferred decisions (ASI vs feat, fighting style, subclass selection, spell selection). Resolved-choice effects feed into derivations.
+- ✓ **Slice 4.** `plan.save`, `plan.abilityCheck` (with optional skill), record-only `SaveRolled` / `AbilityCheckRolled` resolution events. Honors caller-supplied advantage or derives it from the effect stack. Skill checks apply half / proficient / expertise multipliers. `computeAbilityCheck` + `computePassiveScore` derivations.
+- ✓ **Slice 5.** Spellcasting. `plan.castSpell` handles cantrips and leveled spells; dispatches per-target attack / save / heal mechanics through the existing resolution chains; consumes standard or pact slots (auto-picks pact when both apply); upcasting via `extraDicePerSlotLevel`. `SpellCastDeclared`, `SpellSlotConsumed`, `PactSlotConsumed` events. Long rest restores all slots, short rest restores pact slots only. `computeAvailableSpellSlots` derivation.
+- ✓ **Slice 6.** Concentration enforcement. `EffectInstance` table tracks active spell effects with their applied conditions; concentration spells emit `ConcentrationStarted` and set `Character.concentrationEffectId`. `plan.checkConcentration(characterId, damage)` rolls a CON save with DC `max(10, floor(damage/2))`, emits `ConcentrationBroken` on failure which auto-removes every condition the effect installed. Casting a new concentration spell while already concentrating evicts the prior effect.
+- ✓ **Slice 7.** OnEvent trigger system. The dispatcher walks every character's effect stack after each triggering event, evaluates the `Predicate` filter against event facts, checks cadence (`oncePer: 'turn' | 'round' | 'shortRest' | 'longRest'`), and fires `AddDamage` actions producing rider events. `TriggerFired` event marks usage; `Character.triggerCounters` tracks per-cadence state. Test pack has a Rogue with Sneak Attack as the canonical OnEvent feature.
+- ✓ **Slice 8.** Action economy. `Combatant.turnUsage` tracks per-turn usage; `ActionEconomyConsumed` events enforce "can't double-use the Action" / "Bonus Action" / "Reaction this round". `computeActionEconomyBudget` reads `ModifyActionEconomy` effects (Extra Attack, Action Surge, Bonus Action grants). `planAttack` enforces the attack budget when the attacker is the active combatant in an active encounter.
+- ✓ **Slice 9.** Reactions protocol, scoped to opportunity attacks. `resolveAttack` extracted as a shared helper so `planOpportunityAttack` reuses the d20 / damage / OnEvent-trigger pipeline. Emits `ActionEconomyConsumed { kind: 'reaction' }` and bypasses the action / attack-budget checks. Throws on a second reaction same round; refreshes at `RoundEnded`.
+- ✓ **Slice 9b.** Reaction-window expansion. Action Surge resets the action consumption flag; off-hand attacks consume the bonus action and suppress ability mod on damage; `FlatDamageReduction` effect primitive (Heavy Armor Master, similar) reduces incoming damage before resistance.
+- ✓ **Slice 10.** Movement and positioning. Combatants gain optional `position: { x, y }` in feet and per-turn movement state (`feetMovedThisTurn`, `dashed`, `disengaged`). `planMove` enforces the budget against `Character.speedFeet` (doubled if Dashed) using Chebyshev distance.
+- ✓ **Slice 11.** Damage mitigation order of operations. `mitigateDamage` walks the target's effect stack and applies flat reduction, then immunity (zero), then vulnerability (×2), then resistance (½ rounded down) to each damage component.
+- ✓ **Slice 12.** Inventory mechanics. `ItemEquipped`, `ItemUnequipped`, `ItemAttuned`, `ItemUnattuned` events with reducers enforcing the 3-slot attunement cap. `computeCarryingCapacity` (STR × 15) and `computeEncumbrance` derivations.
+- ✓ **Slice 13.** Creature as a first-class combatant. `Character.kind: 'pc' | 'npc' | 'creature'` discriminator with optional `statblockId` and `multiattack` pattern. `planMultiattack` consumes a single Action and runs `resolveAttack` once per weapon swing in the pattern.
+- ✓ **Slice 14.** Environmental hazards. `planFalling` rolls 1d6 per 10ft (capped at 20d6) routed through `mitigateDamage` as bludgeoning. Cover (`half`, `three-quarters`, `total`) adds +2 / +5 AC respectively; total cover refuses the attack.
+- ✓ **Slice 15.** Full 2024 conditions library. All 15 conditions (blinded, charmed, deafened, exhaustion, frightened, grappled, incapacitated, invisible, paralyzed, petrified, poisoned, prone, restrained, stunned, unconscious) load from content packs and apply their effects to derivations.
+- ✓ **Slice 16.** Spellcasting polish. Cantrip damage scaling at character levels 5 / 11 / 17 via `cantripScalingDice`. Ritual casting via the `asRitual` flag (skips slot consumption; rejects non-ritual spells). Spell area targeting metadata (cone / cube / line / sphere / cylinder).
+
+### Phase B: Full state schemas (4 slices, all done)
+
+The campaign-state surface area beyond combatants.
+
+- ✓ **Slice 17.** Parties, shared inventory, currency, treasure ledger. `PartyCreated`, `PartyMembersChanged`, `CurrencyAcquired`, `CurrencySpent`, `ItemDepositedToParty`, `ItemWithdrawnFromParty` events. Currency helpers (`totalInCopper`, `addCurrency`, `subtractCurrency`) refuse to let the purse go negative.
+- ✓ **Slice 18.** Sessions, journal entries (player / DM, with party / dm-only / character visibility), in-game clock (minutes from epoch, formatted as `Day NN HH:MM`). Only one session can be active at a time; starting a session syncs the campaign clock and refuses to rewind it.
+- ✓ **Slice 19.** Locations and environmental terrain. `Location` (with optional parent and `LocationMap` of cells: normal / difficult / impassable / water), `Door` (open / closed / locked, blocks LOS and movement when shut). New events `LocationCreated`, `DoorAdded`, `DoorStateChanged`, `CharacterLocationChanged`. Derivations `terrainAt`, `movementCostAt`, `chebyshevDistanceFeet`, `isInRangeFeet`, `hasLineOfSight`, `hasLineOfEffect` (Bresenham ray, blocked by impassable cells and closed/locked doors).
+- ✓ **Slice 20.** Quests, objectives, rewards, milestone XP. `Quest` (active / completed / failed / abandoned) with required and optional `QuestObjective`s tracking progress against thresholds. New events `QuestStarted`, `ObjectiveProgressed` / `Completed` / `Failed`, `QuestCompleted` / `Failed` / `Abandoned`, `QuestRewardClaimed` (distributes XP per beneficiary and currency to the linked party), `XPAwarded` (direct grant), `MilestoneAwarded` (minor / major / campaign tags appended to the campaign state).
+
+### Phase C: Combat fill-in (10 slices, all done)
+
+High-impact mechanics consumers will immediately want. Each slice closes a gap that's currently missing or partial.
+
+- ✓ **Slice 21.** Grapple, shove, hide actions. `planGrapple` rolls the attacker's unarmed save DC (8 + STR mod + prof) and emits a `SaveRolled` for the target (STR or DEX); failure applies the `grappled` condition. `planShove` does the same with a STR save and applies `prone` or emits a forced `CombatantMoved` (5 ft push). `planHide` rolls a DEX (stealth) check against DC 15 (or caller-provided DC) and applies the `invisible` condition on success. All three consume an Action when the actor is an active combatant; out-of-combat usage is unmetered.
+- ✓ **Slice 22.** Counterspell, Dispel Magic, Identify. `planCounterspell` follows the 2024 model: reaction consumed, 3rd-level slot spent, target makes a CON save against the counter-caster's spell save DC; on failed save a `SpellCountered` event records the outcome (callers omit the original spell's resolution events). `planDispelMagic` auto-succeeds on effects whose level is at or below the dispel slot level, otherwise an `AbilityCheckRolled` against DC 10 + spell level; on success `SpellDispelled` removes the effect plus its conditions and clears any concentration link. `planIdentify` emits `ItemIdentified`, appending the character to `ItemInstance.identifiedByCharacterIds`.
+- ✓ **Slice 23.** Weapon Mastery effects via `planWeaponMastery({mastery, attackerId, targetId, weaponInstanceId})`. Sap, Vex, and Slow apply marker conditions (`sapped`, `vexed-by`, `slowed-10ft`). Topple emits a CON save against the attacker's unarmed save DC; failure applies `prone`. Push emits a forced 10 ft `CombatantMoved` when positions exist. Graze emits a `DamageApplied` for the attacker's STR modifier in the weapon's damage type. Every activation also emits a `WeaponMasteryActivated` record event for replay narrative. Cleave / Nick / Flex are sequencing concerns that belong to the attack planner and are deferred.
+- ✓ **Slice 24.** Mounts, vehicles, mounted combat. Mounts are creatures (kind `creature`) with a rider linked via `Character.mountedOnId`; `Mounted` and `Dismounted` events maintain that back-link. Vehicles are a separate entity (`land` / `water` / `air`) with their own HP, AC, capacity, and occupant roster. New events: `VehicleAcquired`, `VehicleBoarded`, `VehicleDeparted`, `VehicleDamaged`, `VehicleRepaired`; capacity is enforced at boarding time.
+- ✓ **Slice 25.** Travel and overland. `TravelLegCompleted` events append to a `travelLog` on the campaign (pace, hours, miles, optional from/to locations, notes). `planNavigationCheck` rolls Wisdom (Survival) against caller DC and emits `NavigationCheckRolled`. `planForage` rolls Wisdom (Survival) and emits `ForagedFor` with food and water pounds gained on success. Forced-march exhaustion is recorded via the existing `ExhaustionChanged` event so callers can stack incremental exhaustion onto the same character without engine-side bookkeeping.
+- ✓ **Slice 26.** NPCs with reaction and morale mechanics. Character schema gains optional `attitude`, `morale`, and `moraleBroken` fields. `planReactionRoll` rolls the presenter's CHA (Persuasion) against a DC and bumps the NPC's attitude (hostile / unfriendly / indifferent / friendly / helpful) based on margin. `planMoraleCheck` rolls the NPC's Wisdom against a DC; failed checks decrement morale and emit `MoraleBroken` (flee / surrender) when morale hits zero.
+- ✓ **Slice 27.** Downtime, crafting, training. `DowntimeActivityResolved` appends to a `downtimeLog` on the campaign with kind (`crafting` / `training` / `recuperating` / `research` / `work` / `other`), day count, outcome (`success` / `partial` / `failure`), summary, optional produced item definition ID, and optional tool proficiency gained. Tool proficiencies accumulate per character in `toolProficienciesByCharacter`.
+- ✓ **Slice 28.** Magic item charges, recharge, sentient items. ItemInstance gains `maxCharges` and `sentient { ego, alignment, personality }` fields. `ItemChargeConsumed` decrements `chargesRemaining` (refuses to over-spend), `ItemRecharged` adds back up to `maxCharges` on one of five cadences (`dawn`, `dusk`, `shortRest`, `longRest`, `manual`), `SentientItemConflict` records the outcome of an item-vs-wielder showdown.
+- ✓ **Slice 29.** Resurrection variants. `CharacterResurrected` event with `spell` discriminator (`revivify`, `raise-dead`, `reincarnate`, `resurrection`, `true-resurrection`) restores the target to `hpAfter` HP, clears temp HP, resets death saves, and zeroes exhaustion. Reincarnate may set `newSpeciesId` to swap the character's species. Currency cost is left to the caller via the existing `CurrencySpent` event so consumers can apply table-specific economies.
+- ✓ **Slice 30.** Wild Shape, Polymorph, Simulacrum, Wish. `PolymorphApplied` swaps HP, ability scores, speed, and species into a new form and snapshots the originals to `Character.polymorphedSnapshot`; `PolymorphReverted` restores them. `wild-shape`, `polymorph`, and `true-polymorph` share the machinery via a `kind` discriminator. `SimulacrumCreated` clones a character into a creature-kind duplicate at half-HP (transient state reset). `WishGranted` records a freeform wish description; `stressApplied: true` increments the granter's exhaustion. Concrete spell effects beyond the form swap stay in the consumer's hands.
+
+### Phase D: Adoption surface (7 slices, all done)
+
+These don't add rules; they make the library usable by people who didn't write it. Higher priority than Phase E for any consumer that isn't this repo's author.
+
+- ✓ **Slice 31.** Starter content pack bundled in the package as `src/content/packs/starter-pack.json` and exported via `loadStarterPack()`. Includes Fighter, Wizard, Rogue, Paladin, and Warlock classes (levels 1-5 for combat-relevant features), Human species, Soldier background, all 15 conditions, ~6 spells, ~10 items, plus the canonical Sneak Attack OnEvent feature. Enough to instantiate a character and run combat without writing any content from scratch; consumers extend it from the 2024 SRD CC-BY release as their needs grow.
+- ✓ **Slice 32.** `/examples` directory with three runnable TypeScript apps: a character-sheet printer ([01-character-sheet](examples/01-character-sheet/)), an encounter-and-replay demo ([02-combat-encounter](examples/02-combat-encounter/)), and a save/load round-trip ([03-save-and-load](examples/03-save-and-load/)). Each is a single `npx tsx`-runnable file. An integration test in [tests/integration/examples.test.ts](tests/integration/examples.test.ts) executes them in CI so regressions in the public API surface get caught immediately.
+- ✓ **Slice 33.** Getting-started doc at [docs/getting-started.md](docs/getting-started.md) walking through install, engine setup, character creation, attack resolution, and save/load round-trip. API reference at [docs/api-overview.md](docs/api-overview.md) maps every public symbol by namespace (planners, derivations, events, schemas, content packs, RNG, IDs, migrations).
+- ✓ **Slice 34.** Public API conveniences. `engine.do(campaign, intent)` dispatches on `intent.type` to the right planner and commits the result in one call (covers every Phase A-C planner). `serializeCampaign(c)` writes a JSON string with id, name, schemaVersion, and events only; state is omitted because `loadCampaign(json)` replays the events to reconstruct it. `createPC({name, speciesId, backgroundId, classId, hpMax, ...})` returns a `Character` with sensible defaults; caller emits the `CharacterCreated` event themselves to add to a campaign.
+- ✓ **Slice 35.** Derivation memoization keyed on `CampaignState.version`. Every `engine.derive.*` method now caches its result per-engine; the cache invalidates automatically when `state.version` advances (i.e., on every commit). Repeated calls at the same version return the same object reference, so a UI that asks for derived AC ten times per frame across twelve combatants pays for one computation each.
+- ✓ **Slice 36.** npm publish prep. `package.json` declares `main` (CJS), `module` (ESM), `types` (`.d.ts`), and `exports` for both formats. `files` whitelists `dist/`, `docs/`, license, and READMEs. `prepublishOnly` runs the full CI gate (typecheck + tests + coverage + build) before any publish. `publishConfig: { access: public }` is set. `npm pack --dry-run` reports a ~398 KB tarball with no source or test code. Publishing is `npm publish` away.
+- ✓ **Slice 37.** Content pack validator with diagnostic errors. `loadContentPack` throws a `ContentPackLoadError` whose `.issues` is a list of `{path, message}` entries derived from Zod's `safeParse` (e.g. `classes.0.hitDie: Expected number, received string`). `validateCrossReferences` returns issues with optional Levenshtein-based `suggestion` strings like `Did you mean "savage-attacker"?` so a one-character typo is identifiable from the error alone.
+
+### Phase E: 2024 content fill-out (9 slices, all done)
+
+Heavy on data, light on engine code. Each class slice stress-tests Phases A and C.
+
+- ✓ **Slice 38.** Classes group 1: Barbarian, Bard, Cleric, Druid added to the starter pack with 1-20 level tables, signature features at landmark levels (Rage, Fast Movement, Bardic Inspiration, Channel Divinity, Wild Shape), and spellcasting blocks for the three full-casters. Subclasses and per-level feature details are consumer extension; the engine schema accepts the full 2024 progression.
+- ✓ **Slice 39.** Classes group 2: Fighter and Paladin were already in the starter pack from earlier slices; Monk and Ranger added with full 1-20 level tables. Monk features: Martial Arts, Unarmored Defense (OverrideACFormula with DEX+WIS), Monk's Focus (Ki resource), Unarmored Movement, Extra Attack at 5, Stunning Strike, Evasion. Ranger features: Favored Enemy with Hunter's Mark resource, Weapon Mastery grant (all 9 masteries, 2 slots), Fighting Style, Extra Attack, half-caster spellcasting on WIS.
+- ✓ **Slice 40.** Classes group 3: Rogue, Warlock, and Wizard were already in the starter pack; Sorcerer added with Innate Sorcery and Font of Magic (sorcery-points resource), Metamagic placeholder, full CHA spellcasting. With this slice all 12 PHB classes ship in the starter pack.
+- ✓ **Slice 41.** Spell catalog expanded to ~31 spells across cantrip + level 1-3 tiers covering the common archetypes: damage cantrips (Sacred Flame, Eldritch Blast, Ray of Frost, Shocking Grasp), utility cantrips (Guidance, Light, Mage Hand, Prestidigitation), save-or-suck level-1 (Bane, Sleep, Faerie Fire, Thunderwave, Burning Hands), buffs (Bless, Mage Armor, Shield), healing (Healing Word), AoE (Spirit Guardians, Web, Spiritual Weapon), utility (Misty Step, Aid, Lesser Restoration, Identify with ritual flag), and the reactive trio (Counterspell, Dispel Magic, Identify) that pair with the Slice 22 planners. Filling out the full 2024 catalog (~370 spells) is consumer territory; the schema and planners support every required shape.
+- ✓ **Slice 42.** Species + backgrounds + feats + fighting styles + equipment + tools. Species expanded from Human only to seven (Human, Elf, Dwarf, Halfling, Tiefling, Dragonborn, Gnome). Backgrounds expanded to eight (Soldier, Sage, Criminal, Acolyte, Folk Hero, Noble, Guild Artisan, Outlander) each pointing at an origin feat. Feat list grew to ~22 covering origin feats (Alert, Magic Initiate variants, Tough, Skilled, Crafter, Lucky), general feats (Great Weapon Master, Sharpshooter, Polearm Master, War Caster, Resilient), and all six 2024 Fighting Styles as the new `fighting-style` category. Equipment doubled: 8 more weapons (Greatsword, Greataxe, Warhammer, Mace, Spear, Quarterstaff, Handaxe, Crossbow), 6 more armors (Studded Leather, Scale Mail, Breastplate, Half Plate, Ring Mail, Splint), 5 tools, and 7 adventuring-gear items.
+- ✓ **Slice 43.** Magic items and monster statblocks. 9 magic items added across all rarity tiers (common Bag of Holding through legendary Deck of Many Things), with a charged wand (Wand of Magic Missiles, 7 charges, dawn recharge `1d6+1`) demonstrating the Slice 28 charge tracking. 6 monster statblocks added (Goblin, Orc, Wolf, Skeleton, Ogre, Young Red Dragon) covering Humanoid / Beast / Undead / Giant / Dragon creature types and CR 0.25 through 10, plus damage immunities/vulnerabilities/resistances and condition immunities where canonical.
+- ✓ **Slice 44.** Bastions (2024 stronghold system). New `Bastion` entity (id, name, owner character, optional location, level 1-9, facilities, hirelings, defenders, treasury, HP). Six new events: `BastionFounded`, `BastionFacilityAdded` (basic / special, cramped / roomy / vast), `BastionHirelingAdded`, `BastionTurnTaken` (turn order: maintain / craft / recruit / research / trade / empower, with treasury delta and optional summary), `BastionDamaged` (clamps HP at zero), `BastionLevelChanged` (rejects mismatched fromLevel). Sufficient state for a consumer to run a full Bastion progression alongside an adventuring campaign.
+- ✓ **Slice 45.** Epic boons (post-20 progression). The Feat schema already supported `category: 'epic-boon'`; this slice adds 9 boons to the starter pack (Combat Prowess, Dimensional Travel, Energy Resistance, Fortitude, Irresistible Offense, Skill, Spell Recall, the Night Spirit, Truesight) so consumers have working post-20 reward content. Granting a boon uses the existing `featsTaken` array on a Character; no new event type required.
+- ✓ **Slice 46.** Variant rules toggles. New `CampaignSettings` shape on `CampaignState.settings` with boolean flags for `grittyRest`, `heroPoints`, `sanity`, `massCombat`, `feaCharacterFlaws`, plus a `customHouserules: string[]` for arbitrary table-specific tags. `CampaignSettingsChanged` event flips any subset of toggles in one go and add/removes custom houserule strings (dedupe on add). Consumers can branch their planner logic on these flags; the engine doesn't enforce them yet, leaving the rule interpretation to the consumer (e.g., a custom rest planner that respects `grittyRest` to scale short/long rest durations).
+
+### Phase F: Core extraction (1 slice, optional, future)
+
+- **Slice 47.** Extract `ttrpg-engine-core` as a separate package. The architectural layer (event sourcing, plan/commit, branded IDs, content packs, sessions, journal, party + currency abstraction, predicate + formula DSL, PendingChoice protocol, undo/redo, transcript formatter, RNG-capture proof) is system-agnostic and could be the foundation for other TTRPG engines (Pathfinder, Tales of the Valiant, Gamma World, etc.). `ttrpg-engine-dnd` (this package) becomes the 5.5e adapter on top of the core. Only do this if multi-system support becomes a real goal; premature abstraction would slow the D&D work down for a hypothetical second consumer that doesn't exist yet. Estimated 2-4 weeks once this package is mature.
+
+### What "perfect" cannot mean
+
+5.5e explicitly delegates some rulings to the DM: improvised actions, narrative consequences, table houserules, ambiguous spell interactions that even Sage Advice has issued multiple clarifications on. A rules engine cannot adjudicate these. The `CustomEffect` code-handler escape hatch is the explicit spot for table-specific rulings. After all phases the engine covers ~95% of printed mechanics by surface area; the rest is documented as DM-discretion territory.
+
+## Install
+
+```sh
+npm install ttrpg-engine-dnd@alpha
+```
+
+The package is published under the `alpha` dist-tag and ships ESM, CJS, and `.d.ts`. Peer dependencies (`zod`, `immer`, `ulid`) install transitively. See [VERSIONING.md](VERSIONING.md) for the alpha-to-1.0 roadmap and the alpha->beta promotion gate.
+
+You can also pin to a git ref while iterating alongside the engine:
+
+```jsonc
+// in your consumer's package.json
+"dependencies": {
+  "ttrpg-engine-dnd": "github:greghcarr/ttrpg-engine-dnd"
+  // or, when developing alongside the engine:
+  // "ttrpg-engine-dnd": "file:../dnd-engine"
+}
+```
+
+## Usage (preview)
+
+```ts
+import {
+  createEngine,
+  loadContentPack,
+  seededRNG,
+} from 'ttrpg-engine-dnd';
+import myContent from './my-content-pack.json';
+
+const engine = createEngine({
+  contentPacks: [loadContentPack(myContent)],
+  rng: seededRNG(42),
+});
+
+let campaign = engine.createCampaign({ name: 'home game' });
+// commit CharacterCreated + ItemAcquired events, then:
+
+// melee attack
+campaign = engine.commit(campaign, engine.plan.attack(campaign.state, {
+  attackerId: alyx.id,
+  targetId: goblin.id,
+  weaponInstanceId: longsword.id,
+}).events);
+
+// cast a spell
+campaign = engine.commit(campaign, engine.plan.castSpell(campaign.state, {
+  characterId: wizard.id,
+  spellId: 'fireball',
+  slotLevel: 3,
+  targetIds: [goblin1.id, goblin2.id, goblin3.id],
+}).events);
+
+// level up with a rolled HP gain
+campaign = engine.commit(campaign, engine.plan.levelUp(campaign.state, {
+  characterId: alyx.id,
+  classId: 'fighter',
+  hpStrategy: 'roll',
+}).events);
+
+// derive a character sheet (effective AC, saves, spell slots, etc.)
+const sheet = engine.derive.character(campaign.state, alyx.id);
+// sheet.ac, sheet.savingThrows, sheet.spellSlots, etc.
+```
+
+For a step-by-step walkthrough, see [docs/getting-started.md](docs/getting-started.md). For the full surface, see [docs/api-overview.md](docs/api-overview.md). See [DEVELOPMENT.md](DEVELOPMENT.md) for the dev workflow and [CLAUDE.md](CLAUDE.md) for architecture conventions.
+
+## Intellectual property
+
+This library is original work. It contains zero text, statblocks, or content from the Wizards of the Coast D&D 5.5e rulebooks. The schemas describe the *shape* of D&D content (a spell has a level, a school, a list of mechanical effects) but no copyrighted content.
+
+D&D content is published by Wizards of the Coast. The 2024 SRD (System Reference Document) is released under Creative Commons CC BY 4.0; portions of older 5e content are available under the OGL 1.0a. If you build a content pack to load into this engine, your pack is subject to those licenses, not this library's license. This library does not ship, distribute, or endorse any specific content pack.
+
+Dungeons & Dragons is a trademark of Wizards of the Coast LLC. This project is not affiliated with or endorsed by Wizards of the Coast.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). The architecture is locked (see [CLAUDE.md](CLAUDE.md)); contributions that fit within it are very welcome. Open an issue before a large change.
+
+## License
+
+[MIT](LICENSE). Copyright (c) 2026 Greg Carr.