feat(dx): adopter-owned app zones for easier template upgrades

[ZappoMan]

Business need

Every Beaker Stack fork diverges immediately — that is expected and healthy. Adopters customize branding, marketing, pricing, policies, dashboard UI, and eventually their own database schema. They rarely modify core template features (admin panel, billing package, email packages, waitlist, observability).

The problem today: adopter-owned customization is scattered across the repo (packages/shared, apps/web/src/billing/, apps/web/public/landing/, assets/, mobile mirrors, etc.). When a fork merges a new CalVer template tag, conflicts land in files the adopter edited for branding, demo dashboard, or config — mixed together with template wiring they never intended to own.

This makes template upgrades painful and unpredictable. Release notes cannot reliably say "these paths are safe" vs "expect conflicts here." The rename script walks the entire repo and leaves template code mutated, which further drifts forks from upstream.

What we want: a clear ownership model so fork owners can:

1. Customize their adopter app (one app per fork, web + mobile) in a single predictable tree
2. Merge upstream template updates with conflicts concentrated in template/ and packages/, not in their app code
3. Rebrand via npm run rename without touching template code at all
4. Add adopter-specific database schema, integration tests, and pgTAP tests without fighting template migrations

This directly supports the product promise in README: "Fork the template; update the packages."

---

Expected adopter workflow (after this work)

Adopter customizes	Lives in
Branding, logo, colors, legal	adopter/config/, adopter/assets/
Landing copy + marketing images	adopter/config/landing.ts, adopter/assets/landing/
Plan tiers / feature keys	adopter/config/billing.ts
Policies, waitlist copy, email personalization	adopter/content/, adopter/config/, adopter/email/
Dashboard, custom pages/components (web + mobile)	adopter/web/, adopter/mobile/
Adopter database schema	adopter/db/migrations/
Adopter tests (unit, integration, db, e2e)	adopter/**/__tests__/, adopter/tests/, adopter/e2e/

Adopter rarely edits	Lives in
Admin, billing shells, auth pages, landing section components	apps/*/src/template/
Framework packages	packages/ (@beakerstack/*)
Template migrations, CI, setup scripts	supabase/migrations/, .github/, scripts/

Typical upgrade after reorg:

git merge 2026.NNN
# conflicts in apps/*/src/template/** and infra — not in adopter/
npm install
supabase db reset && npm run db:apply-adopter
npm run type-check && npm run test

---

Naming model

Three tiers — avoid confusing "product" (billing tiers) with "adopter app":

Tier	Form	Where
Template scope	@beakerstack/*	packages/, imports in apps — stays in template code
Demo product name	Beaker Stack, logo, landing copy/images	adopter/ only
Demo app identifiers	beakerstack, productId: 'beakerstack'	adopter/config/ only — what npm run rename rewrites

Template code uses neutral local names (billingConfig, waitlistConfig). No beakerstack* file/export/class names outside adopter/.

---

Proposed layout (summary)

adopter/                         # Entire tree = adopter-owned
  config/                        # branding, legal, colors, landing, billing, waitlist
  content/                       # policy markdown
  assets/                        # icon, landing images
  email/                         # .personalization.json
  web/                           # pages, components, routes.tsx
  mobile/                        # screens, components, navigation.tsx
  db/migrations/                 # adopter schema (never supabase/migrations/)
  tests/integration/             # adopter Jest integration tests
  tests/db/                      # adopter pgTAP tests
  e2e/web/specs/, e2e/mobile/flows/

apps/web/src/template/           # admin, billing wiring, landing components, auth pages
apps/mobile/src/template/        # mirror template wiring

Key structural changes:

1. configureAdopter() bootstrap — extract branding/legal/colors/policies from @beakerstack/shared into adopter/config/; shared package reads injected config at runtime
2. Route/screen registries — adopter/web/routes.tsx and adopter/mobile/navigation.tsx imported by thin App.tsx / AppNavigator.tsx
3. Adopter-only rename — npm run rename scans only adopter/**; template code stays byte-identical to upstream
4. Adopter DB workflow — supabase db reset (template) → npm run db:apply-adopter (adopter migrations on top)
5. Test split — template tests in packages/, template/**, tests/integration/, supabase/tests/; adopter tests under adopter/

---

Acceptance criteria

Layout & ownership

• adopter/ directory exists with documented zone map in docs/CUSTOMIZING.md
• All adopter config (branding, legal, colors, landing, billing, waitlist, policies, landing images) lives under adopter/
• Template wiring lives under apps/web/src/template/ and apps/mobile/src/template/
• Demo dashboard (web + mobile) lives under adopter/web/ and adopter/mobile/ as replaceable starter
• App.tsx and AppNavigator.tsx import adopter routes/screens via stable registry modules

Naming & rename

• Template code uses neutral exports (billingConfig, waitlistConfig); demo productId: 'beakerstack' and displayName: 'Beaker Stack' live only in adopter/config/
• @beakerstack/* npm scope unchanged in template code
• npm run rename scopes exclusively to adopter/** — no changes to apps/, packages/, supabase/, scripts/, docs/, .github/
• docs/renaming.md updated for adopter-only rename model

Database

• adopter/db/migrations/ established; adopter schema never added to supabase/migrations/
• npm run db:apply-adopter applies adopter migrations after template reset
• npm run migration:new:adopter scaffolds adopter migration files
• Adopter DB types generated to adopter/db/types/ separately from template types

Tests

• Adopter unit tests co-located under adopter/**/__tests__/
• Template unit tests under apps/*/src/template/**/__tests__/ and packages/*
• Template integration tests remain in tests/integration/
• Adopter integration tests in adopter/tests/integration/ with test:integration:adopter
• Template pgTAP in supabase/tests/; adopter pgTAP in adopter/tests/db/ with test:db:adopter
• Marketing/copy E2E in adopter/e2e/; functional flow E2E stays in tests/e2e/web/specs/
• Mock adopter config fixture for template/framework tests (no direct import of live adopter/config/branding.ts)
• docs/TESTING.md decision matrix updated

Upgrade ergonomics

• docs/UPGRADING.md documents conflict resolution: keep adopter/**, accept upstream for template/** and packages/**
• Promotion PR adopter notes template lists likely conflict paths by zone
• Optional: .gitattributes adopter/** merge=ours documented
• Optional: npm run upgrade:check script

Quality gates

• All existing tests pass after migration
• npm run type-check passes
• CI runs full suite (template + adopter); documents fork CI adopter-only slice

---

Phased rollout

Phase 1 — Document + physical moves (low risk)

• Create adopter/ tree; move config files, landing images
• Add apps/*/src/template/; move admin + billing wiring
• Add docs/CUSTOMIZING.md
• Begin test moves (adopter config tests → adopter/config/__tests__/)

Phase 2 — Shared decoupling + naming (medium)

• Extract branding/legal/colors/policies from @beakerstack/shared
• Add configureAdopter() bootstrap
• Neutral export names; rewrite rename script (adopter-only)
• Move dashboard demo to adopter/web + adopter/mobile

Phase 3 — Upgrade ergonomics + test/DB completion (polish)

• Route/screen registries, .gitattributes, release notes automation
• adopter/e2e/, adopter/tests/integration/, adopter/tests/db/
• db:apply-adopter, migration:new:adopter, adopter test scripts

---

Success criteria (outcome)

After shipping, a fork owner who has customized branding, dashboard, and added adopter DB schema can merge a CalVer tag with:

