Staying on the upgrade path
Most templates force a choice: customize it heavily, or keep getting updates. This one does not — but only because the line between “yours” and “ours” is written into the files themselves and checked by a command. Here is how to stay on the right side of it, and how to get back if you cross it.
1. Every file tells you who owns it
Line one of every code and config file carries a marker. Read it before you edit — or grep @genesis-managed: across the repo.
CORE
Framework machinery, hash-locked. Do not edit — make the change in a lane.
FRAMEWORK
Pages we maintain and upgrade. Change their words via content files; add your own pages beside them.
LANE
Yours. Edit freely — upgrades never overwrite these.
2. One command tells you the truth
$ npm run upgrade:check upgrade-check: 166 core files, 0 edited, 0 missing ✓ on the upgrade path — no core files edited. Framework upgrades will drop in cleanly.
It also runs inside pnpm verify, so a normal pre-ship check catches drift before it reaches your repository.
3. Taking a new release
$ git fetch template $ git merge template/main # read WHATS-CHANGED.md to see what moved $ pnpm verify && pnpm build $ git push # your host deploys
Each release ships a WHATS-CHANGED map: what changed, whether it touches files you own, and what action (if any) it needs from you. You upgrade on your schedule, not ours.
4. If you drift — recovering
Say the check reports an edited core file. The fix is two moves, and it never costs you your content:
# 1. take our version of the framework file back $ git checkout template/main -- path/to/core-file.tsx # 2. re-apply your change in a lane instead # (site.config.ts · lib/content/* · your own components · your own app segments) $ npm run upgrade:check # green again
Rebuilding from a fresh clone is the heavier option and still short: clone the current template, copy your lane files across, done. Customization is confined to a small, known list of files by design — which is exactly what makes starting over cheap instead of catastrophic.
Common questions
What does “on the upgrade path” actually mean?
Your clone has not edited any framework file. Those files are content-hash-locked, so an upstream release can replace them cleanly. Your brand, words, pages, and components live in separate lane files that upgrades never touch.
How do I know if I have drifted?
Run `npm run upgrade:check`. It prints how many core files exist, how many you edited, and how many are missing — for example “166 core files, 0 edited, 0 missing”. Any non-zero edited count names the exact files.
I edited a framework file and the check is red. Did I lose my work?
No. Restore the framework file with `git checkout template/main -- <path>` and move your change into a lane. Your content lanes are untouched by that restore, so you never lose your words or your pages re-taking our base files.
What if I drifted so far that merging is a mess?
Rebase onto a fresh clone: take the current template, copy your lane files across (site.config.ts, lib/content/*, your components, your app segments, public assets), and you are current in one step. Because customization is confined to those files by design, “start fresh and bring my lanes” is a short list, not a rewrite.
How often should I merge upstream releases?
Whenever you like — sites upgrade on their own schedule. Each release ships a WHATS-CHANGED map telling you what moved and whether it touches anything you own, so you can decide per release rather than living on a treadmill.