create-bw-app 0.12.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.12.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 }),

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",

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",
   ],
 };
 
@@ -79,7 +78,7 @@ export const APP_DEPENDENCY_DEFAULTS = {
   "@brightweblabs/app-shell": "^0.4.1",
   "@brightweblabs/core-auth": "^0.3.4",
   "@brightweblabs/infra": "^0.3.1",
-  "@brightweblabs/module-admin": "^0.3.5",
+  "@brightweblabs/module-admin": "^0.4.0",
   "@brightweblabs/module-crm": "^0.5.2",
   "@brightweblabs/module-orgs": "^0.2.2",
   "@brightweblabs/module-projects": "^0.4.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/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 }),

package/src/update.mjs

@@ -15,6 +15,7 @@ import {
   createDbInstallPlan,
   createNextConfig,
   createPackageJson,
+  createPlatformGlobalsCss,
   createPlatformModulesConfigFile,
   createShellConfig,
   detectPackageManager,
@@ -27,6 +28,7 @@ import {
 
 const MANAGED_PLATFORM_FILES = [
   "next.config.ts",
+  path.join("app", "globals.css"),
   path.join("config", "modules.ts"),
   path.join("config", "shell.ts"),
   path.join("docs", "ai", "app-context.json"),
@@ -490,6 +492,7 @@ export async function buildBrightwebAppUpdatePlan(argvOptions = {}, runtimeOptio
   if (template === "platform") {
     const canonicalConfigFiles = {
       "next.config.ts": createNextConfig({ template: "platform", selectedModules: installedModules }),
+      [path.join("app", "globals.css")]: await createPlatformGlobalsCss(installedModules),
       [path.join("config", "modules.ts")]: createPlatformModulesConfigFile(installedModules),
       [path.join("config", "shell.ts")]: createShellConfig(installedModules),
       [path.join("docs", "ai", "app-context.json")]: createAppContextFile({

package/template/base/AGENTS.md

@@ -1,31 +1,27 @@
 # AGENTS.md
 
-This generated project is a BrightWeb platform starter. Use this file as the local entrypoint for AI agents working inside the app.
+This is a thin BrightWeb platform app. The app owns environment values and settings; reusable UI, domain behavior, and helpers belong in `@brightweblabs/*` packages.
 
 ## Start here
 
-- `README.md`: local setup commands and starter routes.
-- `docs/ai/README.md`: app-specific routing guide for agents.
-- `docs/ai/examples.md`: common setup and customization flows.
-- `docs/ai/app-context.json`: machine-readable app summary for quick discovery.
-- `components/`: local app components used by starter routes and future product surfaces.
-- `config/brand.ts`: client identity, naming, and contact defaults.
-- `app/globals.css`: global design tokens, theme mapping, and shared visual styling.
-- `config/modules.ts`: selected module set and runtime enablement.
-- `config/client.ts`: starter-facing derived state used by the home page and setup surfaces.
-- `.env.local`: runtime service values for local development.
+- `README.md`: setup commands and mounted package routes.
+- `docs/ai/app-context.json`: machine-readable module, path, and ownership summary.
+- `config/brand.ts`: client identity and contact defaults.
+- `config/modules.ts`: selected module set and route metadata.
+- `config/shell.overrides.ts`: app-owned shell customizations.
+- `app/theme.css`: app-owned theme token overrides.
+- `.env.local`: runtime service values.
 
 ## Working rules
 
-- Treat `/bootstrap`, `/preview/app-shell`, and `/playground/*` as starter validation surfaces. They are app-owned and can be removed after setup if links and references are cleaned up too.
-- Keep identity/contact in `config/brand.ts`, and keep all color/theme tokens in `app/globals.css`.
-- Check `config/modules.ts` before assuming CRM, Projects, or Admin routes exist.
-- Prefer composing app-level routes and config before forking logic from `@brightweblabs/*` packages.
-- Keep edits local to this app unless the change is intentionally shared across multiple BrightWeb projects.
+- Keep every `route.ts` as a direct package re-export; a `page.tsx` may instead import one package component and return only that mount.
+- Do not add feature components, demos, hooks, data access, or helper libraries to this app.
+- Put reusable behavior in the owning package, then mount its export here.
+- Keep identity and theme changes in config and theme files.
+- Check `config/modules.ts` before assuming an optional route exists. Projects currently has no default UI route.
 
 ## First validation pass
 
-1. Run the local dev server from this project or workspace.
-2. Open `/`, `/bootstrap`, `/preview/app-shell`, and `/playground/auth`.
-3. If optional modules are enabled, open the matching `/playground/*` route for each one.
-4. Confirm `.env.local` contains real service values before debugging runtime behavior.
+1. Fill `.env.local` with real service values.
+2. Run the local type check or build.
+3. Validate `/crm` and `/admin/users` only when their modules are enabled.