• Zero conflicts in adopter/** (or auto-preserved via merge driver)
• Conflicts only in apps/*/src/template/**, supabase/migrations/, and infra they expect to review
• Rebrand without any template code diff
• Day-to-day CI via adopter test slice; full template suite after upgrades

---

Related docs

• docs/UPGRADING.md
• docs/VERSIONING.md
• docs/renaming.md
• docs/specs/beakerstack-billing-v1.md (module vs app boundary)

[diego-artificerinnovations]

Critique — Issue #369: Adopter-owned app zones

The business problem is real and the direction is right. Clear ownership zones will genuinely improve the upgrade story. A few structural issues in the plan need resolution before implementation starts.

---

BLOCKING: Phase ordering is inverted

The plan labels Phase 1 (file moves) "low risk" and Phase 2 (shared decoupling + configureAdopter() bootstrap) "medium." But you cannot safely move the config files in Phase 1 until @beakerstack/shared knows how to read config from the new adopter/config/ location — that's Phase 2's work. Doing the moves first means either:

a) All existing import paths update in Phase 1 (import path refactor is not "low risk" — it touches every consumer of the moved files), or
b) Phase 1 moves the files but leaves behind re-export shims in the old locations, creating a temporary three-way mess.

The correct ordering is: Phase 2's decoupling work must precede Phase 1's moves. Alternatively, collapse Phases 1 and 2 into a single "decoupled config + physical layout" phase with one PR.

---

BLOCKING: configureAdopter() bootstrap is underspecified

This is the most load-bearing architectural decision in the entire plan, and it gets one sentence: "shared package reads injected config at runtime." Key questions that must be answered before anyone writes code:

1. Initialization timing. When is configureAdopter() called — before module evaluation, in a top-level App.tsx effect, or at first use? In both React Native (Expo) and Vite/React, a module that reads config at import time will run before configureAdopter() is called if the call is deferred to a useEffect or component tree. The init must happen synchronously before any config-consuming import is evaluated.

2. Singleton testability. If @beakerstack/shared exposes a global config singleton, template tests (which import shared code) need a way to inject a mock config without importing the real adopter/config/branding.ts. The acceptance criteria mention "Mock adopter config fixture" but don't describe the API — specifically, is there a resetConfig() for tests, and what's the fallback when configureAdopter() hasn't been called?

3. Type contract. What does configureAdopter accept? Is it a full object, partial with defaults, or schema-validated? What happens when a required field is missing — throw at call time, or fail silently?

These aren't implementation details; they determine whether the whole architecture is testable.

---

BLOCKING: Rename script scope change breaks existing fork upgrade paths

The acceptance criterion says "npm run rename scopes exclusively to adopter/**" — but the current script walks the entire repo. Existing forks that have already run npm run rename have customized names in apps/, packages/, and supabase/ (wherever the script reached). When those forks try to upgrade to the reorg CalVer tag and then rerun rename, the new scope-limited script will miss every non-adopter file they previously renamed.

The plan needs to address what happens to forks-in-flight. Minimally, this needs a one-time migration path: "if you renamed before the reorg, run npm run rename:migrate which does a full scan once to undo remaining non-adopter names, then you're on the new model." Without this, the first adopter who upgrades is broken.

---

BLOCKING: Route/screen registries create more complex merge conflicts, not simpler

The plan proposes moving navigation to adopter/mobile/navigation.tsx (and web equivalent) and having a thin AppNavigator.tsx import from it. The current AppNavigator.tsx has typed route params (RootStackParamList), typed navigation props, and linking configuration for deep links.

If the registry lives in adopter/, the adopter now owns the type system for navigation. When a template upgrade adds a new screen (e.g. future MFA or team-invite flow), the adopter must manually update their registry to add the screen — that is a merge conflict they must resolve, in a file they own, for code they didn't write. This is strictly worse than the current model where the conflict lands in template code they expect to review.

A better pattern: template owns the navigator with all template screens; adopter injects additional screens via an explicit extension slot (extraScreens?: ScreenDef[]), mirroring the sidebarFooter slot pattern from PR #333. The adopter only owns the slot content, not the registry.

---

NON-BLOCKING: Adopter DB migration interleaving is unspecified

The proposed workflow is supabase db reset (template migrations) → npm run db:apply-adopter (adopter migrations on top). This creates a timestamp sequencing problem: when a new template migration is released with a timestamp between two existing adopter migrations, supabase db reset applies them in interleaved order. The adopter migration may reference a table that the later template migration hasn't created yet.

The plan needs to document the timestamp namespace convention. Options:

• Adopter migrations use a prefix that sorts after all template migrations (e.g. 9000_ series)
• Adopter migrations live in a separate Postgres schema
• db:apply-adopter uses psql directly rather than Supabase migration runner to avoid ordering

Also: "Adopter DB types generated to adopter/db/types/ separately from template types" — Supabase's gen types typescript generates from the entire schema with no per-table filter. This acceptance criterion is not achievable with the current Supabase tooling as stated. The plan should specify the approach (separate schema, separate project, or hand-written types for adopter tables).

---

NON-BLOCKING: apps/*/src/template/ naming is counterintuitive

