Generated folders

shared/ is the one place edited by hand. Everything tools/sync-shared.mjs copies out of it, and everything any other tools/*/build.mjs script writes, is generated output: editing the copy appears to work and then vanishes at the next sync or build, with no warning. Edit the source it names instead.

Recognising a generated file

GENERATED by <tool> from <source> — edit the source, not this copy. — every file in the ten mirrors below (tools/sync-shared.mjs:94), plus the icon sprite (GENERATED by tools/icons/build.mjs) and the brand assets (GENERATED by tools/brand/build.mjs).
GENERATED-SOURCE: written by <tool> — used where a tool computes the whole file rather than copying it, for example shared/tokens/fonts.css's GENERATED-SOURCE: written by tools/fonts/build.mjs.
GENERATED by `tools/emails/build.mjs` (with backticks) — the first lines of emails/README.md.
GENERATED.json — one manifest per mirror, listing every file it wrote, its source and a hash, so a diff shows exactly what changed.
tools/starter/.generated/<name>.json — the same idea for a starter: which edition file backs each overlay's pin.

None of these mean "do not read" — they mean "do not edit here". The file you want is named on the same line. shared/tokens/index.css, for instance, begins GENERATED-SOURCE: edit in shared/tokens/, never in an edition — that header marks the hand-edited source itself, not a copy of it.

The ten mirrors

Package	Mirror	Marker	In a standalone folder
html	`html/shared`	`GENERATED.json`; header `GENERATED by tools/sync-shared.mjs from …`	Yours to edit
react	`react/src/shared`	`GENERATED.json`; header `GENERATED by tools/sync-shared.mjs from …`	Yours to edit
nextjs	`nextjs/src/shared`	`GENERATED.json`; header `GENERATED by tools/sync-shared.mjs from …`	Yours to edit
vue	`vue/src/shared`	`GENERATED.json`; header `GENERATED by tools/sync-shared.mjs from …`	Yours to edit
nuxt	`nuxt/app/shared`	`GENERATED.json`; header `GENERATED by tools/sync-shared.mjs from …`	Yours to edit
starter-html	`starters/html/shared`	`GENERATED.json`; header `GENERATED by tools/sync-shared.mjs from …`	Yours to edit
starter-react	`starters/react/src/shared`	`GENERATED.json`; header `GENERATED by tools/sync-shared.mjs from …`	Yours to edit
starter-nextjs	`starters/nextjs/src/shared`	`GENERATED.json`; header `GENERATED by tools/sync-shared.mjs from …`	Yours to edit
starter-vue	`starters/vue/src/shared`	`GENERATED.json`; header `GENERATED by tools/sync-shared.mjs from …`	Yours to edit
starter-nuxt	`starters/nuxt/app/shared`	`GENERATED.json`; header `GENERATED by tools/sync-shared.mjs from …`	Yours to edit

Everything else that is generated

Path	Produced by	Regenerate with	How to recognise
`html-dist/`	`html/build.mjs`	`cd html && pnpm run build`	build output next to the html/ folder
`starters/html-dist/`	`starters/html/build.mjs`	`cd starters/html && pnpm run build`	build output next to the starter
`html/assets/vendor/, starters/html/assets/vendor/`	`html/vendor.mjs`	`cd html && pnpm run build (starters/html the same)`	third-party scripts fetched once by vendor.mjs, bundled in by bundle.mjs
`dist/, .next/, .nuxt/, .output/`	the framework's build	`pnpm run build`	the framework's own build output — Vite, Next.js or Nuxt, not an Orion script
`docs-dist/`	`tools/docs/build.mjs`	`node tools/docs/build.mjs`	this site
`shared/icons/sprite.svg, shared/icons/sprite.mjs, shared/icons/sprite.d.mts, shared/icons/sprite.inline.js, shared/icons/icons.css`	`tools/icons/build.mjs`	`node tools/icons/build.mjs`	the header comment
`shared/brand/*`	`tools/brand/build.mjs`	`node tools/brand/build.mjs`	the header comment (the favicon PNGs are binary and carry none)
`shared/fonts/, shared/tokens/fonts.css`	`tools/fonts/build.mjs`	`node tools/fonts/build.mjs`	the header comment on fonts.css (the font files themselves are binary)
`shared/mock/*.json (12 fixtures), shared/mock/dataset.inline.js`	`tools/mock-data/build.mjs`	`node tools/mock-data/build.mjs`	the header comment on dataset.inline.js (the JSON fixtures carry none)
`emails/`	`tools/emails/build.mjs`	`node tools/emails/build.mjs`	the header on emails/README.md
`starters/ (each starter’s own pnpm-lock.yaml excepted)`	`tools/starter/build.mjs`	`node tools/starter/build.mjs <name>`	the ledger, tools/starter/.generated/.json
`tools/icons/icons.generated.js`	`tools/icons/build.mjs`	`node tools/icons/build.mjs`	the filename
`tools/token-specimen/tokens.generated.js`	`tools/token-specimen/build.mjs`	`node tools/token-specimen/build.mjs`	the filename

Checking for drift

Full repository only

node tools/sync-shared.mjs
node tools/sync-shared.mjs --check

--check fails the moment a mirror has been hand-edited instead of its source in shared/, is missing, or contains a file with no source at all. Every edition and starter's build script — and dev, for the ones that have one — runs the sync in write mode first (pnpm run sync), which overwrites a hand-edited copy rather than catching it; pnpm run check, run separately, is what calls --check.