create-bw-app 0.11.0 → 0.13.0

package/README.md

@@ -35,7 +35,7 @@ bw upgrade
 bw doctor
 ```
 
-- `bw add <moduleKey>` resolves requirements, installs module wiring and starter overlays, and appends migrations.
+- `bw add <moduleKey>` resolves requirements, installs thin package mounts and module wiring, and appends migrations.
 - `bw upgrade [moduleKey]` includes the existing managed update flow plus forward-only module migrations.
 - `bw doctor` checks package, config, scaffold, environment-name, and migration consistency. Add `--report` to stamp the result in the app manifest.
 - All mutating commands support `--dry-run`.
@@ -58,7 +58,7 @@ Current updater behavior:
 - fails the update if npm resolution fails unless you pass `--allow-stale-fallback`
 - re-syncs managed BrightWeb config files such as `next.config.ts`, `config/modules.ts`, and `config/shell.ts`
 - preserves app-owned shell customizations in the scaffolded `config/shell.overrides.ts`
-- reports missing or drifted starter files and only rewrites them with `--refresh-starters`
+- reports missing or drifted scaffold mounts and only rewrites them with `--refresh-starters`
 - prints the follow-up install command unless `--install` is passed
 - preserves unrelated third-party dependencies and app-owned product pages
 
@@ -69,10 +69,10 @@ Current updater behavior:
 - prompts for optional platform modules: `admin`, `crm`, and `projects`
 - prompts to install dependencies immediately
 - copies a clean Next.js App Router starter template
-- platform apps include BrightWeb auth, shell wiring, and optional module starter surfaces
-- platform apps include a local `components/` folder for app-owned UI alongside the shared BrightWeb packages
+- platform apps include BrightWeb auth, shell wiring, and optional direct package mounts
+- generated route files contain direct `@brightweblabs/*` re-exports only
 - platform apps in published mode also write `supabase/config.toml`, a CLI-ready flat `supabase/migrations/` folder, `supabase/module-registry.json`, `supabase/clients/<slug>/stack.json`, and the resolved shared SQL migrations under `supabase/modules/<module>/migrations`
-- site apps include Next.js, Tailwind CSS v4, and local component primitives
+- site apps include a thin Next.js and Tailwind CSS shell with no default feature page or local component library
 - writes `package.json`, `next.config.ts`, `.gitignore`, and `README.md` for both templates
 - platform apps also write `.env.local`, `AGENTS.md`, `docs/ai/README.md`, `docs/ai/examples.md`, `docs/ai/app-context.json`, and generated config files for brand and module state
 - site apps also write `AGENTS.md`, `docs/ai/README.md`, `docs/ai/examples.md`, and `docs/ai/app-context.json` for app-local AI handoff
@@ -88,7 +88,7 @@ When this package runs in BrightWeb workspace mode, it can:
 - create `supabase/clients/<slug>/stack.json`
 - create a client-only migrations folder so database planning stays aligned with scaffolded modules
 
-Platform mode always resolves to the `Core + Admin` database baseline. Selecting `admin` affects the Admin starter UI and package wiring, not whether the Admin database layer exists.
+Platform mode always resolves to the `Core + Admin` database baseline. Selecting `admin` affects the Admin package mount and wiring, not whether the Admin database layer exists.
 
 ## Related references
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-bw-app",
   "private": false,
-  "version": "0.11.0",
+  "version": "0.13.0",
   "type": "module",
   "bin": {
     "create-bw-app": "bin/create-bw-app.mjs",

package/src/add.mjs

@@ -2,7 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { stdout as output } from "node:process";
 import { SELECTABLE_MODULES } from "./constants.mjs";
-import { TEMPLATE_ROOT, createAppContextFile, createDbInstallPlan, createNextConfig, createPlatformModulesConfigFile, createShellConfig, getDbModuleRegistry, getVersionMap, pathExists, readJsonIfPresent } from "./generator.mjs";
+import { TEMPLATE_ROOT, createAppContextFile, createDbInstallPlan, createNextConfig, createPlatformGlobalsCss, createPlatformModulesConfigFile, createShellConfig, getDbModuleRegistry, getVersionMap, pathExists, readJsonIfPresent } from "./generator.mjs";
 import { collectScaffoldFiles, findWorkspaceRoot, loadModuleCatalog, MODULE_PACKAGES, readAppManifest, resolveModuleClosure, satisfiesVersion, writeAppManifest } from "./app-manifest.mjs";
 import { applyMigrationWrites, planMigrationAppends } from "./migrations.mjs";
 
@@ -65,6 +65,7 @@ export async function addBrightwebModule(moduleKey, argvOptions = {}, runtimeOpt
   }
   const managedWrites = {
     "next.config.ts": createNextConfig({ template: "platform", selectedModules: installedModuleKeys }),
+    "app/globals.css": await createPlatformGlobalsCss(installedModuleKeys),
     "config/modules.ts": createPlatformModulesConfigFile(installedModuleKeys),
     "config/shell.ts": createShellConfig(installedModuleKeys),
     "docs/ai/app-context.json": createAppContextFile({ slug: appManifest.app.slug, template: "platform", selectedModules: installedModuleKeys.filter((key) => key !== "orgs"), dbInstallPlan }),
@@ -91,7 +92,8 @@ export async function addBrightwebModule(moduleKey, argvOptions = {}, runtimeOpt
   const now = new Date().toISOString();
   for (const key of newModules) appManifest.modules[key] = { version: catalog[key].version, installedAt: now, exposed: true };
   appManifest.migrationCursor = migrationPlan.nextCursor;
-  appManifest.scaffoldFiles = { ...appManifest.scaffoldFiles, ...await collectScaffoldFiles(targetDir, installedModuleKeys) };
+  const collectedScaffoldFiles = await collectScaffoldFiles(targetDir, installedModuleKeys);
+  appManifest.scaffoldFiles = { ...collectedScaffoldFiles, ...appManifest.scaffoldFiles };
   await writeAppManifest(targetDir, appManifest);
   output.write(`Installed ${newModules.length} module${newModules.length === 1 ? "" : "s"}. ${migrationPlan.writes.length > 0 ? "Run your Supabase migration apply command. " : ""}Run your package manager install command next.\n`);
   return { dryRun: false, newModules, migrationPlan };

package/src/adopt.mjs

@@ -18,7 +18,7 @@ import { inventoryScaffoldFiles, resolveTemplateRoot } from "./scaffold.mjs";
 import { detectDependencyMode, detectTemplate } from "./update.mjs";
 
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const HELP = `Usage: bw adopt [options]\n\nOptions:\n  --target-dir <path>                 App directory (defaults to cwd)\n  --workspace-root <path>             BrightWeb workspace root\n  --cursor <key>=<migrationFilename>  Override a migration cursor (repeatable)\n  --owned-surface <name>              Record an app-owned surface (repeatable)\n  --allow-uncursored                   Allow doctor to warn instead of fail on null cursors\n  --force                              Replace an existing app manifest\n  --dry-run                            Print the manifest and warnings without writing\n  --help                               Show this help`;
+const HELP = `Usage: bw adopt [options]\n\nOptions:\n  --target-dir <path>                 App directory (defaults to cwd)\n  --workspace-root <path>             BrightWeb workspace root\n  --cursor <key>=<migrationFilename>  Override a migration cursor (repeatable)\n  --owned-surface <name>              Record an app-owned surface (repeatable)\n  --own <path>                        Mark an existing scaffold file app-owned (repeatable)\n  --skip <path>                       Mark a missing scaffold file intentionally absent (repeatable)\n  --allow-uncursored                   Allow doctor to warn instead of fail on null cursors\n  --force                              Replace an existing app manifest\n  --dry-run                            Print the manifest and warnings without writing\n  --help                               Show this help`;
 
 function asList(value) {
   if (value == null) return [];
@@ -123,10 +123,24 @@ export async function adoptBrightwebApp(argvOptions = {}, runtimeOptions = {}) {
   const scaffold = template === "platform"
     ? await inventoryScaffoldFiles({ targetDir, moduleKeys: Object.keys(modules), templateRoot })
     : { records: {}, unsupported: [] };
+  const ownedPaths = new Set(asList(argvOptions.own).map(String));
+  const skippedPaths = new Set(asList(argvOptions.skip).map(String));
+  for (const relativePath of [...ownedPaths, ...skippedPaths]) {
+    if (!scaffold.records[relativePath]) throw new Error(`${relativePath} is not a tracked scaffold file.`);
+  }
+  for (const relativePath of ownedPaths) {
+    if (skippedPaths.has(relativePath)) throw new Error(`${relativePath} cannot be both --own and --skip.`);
+    if (scaffold.records[relativePath].status === "missing") throw new Error(`Cannot own missing scaffold file: ${relativePath}`);
+    scaffold.records[relativePath].intent = "owned";
+  }
+  for (const relativePath of skippedPaths) {
+    if (scaffold.records[relativePath].status !== "missing") throw new Error(`Cannot skip existing scaffold file: ${relativePath}`);
+    scaffold.records[relativePath].intent = "skipped";
+  }
   for (const relativePath of scaffold.unsupported) warnings.push(`WARN ${relativePath}: installed-version template is unavailable; scaffold comparison is unsupported.`);
   for (const [relativePath, record] of Object.entries(scaffold.records)) {
-    if (record.status === "drifted") warnings.push(`WARN drifted scaffold file: ${relativePath}`);
-    if (record.status === "missing") warnings.push(`WARN missing scaffold file: ${relativePath} (not created; use bw diff and the current template as guidance).`);
+    if (record.status === "drifted" && record.intent !== "owned") warnings.push(`WARN drifted scaffold file: ${relativePath}`);
+    if (record.status === "missing" && record.intent !== "skipped") warnings.push(`WARN missing scaffold file: ${relativePath} (not created; use bw diff and the current template as guidance).`);
   }
 
   const overrides = parseCursorOverrides(argvOptions.cursor);

package/src/app-manifest.mjs

@@ -18,6 +18,7 @@ async function readJsonIfPresent(filePath) {
 export const APP_MANIFEST_PATH = path.join(".brightweb", "app-manifest.json");
 export const MANAGED_APP_FILES = [
   "next.config.ts",
+  "app/globals.css",
   "config/modules.ts",
   "config/shell.ts",
   "docs/ai/app-context.json",
@@ -89,7 +90,14 @@ export async function readAppManifest(targetDir, { required = true } = {}) {
 export async function writeAppManifest(targetDir, manifest) {
   const manifestPath = path.join(targetDir, APP_MANIFEST_PATH);
   await fs.mkdir(path.dirname(manifestPath), { recursive: true });
-  await fs.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+  const temporaryPath = `${manifestPath}.${process.pid}.${crypto.randomBytes(6).toString("hex")}.tmp`;
+  try {
+    await fs.writeFile(temporaryPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    await fs.rename(temporaryPath, manifestPath);
+  } catch (error) {
+    await fs.rm(temporaryPath, { force: true }).catch(() => {});
+    throw error;
+  }
 }
 
 export function validateAppManifest(manifest) {
@@ -107,7 +115,7 @@ export function validateAppManifest(manifest) {
     if (!entry || !cleanVersion(entry.version) || typeof entry.installedAt !== "string" || typeof entry.exposed !== "boolean") errors.push(`modules.${key} is invalid`);
   }
   for (const [relativePath, entry] of Object.entries(manifest.scaffoldFiles || {})) {
-    if (!entry || typeof entry.module !== "string" || !/^sha256:[a-f0-9]{64}$/.test(entry.hash || "") || !["current", "drifted", "missing"].includes(entry.status)) errors.push(`scaffoldFiles.${relativePath} is invalid`);
+    if (!entry || typeof entry.module !== "string" || !/^sha256:[a-f0-9]{64}$/.test(entry.hash || "") || !["current", "drifted", "missing"].includes(entry.status) || (entry.intent != null && !["managed", "owned", "skipped"].includes(entry.intent))) errors.push(`scaffoldFiles.${relativePath} is invalid`);
   }
   if (manifest.lastDoctor != null && (typeof manifest.lastDoctor.at !== "string" || typeof manifest.lastDoctor.ok !== "boolean")) errors.push("lastDoctor is invalid");
   return errors;

package/src/bw.mjs

@@ -3,16 +3,17 @@ import { adoptBrightwebApp } from "./adopt.mjs";
 import { diffBrightwebScaffold } from "./diff.mjs";
 import { doctorBrightwebApp } from "./doctor.mjs";
 import { removeBrightwebModule } from "./remove.mjs";
+import { scaffoldBrightwebApp } from "./scaffold-cmd.mjs";
 import { updateBrightwebApp } from "./update.mjs";
 import { upgradeBrightwebApp } from "./upgrade.mjs";
 
-const HELP = `Usage: bw <command> [options]\n\nCommands:\n  add <moduleKey>       Install a module and its requirements\n  adopt                 Create an honest manifest for a legacy app\n  diff <relpath>        Compare a tracked scaffold file with its template\n  remove <moduleKey>    Conservatively remove module package wiring\n  upgrade [moduleKey]   Upgrade packages, managed files, and migrations\n  update                Alias for the legacy create-bw-app update flow\n  doctor                Validate app health and manifest consistency\n\nRun bw <command> --help for command-specific options.`;
+const HELP = `Usage: bw <command> [options]\n\nCommands:\n  add <moduleKey>       Install a module and its requirements\n  adopt                 Create an honest manifest for a legacy app\n  diff <relpath>        Compare a tracked scaffold file with its template\n  scaffold <action>     List or record per-file scaffold intent\n  remove <moduleKey>    Conservatively remove module package wiring\n  upgrade [moduleKey]   Upgrade packages, managed files, and migrations\n  update                Alias for the legacy create-bw-app update flow\n  doctor                Validate app health and manifest consistency\n\nRun bw <command> --help for command-specific options.`;
 
 function parseOptions(argv) {
   const options = {};
   const positionals = [];
   const booleanFlags = new Set(["help", "dry-run", "strict", "report", "install", "refresh-starters", "allow-stale-fallback", "allow-uncursored", "force", "list", "yes"]);
-  const repeatableFlags = new Set(["cursor", "owned-surface"]);
+  const repeatableFlags = new Set(["cursor", "owned-surface", "own", "skip"]);
   for (let index = 0; index < argv.length; index += 1) {
     const token = argv[index];
     if (!token.startsWith("--")) { positionals.push(token); continue; }
@@ -37,6 +38,7 @@ export async function runBwCli(argv = process.argv.slice(2), runtimeOptions = {}
     if (command === "add") await addBrightwebModule(positionals[0], options, runtimeOptions);
     else if (command === "adopt") await adoptBrightwebApp(options, runtimeOptions);
     else if (command === "diff") await diffBrightwebScaffold(positionals[0], options, runtimeOptions);
+    else if (command === "scaffold") await scaffoldBrightwebApp(positionals[0], positionals.slice(1), options, runtimeOptions);
     else if (command === "remove") await removeBrightwebModule(positionals[0], options, runtimeOptions);
     else if (command === "upgrade") await upgradeBrightwebApp(positionals[0], options, runtimeOptions);
     else if (command === "update") await updateBrightwebApp(options, runtimeOptions);

package/src/constants.mjs

@@ -10,7 +10,7 @@ export const TEMPLATE_OPTIONS = [
   {
     key: "site",
     label: "Site",
-    description: "Standalone Next.js + Tailwind site starter with a local UI layer.",
+    description: "Thin Next.js + Tailwind site shell for package-owned surfaces.",
   },
 ];
 
@@ -55,7 +55,7 @@ export const MODULE_STARTER_FILES = {
   admin: [
     "app/api/admin/users/route.ts",
     "app/api/admin/users/roles/route.ts",
-    "app/playground/admin/page.tsx",
+    "app/admin/users/page.tsx",
   ],
   crm: [
     "app/crm/layout.tsx",
@@ -67,7 +67,6 @@ export const MODULE_STARTER_FILES = {
     "app/api/crm/timeline/route.ts",
   ],
   projects: [
-    "app/playground/projects/page.tsx",
   ],
 };
 
@@ -76,15 +75,15 @@ export const PLATFORM_STARTER_FILES = [
 ];
 
 export const APP_DEPENDENCY_DEFAULTS = {
-  "@brightweblabs/app-shell": "^0.4.0",
+  "@brightweblabs/app-shell": "^0.4.1",
   "@brightweblabs/core-auth": "^0.3.4",
   "@brightweblabs/infra": "^0.3.1",
-  "@brightweblabs/module-admin": "^0.3.4",
-  "@brightweblabs/module-crm": "^0.5.0",
-  "@brightweblabs/module-orgs": "^0.2.0",
-  "@brightweblabs/module-projects": "^0.4.2",
-  "@brightweblabs/theme": "^0.2.0",
-  "@brightweblabs/ui": "^1.0.0",
+  "@brightweblabs/module-admin": "^0.4.0",
+  "@brightweblabs/module-crm": "^0.5.2",
+  "@brightweblabs/module-orgs": "^0.2.2",
+  "@brightweblabs/module-projects": "^0.4.3",
+  "@brightweblabs/theme": "^0.2.1",
+  "@brightweblabs/ui": "^1.0.1",
   "lucide-react": "^1.8.0",
   "next": "16.1.6",
   "react": "19.2.3",
@@ -92,13 +91,9 @@ export const APP_DEPENDENCY_DEFAULTS = {
 };
 
 export const SITE_DEPENDENCY_DEFAULTS = {
-  "class-variance-authority": "^0.7.1",
-  "clsx": "^2.1.1",
-  "lucide-react": "^1.8.0",
   "next": "16.1.6",
   "react": "19.2.3",
   "react-dom": "19.2.3",
-  "tailwind-merge": "^3.4.0",
 };
 
 export const APP_DEV_DEPENDENCY_DEFAULTS = {
@@ -149,6 +144,6 @@ Update options:
   --package-manager <name>       Override package manager: pnpm, npm, yarn, or bun
   --allow-stale-fallback         Use baked-in BrightWeb package versions if npm lookup fails
   --install                      Run install after writing package changes
-  --refresh-starters             Rewrite starter route files from the latest template
+  --refresh-starters             Rewrite tracked package mount files from the latest template
   --dry-run                      Print the update plan without writing files
 `.trim();

package/src/doctor.mjs

@@ -52,7 +52,21 @@ export async function doctorBrightwebApp(argvOptions = {}, runtimeOptions = {})
   add(topologyProblems.length ? "FAIL" : "PASS", "topology", topologyProblems.join("; ") || "Module requirements are satisfied.");
 
   const scaffold = await scaffoldDrift(targetDir, appManifest.scaffoldFiles);
-  add(scaffold.drifted.length || scaffold.missing.length ? "FAIL" : "PASS", "scaffold", `${scaffold.current.length} current, ${scaffold.drifted.length} drifted, ${scaffold.missing.length} missing; drifted scaffold files: ${scaffold.drifted.length} (see bw diff --list)${scaffold.missing.length ? `; missing: ${scaffold.missing.join(", ")}` : ""}`);
+  const scaffoldGroups = {
+    current: scaffold.entries.filter((entry) => entry.status === "current" && entry.intent !== "skipped"),
+    owned: scaffold.entries.filter((entry) => entry.intent === "owned" && entry.status === "drifted"),
+    skipped: scaffold.entries.filter((entry) => entry.intent === "skipped" && entry.status === "missing"),
+    undecidedDrift: scaffold.entries.filter((entry) => entry.intent === "managed" && entry.status === "drifted"),
+    undecidedMissing: scaffold.entries.filter((entry) => entry.intent === "managed" && entry.status === "missing"),
+    mismatched: scaffold.entries.filter((entry) => (entry.intent === "owned" && entry.status === "missing") || (entry.intent === "skipped" && entry.status !== "missing")),
+  };
+  if (scaffoldGroups.owned.length) add("INFO", "scaffold-owned", `App-owned scaffold files: ${scaffoldGroups.owned.map((entry) => entry.relativePath).join(", ")}.`);
+  if (scaffoldGroups.skipped.length) add("INFO", "scaffold-skipped", `Intentionally skipped scaffold files: ${scaffoldGroups.skipped.map((entry) => entry.relativePath).join(", ")}.`);
+  if (scaffoldGroups.undecidedDrift.length) add("WARN", "scaffold-undecided-drift", `Unacknowledged drift: ${scaffoldGroups.undecidedDrift.map((entry) => entry.relativePath).join(", ")} (use bw scaffold own or bw diff).`);
+  if (scaffoldGroups.undecidedMissing.length) add("WARN", "scaffold-undecided-missing", `Unacknowledged missing files: ${scaffoldGroups.undecidedMissing.map((entry) => entry.relativePath).join(", ")} (use bw scaffold skip after review).`);
+  if (scaffoldGroups.mismatched.length) add("FAIL", "scaffold-intent-mismatch", `Recorded scaffold intent no longer matches reality: ${scaffoldGroups.mismatched.map((entry) => `${entry.relativePath} (${entry.intent}, ${entry.status})`).join(", ")}.`);
+  const scaffoldStatus = scaffoldGroups.mismatched.length ? "FAIL" : scaffoldGroups.undecidedDrift.length || scaffoldGroups.undecidedMissing.length ? "WARN" : "PASS";
+  add(scaffoldStatus, "scaffold", `${scaffoldGroups.current.length} current, ${scaffoldGroups.owned.length} owned, ${scaffoldGroups.skipped.length} skipped, ${scaffoldGroups.undecidedDrift.length} undecided-drift, ${scaffoldGroups.undecidedMissing.length} undecided-missing, ${scaffoldGroups.mismatched.length} intent-mismatch.`);
   add("INFO", "owned-surfaces", `Owned surfaces: ${(appManifest.ownedSurfaces || []).join(", ") || "none"}.`);
 
   const envNames = new Set(Object.keys(process.env));

package/src/generator.mjs

@@ -198,7 +198,7 @@ export function createDbInstallPlan({ selectedModules, workspaceMode, registry }
   const notes = [];
 
   if (!selectedModules.includes("admin") && resolvedOrder.includes("admin")) {
-    notes.push("Platform always resolves to the Core + Admin database baseline; selecting Admin only controls whether the Admin starter UI and package wiring are scaffolded.");
+    notes.push("Platform always resolves to the Core + Admin database baseline; selecting Admin only controls whether the Admin package mount and wiring are scaffolded.");
   }
 
   for (const moduleKey of resolvedOrder) {
@@ -315,7 +315,7 @@ export function createPlatformModulesConfigFile(selectedModules) {
     "  description: string;",
     "  enabled: boolean;",
     "  packageName: string;",
-    "  playgroundHref?: string;",
+    "  routeHref?: string;",
     '  placement: "core" | "primary" | "admin" | "hidden";',
     "};",
     "",
@@ -326,7 +326,6 @@ export function createPlatformModulesConfigFile(selectedModules) {
     '    description: "Login, reset-password, callback URLs, and shared auth validation utilities.",',
     "    enabled: true,",
     '    packageName: "@brightweblabs/core-auth",',
-    '    playgroundHref: "/playground/auth",',
     '    placement: "core",',
     "  },",
     "  {",
@@ -343,7 +342,7 @@ export function createPlatformModulesConfigFile(selectedModules) {
     '    description: "Contacts and CRM server/data layer, with marketing-adjacent operational data stored in Supabase.",',
     `    enabled: ${String(selected.has("crm"))},`,
     '    packageName: "@brightweblabs/module-crm",',
-    '    playgroundHref: "/crm",',
+    '    routeHref: "/crm",',
     '    placement: "primary",',
     "  },",
     "  {",
@@ -352,7 +351,6 @@ export function createPlatformModulesConfigFile(selectedModules) {
     '    description: "Project portfolio, detail routes, and work-management server logic.",',
     `    enabled: ${String(selected.has("projects"))},`,
     '    packageName: "@brightweblabs/module-projects",',
-    '    playgroundHref: "/playground/projects",',
     '    placement: "primary",',
     "  },",
     "  {",
@@ -361,7 +359,7 @@ export function createPlatformModulesConfigFile(selectedModules) {
     '    description: "User role governance, admin tools, and access-control surfaces.",',
     `    enabled: ${String(selected.has("admin"))},`,
     '    packageName: "@brightweblabs/module-admin",',
-    '    playgroundHref: "/playground/admin",',
+    '    routeHref: "/admin/users",',
     '    placement: "admin",',
     "  },",
     "];",
@@ -438,17 +436,15 @@ function createGitignore() {
 }
 
 function getPlatformStarterRoutes(selectedModules) {
-  return [
-    "/",
-    "/bootstrap",
-    "/preview/app-shell",
-    "/playground/auth",
-    ...selectedModules.map((moduleKey) => moduleKey === "crm" ? "/crm" : `/playground/${moduleKey}`),
-  ];
+  return selectedModules.flatMap((moduleKey) => {
+    if (moduleKey === "crm") return ["/crm"];
+    if (moduleKey === "admin") return ["/admin/users"];
+    return [];
+  });
 }
 
 function getSiteStarterRoutes() {
-  return ["/"];
+  return [];
 }
 
 function createPlatformReadme({
@@ -508,7 +504,7 @@ function createPlatformReadme({
           "",
         ]
       : []),
-    "## Starter routes",
+    "## Package mounts",
     "",
     ...getPlatformStarterRoutes(selectedModules).map((route) => `- \`${route}\``),
     "",
@@ -542,17 +538,17 @@ function createSiteReadme({ slug, workspaceMode, packageManager }) {
     "",
     "- Next.js App Router",
     "- Tailwind CSS v4",
-    "- Local shadcn-style component primitives",
+    "- App-owned settings and theme tokens",
     "",
     "## Local setup",
     "",
     ...localSteps,
     "",
-    "## Starter surfaces",
+    "## Package mounts",
     "",
     ...getSiteStarterRoutes().map((route) => `- \`${route}\``),
     "",
-    "Edit `config/site.ts` to change the site name, copy, and public links.",
+    "This thin scaffold intentionally ships no feature page. Add routes only as thin mounts of package-owned surfaces.",
     "",
     "## AI handoff",
     "",
@@ -591,33 +587,32 @@ export function createAppContextFile({
             "docs/ai/README.md",
             "README.md",
             "config/site.ts",
-            "app/page.tsx",
             "app/globals.css",
           ],
           appRoutesRoot: "app",
           configRoot: "config",
-          componentsRoot: "components",
-          uiComponentsRoot: "components/ui",
-          libRoot: "lib",
         },
         starterRoutes: getSiteStarterRoutes(),
         ownership: {
           appOwned: [
-            "app/**",
-            "components/**",
             "config/**",
             "docs/ai/**",
-            "lib/**",
             "public/**",
             "AGENTS.md",
             "README.md",
           ],
+          scaffoldManaged: [
+            "app/layout.tsx",
+            "app/globals.css",
+            "next.config.ts",
+            "postcss.config.mjs",
+            "tsconfig.json",
+          ],
           packageOwned: [],
         },
         agentRules: {
-          editConfigBeforeCopyTweaks: true,
-          keepUiPrimitiveChangesLocal: true,
-          treatStarterHomeAsAppOwned: true,
+          keepRoutesAsThinPackageMounts: true,
+          doNotAddFeatureOrLibraryCodeToTheApp: true,
         },
       },
       null,
@@ -649,30 +644,35 @@ export function createAppContextFile({
           "docs/ai/README.md",
           "README.md",
           "app/globals.css",
+          "app/theme.css",
           "config/brand.ts",
           "config/modules.ts",
-          "config/client.ts",
-          "config/bootstrap.ts",
           "config/shell.ts",
           "config/shell.overrides.ts",
           ".env.local",
         ],
         appRoutesRoot: "app",
-        componentsRoot: "components",
         configRoot: "config",
         brandAssetsRoot: "public/brand",
       },
       starterRoutes: getPlatformStarterRoutes(selectedModules),
       ownership: {
         appOwned: [
-          "app/**",
-          "components/**",
           "config/**",
           "docs/ai/**",
           "public/brand/**",
           "AGENTS.md",
           "README.md",
         ],
+        scaffoldManaged: [
+          "app/layout.tsx",
+          "app/globals.css",
+          "app/**/page.tsx",
+          "app/**/route.ts",
+          "next.config.ts",
+          "postcss.config.mjs",
+          "tsconfig.json",
+        ],
         packageOwned: [
           ...CORE_PACKAGES,
           ...(selectedModules.includes("crm") || selectedModules.includes("projects") ? [ORGS_PACKAGE_NAME] : []),
@@ -683,8 +683,8 @@ export function createAppContextFile({
       },
       agentRules: {
         checkModulesBeforeEditing: true,
-        preferAppLevelCompositionOverPackageForks: true,
-        treatStarterRoutesAsRemovable: true,
+        keepRoutesAsThinPackageMounts: true,
+        moveFeatureAndLibraryCodeToPackages: true,
       },
     },
     null,
@@ -711,13 +711,9 @@ export function createPackageJson({
         lint: "tsc --noEmit",
       },
       dependencies: sortObjectKeys({
-        "class-variance-authority": versionMap["class-variance-authority"],
-        "clsx": versionMap.clsx,
-        "lucide-react": versionMap["lucide-react"],
         "next": versionMap.next,
         "react": versionMap.react,
         "react-dom": versionMap["react-dom"],
-        "tailwind-merge": versionMap["tailwind-merge"],
       }),
       devDependencies: sortObjectKeys({
         "@tailwindcss/postcss": versionMap["@tailwindcss/postcss"],
@@ -813,6 +809,27 @@ export function createNextConfig({ template, selectedModules }) {
   ].join("\n");
 }
 
+export async function createPlatformGlobalsCss(selectedModules) {
+  const template = await fs.readFile(path.join(TEMPLATE_ROOT, "base", "app", "globals.css"), "utf8");
+  const sourcePackages = [
+    "@brightweblabs/ui",
+    "@brightweblabs/app-shell",
+    ...SELECTABLE_MODULES
+      .filter((moduleDefinition) => selectedModules.includes(moduleDefinition.key))
+      .map((moduleDefinition) => moduleDefinition.packageName),
+  ];
+  const sourceBlock = [
+    "/* BRIGHTWEB_SOURCES_START */",
+    ...sourcePackages.map((packageName) => `@source "../node_modules/${packageName}/src";`),
+    "/* BRIGHTWEB_SOURCES_END */",
+  ].join("\n");
+
+  return template.replace(
+    /\/\* BRIGHTWEB_SOURCES_START \*\/[\s\S]*?\/\* BRIGHTWEB_SOURCES_END \*\//,
+    sourceBlock,
+  );
+}
+
 export function createShellConfig(selectedModules) {
   const importLines = [];
   const registrationLines = [];
@@ -832,14 +849,9 @@ export function createShellConfig(selectedModules) {
     registrationLines.push('  if (enabled.has("crm")) registrations.push(crmModuleRegistration);');
   }
 
-  if (selectedModules.includes("projects")) {
-    importLines.push('import { projectsModuleRegistration } from "@brightweblabs/module-projects/registration";');
-    registrationLines.push('  if (enabled.has("projects")) registrations.push(projectsModuleRegistration);');
-  }
-
   return [
     "// MANAGED BY BRIGHTWEB — regenerated by create-bw-app update; put customizations in config/shell.overrides.ts",
-    'import { LayoutDashboard, Wrench } from "lucide-react";',
+    'import { Wrench } from "lucide-react";',
     "import {",
     "  applyShellRegistrationOverrides,",
     "  buildClientAppShellRegistration,",
@@ -853,16 +865,9 @@ export function createShellConfig(selectedModules) {
     'import { getEnabledStarterModules } from "./modules";',
     'import { shellRegistrationOverrides } from "./shell.overrides";',
     "",
-    "const dashboardModuleRegistration: ShellModuleRegistration<ShellContextualAction> = {",
-    '  key: "dashboard",',
-    '  placement: "primary",',
-    '  navItems: [{ href: "/dashboard", label: "Dashboard", icon: LayoutDashboard }],',
-    '  toolbarRoutes: [{ surface: "dashboard", match: { exact: ["/dashboard"] } }],',
-    "};",
-    "",
     "function getStarterModuleRegistrations() {",
     '  const enabled = new Set(getEnabledStarterModules().map((moduleConfig) => moduleConfig.key));',
-    "  const registrations: ShellModuleRegistration<ShellContextualAction>[] = [dashboardModuleRegistration];",
+    "  const registrations: ShellModuleRegistration<ShellContextualAction>[] = [];",
     "",
     ...registrationLines,
     "",
@@ -900,7 +905,7 @@ export function createShellConfig(selectedModules) {
     '      key: "tools",',
     '      label: "Ferramentas",',
     "      icon: Wrench,",
-    '      collapsedHref: enabledModules.find((moduleConfig) => moduleConfig.playgroundHref)?.playgroundHref || "/",',
+    '      collapsedHref: enabledModules.find((moduleConfig) => moduleConfig.routeHref)?.routeHref || "/",',
     "    },",
     "    modules,",
     "  };",
@@ -1013,7 +1018,7 @@ async function writeClientStack(baseRoot, slug, dbInstallPlan, options = {}) {
             : "Generated by create-bw-app in published mode.",
           `Selected app modules: ${dbInstallPlan.selectedLabels.length > 0 ? dbInstallPlan.selectedLabels.join(", ") : "none"}.`,
           `Resolved database stack: ${enabledModules.map((moduleKey) => getModuleLabel(moduleKey)).join(" -> ")}.`,
-          "Platform always resolves to the Core + Admin database baseline; selecting Admin only controls whether the Admin starter UI and package wiring are scaffolded.",
+          "Platform always resolves to the Core + Admin database baseline; selecting Admin only controls whether the Admin package mount and wiring are scaffolded.",
           "The database install order is resolved from supabase/module-registry.json.",
         ],
       },
@@ -1240,7 +1245,9 @@ async function scaffoldPlatformProject({
   for (const moduleDefinition of SELECTABLE_MODULES) {
     if (!selectedModules.includes(moduleDefinition.key)) continue;
     const moduleTemplateDir = path.join(TEMPLATE_ROOT, "modules", moduleDefinition.templateFolder);
-    await copyDirectory(moduleTemplateDir, targetDir);
+    if (await pathExists(moduleTemplateDir)) {
+      await copyDirectory(moduleTemplateDir, targetDir);
+    }
   }
 
   await fs.writeFile(
@@ -1258,6 +1265,7 @@ async function scaffoldPlatformProject({
     )}\n`,
   );
   await fs.writeFile(path.join(targetDir, "next.config.ts"), createNextConfig({ template: "platform", selectedModules }));
+  await fs.writeFile(path.join(targetDir, "app", "globals.css"), await createPlatformGlobalsCss(selectedModules));
   await fs.writeFile(
     path.join(targetDir, "config", "brand.ts"),
     createPlatformBrandConfigFile({ slug: answers.slug, brandValues }),

package/src/remove.mjs

@@ -13,6 +13,7 @@ import {
   createAppContextFile,
   createDbInstallPlan,
   createNextConfig,
+  createPlatformGlobalsCss,
   createPlatformModulesConfigFile,
   createShellConfig,
   getDbModuleRegistry,
@@ -59,6 +60,7 @@ export async function removeBrightwebModule(moduleKey, argvOptions = {}, runtime
   });
   const managedWrites = {
     "next.config.ts": createNextConfig({ template: "platform", selectedModules: remainingModules }),
+    "app/globals.css": await createPlatformGlobalsCss(remainingModules),
     "config/modules.ts": createPlatformModulesConfigFile(remainingModules),
     "config/shell.ts": createShellConfig(remainingModules),
     "docs/ai/app-context.json": createAppContextFile({ slug: appManifest.app.slug, template: "platform", selectedModules: remainingModules.filter((key) => key !== "orgs"), dbInstallPlan }),
@@ -70,7 +72,7 @@ export async function removeBrightwebModule(moduleKey, argvOptions = {}, runtime
     if (record.module !== moduleKey) continue;
     const filePath = path.join(targetDir, relativePath);
     if (!(await pathExists(filePath))) continue;
-    if (await hashFile(filePath) === record.hash) cleanFiles.push(relativePath);
+    if ((record.intent || "managed") === "managed" && await hashFile(filePath) === record.hash) cleanFiles.push(relativePath);
     else driftedFiles.push(relativePath);
   }
   const notice = databaseNotice(moduleKey, catalog[moduleKey]?.manifest?.database?.ownedObjects || []);