Conventionally, everything in apps/web/src/ is the app. Adding apps/web/src/template/ creates a sub-zone called "template" inside the app — which reads as "template code that lives in the app," not "the app-layer wiring that is template-owned." This naming will confuse contributors and is redundant: the distinction between template-owned and adopter-owned is already expressed by whether code is in apps/*/src/ vs adopter/. Consider just leaving it as apps/web/src/ (template-owned by definition) vs adopter/web/ (adopter-owned), without introducing template/ as an explicit sub-directory.

---

NON-BLOCKING: .gitattributes merge driver marked "Optional" but is load-bearing

The headline success criterion is "zero conflicts in adopter/**." Without the .gitattributes merge=ours driver, adopters still see conflict markers in their files during git merge — they just know to resolve them by accepting their own version. That is a UX failure relative to the stated goal. This should be promoted from Optional to Phase 3 required, with documentation of when merge=ours is appropriate (it's a blunt instrument; adopters who intentionally merge template changes into their adopter code need to know it bypasses those merges entirely).

---

NON-BLOCKING: CI stub for template repo is not designed

"CI runs full suite (template + adopter); documents fork CI adopter-only slice" — the template repo itself has no real adopter code. The CI plan needs to specify:

• What lives in the template's adopter/ (a minimal stub, or real demo content?)
• Whether template CI fails if adopter test scripts are missing (they shouldn't)
• How a fork adds its adopter test slice to CI without merge-conflicting on .github/workflows/

---

Summary

The three-phase structure is reasonable but Phase ordering needs fixing (Phase 2 must precede Phase 1), and the configureAdopter() interface needs a design spike before any code is written. The navigation registry approach solves the wrong problem — adopter-owned navigation creates harder conflicts than it prevents. The rename migration path for in-flight forks is a day-1 upgrade blocker.

Recommend: plan a design doc for configureAdopter() (initialization contract, singleton API, test fixtures) before any implementation begins, and revise the phasing so shared decoupling leads.

[mei-artificerinnovations]

Plan critique — adopter zones

The problem statement is correct and the three-tier naming model (template scope / demo product name / demo app identifiers) is clean. The phased rollout ordering (physical moves → decoupling → ergonomics) is sensible. The goal is the right one. That said, there are four issues I think need answers before implementation starts, and several smaller items worth tracking.

---

Blocking / needs resolution before Phase 1

1. configureAdopter() injection mechanism is unspecified

The plan says @beakerstack/shared will "read injected config at runtime," but doesn't define the mechanism. The risk is a circular dependency: adopter/config/branding.ts will import types from @beakerstack/shared; if shared also imports from adopter/config/ (or from a registry that adopter/ populates), you get a cycle at module initialization time.

Common patterns that avoid this:

• Dependency injection at app bootstrap — App.tsx calls configureAdopter(config) before any package code runs; packages read from a module-level singleton initialized by that call. No import from adopter/ inside packages/.
• Vite/Metro virtual modules — build-time resolution of a virtual:adopter-config alias pointing to adopter/config/index.ts.
• Re-export shim in apps/web/src/ — template code imports ../adopterConfig which re-exports from the adopter tree.

Each has different implications for tree-shaking, SSR, and test mocking. The plan should commit to one approach before Phase 2 work starts, because the choice shapes the Phase 2 diff substantially.

2. Cross-tree imports: adopter/web/ ↔ apps/web/src/template/ — build tooling not addressed

adopter/ lives at the repo root. apps/web/src/template/ is inside the Vite project. Adopter pages in adopter/web/ will need to import template components (layout shells, auth wrappers), and template components may need to reference adopter-registered routes.

This requires:

• Vite: resolve.alias entries pointing into adopter/, and adopter/ added to the TS project references or paths in tsconfig.json
• Metro (mobile): watchFolders and resolver.extraNodeModules to pick up adopter/mobile/

Neither is mentioned. Without this, Phase 1 file moves will break the build immediately. The plan should include the specific Vite/Metro config changes needed, or explicitly defer them to Phase 1's definition of done.

3. Supabase two-migration-directory workflow in production is not defined

supabase db reset + npm run db:apply-adopter works locally. But supabase db push (production deploys) only knows about supabase/migrations/. If adopter migrations live in adopter/db/migrations/, they won't be applied by the standard Supabase deploy workflow.

Options to resolve:

• Run a second psql pass after supabase db push for adopter migrations
• Use a single supabase/ directory with a filename prefix convention (adopter_ vs no prefix) and a filter script
• Supabase linked project + separate schema — probably too heavy

This needs a defined answer before the DB acceptance criteria can be written as testable. The current ACs (npm run db:apply-adopter exists, migration:new:adopter exists) describe scripts but not the production path.

4. Phase 1 surface area is underestimated

Moving files from apps/web/src/ to apps/web/src/template/ and from scattered locations into adopter/ will touch every import path that references the moved files — potentially hundreds of statements across both apps, packages, and tests. This is logically low-risk but operationally high-surface: any in-flight PR that edits a moved file will get a merge conflict, and CI will be broken in the gap between the first move commit and the final import-rewrite commit.

Recommendation: call out explicitly that Phase 1 requires a short trunk freeze (or a single atomic PR that moves + rewrites imports in one commit so CI is never broken mid-move), and estimate the diff size so the team can plan the review window.

---

Non-blocking — worth resolving during planning

5. .gitattributes merge driver is optional but it's the primary mechanism

The success criterion says "zero conflicts in adopter/**" but the adopter/** merge=ours driver is listed as optional. If a fork owner doesn't configure this, they'll still get conflicts in adopter/ whenever upstream touches files that were also in those paths before the reorg. The driver should be a required Phase 3 deliverable and the docs should explain that forks need to configure it after cloning.

6. Route registry interface: how does template code reference adopter-defined routes?

If a template component (say, the post-login redirect in the auth flow) needs to navigate to /dashboard, it currently hard-codes the path or reads it from a config. After the split, /dashboard may be an adopter-defined route. The plan needs to define the stable interface: does template code import a ROUTES constant from the registry? Does it call a navigation service? Or is it always a template-defined path (in which case, what's the rule)?

7. npm package scope rename: in scope or explicitly out?

The plan says @beakerstack/* scope is "unchanged in template code," which is correct for the packages themselves. But today's rename script likely also rewrites package names in fork owners' own new packages. Clarify: can a fork owner rename the @beakerstack npm scope across the repo, or is that intentionally not supported? If not supported, document why (e.g., upstream merges become impractical if package names diverge).

8. Acceptance criteria are implementation steps, not behavioral outcomes

Most ACs describe artifacts (directory exists, script runs) rather than behaviors. The top-level success criterion is a merge with zero conflicts in adopter/ — that should have a corresponding AC: "Create a test fork with adopter customizations, merge a synthetic upstream tag, confirm conflict set is confined to apps/*/src/template/** and supabase/migrations/**." Without a test of the actual upgrade flow, the ACs can all pass while the goal remains unachieved.

9. Shadow/override for template components not addressed

Some adopters will want to replace a specific template component (e.g., customize the admin layout header, replace the auth page design). The plan covers adding adopter-only pages via the route registry but doesn't address overriding template components. If the answer is "fork the template file directly" (i.e., they edit apps/web/src/template/), that's fine — but it should be documented explicitly so adopters know what to expect when that file gets an upstream update.

---

Summary

Issue	Severity
configureAdopter() injection mechanism unspecified	Blocking
Cross-tree imports + build tooling not addressed	Blocking
Production Supabase deploy path for adopter migrations	Blocking
Phase 1 trunk freeze / atomic PR strategy not called out	Blocking
.gitattributes merge driver should be required	Non-blocking
Route registry interface for template→adopter routes	Non-blocking
npm package scope rename stance	Non-blocking
ACs need behavioral upgrade-flow test	Non-blocking
Template component override pattern	Non-blocking

Happy to help spec out the configureAdopter() injection pattern or the Vite/Metro config changes if that would move things forward.

[rahul-artificerinnovations]

Plan critique

The problem statement is correct and the outcome is the right target. The adopter/ zone model is a clean solution. Most of the design is sound — the route registry fits naturally with React Router, and the phase structure makes sense as written. That said there are several gaps that need answers before Phase 1 begins, a few places where the framing undersells the actual scope, and one API-breaking change that deserves explicit acknowledgment.

---

1. Phase 1 → Phase 2 broken state (must resolve before work starts)

Phase 1 "moves config files" (branding, landing, billing config) from apps/web/src/config/ and packages/shared/src/ into adopter/config/. Phase 2 does the configureAdopter() extraction from @beakerstack/shared.

The problem: Phase 1 physically moves files that packages and app code still import. If the files move in Phase 1 but the configureAdopter() injection pattern isn't in place until Phase 2, the codebase is either broken between phases or relies on shim re-exports at the old paths. The plan doesn't say which.

If Phase 1 leaves shim re-exports (export { ... } from '../../adopter/config/branding.js') to keep the build green, those shims are tech debt that must be cleaned up in Phase 2 — and that cleanup is itself a large import-updating pass. If Phase 1 updates all imports immediately, it must happen atomically with the file moves in the same PR. Either way, this is not a clean sequential split.

Recommendation: Either (a) define Phase 1 as config extraction + shim pattern explicitly, with Phase 2 removing the shims; or (b) collapse Phases 1 and 2 into a single PR for the config side. The physical moves and the API extraction are not independently shippable.

---

2. configureAdopter() bootstrap call site is underspecified

The plan says "shared package reads injected config at runtime" but doesn't say when or where configureAdopter() is called, or what happens before it is.

Questions that need answers before coding:

• Call site: Is it called in main.tsx before <App />? In a module initializer? Must it complete synchronously?
• Uninitialized access: If a package imports branding before configureAdopter() runs — during module evaluation, in a Vitest test, or in a Storybook story — does it throw, return defaults, or return undefined? The fallback contract needs to be defined.
• Unit testing: The acceptance criteria mentions "mock adopter config fixture for template/framework tests" but doesn't specify the mechanism. If @beakerstack/shared reads from a singleton populated by configureAdopter(), tests need to either call configureAdopter() with fixtures or mock the singleton. Which pattern is expected? If it's the latter, there's a test isolation risk across test files.
• Web workers / service workers: Any code that runs outside the main JS thread won't have configureAdopter() called unless explicitly included.

This doesn't need to be fully specced in the issue, but the pattern (singleton, module default export, React context, or something else) should be settled before Phase 2 begins.

---

3. @beakerstack/shared API break deserves explicit acknowledgment

Extracting branding/legal/colors/policies out of @beakerstack/shared removes exports that adopters may be importing directly. This is a semver major change to the shared package.

Adopters who have forked and are importing import { BRAND_COLORS } from '@beakerstack/shared' (or similar) will have a compilation error after upgrading to the CalVer release that ships this work. The plan doesn't address a migration path — even a codemods script or a one-CalVer deprecation window.

This doesn't need to block the work, but the release notes and UPGRADING.md need a section that says "these exports moved; here's how to migrate" before this ships.

---

4. Production DB deploy for adopter migrations

npm run db:apply-adopter is documented for local dev and CI reset. But Supabase's production/staging deploy workflow applies supabase/migrations/ via supabase db push or supabase migration up. If adopter migrations live in adopter/db/migrations/, they are invisible to the standard Supabase deploy step.

The question: how does an adopter add a column to their own table and have it appear in production?

The plan mentions Phase 3 scripts (db:apply-adopter, migration:new:adopter) but not the deploy-time wiring. deploy-staging.yml and deploy-production.yml would need an explicit step that applies adopter migrations after the Supabase deploy step — and this step needs to run in the right order (template schema first, adopter on top). This is an operational requirement for the feature to work end-to-end and should be specified in Phase 3, not left implicit.

---

5. npm run rename scope — what about docs and README?

The plan says rename scans only adopter/**. But the repo README and docs/ reference "Beaker Stack" and "beakerstack" as the demo product name. If rename doesn't touch these, a fork that runs npm run rename will have a renamed app but docs that still say "Beaker Stack."

Is that intentional? Docs live in the template zone (rarely customized), and fork owners may be fine leaving them as "Beaker Stack" docs. But it should be a stated decision, not an oversight. docs/renaming.md (acceptance criteria) should explicitly say which occurrences rename touches and which it doesn't.

---

6. merge=ours for adopter/ should be a first-class decision, not optional

The plan lists .gitattributes adopter/** merge=ours as "optional." But this is what actually delivers the "zero conflicts in adopter/" promise.

There's a design fork here that the plan leaves open:

• Option A: Upstream template ships adopter/ as example starters (sample landing copy, sample dashboard). merge=ours keeps fork customizations on merge; upstream example improvements are silently dropped.
• Option B: Upstream template ships adopter/ as minimal stubs or doesn't include it at all. Fork adds their own content. No conflict risk by construction; merge=ours is irrelevant.

Option A gives adopters a better initial experience (working examples to modify). Option B is cleaner architecturally (no upstream opinion on adopter content). The plan should pick one. If Option A, merge=ours is required not optional.

---

7. Adopter type generation is a tooling gap that needs a concrete solution

"Adopter DB types generated to adopter/db/types/ separately from template types" is in the acceptance criteria, but supabase gen types generates the full schema — it doesn't support filtering by table. The options are:

• Run supabase gen types once and split the output with a script (fragile; breaks when table names change)
• Run against a schema-qualified prefix (e.g., adopter tables under a separate PostgreSQL schema like adopter rather than public) — clean but requires adopter migrations to use a separate schema
• Just generate the full type output and have both template and adopter code use it — simpler but doesn't cleanly separate ownership

This deserves a concrete decision before Phase 3. The separate-schema option would be the cleanest but it's an additional constraint on adopter migrations that isn't mentioned in the plan.

---

8. Phase 1 "low risk" framing undersells the mechanical scope

Phase 1 moves files across a large surface: apps/web/src/billing/, apps/web/src/admin/ (presumably), landing/config files, template component moves. Each moved file requires import path updates in every file that references it.

The logic is low risk — no behavior change. But the blast radius on import paths is large. A missed import silently compiles (if TypeScript path aliases are loose) or loudly fails. This isn't a reason to avoid Phase 1, but calling it "low risk" may lead to underestimating the PR scope. The Phase 1 PR should include a full list of moved files and a CI check specifically for "no remaining imports from old paths."

---

9. Mobile side is thin — needs a separate spec for React Navigation

The plan gives significant detail to the web route registry but is sparse on mobile. The mobile equivalent — adopter/mobile/navigation.tsx imported by AppNavigator.tsx — works differently depending on whether the app uses React Navigation v6 or Expo Router.

• React Navigation: screen registry is a JS object passed to navigators, not file-system-based. Route registry pattern is directly compatible.
• Expo Router: routes ARE the file system. adopter/mobile/ screens can't be registered externally; Expo Router discovers them by path convention.

If the mobile app uses Expo Router, the entire "route registry" model for mobile doesn't apply and the architecture needs a different approach. This should be resolved before Phase 3 begins for mobile.

---

Minor

• Template → adopter import direction: App.tsx (template code) will import the adopter route registry. This is intentional but worth stating explicitly in the doc — it's the only deliberate template-imports-adopter seam, and it should stay the only one. Any other template code that imports from adopter/ is a boundary violation.
• Test split decision matrix: Six test locations is a lot of cognitive overhead. The "CI adopter-only slice" should be a named script (test:adopter) that runs all adopter tests in a single command, regardless of how they're structured internally.

[ZappoMan]

Detailed implementation plan

This comment captures the full technical plan discussed during design. It supplements the issue description with diagrams, directory layout, mapping tables, and test/DB organization.

---

Terminology

Term	Meaning
Adopter app	The one application a fork owner builds on top of the template (dashboard, custom pages, domain components). Not Stripe/billing "products" or plan tiers.
Adopter config	Branding, legal, landing copy, landing images, plan catalog, waitlist copy, policy markdown, email personalization.
Template wiring	Admin panel, billing route shells, auth pages, landing section components, demo RPCs — things adopters rarely edit but the template updates frequently.
Framework packages	@beakerstack/billing, @beakerstack/admin, etc. — template scope; never edit in a fork; bump via npm or merge.

Naming model (three tiers)

Tier	Form	Where it belongs	Template code?
Template scope	@beakerstack/*	packages/, imports in apps	Yes — framework npm scope
Demo product name	Beaker Stack, logo, marketing copy, landing images	adopter/config/, adopter/content/, adopter/assets/	No — adopter zone only
Demo app identifiers	beakerstack, beaker-stack, productId: 'beakerstack'	adopter/config/ (branding flatName, billing productId, bundle slugs)	No — except inside adopter/ as the shipped example

Rule of thumb: Template code uses @beakerstack imports and neutral local names (billingConfig, waitlistConfig). It never uses beakerstack as a file name, export name, class name, or variable name. The demo app's beakerstack slug and "Beaker Stack" display name live entirely in adopter/ and are what npm run rename rewrites.

---

Zone architecture

One adopter-owned application per fork, spanning web + mobile. Shared config root plus per-surface UI folders.

flowchart TB
  subgraph adopterOwned [Adopter-owned — customize freely]
    AC[adopter/config]
    AW[adopter/web]
    AM[adopter/mobile]
    ADB[adopter/db]
  end

  subgraph templateOwned [Template-owned — merge upstream]
    TW[apps/web/src/template]
    TM[apps/mobile/src/template]
    INFRA[supabase/migrations CI scripts]
  end

  subgraph framework [Framework — bump npm packages]
    PKG["@beakerstack/* packages"]
  end

  AC --> AW
  AC --> AM
  ADB --> AW
  ADB --> AM
  AW --> PKG
  AM --> PKG
  TW --> PKG
  TM --> PKG

Loading

---

Proposed directory tree

adopter/                              # Entire tree = adopter-owned
  README.md                           # "Edit here; upstream never touches this"
  config/
    branding.ts                       # move from packages/shared
    legal.ts
    colors.ts
    strings.ts
    landing.ts                        # move from apps/web/src/config
    billing.ts                        # export billingConfig
    waitlist.ts                       # export waitlistConfig
  content/
    terms.md
    privacy.md
    refunds.md                        # move from packages/shared/src/content
  assets/
    icon.svg                          # move from assets/demo-flask-icon.svg
    landing/                          # move from apps/web/public/landing/
      hero.avif
      ...
  email/
    .personalization.json
  web/
    pages/                            # DashboardPage, custom routes
    components/                       # adopter UI (replaces demo dashboard)
    routes.tsx                        # registers adopter routes into App.tsx
  mobile/
    screens/                          # DashboardScreen, custom screens
    components/
    navigation.tsx                    # registers adopter screens into AppNavigator
  db/
    migrations/                       # adopter-specific schema (never in supabase/migrations/)
    seed.sql                          # optional adopter seed data
    types/
      database.ts                     # adopter-generated DB types
    README.md                         # migration workflow for adopters
  tests/
    integration/                      # adopter cross-system tests (Jest)
    db/                               # adopter pgTAP tests (*.test.sql)
    utils/                            # adopter test fixtures
  e2e/
    web/specs/                        # adopter Playwright specs
    mobile/flows/                     # adopter Maestro flows

apps/web/src/
  template/                           # Template-owned (upstream merges here)
    admin/
    billing/                          # BillingProviderLayout, demo RPC hooks only
    pages/billing/
    components/billing/
    components/landing/               # reusable section components (not copy)
    pages/auth/                       # login, signup, etc. (optional grouping)
  App.tsx                             # thin: template routes + import adopter routes

apps/mobile/src/
  template/
    billing/
    screens/billing/
  navigation/AppNavigator.tsx         # thin: template nav + adopter nav

Why hybrid (not a single apps/adopter/ app):

• Branding, legal, plan catalog, and policies are identical across web + mobile — one adopter/config/ avoids drift.
• Dashboard UI is platform-specific — adopter/web/ and adopter/mobile/ share hooks/types from @beakerstack/* but own their components.
• Template routes (admin, billing shells, auth) stay in each app under template/ so upstream merges are predictable.

Landing images (adopter-owned)

• Source of truth: adopter/assets/landing/
• Config references: adopter/config/landing.ts via publicUrl('landing/...')
• Build serving: Vite copies or aliases adopter/assets/landing/ → web public /landing/ at dev/build time
• Template owns: landing section components only (apps/web/src/template/components/landing/)

---

Mapping: what adopters customize → where it lives

Adopter concern	New home	Notes
Product name, logo, colors	adopter/config/branding.ts, colors.ts, adopter/assets/icon.svg	Remove from @beakerstack/shared
Marketing landing copy	adopter/config/landing.ts	Section components stay in apps/web/src/template/components/landing/
Marketing landing images	adopter/assets/landing/	Referenced from landing.ts via publicUrl(); Vite serves from adopter path at build
Plan tiers / feature keys	adopter/config/billing.ts	Single file imported by web + mobile; Stripe sync unchanged
Policy documents	adopter/content/*.md	build:policies reads from here
Waitlist copy	adopter/config/waitlist.ts
Email branding	adopter/email/.personalization.json	Pure templates remain template-owned in supabase/templates/
Adopter app UI (dashboard, custom pages)	adopter/web/pages, adopter/web/components, adopter/mobile/screens, adopter/mobile/components	Replace demo dashboard; add routes via routes.tsx / navigation.tsx
Adopter database schema	adopter/db/migrations/, optional adopter/db/seed.sql	Applied after template migrations; never in supabase/migrations/
Adopter DB + integration tests	adopter/tests/db/, adopter/tests/integration/	Test adopter schema, RLS, RPCs, and cross-system flows
Admin panel	apps/web/src/template/admin/	Adopters rarely edit; clearly template-owned
Billing UI shells	apps/web/src/template/billing/ + @beakerstack/billing	Adopters configure tiers, not package internals

---

Key structural changes

1. Move adopter config out of @beakerstack/shared

Today shared components import branding directly (packages/shared/src/components/navigation/AppHeader.web.tsx). Refactor to runtime config injection:

// apps/web/src/main.tsx (bootstrap)
import { configureAdopter } from '@beakerstack/shared/config';
import { adopterConfig } from '../../../adopter/config';

configureAdopter(adopterConfig);

@beakerstack/shared keeps template defaults for tests and Storybook; forked apps inject from adopter/config/ at startup.

2. Route/screen registry

Web — apps/web/src/App.tsx imports adopter routes as a separate module:

import { adopterRoutes } from '../../../adopter/web/routes';
// ... template routes ...
{adopterRoutes}

Mobile — apps/mobile/src/navigation/AppNavigator.tsx merges adopter screen definitions from adopter/mobile/navigation.tsx.

Upstream can rewrite App.tsx and AppNavigator.tsx freely as long as the stable import { adopterRoutes } line remains.

3. Retire the demo dashboard as the default adopter starting point

• Move current demo from apps/web/src/components/dashboard/ → adopter/web/ (starter the adopter replaces)
• Template keeps zero dashboard components; documents "start in adopter/web/pages/DashboardPage.tsx"
• Same for mobile DashboardScreen.tsx → adopter/mobile/screens/

4. Naming cleanup

Layer	@beakerstack scope	Beaker Stack display name	beakerstack as identifier
packages/**, template imports	Yes	No	No
apps/*/src/template/**	Yes (imports)	No	No — use neutral names (billingConfig)
adopter/**	No (imports @beakerstack/* from outside)	Yes — demo default	Yes — productId: 'beakerstack', flatName: 'beakerstack', bundle slugs
supabase/, scripts/, CI	Yes where importing packages	No literals	No — read from adopter/config at setup if needed

File/export renames:

• beakerstackBillingConfig.ts → adopter/config/billing.ts, export billingConfig
• beakerstackWaitlistConfig.ts → adopter/config/waitlist.ts, export waitlistConfig
• Inside adopter/config/billing.ts: keep productId: 'beakerstack' — demo app's billing product id
• Inside adopter/config/branding.ts: keep displayName: 'Beaker Stack', flatName: 'beakerstack' — demo defaults until rename
• Template wiring imports billingConfig from adopter; never names anything beakerstack* locally

---

Rename script: adopter-only scope

Before: scan entire repo, skip some paths/identifiers
After: scan only adopter/**, leave everything else untouched

npm run rename -- --to "Acme App"
  → reads current name from adopter/config/branding.ts
  → rewrites adopter/** only (config, content, assets, email personalization)
  → does NOT touch apps/, packages/, supabase/, scripts/, docs/, .github/

Benefits:

• Template code in a fork is byte-identical to upstream after rename
• No more PRESERVE_UPSTREAM_RELATIVE_PATHS skip lists or word-boundary hacks
• Rename becomes a simple, predictable "rebrand my app" operation

What rename rewrites (adopter only):

• Beaker Stack → adopter's display name
• beakerstack / beaker-stack slugs → adopter's identifiers (including productId, bundle IDs)
• Logo, landing copy, landing images, policies, email personalization

Docs: rewrite docs/renaming.md around adopter-only scope.

---

Upgrade support

Documentation

• New docs/CUSTOMIZING.md: zone map, "edit adopter/ only", what each template/ folder is for
• Update docs/UPGRADING.md: conflict resolution — keep adopter/**, accept upstream for apps/*/src/template/** and packages/**
• Update promotion PR adopter notes template: adopter/** (safe), apps/*/src/template/** (review), packages/** (usually auto-merge or npm bump)

Git merge hints (optional)

.gitattributes:

adopter/** merge=ours

Document configuring a merge=ours driver in docs/UPGRADING.md.

Upgrade checklist script (future)

npm run upgrade:check — after merging a CalVer tag, verify:

• adopter/ untouched by merge (or list conflicts)
• template/ paths updated as release notes specify
• @beakerstack/* versions in lockfile match release notes

---

Test organization

Tests follow the same three-zone model: tests live next to the code they protect, and adopter tests never merge-conflict with upstream.

flowchart TB
  subgraph unit [Unit tests — co-located]
    PKG["packages/*/__tests__\nframework"]
    ST["packages/shared-tests\nframework + mock adopter config"]
    TPL["apps/*/src/template/**/__tests__\ntemplate wiring"]
    ADP["adopter/**/__tests__\nadopter app + config"]
  end

  subgraph system [System tests — centralized + adopter]
    INT_T["tests/integration/\ntemplate framework"]
    INT_A["adopter/tests/integration/\nadopter app"]
    E2E_T["tests/e2e/web/specs/\ntemplate flows"]
    E2E_A["adopter/e2e/\nadopter flows"]
    DB_T["supabase/tests/\ntemplate pgTAP"]
    DB_A["adopter/tests/db/\nadopter pgTAP"]
  end

  subgraph schema [Database schema]
    MIG_T["supabase/migrations/\ntemplate"]
    MIG_A["adopter/db/migrations/\nadopter app"]
  end

  MIG_A --> INT_A
  MIG_A --> DB_A
  MIG_T --> INT_T
  MIG_T --> DB_T
  ADP --> INT_A

