Owner's guide

Releases and upgrades

Your instance is a fork of a maintained base. Improvements to the base come as numbered releases, and you pull the ones you want, on your word. This is how a release gets cut, how your fork takes one in, and what happens to your own changes when it does.

The release streamA release changes your instance only when you pull it

Work on the base happens in its own repository, and none of it changes your instance until you pull a release. News of a new version comes the same way, when you ask. "Is there a new version?" has your Claude check the base for releases newer than yours and read you their notes.

A releaseA release is a numbered version of the base plus its notes

Cutting a release stamps a version number on one exact point in the base's history and writes the notes a fork owner reads before upgrading. It happens when the base's owner says so, never as a side effect of a change, and doc-only changes go out with the next real release rather than getting one of their own. So far the base has cut none. The numbering starts when the first fork needs a version to absorb, so you may be reading this page before the first release exists.

UpgradingAn upgrade applies the release and re-checks everything

Say the word and your Claude follows the written procedure: read the release notes, record your current version as a rollback point, apply the release, re-run every check, and confirm the apps still work. If anything breaks, it resets to the rollback point and redeploys.

An upgrade changes code, not data. Your journal, tasks, and everything else stay exactly as they were. A release that changes how your data is stored has to say so in its notes, and none has ever existed.

Getting it onto your phoneYour phone takes a change one of two ways

Deploying the web app puts a change in front of you the next time you reload. A phone holds an installed app, so a change reaches it by one of two routes, and which route it takes is decided by what changed.

An over-the-air update, for a change that is only JavaScript: Most of what gets built is JavaScript: screens, layout, wording, the rules the app follows. Your Claude publishes that to the app already on your phone in about a minute, with no build, no store and nothing for you to install. Your app asks for one each time it opens, downloads it in the background, and runs it the next time you open the app. So the open that fetches an update still shows you yesterday's version, and the one after it shows the new one.
A full build, for anything native: Some changes are part of the installed program itself rather than the JavaScript on top of it: a new capability the phone has to grant, a permission, the icon, the splash screen, or a move to a newer Expo. Those take the slow route. About fifteen minutes to build, then Apple's own processing, then you tapping Update in TestFlight.
The version number is the fence between them: Every build is stamped with the app's version, and an update is offered only to builds stamped with the same one. That is what stops a JavaScript update from landing on a build that does not contain the code it calls, which would open to a white screen. So a native change bumps the version, and the phones on the old version stop being offered updates until they take the new build.

The first build has to arrive the slow way. The piece that asks for updates is itself part of the installed program, and no build shipped before Aug 30 2026 contains it. Version 1.7.0 is the first that does. Until a phone is carrying 1.7.0 or later, an over-the-air update reaches it zero times, however successfully it published.

You do not choose between the routes. Say what you want and your Claude takes whichever one the change needs, and tells you which it was and when you will see it.

Your forkAn upgrade re-applies your changes on top of the new base

Your changes stay in your fork as their own series on top of the base. Your Claude keeps a ledger of them in docs/DIVERGENCE.md, one line per change saying what it does and why. A release can conflict with one of your changes when the base changed the same part you did. Your Claude then re-reads that change's line in the ledger and either adapts your change to the new base or retires it because the base now covers it, and it tells you which. Rewording these guides counts too. Opening a page with ?edit turns on its editor, and a save writes your words straight into the file, a change that goes in the ledger like any other.