Customization boundaries

Last updated

Source file

docs/foundations/customization-boundaries.md

Keep application customizations in the existing app-owned files, and let generated integration consume them through supported package interfaces. Central ownership rules should protect those boundaries across CLI operations; moving every customization into one file is unnecessary.

Where changes belong

CustomizationApplication locationPlatform integration
Branding and logosconfig/brand.ts, public/brand/Generated shell and layout consume the brand configuration
Theme tokens and custom CSSapp/theme.cssGenerated app/globals.css retains the app-theme import
Existing module navigationshellRegistrationOverrides in config/shell.overrides.tsTransforms package registrations
Additional application surfacesadditionalShellModules in the same overrides file, plus app routesAdds navigation, toolbar metadata and dashboard contributions
Social Media contentconfig/social-media-plan.jsonThe app-owned page passes the plan to the package viewer
Social Media page compositionapp/(shell)/marketing/social-media/page.tsxSetup creates it once; existing content is preserved
Larger React composition changesAn explicitly owned tracked layout or mountContinue consuming public package components and types
Client-only database behaviorClient forward migrations, outside shared module historyShared SQL is authored once and checked against the CLI bundle
Customized invitation contact integrationClient migration defining public.client_organization_invitation_contact_hook(uuid, uuid)Runs inside acceptance and direct membership transactions; the package never creates or replaces this client hook

Generated files such as config/shell.ts, config/modules.ts, config/module-toolbar-controls.tsx, next.config.ts, app/globals.css and docs/ai/app-context.json are not general customization stores. Module selection belongs to the CLI lifecycle; styling belongs in the app theme. Custom toolbar React rendering currently has no separate renderer-map extension point, so do not assume editing its generated file survives updates.

Tracked file ownership

Use bw scaffold list to inspect tracked files. For a deliberate fork of an existing tracked file, record bw scaffold own <path>. For an intentionally absent tracked file, use bw scaffold skip <path>. These decisions refer to exact paths, regardless of whether a command renders the path as configuration or a starter.

Returning a path with bw scaffold manage <path> compares it against the available template. It does not make customized bytes canonical or authorize their deletion. A recorded drift remains meaningful even if a historical command stored the same hash as the current file.

Historical manifests whose original baseline and drift information were already erased cannot always be reconstructed from their current hash. Review such files and mark deliberate forks owned before destructive lifecycle operations; do not assume a new CLI can recover missing history.

Compatibility and remaining boundaries

Preserving a file is only one part of preserving a customization. Public package exports, component props, registration types, content validation and CSS precedence also need compatible behavior. Private package file paths are not stable extension points. Breaking extension contracts need an explicit migration path.

Removal scans surviving source files for literal imports of the package being removed and refuses before writing when it finds dependents. Reconcile those imports explicitly; owned content is never deleted to make removal succeed. This is a conservative static diagnostic, not a complete bundler or proof that computed imports and all application behavior remain compatible.

The CLI shares exact generated, app-owned seed and scaffold path declarations across its managed inventory and generated orientation JSON. Unknown paths default to app ownership; broad page/config globs do not grant generation authority. Explicit intent and live drift protect tracked files. Generated configuration remains generated unless an existing tracked ownership decision protects it. Keep app content out of the manifest and retain native TypeScript, React, CSS and JSON extension formats.

Lifecycle commands resolve the explicitly selected app root to its canonical directory, so a root alias is supported. Writable targets and their ancestors inside that root must be real files/directories, never symlinks. Preflight rejects linked, dangling and incorrectly typed targets before writes; migration outputs outside the selected app root are refused. This assumes no concurrent filesystem modification and is not an operating-system sandbox or race-proof guarantee.

See CLI ownership commands and CSS layer order for the operational contracts.

Invitation acceptance and direct membership assignment have an explicit migration step for customized callbacks. Move that behavior into the client-owned transactional hook and opt in through the adapter; an unrecognized callback is rejected before mutation. See invitation transactions for the signature, privileges, upgrade order, and retry behavior.