Loading

Unit tests

Zone	Location	What it tests	Upgrade behavior
Framework	packages/*/**/*.test.{ts,tsx}	@beakerstack/* hooks, components, adapters	Merge from upstream / npm bump
Shared UI	packages/shared-tests/__tests__/	Shared components; inject mock adopter config fixture	Merge from upstream
Template wiring	apps/*/src/template/**/__tests__/	Admin, billing shells, landing sections, auth pages	Merge from upstream
Adopter app	adopter/**/__tests__/	Config shape, dashboard demo, adopter pages/components	Fork-owned; no upstream conflicts

Moves from today:

Current path	New path
apps/web/src/config/__tests__/landing.test.ts	adopter/config/__tests__/landing.test.ts
apps/web/src/billing/__tests__/beakerstackBillingConfig.test.ts	adopter/config/__tests__/billing.test.ts
apps/web/src/waitlist/__tests__/beakerstackWaitlistConfig*.test.ts	adopter/config/__tests__/waitlist.test.ts
apps/web/src/components/dashboard/__tests__/	adopter/web/components/__tests__/
apps/web/src/pages/__tests__/DashboardPage*.test.tsx	adopter/web/pages/__tests__/
apps/web/src/admin/__tests__/	apps/web/src/template/admin/__tests__/
apps/web/src/pages/billing/__tests__/	apps/web/src/template/pages/billing/__tests__/
apps/web/src/components/landing/sections/__tests__/	Split: rendering → template/; copy assertions → adopter/config/__tests__/
packages/shared-tests/__tests__/config/branding.test.ts	adopter/config/__tests__/branding.test.ts
apps/mobile/__tests__/screens/DashboardScreen.test.tsx	adopter/mobile/screens/__tests__/
apps/mobile/src/components/dashboard/__tests__/	adopter/mobile/components/__tests__/

