create-bw-app 0.10.0 → 0.11.0

package/src/remove.mjs

@@ -0,0 +1,100 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { stdout as output } from "node:process";
+import {
+  MODULE_PACKAGES,
+  findWorkspaceRoot,
+  hashFile,
+  loadModuleCatalog,
+  readAppManifest,
+  writeAppManifest,
+} from "./app-manifest.mjs";
+import {
+  createAppContextFile,
+  createDbInstallPlan,
+  createNextConfig,
+  createPlatformModulesConfigFile,
+  createShellConfig,
+  getDbModuleRegistry,
+  pathExists,
+  readJsonIfPresent,
+} from "./generator.mjs";
+
+const HELP = `Usage: bw remove <moduleKey> [options]\n\nOptions:\n  --target-dir <path>       App directory (defaults to cwd)\n  --workspace-root <path>   BrightWeb workspace root\n  --dry-run                 Print the removal plan without writing\n  --yes                     Apply the removal plan\n  --help                    Show this help`;
+
+function databaseNotice(moduleKey, ownedObjects) {
+  const names = ownedObjects.length > 0 ? ownedObjects.join(", ") : "none declared";
+  return [
+    `-- Database objects owned by ${moduleKey}: ${names}`,
+    "-- No database objects or migration files were changed.",
+    "-- Dropping owned objects is a deliberate manual data-removal act.",
+    "-- Applied migrations remain in app history under the append-only migration principle.",
+  ];
+}
+
+export async function removeBrightwebModule(moduleKey, argvOptions = {}, runtimeOptions = {}) {
+  if (!moduleKey || argvOptions.help) { output.write(`${HELP}\n`); return { help: true }; }
+  const targetDir = path.resolve(runtimeOptions.targetDir || argvOptions.targetDir || process.cwd());
+  const appManifest = await readAppManifest(targetDir);
+  if (!appManifest.modules[moduleKey]) throw new Error(`Module ${moduleKey} is not installed according to .brightweb/app-manifest.json.`);
+  const workspaceRoot = runtimeOptions.workspaceRoot || argvOptions.workspaceRoot || await findWorkspaceRoot(targetDir);
+  const catalog = await loadModuleCatalog({ targetDir, workspaceRoot });
+  const dependents = Object.keys(appManifest.modules)
+    .filter((key) => key !== moduleKey && catalog[key]?.requires?.[moduleKey]);
+  if (dependents.length > 0) throw new Error(`Cannot remove ${moduleKey}; installed module${dependents.length === 1 ? "" : "s"} ${dependents.join(", ")} require${dependents.length === 1 ? "s" : ""} it.`);
+
+  const packagePath = path.join(targetDir, "package.json");
+  const packageJson = await readJsonIfPresent(packagePath);
+  if (!packageJson) throw new Error(`Target directory does not contain package.json: ${targetDir}`);
+  const nextPackageJson = structuredClone(packageJson);
+  const packageName = MODULE_PACKAGES[moduleKey];
+  for (const section of ["dependencies", "devDependencies"]) if (nextPackageJson[section]) delete nextPackageJson[section][packageName];
+
+  const remainingModules = Object.keys(appManifest.modules).filter((key) => key !== moduleKey);
+  const dbRegistry = await getDbModuleRegistry(workspaceRoot);
+  const dbInstallPlan = createDbInstallPlan({
+    selectedModules: remainingModules.filter((key) => key !== "orgs"),
+    workspaceMode: Object.values(nextPackageJson.dependencies || {}).some((value) => String(value).startsWith("workspace:")),
+    registry: dbRegistry,
+  });
+  const managedWrites = {
+    "next.config.ts": createNextConfig({ template: "platform", selectedModules: 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 }),
+  };
+
+  const cleanFiles = [];
+  const driftedFiles = [];
+  for (const [relativePath, record] of Object.entries(appManifest.scaffoldFiles || {})) {
+    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);
+    else driftedFiles.push(relativePath);
+  }
+  const notice = databaseNotice(moduleKey, catalog[moduleKey]?.manifest?.database?.ownedObjects || []);
+  const apply = argvOptions.yes === true && argvOptions.dryRun !== true;
+  output.write(`bw remove ${moduleKey}${apply ? "" : " (plan only; pass --yes to apply)"}\n`);
+  output.write(`Dependency to remove: ${packageName}\n`);
+  output.write(`Clean scaffold files to remove: ${cleanFiles.join(", ") || "none"}\n`);
+  output.write(`Drifted scaffold files left in place: ${driftedFiles.join(", ") || "none"}\n`);
+  for (const relativePath of driftedFiles) output.write(`WARN ${relativePath} is drifted and will be left in place.\n`);
+  for (const line of notice) output.write(`${line}\n`);
+  if (!apply) return { dryRun: true, moduleKey, cleanFiles, driftedFiles, notice };
+
+  await fs.writeFile(packagePath, `${JSON.stringify(nextPackageJson, null, 2)}\n`, "utf8");
+  for (const relativePath of cleanFiles) await fs.rm(path.join(targetDir, relativePath));
+  for (const [relativePath, content] of Object.entries(managedWrites)) {
+    const targetPath = path.join(targetDir, relativePath);
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    await fs.writeFile(targetPath, content, "utf8");
+  }
+  delete appManifest.modules[moduleKey];
+  for (const [relativePath, record] of Object.entries(appManifest.scaffoldFiles || {})) if (record.module === moduleKey) delete appManifest.scaffoldFiles[relativePath];
+  await writeAppManifest(targetDir, appManifest);
+  output.write(`Removed ${moduleKey} package wiring and ${cleanFiles.length} clean scaffold file${cleanFiles.length === 1 ? "" : "s"}. Install dependencies next.\n`);
+  return { dryRun: false, moduleKey, cleanFiles, driftedFiles, notice };
+}
+
+export { HELP as REMOVE_HELP };

