Customize your copy and take updates safely

Your copy of the code and your database are yours to change, with your own Claude Code. When we ship a release, the update compares what you changed with what the release changes, rehearses it on your database first, and never replaces something of yours without asking you.

Where your changes belong

• Screens and code of your own: in the src/custom folder of your copy. Releases never touch it.
• Database changes of your own: in a numbered file from 9000 up in supabase/migrations (for example 9001_our_price_rules.sql). Our files never reach 9000.
• Settings, dropdowns, templates and roles: change them on your screens, as always. An update that would write one you changed asks you first.
• You can change our own files too, once you unlock them (below). It works, but each update that changes the same file asks you to merge the two, so keep those changes few.

The locked core

A new copy comes with its core locked. The product's own files and database objects refuse changes made anywhere but your own places, so your Claude Code (or anyone in the SQL editor) cannot change something of ours by accident. It is told where the change belongs instead. Updates pass the lock by themselves.

• To change one thing of ours anyway: for a file, add an entry for it in CUSTOMIZATIONS.md; for something in the database, run select public.core_unlock('<kind>', '<name>', '<why>'); with the kind and name the refusal showed.
• To see what is unlocked: Settings, Tools, Health, Your changes.
• A copy from before release 0.35.0 is not locked until you turn it on (UPDATING.md in your copy says how).

Steps

1. Open Settings, Tools, Health. Updates lists the newer release; Your changes says what in your database differs from what we shipped.
2. Open your copy's folder in Claude Code and type /update.
3. It makes sure there is a fresh backup of your database. If there is none, it offers to take one, and does not go on without it.
4. It shows what the release changes and sorts it: safe, a file you both changed, something in your database you changed, something of yours that uses what the release changes, and data at risk.
5. For each thing of yours the release would replace, it shows both versions and asks you: keep mine, take yours or a merged version. It never picks for you.
6. It takes the release on a separate branch, so your main copy is untouched until you say so.
7. It rehearses the whole update on your database and undoes it, then runs the tests and the build.
8. Only when everything passed, and you say go, it applies the update to your database, then tells you which server programs to deploy and how to publish the app.
9. Back on Health, Updates should say you have the newest release.

Good to know

• Keep mine saves your version as a 9000-range file that runs after the release, so yours stays. Take yours keeps a word for word copy of what you had, in case you want it back.
• A database change you made is only asked about when a release would replace it. Everything else of yours is left alone.
• The update stops on its own if a release file ever tries to replace something you changed, even if someone runs it by hand.
• No release removes your data. A release file that would delete rows, tables or columns must say why, and the update shows it to you before anything runs.
• Nothing is sent anywhere: the checks run on your computer and against your own database.

If something goes wrong

• "Update stopped before migration ... changed anything". Something in your database differs from what we shipped, and the release would replace it. Nothing was changed. Run /update to see it and choose.
• "No fresh backup, so the update will not start." Let it take one (it may need Docker for this), turn on point-in-time recovery in Supabase, or take a backup another way and give it the file.
• A test or the build fails after the merge. Usually a file you both changed. The update stops on its branch; ask Claude Code to explain the failure, fix it there, and run /update again.
• You want to undo. Ask /update to roll back. Your main branch was never changed; the database goes back from the backup taken at the start. See Restore a backup.