Shared test fixture: packages/test-utils/src/adopterFixtures.ts (or tests/utils/adopter-fixtures.ts) — mock adopter config for template/framework tests.

---

Integration tests

Zone	Location	What it tests	Upgrade behavior
Template integration	tests/integration/	Auth, RLS, billing entitlements, demo RPCs, waitlist, admin, edge functions	Merge from upstream
Adopter integration	adopter/tests/integration/	Adopter tables, RPCs, RLS, flows spanning adopter schema + app code	Fork-owned; no upstream conflicts

Jest config:

// tests/jest.integration.adopter.config.js
testMatch: ['**/adopter/tests/integration/**/*.test.ts']

Example adopter integration test concerns:

• Adopter table constraints and RLS policies
• Adopter RPCs / triggers from adopter/db/migrations/
• App hooks against real adopter schema
• Cross-feature flows combining template auth/billing with adopter domain tables

Template fixtures (tests/utils/billing-fixtures.ts) import plan IDs from adopter/config/billing.ts.

---

Adopter database schema

Adopters add tables, views, RPCs, and policies for their app. These must not live in supabase/migrations/.

Path	Purpose
supabase/migrations/	Template schema only — billing, waitlist, auth, admin, demo RPCs
adopter/db/migrations/	Adopter app schema — timestamped SQL
adopter/db/seed.sql	Optional adopter seed data (loaded after template seed)
adopter/db/README.md	Workflow: create migration, reset, type-gen

Apply order (local dev + CI):

1. supabase db reset          # applies supabase/migrations/ + supabase/seed.sql
2. npm run db:apply-adopter   # applies adopter/db/migrations/ + adopter/db/seed.sql

New scripts:

• npm run db:apply-adopter — apply adopter migrations after template reset
• npm run migration:new:adopter -- create_collections_table — scaffold adopter migration
• npm run types:generate:adopter — output types to adopter/db/types/database.ts

Upgrade impact: merging a CalVer tag may add template migrations — adopter runs db:reset + db:apply-adopter. adopter/db/migrations/ is never touched by upstream.

Optional future: adopter/edge/ for adopter-specific Edge Functions.

---

E2E tests

Zone	Location	What it tests
Template E2E	tests/e2e/web/specs/	Auth, billing navigation, admin access, waitlist modes, profile
Adopter E2E	adopter/e2e/web/specs/	Landing copy/images, dashboard demo showcase, marketing CTAs
Mobile E2E	tests/e2e/mobile/flows/ + adopter/e2e/mobile/flows/	Template auth smoke; adopter home flow

Playwright: add second project for adopter/e2e/web/specs/. npm run test:e2e:web runs both; add test:e2e:adopter for adopter-only.

Split rule: marketing copy E2E → adopter; functional flow E2E → template.

---

Database tests (pgTAP)

Zone	Location	What it tests	Upgrade behavior
Template DB tests	supabase/tests/*.test.sql	Template schema: RLS, billing, waitlist, admin, storage	Merge from upstream
Adopter DB tests	adopter/tests/db/*.test.sql	Adopter tables, RLS, triggers, RPCs	Fork-owned; no upstream conflicts

Run commands:

Script	Scope
test:db	Template pgTAP + migration filename lint
test:db:adopter	Adopter pgTAP after db:apply-adopter
test:db:all	Both

Demo dashboard migration story: template demo RPCs (billing_demo_*) stay in template migrations. Real adopter tables (e.g. collections) move to adopter/db/migrations/ with tests in adopter/tests/db/ and integration coverage in adopter/tests/integration/.

---

Scripts / CI test matrix

Script	Scope
test:unit	All packages + template unit + adopter unit
test:unit:adopter	Vitest/Jest scoped to adopter/** (excludes integration/db)
test:integration	Template — tests/integration/
test:integration:adopter	Adopter — adopter/tests/integration/
test:integration:all	Both
test:e2e:web	Template + adopter Playwright specs
test:e2e:adopter	Adopter E2E only
test:db	Template pgTAP
test:db:adopter	Adopter pgTAP
db:apply-adopter	Apply adopter/db/migrations/ after template reset
migration:new:adopter	Scaffold adopter migration file

CI setup order (full run):

supabase db reset → db:apply-adopter → test:db → test:db:adopter → test:integration → test:integration:adopter → test:unit → test:e2e

Fork CI (day-to-day):

db:apply-adopter → test:db:adopter → test:integration:adopter → test:unit:adopter → test:e2e:adopter

Run full template suite after merging a CalVer tag.

---

Upgrade impact summary

Test / asset type	Fork upgrade	Adopter schema/copy change
packages/* unit	Merge upstream	Unaffected
template/**/__tests__	Merge upstream	Unaffected
adopter/**/__tests__	No conflicts	Update as needed
tests/integration/ (template)	Merge upstream	Unaffected
adopter/tests/integration/	No conflicts	Add/update for new schema
supabase/tests/ (template pgTAP)	Merge upstream	Unaffected
adopter/tests/db/	No conflicts	Add/update for new schema
adopter/db/migrations/	No conflicts	Adopter adds migrations freely
supabase/migrations/	Merge upstream; then db:reset + db:apply-adopter	Re-apply adopter migrations on top
tests/e2e/web/specs/ (template)	Merge upstream	Unaffected if config-driven
adopter/e2e/	No conflicts	Update copy-specific assertions