package/src/scaffold.mjs

@@ -0,0 +1,82 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { MODULE_STARTER_FILES, PLATFORM_STARTER_FILES, SELECTABLE_MODULES } from "./constants.mjs";
+import { hashFile } from "./app-manifest.mjs";
+import { pathExists } from "./generator.mjs";
+
+const BUNDLED_TEMPLATE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "template");
+
+export async function resolveTemplateRoot({ targetDir, workspaceRoot } = {}) {
+  const candidates = [
+    workspaceRoot && path.join(path.resolve(workspaceRoot), "packages", "create-bw-app", "template"),
+    targetDir && path.join(path.resolve(targetDir), "node_modules", "create-bw-app", "template"),
+    BUNDLED_TEMPLATE_ROOT,
+  ].filter(Boolean);
+  for (const candidate of candidates) if (await pathExists(candidate)) return candidate;
+  return null;
+}
+
+export function trackedScaffoldDefinitions(moduleKeys = []) {
+  const definitions = PLATFORM_STARTER_FILES.map((relativePath) => ({
+    moduleKey: "platform-base",
+    relativePath,
+    templateRelativePath: path.join("base", relativePath),
+  }));
+  for (const moduleKey of moduleKeys) {
+    const folder = SELECTABLE_MODULES.find((entry) => entry.key === moduleKey)?.templateFolder;
+    if (!folder) continue;
+    for (const relativePath of MODULE_STARTER_FILES[moduleKey] || []) {
+      definitions.push({ moduleKey, relativePath, templateRelativePath: path.join("modules", folder, relativePath) });
+    }
+  }
+  return definitions.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+
+export async function inventoryScaffoldFiles({ targetDir, moduleKeys, templateRoot }) {
+  const records = {};
+  const unsupported = [];
+  for (const definition of trackedScaffoldDefinitions(moduleKeys)) {
+    const templatePath = templateRoot && path.join(templateRoot, definition.templateRelativePath);
+    if (!templatePath || !(await pathExists(templatePath))) {
+      unsupported.push(definition.relativePath);
+      continue;
+    }
+    const appPath = path.join(targetDir, definition.relativePath);
+    const templateHash = await hashFile(templatePath);
+    const exists = await pathExists(appPath);
+    records[definition.relativePath] = {
+      module: definition.moduleKey,
+      hash: templateHash,
+      status: !exists ? "missing" : await hashFile(appPath) === templateHash ? "current" : "drifted",
+    };
+  }
+  return { records, unsupported };
+}
+
+export async function scaffoldDrift(targetDir, scaffoldFiles = {}) {
+  const current = [];
+  const drifted = [];
+  const missing = [];
+  for (const [relativePath, record] of Object.entries(scaffoldFiles)) {
+    const appPath = path.join(targetDir, relativePath);
+    if (!(await pathExists(appPath))) missing.push(relativePath);
+    else if (await hashFile(appPath) === record.hash) current.push(relativePath);
+    else drifted.push(relativePath);
+  }
+  return { current, drifted, missing };
+}
+
+export async function findTrackedTemplate({ relativePath, manifest, targetDir, workspaceRoot }) {
+  const record = manifest.scaffoldFiles?.[relativePath];
+  if (!record) return { record: null, templatePath: null, templateRoot: null };
+  const definition = trackedScaffoldDefinitions(Object.keys(manifest.modules || {}))
+    .find((entry) => entry.relativePath === relativePath && entry.moduleKey === record.module);
+  const templateRoot = await resolveTemplateRoot({ targetDir, workspaceRoot });
+  const templatePath = definition && templateRoot ? path.join(templateRoot, definition.templateRelativePath) : null;
+  return { record, templatePath: templatePath && await pathExists(templatePath) ? templatePath : null, templateRoot };
+}
+
+export async function readTextFile(filePath) {
+  return fs.readFile(filePath, "utf8");
+}

package/src/update.mjs

@@ -5,6 +5,8 @@ import {
   BRIGHTWEB_PACKAGE_NAMES,
   CLI_DISPLAY_NAME,
   MODULE_STARTER_FILES,
+  ORGS_PACKAGE_NAME,
+  PLATFORM_STARTER_FILES,
   SELECTABLE_MODULES,
 } from "./constants.mjs";
 import {
@@ -146,7 +148,7 @@ function parseConfiguredModules(content) {
   return enabledModules;
 }
 
-async function detectTemplate(targetDir, installedBrightwebPackages) {
+export async function detectTemplate(targetDir, installedBrightwebPackages) {
   if (await pathExists(path.join(targetDir, "config", "modules.ts"))) {
     return "platform";
   }
@@ -154,7 +156,7 @@ async function detectTemplate(targetDir, installedBrightwebPackages) {
   return installedBrightwebPackages.size > 0 ? "platform" : "site";
 }
 
-function detectDependencyMode(installedBrightwebPackages) {
+export function detectDependencyMode(installedBrightwebPackages) {
   for (const { version } of installedBrightwebPackages.values()) {
     if (typeof version === "string" && version.startsWith("workspace:")) {
       return "workspace";
@@ -220,6 +222,19 @@ function mergeManagedPackageUpdates({ manifest, targetVersions, installedBrightw
     changed = true;
   }
 
+  const requiredOrgsVersion = targetVersions[ORGS_PACKAGE_NAME];
+  if (requiredOrgsVersion && !installedBrightwebPackages.has(ORGS_PACKAGE_NAME)) {
+    nextManifest.dependencies = nextManifest.dependencies || {};
+    nextManifest.dependencies[ORGS_PACKAGE_NAME] = requiredOrgsVersion;
+    packageUpdates.push({
+      packageName: ORGS_PACKAGE_NAME,
+      from: null,
+      to: requiredOrgsVersion,
+      section: "dependencies",
+    });
+    changed = true;
+  }
+
   return {
     changed,
     packageUpdates,
@@ -230,6 +245,38 @@ function mergeManagedPackageUpdates({ manifest, targetVersions, installedBrightw
 async function getStarterFileStatus(targetDir, installedModules) {
   const starterFiles = [];
 
+  for (const relativePath of PLATFORM_STARTER_FILES) {
+    const sourcePath = path.join(TEMPLATE_ROOT, "base", relativePath);
+    const targetPath = path.join(targetDir, relativePath);
+    const exists = await pathExists(targetPath);
+
+    if (!exists) {
+      starterFiles.push({
+        moduleKey: "platform-base",
+        relativePath,
+        sourcePath,
+        targetPath,
+        status: "missing",
+        refreshable: false,
+      });
+      continue;
+    }
+
+    const [sourceContent, targetContent] = await Promise.all([
+      fs.readFile(sourcePath, "utf8"),
+      fs.readFile(targetPath, "utf8"),
+    ]);
+
+    starterFiles.push({
+      moduleKey: "platform-base",
+      relativePath,
+      sourcePath,
+      targetPath,
+      status: sourceContent === targetContent ? "current" : "drifted",
+      refreshable: false,
+    });
+  }
+
   for (const moduleKey of installedModules) {
     const templateFolder = SELECTABLE_MODULES.find((moduleDefinition) => moduleDefinition.key === moduleKey)?.templateFolder;
     if (!templateFolder) continue;
@@ -498,7 +545,8 @@ export async function buildBrightwebAppUpdatePlan(argvOptions = {}, runtimeOptio
   const starterFilesDrifted = starterFiles.filter((entry) => entry.status === "drifted");
 
   if (argvOptions.refreshStarters) {
-    for (const entry of starterFiles.filter((candidate) => candidate.status !== "current")) {
+    for (const entry of starterFiles.filter((candidate) =>
+      candidate.status !== "current" && (candidate.status === "missing" || candidate.refreshable !== false))) {
       fileWrites.push({
         relativePath: entry.relativePath,
         targetPath: entry.targetPath,

package/src/upgrade.mjs

@@ -0,0 +1,73 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { stdout as output } from "node:process";
+import { hashFile, findWorkspaceRoot, loadModuleCatalog, readAppManifest, writeAppManifest, cleanVersion } from "./app-manifest.mjs";
+import { pathExists, runInstall } from "./generator.mjs";
+import { applyMigrationWrites, getModuleMigrations, planMigrationAppends } from "./migrations.mjs";
+import { buildBrightwebAppUpdatePlan } from "./update.mjs";
+
+const HELP = `Usage: bw upgrade [moduleKey] [options]\n\nOptions:\n  --target-dir <path>          App directory (defaults to cwd)\n  --workspace-root <path>      BrightWeb workspace root\n  --allow-stale-fallback       Use baked-in versions if npm lookup fails\n  --install                    Install changed dependencies\n  --refresh-starters           Refresh unchanged starter files\n  --dry-run                    Print the upgrade plan without writing\n  --help                       Show this help`;
+
+export async function upgradeBrightwebApp(moduleKey, argvOptions = {}, runtimeOptions = {}) {
+  if (argvOptions.help) { output.write(`${HELP}\n`); return { help: true }; }
+  const targetDir = path.resolve(runtimeOptions.targetDir || argvOptions.targetDir || process.cwd());
+  const appManifest = await readAppManifest(targetDir);
+  if (moduleKey && !appManifest.modules[moduleKey]) throw new Error(`Module ${moduleKey} is not installed according to ${path.join(".brightweb", "app-manifest.json")}.`);
+  const workspaceRoot = runtimeOptions.workspaceRoot || argvOptions.workspaceRoot || await findWorkspaceRoot(targetDir);
+  const updateOptions = { ...argvOptions, targetDir, ...(workspaceRoot ? { workspaceRoot } : {}) };
+  const plan = await buildBrightwebAppUpdatePlan(updateOptions, runtimeOptions);
+  const drifted = [];
+  const missing = [];
+  for (const [relativePath, record] of Object.entries(appManifest.scaffoldFiles)) {
+    const filePath = path.join(targetDir, relativePath);
+    if (!(await pathExists(filePath))) { missing.push(relativePath); continue; }
+    if (await hashFile(filePath) !== record.hash) drifted.push(relativePath);
+  }
+  const protectedPaths = new Set(drifted);
+  plan.fileWrites = plan.fileWrites.filter((entry) => entry.type !== "starter" || !protectedPaths.has(entry.relativePath));
+  plan.starterFilesDrifted = Array.from(new Set([...plan.starterFilesDrifted, ...drifted]));
+  plan.starterFilesMissing = Array.from(new Set([...plan.starterFilesMissing, ...missing]));
+
+  const catalog = await loadModuleCatalog({ targetDir, workspaceRoot });
+  for (const update of plan.packageUpdates) {
+    const key = Object.keys(catalog).find((candidate) => catalog[candidate].packageName === update.packageName);
+    if (key) catalog[key].version = cleanVersion(update.to) || catalog[key].version;
+  }
+  const moduleKeys = moduleKey ? [moduleKey] : Object.keys(appManifest.modules);
+  const uncursored = [];
+  for (const key of moduleKeys) {
+    if (appManifest.migrationCursor?.[key] == null && (await getModuleMigrations(key, catalog[key])).length > 0) uncursored.push(key);
+  }
+  if (uncursored.length > 0) throw new Error(`Migration upgrade blocked: ${uncursored.join(", ")} ${uncursored.length === 1 ? "has" : "have"} a null migration cursor. Set an explicit cursor with bw adopt --force --cursor before upgrading.`);
+  const migrationPlan = await planMigrationAppends({ targetDir, moduleKeys, catalog, migrationCursor: appManifest.migrationCursor });
+  output.write(`bw upgrade\nPackages to update: ${plan.packageUpdates.length}\nManaged files to write: ${plan.fileWrites.length}\nMigrations to append: ${migrationPlan.writes.length}\n`);
+  for (const relativePath of missing) output.write(`- missing: ${relativePath}\n`);
+  for (const relativePath of drifted) output.write(`- drifted: ${relativePath}\n`);
+  if (argvOptions.dryRun) return { dryRun: true, plan, migrationPlan, drifted, missing };
+
+  for (const write of plan.fileWrites) {
+    await fs.mkdir(path.dirname(write.targetPath), { recursive: true });
+    await fs.writeFile(write.targetPath, write.content, "utf8");
+  }
+  await applyMigrationWrites(migrationPlan.writes);
+  appManifest.migrationCursor = migrationPlan.nextCursor;
+  for (const update of plan.packageUpdates) {
+    const key = Object.keys(catalog).find((candidate) => catalog[candidate].packageName === update.packageName);
+    if (key && appManifest.modules[key]) appManifest.modules[key].version = cleanVersion(update.to) || appManifest.modules[key].version;
+  }
+  for (const relativePath of plan.starterFilesToRefresh || []) {
+    if (!protectedPaths.has(relativePath) && appManifest.scaffoldFiles[relativePath] && await pathExists(path.join(targetDir, relativePath))) {
+      appManifest.scaffoldFiles[relativePath].hash = await hashFile(path.join(targetDir, relativePath));
+    }
+  }
+  await writeAppManifest(targetDir, appManifest);
+  const packageChanged = plan.fileWrites.some((entry) => entry.relativePath === "package.json");
+  if (argvOptions.install && packageChanged) {
+    const runner = runtimeOptions.installRunner || runInstall;
+    await runner(plan.packageManager, plan.dependencyMode === "workspace" && plan.workspaceRoot ? plan.workspaceRoot : targetDir);
+  }
+  output.write(`Applied ${plan.fileWrites.length} managed change${plan.fileWrites.length === 1 ? "" : "s"} and ${migrationPlan.writes.length} migration${migrationPlan.writes.length === 1 ? "" : "s"}.\n`);
+  return { dryRun: false, plan, migrationPlan, drifted, missing };
+}
+
+export { HELP as UPGRADE_HELP };

package/template/base/AGENTS.md

@@ -10,6 +10,7 @@ This generated project is a BrightWeb platform starter. Use this file as the loc
 - `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.
@@ -17,6 +18,7 @@ This generated project is a BrightWeb platform starter. Use this file as the loc
 ## 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.

package/template/base/app/globals.css

@@ -1,20 +1,36 @@
 @import "tailwindcss";
+@import "@brightweblabs/theme/css";
 
 :root {
   color-scheme: light;
   --font-sans: "IBM Plex Sans", "Segoe UI", sans-serif;
   --font-display: Georgia, "Times New Roman", serif;
+  /* Raw brand tokens: customize these first per client. */
+  --brand-primary: #266946;
+  --brand-primary-rgb: 38, 105, 70;
+  --brand-secondary-rgb: 126, 170, 112;
+  --brand-highlight-rgb: 189, 140, 89;
+  --brand-positive-rgb: 113, 196, 139;
+  /* Semantic theme tokens consumed by the UI. */
   --background: #f3efe5;
   --foreground: #18241d;
   --muted-foreground: #5a665c;
   --border: rgba(24, 36, 29, 0.12);
   --panel: rgba(255, 255, 255, 0.82);
   --panel-strong: #ffffff;
-  --accent: #266946;
-  --accent-soft: rgba(38, 105, 70, 0.12);
+  --accent: var(--brand-primary);
+  --accent-soft: rgba(var(--brand-primary-rgb), 0.12);
   --danger: #b43f3f;
   --ink-soft: #eef1e8;
-  --ring: rgba(38, 105, 70, 0.28);
+  --ring: rgba(var(--brand-primary-rgb), 0.28);
+  --surface-glow-cool: rgba(var(--brand-secondary-rgb), 0.18);
+  --surface-glow-warm: rgba(var(--brand-highlight-rgb), 0.12);
+  --accent-glow-strong: rgba(var(--brand-primary-rgb), 0.18);
+  --accent-glow-mid: rgba(var(--brand-primary-rgb), 0.14);
+  --accent-glow-soft: rgba(var(--brand-primary-rgb), 0.08);
+  --positive-glow-strong: rgba(var(--brand-positive-rgb), 0.5);
+  --positive-glow-soft: rgba(var(--brand-positive-rgb), 0.14);
+  --positive-glow-subtle: rgba(var(--brand-positive-rgb), 0.15);
 
   /* Compatibility aliases so both starters expose the same token surface. */
   --bg: var(--background);
@@ -32,8 +48,8 @@ body {
   margin: 0;
   padding: 0;
   background:
-    radial-gradient(circle at 15% 10%, rgba(126, 170, 112, 0.18), transparent 22%),
-    radial-gradient(circle at 85% 12%, rgba(189, 140, 89, 0.12), transparent 18%),
+    radial-gradient(circle at 15% 10%, var(--surface-glow-cool), transparent 22%),
+    radial-gradient(circle at 85% 12%, var(--surface-glow-warm), transparent 18%),
     linear-gradient(180deg, #faf8f1 0%, var(--bg) 48%, #e8e0cf 100%);
   color: var(--text);
   font-family: var(--font-sans), sans-serif;
@@ -97,7 +113,7 @@ input {
   overflow: hidden;
   background:
     linear-gradient(180deg, rgba(255, 255, 255, 0.86), rgba(247, 244, 235, 0.84)),
-    radial-gradient(circle at top right, rgba(38, 105, 70, 0.18), transparent 45%);
+    radial-gradient(circle at top right, var(--accent-glow-strong), transparent 45%);
 }
 
 .starter-hero-card::after {
@@ -107,7 +123,7 @@ input {
   width: 150px;
   height: 150px;
   border-radius: 999px;
-  background: rgba(38, 105, 70, 0.08);
+  background: var(--accent-glow-soft);
 }
 
 .starter-stat-grid {
@@ -185,7 +201,7 @@ input {
 .preview-glass-card {
   background:
     linear-gradient(180deg, rgba(255, 255, 255, 0.84), rgba(246, 244, 236, 0.76)),
-    radial-gradient(circle at top right, rgba(38, 105, 70, 0.08), transparent 45%);
+    radial-gradient(circle at top right, var(--accent-glow-soft), transparent 45%);
 }
 
 .panel h2,
@@ -308,7 +324,7 @@ input {
   border-radius: 28px;
   background:
     linear-gradient(180deg, rgba(255, 255, 255, 0.88), rgba(241, 237, 226, 0.84)),
-    radial-gradient(circle at top, rgba(38, 105, 70, 0.12), transparent 34%);
+    radial-gradient(circle at top, var(--accent-soft), transparent 34%);
   backdrop-filter: blur(16px);
   box-shadow: 0 22px 60px rgba(24, 36, 29, 0.1);
 }
@@ -328,7 +344,7 @@ input {
   border-radius: 28px;
   background:
     linear-gradient(180deg, rgba(255, 255, 255, 0.88), rgba(246, 243, 235, 0.86)),
-    radial-gradient(circle at right top, rgba(38, 105, 70, 0.14), transparent 35%);
+    radial-gradient(circle at right top, var(--accent-glow-mid), transparent 35%);
   backdrop-filter: blur(16px);
 }
 
@@ -374,7 +390,7 @@ input {
 .preview-stage-panel {
   background:
     linear-gradient(180deg, rgba(23, 37, 29, 0.96), rgba(18, 30, 24, 0.95)),
-    radial-gradient(circle at top left, rgba(113, 196, 139, 0.15), transparent 34%);
+    radial-gradient(circle at top left, var(--positive-glow-subtle), transparent 34%);
   color: #f4f1e8;
   border-color: rgba(255, 255, 255, 0.1);
 }
@@ -409,8 +425,8 @@ input {
 
 .nav-chip.active,
 .nav-chip:hover {
-  border-color: rgba(113, 196, 139, 0.5);
-  background: rgba(113, 196, 139, 0.14);
+  border-color: var(--positive-glow-strong);
+  background: var(--positive-glow-soft);
 }
 
 .preview-surface-grid {
@@ -510,7 +526,7 @@ input {
 }
 
 .status.ok {
-  background: rgba(31, 122, 69, 0.14);
+  background: rgba(var(--brand-primary-rgb), 0.14);
   color: var(--accent);
 }
 

package/template/base/app/page.tsx

@@ -113,6 +113,7 @@ export default function HomePage() {
               <h2>Starter controls</h2>
               <ul className="list">
                 <li>`config/brand.ts` for client identity and contact details.</li>
+                <li>`app/globals.css` for color and theme token management.</li>
                 <li>`config/modules.ts` for enabled platform modules.</li>
                 <li>`config/env.ts` for infra requirements and readiness checks.</li>
                 <li>`.env.local` for per-client service credentials and local runtime overrides.</li>

package/template/base/config/bootstrap.ts

@@ -104,7 +104,7 @@ export function getStarterBootstrapChecklist() {
       {
         label: "Preview CRM module",
         done: hasModule(moduleKeys, "crm"),
-        detail: hasModule(moduleKeys, "crm") ? "/playground/crm" : "CRM not enabled",
+        detail: hasModule(moduleKeys, "crm") ? "/crm" : "CRM not enabled",
       },
       {
         label: "Preview Projects module",

package/template/base/config/brand.ts

@@ -5,7 +5,6 @@ export type StarterBrandConfig = {
   tagline: string;
   contactEmail: string;
   supportEmail: string;
-  primaryHex: string;
 };
 
 export const starterBrandConfig: StarterBrandConfig = {
@@ -15,5 +14,4 @@ export const starterBrandConfig: StarterBrandConfig = {
   tagline: "A configurable Brightweb starter app for shipping new client instances without rebuilding the platform.",
   contactEmail: "hello@example.com",
   supportEmail: "support@example.com",
-  primaryHex: "#1f7a45",
 };

package/template/base/config/modules.ts

@@ -23,10 +23,10 @@ export const starterModuleConfig: StarterModuleConfig[] = [
   {
     key: "crm",
     label: "CRM",
-    description: "Contacts, marketing audience, and CRM server/data layer.",
+    description: "Contacts and CRM server/data layer, with marketing-adjacent operational data stored in Supabase.",
     enabled: true,
     packageName: "@brightweblabs/module-crm",
-    playgroundHref: "/playground/crm",
+    playgroundHref: "/crm",
     placement: "primary",
   },
   {

package/template/base/config/shell.overrides.ts

@@ -0,0 +1,16 @@
+import type { ShellRegistrationOverrides } from "@brightweblabs/app-shell";
+
+/**
+ * App-owned shell customizations. This scaffolded file is never overwritten by
+ * `create-bw-app update`.
+ *
+ * @example Rewrite a module href wherever it appears in its registration:
+ * ```ts
+ * import { overrideNavHref } from "@brightweblabs/app-shell";
+ *
+ * const overrides: ShellRegistrationOverrides = {
+ *   crm: (registration) => overrideNavHref(registration, "/admin/marketing", "/crm/marketing"),
+ * };
+ * ```
+ */
+export const shellRegistrationOverrides: ShellRegistrationOverrides = {};

package/template/base/docs/ai/README.md

@@ -20,11 +20,13 @@ This app is a normal Next.js App Router project with BrightWeb runtime wiring la
 - `docs/ai/examples.md`: common setup and customization workflows.
 - `README.md`: first-run setup steps.
 - `components/`: local app component layer for starter surfaces and future product UI.
-- `config/brand.ts`: client name, product name, support inboxes, and brand color.
+- `config/brand.ts`: client identity, product naming, and contact inboxes.
 - `config/modules.ts`: module metadata and enablement flags for CRM, Projects, and Admin.
 - `config/client.ts`: aggregated state consumed by starter pages.
 - `config/bootstrap.ts`: bootstrap checklist content for `/bootstrap`.
-- `config/shell.ts`: app-shell registration and navigation wiring.
+- `config/shell.ts`: managed app-shell registration and navigation wiring.
+- `config/shell.overrides.ts`: app-owned shell registration customizations preserved across updates.
+- `app/globals.css`: color tokens (raw brand + semantic mappings), typography, and global surface styling.
 - `app/page.tsx`: starter landing page for the generated app.
 - `app/bootstrap/page.tsx`: setup checklist surface.
 - `app/preview/app-shell/page.tsx`: shell preview validation route.
@@ -34,9 +36,10 @@ This app is a normal Next.js App Router project with BrightWeb runtime wiring la
 ## Editing strategy
 
 - Change client identity first in `config/brand.ts`.
+- Change colors and theme tokens in `app/globals.css`.
 - Check module presence in `config/modules.ts` before editing or creating module-specific routes.
 - Add app-specific UI in `components/` before forking shared package code.
-- Use `config/shell.ts` when navigation or toolbar behavior needs to change.
+- Use `config/shell.overrides.ts` when navigation or toolbar behavior needs to change.
 - Use `config/bootstrap.ts` and `config/client.ts` when the setup checklist or readiness messaging is wrong.
 - Keep starter validation routes until the real product routes replace their purpose.
 

package/template/base/docs/ai/examples.md

@@ -8,16 +8,18 @@ Goal: get the generated starter running with real credentials.
 
 - Review `.env.local` and replace placeholder values.
 - Review `config/brand.ts` and confirm client identity.
+- Review `app/globals.css` and confirm brand tokens map to the intended visual system.
 - Review `config/modules.ts` before touching module routes.
 - Run the local dev server for this app or workspace.
 - Validate `/`, `/bootstrap`, `/preview/app-shell`, and `/playground/auth`.
-- Validate `/playground/crm`, `/playground/projects`, and `/playground/admin` only when those modules are enabled.
+- Validate `/crm`, `/playground/projects`, and `/playground/admin` only when those modules are enabled.
 
 ## Change brand identity
 
 Goal: update the starter to the real client name and support details.
 
 - Edit `config/brand.ts`.
+- Edit `app/globals.css` when palette or theme token mapping needs to change.
 - Move route-specific presentation into `components/` when the home or preview surfaces need app-owned UI.
 - Check `config/client.ts` or `config/bootstrap.ts` if starter copy still references old defaults.
 - Validate the home page and `/preview/app-shell` after the change.
@@ -28,7 +30,7 @@ Goal: move from validation surfaces to product-owned pages.
 
 - Build the real routes in `app/` first.
 - Keep reusable route UI in `components/` so the app follows the expected Next.js folder split.
-- Update `config/shell.ts` if navigation or toolbar behavior changes.
+- Update `config/shell.overrides.ts` if navigation or toolbar behavior changes.
 - Remove `/bootstrap`, `/preview/app-shell`, or `/playground/*` only after links and config references are cleaned up.
 
 ## Make a module-aware change

package/template/base/public/brand/logo-dark.svg

@@ -1,7 +1,7 @@
 <svg width="176" height="44" viewBox="0 0 176 44" fill="none" xmlns="http://www.w3.org/2000/svg">
   <rect width="44" height="44" rx="12" fill="#F5F4EC"/>
-  <path d="M12 30V14H21.72C25.24 14 27.68 16.08 27.68 19.24C27.68 21.78 26.22 23.63 23.99 24.32L29.3 30H24.9L20.15 24.86H15.8V30H12Z" fill="#102015"/>
-  <circle cx="32.5" cy="12.5" r="3.5" fill="#2C8A53"/>
+  <path d="M12 32V12H22.2C26.18 12 28.52 13.94 28.52 17.06C28.52 19.04 27.56 20.48 25.86 21.22C28.08 21.88 29.4 23.54 29.4 25.94C29.4 29.7 26.68 32 22.22 32H12ZM16.42 20.04H21.48C23.1 20.04 24.02 19.24 24.02 17.86C24.02 16.46 23.1 15.68 21.48 15.68H16.42V20.04ZM16.42 28.28H21.96C23.82 28.28 24.86 27.42 24.86 25.86C24.86 24.32 23.82 23.46 21.96 23.46H16.42V28.28Z" fill="#102015"/>
+  <path d="M30.2 12H34.58L36.72 23.86L39.32 12H43.1L39 32H34.88L32.38 19.64L29.9 32H25.82L25.1 28.56H29.1L30.2 12Z" fill="#2C8A53"/>
   <text x="58" y="19" fill="#F5F4EC" font-family="Georgia, serif" font-size="11" letter-spacing="2">BRIGHTWEB</text>
   <text x="58" y="33" fill="#C8D0C9" font-family="'IBM Plex Sans', sans-serif" font-size="15">starter client</text>
 </svg>

package/template/base/public/brand/logo-light.svg

@@ -1,7 +1,7 @@
 <svg width="176" height="44" viewBox="0 0 176 44" fill="none" xmlns="http://www.w3.org/2000/svg">
   <rect width="44" height="44" rx="12" fill="#13251A"/>
-  <path d="M12 30V14H21.72C25.24 14 27.68 16.08 27.68 19.24C27.68 21.78 26.22 23.63 23.99 24.32L29.3 30H24.9L20.15 24.86H15.8V30H12Z" fill="#F5F4EC"/>
-  <circle cx="32.5" cy="12.5" r="3.5" fill="#71C48B"/>
+  <path d="M12 32V12H22.2C26.18 12 28.52 13.94 28.52 17.06C28.52 19.04 27.56 20.48 25.86 21.22C28.08 21.88 29.4 23.54 29.4 25.94C29.4 29.7 26.68 32 22.22 32H12ZM16.42 20.04H21.48C23.1 20.04 24.02 19.24 24.02 17.86C24.02 16.46 23.1 15.68 21.48 15.68H16.42V20.04ZM16.42 28.28H21.96C23.82 28.28 24.86 27.42 24.86 25.86C24.86 24.32 23.82 23.46 21.96 23.46H16.42V28.28Z" fill="#F5F4EC"/>
+  <path d="M30.2 12H34.58L36.72 23.86L39.32 12H43.1L39 32H34.88L32.38 19.64L29.9 32H25.82L25.1 28.56H29.1L30.2 12Z" fill="#71C48B"/>
   <text x="58" y="19" fill="#13251A" font-family="Georgia, serif" font-size="11" letter-spacing="2">BRIGHTWEB</text>
   <text x="58" y="33" fill="#516252" font-family="'IBM Plex Sans', sans-serif" font-size="15">starter client</text>
 </svg>