Slice 20: Documentation — README + JSON data-model reference

[Jamerrone]

Parent

#1

What to build

Two of the four shipped documentation artefacts: the README for orientation and the JSON data-model reference enumerating every config type's fields with units. The other two (Plugin authoring guide + API reference) ship in Slice 21.

Demoable outcome: a developer encountering the project for the first time reads the README and can (a) install the engine, (b) construct an engine with the built-in plugin bundle in five lines or less, (c) run the Node CLI demo, (d) run the browser demo, (e) find the JSON data-model reference. The JSON data-model reference enumerates every shipped config type — Tower, Enemy, Map, Path, BlockedRegion, Wave, WaveGroup, Scenario, Difficulty, Attack, AttackEffect (all kinds shipped), TargetingStrategy (all kinds), PlacementMode (all kinds), MapFeature, WaveTrigger (all kinds), RewardKind (all kinds), UpgradeOp (all kinds), Upgrade, GameRule, Template — with every field, its type, its unit (where applicable), and a cross-reference to the relevant ADR.

End-to-end behaviour the slice must produce:

• README in the repo root (or engine package root, per package layout):
  • 1–2 sentence orientation: what this engine is.
  • "Install" section.
  • "First Scenario" snippet: import bundle, construct engine, load a tiny in-memory ConfigRegistry, tick, observe an event. Five-line target.
  • Links to: the Node CLI demo, the browser demo, the JSON data-model reference (this slice), the Plugin authoring guide (Slice 21), the API reference (Slice 21), CONTEXT.md, docs/adr/.
  • Brief "Plugins are how you extend the engine, JSON is how you use it" framing.
• JSON data-model reference (single document, or split per config type — implementation team's call):
  • For every shipped config type: field table with name, type, unit (or "N/A"), required/optional, default (if any), one-sentence description.
  • For every plugin-extensible discriminator: list every shipped kind and link to its dedicated subsection.
  • For each AttackEffect / TargetingStrategy / UpgradeOp / PlacementMode / MapFeature / WaveTrigger / RewardKind / GameRule kind: the kind-specific fields, their units, and a one-line behaviour description.
  • Examples per config type drawn from the shared game-data set (Slice 16) so they're real and validated.
  • Cross-references to relevant ADRs (e.g. "see ADR-0004 on canonical units").
• Both documents are checked into the repo (not generated to a separate site).
• Documents reference no internal-only file paths or planning docs — they stand alone per the project's feedback_docs_self_contained.md memory.

Acceptance criteria

• README in place with sections listed above; "First Scenario" snippet runs against the engine as a doctest or is verified by a smoke test.
• JSON data-model reference documents every shipped config type with full field tables (name, type, unit, required/optional, default, description).
• Every shipped kind value across every plugin-extensible registry is documented with its config fields.
• Examples in the reference are drawn from demos/shared-data/ (Slice 16) verbatim — not invented examples.
• All ADR cross-references resolve to existing files in docs/adr/.
• No reference to planning docs or in-flight design docs.
• A meta-test asserts the reference covers every registered kind in the built-in plugin bundle (no kind ships undocumented).
• No regressions on tests from earlier slices.

Blocked by

• Slice 1: Tracer bullet — minimum Scenario plays end-to-end #2
• Slice 2: Loader DX — error catalogue, templates, strict mode #3
• Slice 3: AttackEffects — multi-effect composition #4
• Slice 4: Projectile EntityKind + flight system #5
• Slice 5: TargetingStrategies — full set #6
• Slice 6: Upgrades — purchase, prerequisites, exclusive groups #7
• Slice 7: Sell Tower + sell-value reward #8
• Slice 8: Multi-wave Scenarios + wave-clear #9
• Slice 9: WaveTriggers — auto and hybrid #10
• Slice 10: Placement — free mode + blocked regions #11
• Slice 11: Override targeting + multi-path Scenarios #12
• Slice 12: Aerial Enemies #13
• Slice 13: Guards plugin — the worked example #14
• Slice 14: Save/Load — snapshot & transcript formats #15