Update docs/TESTING.md decision matrix with adopter vs template vs framework rows.

---

Phased rollout

Phase 1 — Document + physical moves (low risk)

• Create adopter/ tree; move config files, landing images
• Add apps/*/src/template/; move admin + billing wiring
• Add docs/CUSTOMIZING.md
• Begin test moves: adopter config tests → adopter/config/__tests__/

Phase 2 — Shared decoupling + naming (medium)

• Extract branding/legal/colors/policies from @beakerstack/shared
• Add configureAdopter() bootstrap
• Neutral export names; rewrite rename script (adopter-only)
• Move dashboard demo to adopter/web + adopter/mobile

Phase 3 — Upgrade ergonomics + test/DB completion (polish)

• Route/screen registries, .gitattributes, release notes automation
• adopter/e2e/, adopter/tests/integration/, adopter/tests/db/
• db:apply-adopter, migration:new:adopter, adopter test scripts
• Optional npm run upgrade:check

---

What adopters should NOT edit

• @beakerstack/admin, @beakerstack/billing, @beakerstack/waitlist, @beakerstack/email, @beakerstack/marketing-email, @beakerstack/observability
• supabase/migrations/, Edge Functions (configure, don't fork logic)
• apps/*/src/template/admin/
• .github/workflows/, setup scripts (follow release notes when they change)

[sarah-artificerinnovations]

Plan critique — #369 adopter zones

Overall the direction is right: the business case is solid, the three-tier naming model is clean, and phased delivery is the correct approach. Several things need tightening before implementation starts.

---

🔴 Critical — must resolve before Phase 1 starts

1. Phase 1 is the highest-risk phase, not the lowest

The plan labels Phase 1 "low risk (physical moves)." It isn't. Moving apps/web/src/billing/, apps/web/src/admin/, apps/web/src/waitlist/, and their mobile mirrors into apps/*/src/template/ breaks every existing import across the monorepo. The churn touches apps/, packages/, and any tests that import those paths directly. Calling it low risk sets the wrong expectation. It should be labeled: highest blast radius — must be done in one atomic PR with all tests green before merge.

2. The adopter→template import mechanism is unspecified

