Where the record lives
Status and roadmap is what ships today; versions and upgrades is the policy this record follows; compatibility is what a version promises; and pithy upgrade is how you move.
Each package carries its own CHANGELOG.md, beside its source. That is the authoritative record for what changed in it.
This page is about how to read one, not a copy of it.
Every capability is versioned independently
pithy doctor reports each composed capability’s version and whether a newer one is available:
Project capabilities:
@pithy-sh/core 1.2.0 ✓
@pithy-sh/auth 1.1.8 (1.2.0 available — run `pithy upgrade`)
@pithy-sh/leaderboard 1.2.0 ✓So you upgrade what you want, when you want, rather than moving everything because one thing changed.
What a version does not cover
Two things that never arrive on their own
A screen pithy ui add wrote is yours from that moment. A later release changing the kit’s version of it changes the template in the package, not your copy — Pithy never rewrites a file it has written.
The generated client types are copied too, so a new declare module block is hand-maintained. Until you add it, the virtual module is unresolved to your compiler and serves correctly at runtime.
What upgrades on its own is everything on the other side of the seam — the negotiation, the merge order, the kit’s translations, the formatting, the client projection.
Migrations are append-only
A migration’s order is stable forever. A released one is never renumbered and never edited — a change to a migration that has run somewhere is a change that will not run there.
Every migration has a tested down.
What a capability’s own docs record
Where a design decision was reversed, the reason is written down — and those entries are the ones worth reading.
The refresh-token grace window, the processedAt column that means finished with rather than seen, the two support category columns that must never merge, the replay guard that moved from KV to D1: each is a defect that reached real behavior, and each is documented as such.
Before you upgrade
pithy doctor
pithy upgradeAnd read the capability’s changelog for anything that moved a default — a default is the value most projects run, and moving one moves them all.