Three documents govern this repo, and nothing else does.
| What it governs | |
|---|---|
| The design spec | What the game is, and why each decision went the way it did |
ui-sensibility.md |
What the interface has to produce |
../CLAUDE.md |
How to write the code |
Everything under superpowers/ is the record of how those three were arrived at:
one spec per change, one plan per spec. Read the design spec first — the rest amends it.
There is no reference/ directory. The planning documents that predated the code specified a
server-authoritative Laravel engine that this project reversed, so they were deleted rather than
left to be half-believed. Everything of theirs that survived was folded into the design spec,
which says so where it happened.
Each one extends the ones before it. Read them in order and the game's shape is the sum.
| Spec | Subject |
|---|---|
| 2026-08-03 · Dread Majesty | The design. The cascade, the layering, the five engine rules, the milestones. |
| 2026-08-04 · Economy retune | Cost tracks purchases rather than holdings. |
| 2026-08-04 · Smite as a system | Smite gains a cost (Apathy), a ceiling, and four upgrade ladders. |
| 2026-08-04 · Stage and rail polish | Eleven interface fixes from a play test. |
| 2026-08-06 · Post-smite tuning | Teeth for the shop, a correct recommendation on the rail. |
| 2026-08-08 · The soul curve | Prestige souls: a tunable exponent in place of a square root. |
| 2026-08-13 · Onboarding | The beat model. One prompt at a time, gating one control. |
| 2026-08-14 · Onboarding presence | The spotlight, and enough visual weight to act on. |
| 2026-08-14 · The Malice track | The second voice: what she wants, and both ways it can end. |
| 2026-08-14 · The title screen | A front door for a genuinely fresh run, and a whole-number rate. |
Every spec carries a Status line, and every one of them reads built — the design spec
through M4, the rest entire. Each also names at its head what it extends or supersedes, so a
section that has been overtaken can be traced to whatever replaced it. Where a spec and the code
disagree, that is a bug in one of them — say which.
One per spec, written to be handed to somebody with no context. They are kept because they record what the work actually cost, not because they are worth reading first.
economy retune · stage and rail polish · smite as a system · post-smite tuning · soul curve · onboarding · onboarding presence · malice track · title screen · card and cadence
ui-sensibility.md is normative for everything in apps/web, and about
thirty source files cite it by section number — tokens.css §4, controls.css §3,
TierNode.css §8, tokens.test.ts §13, and so on.
Section numbers are stable. A section may be rewritten, but renumbering one silently breaks every citation pointing at it. Add at the end, or add a decimal under an existing number.
assets/ holds what the README shows: screenshots, and standalone copies of the
game's own marks. The marks are pinned to the components that draw them — edit a silhouette
and apps/web/src/ui/art/TierArt.test.tsx fails until the copy is brought along.