How does apps/web/src/template/ consume adopter/web/, and vice-versa? Relative paths crossing from apps/web/src/template/billing/ to ../../../../adopter/web/SomePage.tsx are fragile and hard to follow. A tsconfig path alias (@adopter/*) is cleaner — but that alias needs to be designed, added to every app's tsconfig.json, and validated by the type-check gate. This is completely absent from the acceptance criteria. It belongs in Phase 1.

3. configureAdopter() bootstrap timing is unresolved

The plan says @beakerstack/shared "reads injected config at runtime." In a Vite/React app, modules are loaded at build time — there is no runtime injection in the Node.js sense. The realistic options are:

• Module singleton initialized at app startup before React renders — works, but every test that imports from shared must call configureAdopter() or mock it
• React context — works for components, but not for package-level utilities that run outside the render tree
• Build-time code generation — most robust, but more complex

None of these are designed. The acceptance criterion "mock adopter config fixture for template/framework tests" confirms the gap is known but there's no concrete design. Without it, implementation will stall or diverge across packages.

4. Adopter DB migration ordering is unsolved

Supabase tracks a single linear migration history. adopter/db/migrations/ applied after supabase db reset works in dev, but in production you apply incremental migrations — you can't reset first. Questions the plan doesn't answer:

• What numbering convention prevents an adopter migration from colliding with a future template migration (both might use 20260601_ prefix)?
• What Supabase CLI invocation applies only adopter migrations after a production template upgrade?
• What is the baseline assumption — are adopter migrations always applied after all template migrations?

This needs a concrete design (separate numeric namespace, a second db push call, a manifest file, etc.) before Phase 3.

---

🟡 Design gaps — need answers before the relevant phase begins

5. .gitattributes merge driver should be default-on in Phase 1, not optional in Phase 3

The "zero conflicts in adopter/" promise is the core deliverable of this issue. .gitattributes adopter/** merge=ours is the mechanism that makes it real — currently listed as "optional" in Phase 3. It should be committed to the template in Phase 1 alongside the directory creation. Without it, fork owners who don't configure it get the conflict reduction only by convention, not enforcement.

One important caveat to document: merge=ours silently discards upstream changes if a template upgrade modifies something the adopter extended. That's usually correct (they own it), but it can mask breakage at shared API boundaries. UPGRADING.md should call this out so adopters know to manually review adopter/ after upgrades that touch shared package APIs.

6. Route/screen registry needs an actual interface design

"Route registry imported by App.tsx" is a name, not a design. React Navigation graphs are not flat lists of screens — they have nested stacks, tabs, drawers, and deep-link schemas. Before Phase 3, there needs to be a concrete interface:

// What does adopter/mobile/navigation.tsx export?
// What does AppNavigator.tsx consume from it?

Same for web routes if the app uses a router beyond a simple switch in App.tsx. Defining this up front determines whether Phase 3 is a two-day move or a two-week API design problem.

7. packages/shared decoupling is the hardest migration in the plan

packages/shared/src/ contains config/, content/, theme/, components/ — all imported by both apps and other packages. Extracting branding/legal/colors/policies from it is a cross-cutting change that touches every consumer simultaneously. Phase 1 will have already churned import paths. Layering Phase 2's shared decoupling on top amplifies the risk significantly. Consider splitting: 2a = shared decoupling in isolation before any file moves; 2b = file moves and rename rewrite once the shared boundary is stable.

8. @beakerstack npm scope is a permanent brand artifact in template code

The plan correctly says the scope is unchanged but doesn't explain why. A fork owner deploying internally as @mycompany/* will permanently see @beakerstack/* imports in their template code. This is a deliberate tradeoff (scope rename is a separate, harder problem) — but it needs an explicit rationale in both the issue and docs/CUSTOMIZING.md so adopters don't open confusion issues about it.

9. scripts/rename-project.mjs needs a full audit before being rewritten

The plan scopes the rename script to adopter/** only, with "no changes to apps/, packages/, supabase/…" But the script likely currently touches Expo app.config.ts bundle identifiers, supabase/config.toml project name, and .env templates — all of which are legitimately adopter-owned but live outside adopter/. The "no changes to supabase/" constraint may be too strict. Audit what the script currently does and explicitly decide what moves into adopter/ vs what stays in place with template-neutral defaults.

10. No migration path for existing forks

The plan describes the workflow for new forks. Existing BeakerStack forks that already have diverged apps/web/src/billing/, customized packages/shared/src/config/, etc. need a migration guide: what's the recommended one-time reorg PR, and is there a codemod or script to automate the file moves? Without this, adopters on older CalVer tags will either stay stuck or manually reconstruct the layout.

---

🔵 Minor

11. Phase 1 acceptance criteria is missing tsconfig changes. Adding adopter/ as a source root requires updates to the root tsconfig.json and each app's tsconfig.json. Should be an explicit checklist item.

12. "CI adopter-only slice" needs a concrete spec. Currently vague. Does it mean a separate workflow file, a job matrix toggle, or npm run test:adopter? What does it include — just adopter/**/__tests__, or also adopter/tests/integration/ and adopter/tests/db/? Define this before Phase 3.

13. "Zero conflicts" needs a continuous enforcement gate. Without a CI check validating the adopter/template boundary, future template changes can accidentally bleed into adopter/. A simple ESLint no-restricted-imports rule in apps/*/src/template/ blocking direct adopter/ imports (and vice-versa outside the registry modules) enforces the contract on every PR, not just at initial setup.

---

Summary

Strong business case and correct structural direction. Three things to resolve before Phase 1 begins: (1) re-label Phase 1 accurately and plan for the import churn; (2) specify the @adopter/* tsconfig alias and import contract; (3) design the DB migration ordering mechanism. The rest can be addressed iteratively as phases are scoped into PRs.

[ZappoMan]

Plan revision — addressing reviewer feedback

Last updated: Round 3 (Sarah Phase 0 items) incorporated on top of Round 2 revisions.

This comment is the canonical plan for issue #369.

---

Summary of changes (Round 1 + Round 2)

Concern	Resolution
Phase ordering	Phase 0 design spike → Phase 1 foundation → Phase 2 reorg branch (sequential CI-green commits)
configureAdopter() underspecified	Full contract + two-tier config; no env-sniffing in production code
Pre-render / marketing SEO	Static @adopter/config/* at build time; configureAdopter() in prerender script before shared chrome
Route registry	Extension slots with typed auth field; template owns navigator
Post-login redirect	postLoginPath in AdopterConfig — no adopterPaths import seam
apps/*/src/template/	Dropped — boundary is adopter/ vs apps/**
DB migrations	Separate app schema + adopter.schema_migrations + db:apply-adopter
Production DB deploy	DATABASE_URL via supabase db remote connection-string after supabase db push
Type gen	supabase gen types --schema app
Phase 2 size	Sequential CI-green commits on one PR branch — not one monolithic diff
.gitattributes	Required Phase 1
rename:legacy	Removed — no production forks yet
Extension types	AdopterScreenExtension, AdopterRouteExtension in @beakerstack/shared public API
Zod schema	.strip() (not .strict()) for forward-compatible optional fields
ESLint boundaries	Explicit rule config in Phase 1
Prerender ordering	ESLint import/no-unassigned-import + documented constraint on prerender-home.ts
Template 9* lint rationale	Reserved namespace guard — see DB section + Phase 0 db-migrations.md
Web React.ReactNode vs mobile ComponentType	Intentional React Router vs React Navigation API asymmetry — Phase 0 extension-slots.md
postLoginPathMobile validation	Startup check in AppNavigator — dev throw if screen not registered
Phase 2 commit 1 duplication	Transitional only — commit 2 removes old config paths + re-exports
Double configureAdopter()	Warn or throw on second call (Phase 1 AC)
ESLint @adopter depth patterns	Phase 1 CI validates patterns cover all monorepo import depths

---

Revised zone model

adopter/                    # Adopter-owned — merge=ours
  config/                   # branding, legal, landing, billing, waitlist, app-identity, index.ts
  content/, assets/, email/
  web/                      # pages, components, routeExtensions.tsx
  mobile/                   # screens, components, screenExtensions.tsx
  db/migrations/            # schema `app` only
  db/init.sql               # creates `app` schema + adopter.schema_migrations (bootstrap)
  tests/, e2e/

apps/web/src/               # Template-owned
apps/mobile/src/
packages/                   # @beakerstack/*
supabase/migrations/        # Template schema (public)

Allowed template→adopter import seams (only these files may import @adopter/*):

File	Imports
apps/web/src/main.tsx	@adopter/config
apps/web/scripts/prerender-home.ts	@adopter/config
apps/web/src/App.tsx	@adopter/web/routeExtensions
apps/mobile/src/navigation/AppNavigator.tsx	@adopter/mobile/screenExtensions

All other navigation targets (post-login redirect, etc.) read from getAdopterConfig().postLoginPath — not from @adopter/config/routes.

postLoginPathMobile startup validation

After loading adopterStackScreens, AppNavigator.tsx validates at startup:

const config = getAdopterConfig();
const registered = new Set(adopterStackScreens.map((s) => s.name));
if (!registered.has(config.postLoginPathMobile)) {
  throw new Error(
    `postLoginPathMobile "${config.postLoginPathMobile}" is not registered in adopter/mobile/screenExtensions.tsx`
  );
}

Fails fast on typos instead of silent navigate() no-ops. Document in Phase 0 adopter-config.md. Optional Phase 2 follow-up: warn if web postLoginPath is not matched by any adopterRouteExtensions path.

---

Phase 0 — Design spike (before any code)

Deliverables in docs/design/adopter-zones/:

1. adopter-config.md — AdopterConfig schema (Zod, .strip()), postLoginPath / postLoginPathMobile, startup validation contract
2. extension-slots.md — public API in @beakerstack/shared; web vs mobile type asymmetry; lazy-loading pattern
3. build-time-config.md — prerender pipeline, static vs runtime config
4. db-migrations.md — db:apply-adopter runbook, tracking, failure modes, credentials, 9* lint rationale
5. Zod bundle-size note (~13KB minzipped if new dep)

---

configureAdopter() — specified contract (Round 2)

No test-env auto-detection in production code. getAdopterConfig() always throws when uninitialized.

// packages/shared/src/config/adopterRuntime.ts
let configured: AdopterConfig | null = null;

export function configureAdopter(config: AdopterConfig): void {
  configured = adopterConfigSchema.parse(config); // Zod .strip() — unknown keys ignored
}

export function getAdopterConfig(): AdopterConfig {
  if (configured) return configured;
  throw new Error(
    'configureAdopter() must be called before reading adopter config'
  );
}

export function resetAdopterConfigForTests(): void {
  configured = null;
}

Test setup (explicit, not env-sniffing)

// packages/shared-tests/setup.adopter.ts (or vitest setupFiles)
import { configureAdopter, resetAdopterConfigForTests } from '@beakerstack/shared/config/adopterRuntime';
import { TEST_ADOPTER_FIXTURE } from '@beakerstack/test-utils/adopterFixtures';

beforeEach(() => configureAdopter(TEST_ADOPTER_FIXTURE));
afterEach(() => resetAdopterConfigForTests());

AC: packages/shared-tests and template test setups include this file from day one.

AdopterConfig includes navigation without import seams

// adopterConfigSchema (excerpt)
{
  branding: BrandingConfig;
  legal: LegalConfig;
  // ...
  postLoginPath: string;        // e.g. '/dashboard' — template auth redirect reads via getAdopterConfig()
  postLoginPathMobile: string; // e.g. 'Dashboard' — React Navigation screen name
}

Demo defaults in adopter/config/index.ts: postLoginPath: '/dashboard'.

Two-tier config access (unchanged)

Tier	Used by	Mechanism
Static modules	vite.config.ts, landing.ts, landing sections	import { branding } from '@adopter/config/branding'
Runtime singleton	Shared components, template auth redirects	getAdopterConfig()

Zod

• Use .strip() not .strict() so forks with older adopter/config/index.ts shapes survive template adding optional fields
• Document bundle impact if Zod is new to @beakerstack/shared

---

Extension slot types (Phase 0 public API)

Defined in @beakerstack/shared (versioned, semver major):

// packages/shared/src/navigation/adopterExtensions.ts

export type AdopterRouteAuth = 'public' | 'protected';

export type AdopterRouteExtension = {
  path: string;
  element: React.ReactNode;
  auth?: AdopterRouteAuth; // default: 'protected'
};

export type AdopterScreenExtension = {
  name: string;
  component: React.ComponentType;
  auth?: AdopterRouteAuth; // default: 'protected'
};

Web vs mobile type asymmetry (intentional):

Platform	Field	Type	Why
Web	element	React.ReactNode	React Router v6 <Route element={...} /> expects a rendered node
Mobile	component	React.ComponentType	React Navigation <Stack.Screen component={...} /> expects a constructor

Web routes in routeExtensions.tsx use JSX — evaluated at module load (before Router context). This is intentional. Adopters who want code splitting wrap at the definition site:

const LazyDashboard = React.lazy(() => import('./pages/DashboardPage'));

export const adopterRouteExtensions: AdopterRouteExtension[] = [
  {
    path: '/dashboard',
    auth: 'protected',
    element: (
      <Suspense fallback={<PageFallback />}>
        <LazyDashboard />
      </Suspense>
    ),
  },
];

Document in Phase 0 extension-slots.md.

Template wiring: App.tsx wraps auth: 'protected' routes in ProtectedRoute; public routes render bare. Same policy for mobile stack screens.

---

Pre-rendered marketing pages (unchanged capability)

Pipeline preserved: vite build → prerender-home.ts → hydration.

1. vite.config.ts — static @adopter/config/branding
2. adopter/config/landing.ts — static export
3. prerender-home.ts — configureAdopter(adopterConfig) before dynamic imports of LandingPageSSR / AppFooter

Prerender guard: ESLint rule or dedicated lint script flags static imports in prerender-home.ts above the configureAdopter() call (except config/runtime modules). Document in design doc.

Marketing AC: build produces prerendered HTML with <h1> smoke check; hydration test passes; no Supabase at prerender time.

Phase 2 branch includes wiring main.tsx, prerender-home.ts, and vite.config.ts in the same CI-green commit series.

---

ESLint boundary (Phase 1 — explicit config)

// eslint rule (conceptual — exact flat-config shape in implementation)
'no-restricted-imports': ['error', {
  patterns: [{
    group: ['@adopter/*', '../../adopter/*', '../../../adopter/*'],
    message: 'Import @adopter/* only from allowed seam files (main, App, AppNavigator, prerender-home)',
  }],
}]

Apply to packages/** and apps/** with overrides allowing the four seam files. Enforced in CI from Phase 1.

---

Revised phased rollout

Phase 1 — Foundation (no file moves)

• adopter/ stub with demo content
• @adopter/* aliases (tsconfig, Vite, Metro)
• configureAdopter() + Zod schema (.strip()) + @beakerstack/test-utils fixture
• packages/shared-tests/setup.adopter.ts with explicit test bootstrap
• Extension slot types in @beakerstack/shared (types only; wiring in Phase 2)
• adopter/db/init.sql — creates app schema + adopter.schema_migrations table
• npm run db:init-adopter — applies init.sql (runs before first db:apply-adopter)
• .gitattributes: adopter/** merge=ours
• ESLint boundary rules (see above)
• Migration filename lint: template supabase/migrations/ must NOT start with 9; adopter files optional naming (see DB section)
• docs/CUSTOMIZING.md, Phase 0 design docs

Phase 2 — Reorg branch (highest blast radius)

One PR, sequential CI-green commits — branch never breaks CI, but reviewers can read commit-by-commit. Not a single monolithic commit.

Suggested commit order:

#	Commit	Done when
1	@adopter/* wiring + configureAdopter() in main/prerender/vite	CI green. May temporarily re-export old config paths — transitional only.
2	Move config/content/assets → adopter/; wire adopterConfig	All re-exports and old config paths removed; check-no-legacy-adopter-paths.mjs passes for config.
3	Move dashboard → adopter/web, adopter/mobile	Dashboard lives under adopter/ only.
4	Wire extension slots in App.tsx / AppNavigator.tsx	Includes postLoginPathMobile startup validation.
5	Rewrite remaining imports; remove old paths	No legacy adopter config under apps/ or packages/shared.
6	Final check-no-legacy-adopter-paths.mjs CI gate	Full legacy-path lint green.

Reviewers: commit 1 alone is intentionally transitional; commit 2 is required before merge.

Recommend short trunk freeze while PR is open.

Phase 3 — DB runner, deploy, tests, rename

• db:apply-adopter — full spec below
• Deploy workflows: supabase db push then npm run db:apply-adopter -- --linked
• test:adopter, extension slot wiring tests, prerender AC
• Adopter-only rename
• Reusable workflow for fork CI + UPGRADING.md section on pinning workflow @v tags
• upgrade:check + behavioral upgrade simulation

---

Adopter database

Path	Purpose
supabase/migrations/	Template schema (public, etc.)
adopter/db/init.sql	Bootstrap: CREATE SCHEMA app, adopter.schema_migrations table
adopter/db/migrations/	Adopter DDL in schema app

Filename convention: adopter migrations use normal timestamps (20260524120000_description.sql). The separate directory + tracking table provides isolation — a 9* prefix is not required for ordering (document in adopter/db/README.md).

Why template migrations must NOT use 9* prefix (lint kept):

Scenario	Rationale
Accidental misplacement	Contributor adds adopter DDL to supabase/migrations/; 9* makes review and lint catch "adopter namespace" immediately
Future unified tooling	Planned db:status / upgrade checklists may scan both dirs in one sorted list; reserved 9* on template side prevents ambiguous filenames
Human convention	Adopter migrations may optionally use 9* in adopter/db/migrations/ as a visual hint; blocking 9* on template side keeps convention one-directional

Document full rationale in Phase 0 db-migrations.md and adopter/db/README.md.

db:apply-adopter spec

Local / CI (after supabase db reset):

npm run db:init-adopter          # idempotent — ensures schema + tracking table
npm run db:apply-adopter         # applies pending adopter/db/migrations/*.sql

Algorithm:

1. List adopter/db/migrations/*.sql sorted lexicographically
2. Query adopter.schema_migrations for applied filenames
3. Apply each pending file in a transaction; record filename + checksum on success
4. On failure: abort, leave DB at last good migration, print failed file + error

Production (--linked):

supabase db push
npm run db:apply-adopter -- --linked

--linked resolves connection via supabase db remote connection-string (same as other deploy scripts), using DATABASE_URL / Supabase DB password from CI secrets (SUPABASE_DB_PASSWORD + project ref). Direct Postgres psql — not Management API — so DDL including extensions works. Document exact secret names in adopter/db/README.md and deploy workflow comments.

Tests: unit tests for migration runner logic (pending detection, partial failure) in scripts/__tests__/db-apply-adopter.test.mjs.

Types: supabase gen types typescript --schema app → adopter/db/types/database.ts

---

Rename script

• Scans adopter/** only (incl. adopter/config/app-identity.ts)
• Does not rename docs/, README.md
• No rename:legacy
• @beakerstack/* unchanged unless --full-rebrand

---

Fork CI strategy

Template ships .github/workflows/adopter-tests-reusable.yml with workflow_call inputs.

Fork pattern: thin wrapper workflow in fork repo:

jobs:
  adopter:
    uses: Artificer-Innovations/BeakerStack/.github/workflows/adopter-tests-reusable.yml@v2026.NNN

Merge conflict tradeoff: forks that add the wrapper once may need to bump the @v pin on template upgrades — one-line change, documented in UPGRADING.md under "Reusable workflow pins." Forks that customize the wrapper file itself will conflict (opt-in).

Template repo CI runs test:adopter directly (no wrapper indirection).

---

Revised acceptance criteria

• Upgrade simulation: conflicts confined outside adopter/** with merge=ours
• Phase 0 design docs approved
• getAdopterConfig() throws when uninitialized — no VITEST/JEST env sniffing
• shared-tests setup calls configureAdopter(TEST_FIXTURE) explicitly
• Post-login redirect uses getAdopterConfig().postLoginPath
• Extension routes default to auth: 'protected'
• Phase 2 PR: sequential CI-green commits on one branch
• db:init-adopter + db:apply-adopter with documented --linked credentials
• Prerender build AC passes
• ESLint boundary enforced
• @beakerstack/shared semver major + UPGRADING.md migration table

---

Round 2 reviewer checklist

Item	Source	Status
Remove VITEST env fallback	sarah, mei, diego, rahul	✅ Explicit test setup only
Phase 2 not monolithic	sarah	✅ Sequential commits, one PR
Extension types in shared	sarah	✅ Public API in Phase 0/1
postLoginPath not adopterPaths	sarah, mei, rahul	✅ In AdopterConfig
Migration runner spec	sarah	✅ Algorithm + failure mode
Prerender import lint	sarah	✅ ESLint/guard
Migration prefix lint	sarah	✅ Template must not use 9*; adopter prefix optional
Zod bundle + .strip()	sarah, mei	✅ Documented
Fork workflow pin docs	sarah	✅ UPGRADING.md
schema_migrations bootstrap	diego	✅ db:init-adopter Phase 1
--linked credentials	diego, mei, rahul	✅ connection-string + secrets
Route extension auth field	rahul	✅ Default protected
shared-tests setup AC	mei	✅ Phase 1

Round 3 reviewer checklist (Sarah)

Item	Status
Template 9* lint purpose documented	✅ Phase 0 db-migrations.md + expanded DB section
Web React.ReactNode eager instantiation + lazy pattern	✅ Phase 0 extension-slots.md
postLoginPathMobile startup validation	✅ AppNavigator dev-time throw
Phase 2 commit 1 duplication clarified	✅ Commit 2 removes old paths before merge

Status: ready for Phase 0 implementation.

[ZappoMan]

Plan update — rename:legacy removed + pre-render strategy

Two follow-ups incorporated into the plan.

---

1. No rename:legacy

Agreed — no production forks exist yet. The plan drops npm run rename:legacy entirely. Adopter-only rename (adopter/** only) is the sole path from day one. Reviewer checklist item for in-flight forks removed.

---

2. Pre-rendered marketing pages + configureAdopter()

Short answer: pre-rendering is preserved. Marketing uses static @adopter/config/* imports at build time; the runtime singleton is bootstrapped in the prerender script before any shared component renders.

Current pipeline (unchanged goal)

npm run build
  → vite build          # index.html title/og meta from branding
  → prerender-home.ts   # renderToStaticMarkup(LandingPageSSR + AppFooter) → dist/index.html
  → browser hydrates prerendered #root (main.test.tsx covers this)

Two-tier config access

Tier	Used by	Mechanism
Static modules	vite.config.ts, adopter/config/landing.ts, landing sections	import { branding } from '@adopter/config/branding' — plain ES exports, no bootstrap
Runtime singleton	@beakerstack/shared components (AppHeader, AppFooter after decoupling)	configureAdopter(adopterConfig) → getAdopterConfig()

adopter/config/*.ts files are static data — safe to import in Node during vite build and prerender-home.ts. No circular dependency: packages never import @adopter/*; only app/build scripts and apps/web/src do.

Build-time wiring after reorg

Vite HTML transform — switch from packages/shared/.../branding to direct @adopter/config/branding for %APP_TITLE%, og:title, meta description. Build-time only; no singleton.

Landing config — adopter/config/landing.ts imports branding from sibling module. LandingPageSSR imports landingConfig statically (same as today). Landing sections receive config via props — no getAdopterConfig().

Prerender script — call configureAdopter() before dynamic-importing components that touch shared chrome:

// apps/web/scripts/prerender-home.ts (order matters)
const { configureAdopter } = await import('@beakerstack/shared/config/adopterRuntime');
const { adopterConfig } = await import('@adopter/config');
configureAdopter(adopterConfig);

const { LandingPageSSR } = await import('../src/components/landing/LandingPageSSR');
const { AppFooter } = await import('../src/components/AppFooter');
// ... renderToStaticMarkup (unchanged)

Client entry — main.tsx calls configureAdopter(adopterConfig) synchronously before createRoot. Same adopterConfig object as prerender → HTML matches hydration.

What does NOT change

• LandingPageSSR stays eager-import (no React.lazy) for prerender
• No Supabase/auth/BillingProvider on marketing render path
• Canonical + og:url injection in prerender-home.ts
• <h1> smoke check on build output
• Pricing section on landing still client-hydrated where it needs live data (existing trade-off)

New acceptance criteria

• npm run build produces prerendered dist/index.html with <h1> smoke check passing
• index.html meta tags reflect @adopter/config/branding
• Hydration test (prerendered root) passes
• No network/Supabase calls during prerender build step

Phase 2 atomic PR explicitly includes wiring prerender-home.ts + vite.config.ts alongside main.tsx.

---

Plan revision comment above updated conceptually; this supersedes the rename:legacy sections there.