create-bw-app 0.8.0 → 0.9.1

package/README.md

@@ -2,6 +2,8 @@
 
 Scaffold a new BrightWeb app from either the `platform` or `site` starter.
 
+The CLI can also update an existing generated platform app in place.
+
 ## Workspace usage
 
 From the BrightWeb platform repo root:
@@ -21,9 +23,29 @@ Once this package is published to npm:
 ```bash
 pnpm dlx create-bw-app
 pnpm dlx create-bw-app --template site
+pnpm dlx create-bw-app update
 npm create bw-app@latest
 ```
 
+## Update existing apps
+
+Run the updater from an existing generated app directory, or point it at one with `--target-dir`:
+
+```bash
+pnpm dlx create-bw-app update
+pnpm dlx create-bw-app update --dry-run
+pnpm dlx create-bw-app update --refresh-starters
+pnpm dlx create-bw-app update --target-dir ./apps/client-portal
+```
+
+Current updater behavior:
+
+- updates installed `@brightweblabs/*` packages only
+- re-syncs managed BrightWeb config files such as `next.config.ts`, `config/modules.ts`, and `config/shell.ts`
+- reports missing or drifted starter files 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
+
 ## Template behavior
 
 - prompts for app type: `platform` or `site`
@@ -34,7 +56,7 @@ npm create bw-app@latest
 - platform apps include BrightWeb auth, shell wiring, and optional module starter surfaces
 - site apps include Next.js, Tailwind CSS v4, and local component primitives
 - writes `package.json`, `next.config.ts`, `.gitignore`, and `README.md` for both templates
-- platform apps also write `.env.example`, generated config files, and module feature flags
+- platform apps also write `.env.local`, `AGENTS.md`, `docs/ai/README.md`, and generated config files for brand and module state
 - supports repo-local `workspace:*` wiring and future published dependency wiring
 
 ## Workspace mode extras

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-bw-app",
   "private": false,
-  "version": "0.8.0",
+  "version": "0.9.1",
   "type": "module",
   "bin": "bin/create-bw-app.mjs",
   "files": [

package/src/cli.mjs

@@ -1,5 +1,6 @@
 import { HELP_TEXT } from "./constants.mjs";
 import { createBrightwebClientApp } from "./generator.mjs";
+import { updateBrightwebApp } from "./update.mjs";
 
 function toCamelCase(flagName) {
   return flagName.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
@@ -56,7 +57,8 @@ function parseArgv(argv) {
 }
 
 export async function runCreateBwAppCli(argv = process.argv.slice(2), runtimeOptions = {}) {
-  const argvOptions = parseArgv(argv);
+  const isUpdateCommand = argv[0] === "update";
+  const argvOptions = parseArgv(isUpdateCommand ? argv.slice(1) : argv);
 
   if (argvOptions.help) {
     process.stdout.write(`${HELP_TEXT}\n`);
@@ -64,6 +66,11 @@ export async function runCreateBwAppCli(argv = process.argv.slice(2), runtimeOpt
   }
 
   try {
+    if (isUpdateCommand) {
+      await updateBrightwebApp(argvOptions, runtimeOptions);
+      return;
+    }
+
     await createBrightwebClientApp(argvOptions, runtimeOptions);
   } catch (error) {
     const message = error instanceof Error ? error.message : "Unknown error";

package/src/constants.mjs

@@ -20,21 +20,18 @@ export const SELECTABLE_MODULES = [
     label: "CRM",
     packageName: "@brightweblabs/module-crm",
     templateFolder: "crm",
-    envKey: "NEXT_PUBLIC_ENABLE_CRM",
   },
   {
     key: "projects",
     label: "Projects",
     packageName: "@brightweblabs/module-projects",
     templateFolder: "projects",
-    envKey: "NEXT_PUBLIC_ENABLE_PROJECTS",
   },
   {
     key: "admin",
     label: "Admin",
     packageName: "@brightweblabs/module-admin",
     templateFolder: "admin",
-    envKey: "NEXT_PUBLIC_ENABLE_ADMIN",
   },
 ];
 
@@ -45,6 +42,29 @@ export const CORE_PACKAGES = [
   "@brightweblabs/ui",
 ];
 
+export const BRIGHTWEB_PACKAGE_NAMES = [
+  ...CORE_PACKAGES,
+  ...SELECTABLE_MODULES.map((moduleDefinition) => moduleDefinition.packageName),
+];
+
+export const MODULE_STARTER_FILES = {
+  admin: [
+    "app/api/admin/users/route.ts",
+    "app/api/admin/users/roles/route.ts",
+    "app/playground/admin/page.tsx",
+  ],
+  crm: [
+    "app/api/crm/contacts/route.ts",
+    "app/api/crm/organizations/route.ts",
+    "app/api/crm/owners/route.ts",
+    "app/api/crm/stats/route.ts",
+    "app/playground/crm/page.tsx",
+  ],
+  projects: [
+    "app/playground/projects/page.tsx",
+  ],
+};
+
 export const APP_DEPENDENCY_DEFAULTS = {
   "@brightweblabs/app-shell": "^0.1.1",
   "@brightweblabs/core-auth": "^0.1.1",
@@ -96,8 +116,9 @@ export const DEFAULTS = {
 export const HELP_TEXT = `
 Usage:
   create-bw-app [options]
+  create-bw-app update [options]
 
-Options:
+Scaffold options:
   --template <platform|site>    Scaffold a platform app or a standalone site
   --name, --slug <name>          Project name and default directory name
   --modules <list>               Comma-separated modules: crm,projects,admin
@@ -110,4 +131,12 @@ Options:
   --yes                          Accept defaults for any missing optional prompt
   --dry-run                      Print planned actions without writing files
   --help                         Show this help message
+
+Update options:
+  --target-dir <path>            Existing app directory to update (defaults to cwd)
+  --workspace-root <path>        BrightWeb workspace root for workspace:* apps
+  --package-manager <name>       Override package manager: pnpm, npm, yarn, or bun
+  --install                      Run install after writing package changes
+  --refresh-starters             Rewrite starter route files from the latest template
+  --dry-run                      Print the update plan without writing files
 `.trim();

package/src/generator.mjs

@@ -16,8 +16,8 @@ import {
   TEMPLATE_OPTIONS,
 } from "./constants.mjs";
 
-const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const TEMPLATE_ROOT = path.join(PACKAGE_ROOT, "template");
+export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+export const TEMPLATE_ROOT = path.join(PACKAGE_ROOT, "template");
 const TEMPLATE_KEY_SET = new Set(TEMPLATE_OPTIONS.map((templateOption) => templateOption.key));
 const DEFAULT_DB_MODULE_REGISTRY = {
   modules: {
@@ -77,7 +77,7 @@ function parseTemplateInput(rawValue) {
   throw new Error(`Unknown template: ${rawValue}`);
 }
 
-function detectPackageManager(explicitManager) {
+export function detectPackageManager(explicitManager) {
   if (explicitManager) return explicitManager;
 
   const userAgent = process.env.npm_config_user_agent || "";
@@ -88,13 +88,13 @@ function detectPackageManager(explicitManager) {
   return "pnpm";
 }
 
-function sortObjectKeys(inputObject) {
+export function sortObjectKeys(inputObject) {
   return Object.fromEntries(
     Object.entries(inputObject).sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey)),
   );
 }
 
-async function pathExists(targetPath) {
+export async function pathExists(targetPath) {
   try {
     await fs.access(targetPath);
     return true;
@@ -103,7 +103,7 @@ async function pathExists(targetPath) {
   }
 }
 
-async function readJsonIfPresent(filePath) {
+export async function readJsonIfPresent(filePath) {
   if (!(await pathExists(filePath))) {
     return null;
   }
@@ -111,7 +111,7 @@ async function readJsonIfPresent(filePath) {
   return JSON.parse(await fs.readFile(filePath, "utf8"));
 }
 
-async function getDbModuleRegistry(workspaceRoot) {
+export async function getDbModuleRegistry(workspaceRoot) {
   if (!workspaceRoot) {
     return DEFAULT_DB_MODULE_REGISTRY;
   }
@@ -171,7 +171,7 @@ function getModuleLabel(moduleKey) {
   return titleizeSlug(moduleKey);
 }
 
-function createDbInstallPlan({ selectedModules, workspaceMode, registry }) {
+export function createDbInstallPlan({ selectedModules, workspaceMode, registry }) {
   if (!workspaceMode) {
     return {
       selectedLabels: getSelectedModuleLabels(selectedModules),
@@ -218,7 +218,7 @@ function createDbInstallPlan({ selectedModules, workspaceMode, registry }) {
   };
 }
 
-async function getVersionMap(workspaceRoot) {
+export async function getVersionMap(workspaceRoot) {
   const versionMap = {
     ...APP_DEPENDENCY_DEFAULTS,
     ...APP_DEV_DEPENDENCY_DEFAULTS,
@@ -256,13 +256,6 @@ async function getVersionMap(workspaceRoot) {
   return versionMap;
 }
 
-function createModuleFlags(selectedModules) {
-  const selected = new Set(selectedModules);
-  return Object.fromEntries(
-    SELECTABLE_MODULES.map((moduleDefinition) => [moduleDefinition.key, selected.has(moduleDefinition.key)]),
-  );
-}
-
 function createDerivedBrandValues(slug) {
   const projectName = titleizeSlug(slug);
 
@@ -276,7 +269,94 @@ function createDerivedBrandValues(slug) {
   };
 }
 
-function createEnvFileContent({ slug, brandValues, moduleFlags }) {
+function createPlatformBrandConfigFile({ slug, brandValues }) {
+  return [
+    "export type StarterBrandConfig = {",
+    "  companyName: string;",
+    "  productName: string;",
+    "  slug: string;",
+    "  tagline: string;",
+    "  contactEmail: string;",
+    "  supportEmail: string;",
+    "  primaryHex: string;",
+    "};",
+    "",
+    "export const starterBrandConfig: StarterBrandConfig = {",
+    `  companyName: ${JSON.stringify(brandValues.companyName)},`,
+    `  productName: ${JSON.stringify(brandValues.productName)},`,
+    `  slug: ${JSON.stringify(slug)},`,
+    `  tagline: ${JSON.stringify(brandValues.tagline)},`,
+    `  contactEmail: ${JSON.stringify(brandValues.contactEmail)},`,
+    `  supportEmail: ${JSON.stringify(brandValues.supportEmail)},`,
+    `  primaryHex: ${JSON.stringify(brandValues.primaryHex)},`,
+    "};",
+    "",
+  ].join("\n");
+}
+
+export function createPlatformModulesConfigFile(selectedModules) {
+  const selected = new Set(selectedModules);
+
+  return [
+    'export type StarterModuleKey = "core-auth" | "crm" | "projects" | "admin";',
+    "",
+    "export type StarterModuleConfig = {",
+    "  key: StarterModuleKey;",
+    "  label: string;",
+    "  description: string;",
+    "  enabled: boolean;",
+    "  packageName: string;",
+    "  playgroundHref?: string;",
+    '  placement: "core" | "primary" | "admin";',
+    "};",
+    "",
+    "export const starterModuleConfig: StarterModuleConfig[] = [",
+    "  {",
+    '    key: "core-auth",',
+    '    label: "Core Auth",',
+    '    description: "Login, reset-password, callback URLs, and shared auth validation utilities.",',
+    "    enabled: true,",
+    '    packageName: "@brightweblabs/core-auth",',
+    '    playgroundHref: "/playground/auth",',
+    '    placement: "core",',
+    "  },",
+    "  {",
+    '    key: "crm",',
+    '    label: "CRM",',
+    '    description: "Contacts, marketing audience, and CRM server/data layer.",',
+    `    enabled: ${String(selected.has("crm"))},`,
+    '    packageName: "@brightweblabs/module-crm",',
+    '    playgroundHref: "/playground/crm",',
+    '    placement: "primary",',
+    "  },",
+    "  {",
+    '    key: "projects",',
+    '    label: "Projects",',
+    '    description: "Project portfolio, detail routes, and work-management server logic.",',
+    `    enabled: ${String(selected.has("projects"))},`,
+    '    packageName: "@brightweblabs/module-projects",',
+    '    playgroundHref: "/playground/projects",',
+    '    placement: "primary",',
+    "  },",
+    "  {",
+    '    key: "admin",',
+    '    label: "Admin",',
+    '    description: "User role governance, admin tools, and access-control surfaces.",',
+    `    enabled: ${String(selected.has("admin"))},`,
+    '    packageName: "@brightweblabs/module-admin",',
+    '    playgroundHref: "/playground/admin",',
+    '    placement: "admin",',
+    "  },",
+    "];",
+    "",
+    "export function getEnabledStarterModules() {",
+    "  return starterModuleConfig.filter((moduleConfig) => moduleConfig.enabled);",
+    "}",
+    "",
+  ].join("\n");
+}
+
+function createEnvFileContent() {
   return [
     "NEXT_PUBLIC_APP_URL=http://localhost:3000",
     "NEXT_PUBLIC_SUPABASE_URL=",
@@ -284,18 +364,6 @@ function createEnvFileContent({ slug, brandValues, moduleFlags }) {
     "SUPABASE_SERVICE_ROLE_KEY=",
     "RESEND_API_KEY=",
     "",
-    `NEXT_PUBLIC_CLIENT_COMPANY_NAME=${brandValues.companyName}`,
-    `NEXT_PUBLIC_CLIENT_PRODUCT_NAME=${brandValues.productName}`,
-    `NEXT_PUBLIC_CLIENT_SLUG=${slug}`,
-    `NEXT_PUBLIC_CLIENT_TAGLINE=${brandValues.tagline}`,
-    `NEXT_PUBLIC_CLIENT_CONTACT_EMAIL=${brandValues.contactEmail}`,
-    `NEXT_PUBLIC_CLIENT_SUPPORT_EMAIL=${brandValues.supportEmail}`,
-    `NEXT_PUBLIC_CLIENT_PRIMARY_HEX=${brandValues.primaryHex}`,
-    "",
-    `NEXT_PUBLIC_ENABLE_CRM=${String(moduleFlags.crm)}`,
-    `NEXT_PUBLIC_ENABLE_PROJECTS=${String(moduleFlags.projects)}`,
-    `NEXT_PUBLIC_ENABLE_ADMIN=${String(moduleFlags.admin)}`,
-    "",
   ].join("\n");
 }
 
@@ -333,9 +401,8 @@ function createGitignore() {
     "yarn-error.log*",
     ".pnpm-debug.log*",
     "",
-    "# env files (can opt-in for committing if needed)",
+    "# env files",
     ".env*",
-    "!.env.example",
     "",
     "# vercel",
     ".vercel",
@@ -363,12 +430,12 @@ function createPlatformReadme({
 
   const localSteps = workspaceMode
     ? [
-        "1. Review `.env.example`, then copy it to `.env.local` and fill in real service credentials.",
+        "1. Review `.env.local` and fill in real service credentials.",
         "2. Run `pnpm install` from the BrightWeb workspace root.",
         `3. Run \`pnpm --filter ${slug} dev\`.`,
       ]
     : [
-        "1. Review `.env.example`, then copy it to `.env.local` and fill in real service credentials.",
+        "1. Review `.env.local` and fill in real service credentials.",
         `2. Run \`${packageManager} install\`.`,
         `3. Run \`${packageManager} dev\`.`,
       ];
@@ -448,7 +515,7 @@ function createSiteReadme({ slug, workspaceMode, packageManager }) {
   ].join("\n");
 }
 
-function createPackageJson({
+export function createPackageJson({
   slug,
   dependencyMode,
   selectedModules,
@@ -528,7 +595,7 @@ function createPackageJson({
   };
 }
 
-function createNextConfig({ template, selectedModules }) {
+export function createNextConfig({ template, selectedModules }) {
   if (template === "site") {
     return [
       'import type { NextConfig } from "next";',
@@ -562,7 +629,7 @@ function createNextConfig({ template, selectedModules }) {
   ].join("\n");
 }
 
-function createShellConfig(selectedModules) {
+export function createShellConfig(selectedModules) {
   const importLines = [];
   const registrationLines = [];
 
@@ -678,7 +745,7 @@ async function copyDirectory(sourceDir, targetDir) {
   await fs.cp(sourceDir, targetDir, { recursive: true });
 }
 
-async function ensureDirectory(targetDir) {
+export async function ensureDirectory(targetDir) {
   await fs.mkdir(targetDir, { recursive: true });
 }
 
@@ -726,7 +793,7 @@ async function writeWorkspaceClientStack(workspaceRoot, slug, selectedModules) {
   );
 }
 
-async function runInstall(command, cwd) {
+export async function runInstall(command, cwd) {
   return new Promise((resolve, reject) => {
     const child = spawn(command, ["install"], {
       cwd,
@@ -871,7 +938,6 @@ async function scaffoldPlatformProject({
   answers,
   dbInstallPlan,
 }) {
-  const moduleFlags = createModuleFlags(selectedModules);
   const brandValues = createDerivedBrandValues(answers.slug);
   const baseTemplateDir = path.join(TEMPLATE_ROOT, "base");
 
@@ -899,11 +965,16 @@ async function scaffoldPlatformProject({
     )}\n`,
   );
   await fs.writeFile(path.join(targetDir, "next.config.ts"), createNextConfig({ template: "platform", selectedModules }));
+  await fs.writeFile(
+    path.join(targetDir, "config", "brand.ts"),
+    createPlatformBrandConfigFile({ slug: answers.slug, brandValues }),
+  );
+  await fs.writeFile(path.join(targetDir, "config", "modules.ts"), createPlatformModulesConfigFile(selectedModules));
   await fs.writeFile(path.join(targetDir, "config", "shell.ts"), createShellConfig(selectedModules));
 
-  const envFileContent = createEnvFileContent({ slug: answers.slug, brandValues, moduleFlags });
+  const envFileContent = createEnvFileContent();
 
-  await fs.writeFile(path.join(targetDir, ".env.example"), envFileContent);
+  await fs.writeFile(path.join(targetDir, ".env.local"), envFileContent);
   await fs.writeFile(path.join(targetDir, ".gitignore"), createGitignore());
   await fs.writeFile(
     path.join(targetDir, "README.md"),
@@ -1069,7 +1140,8 @@ export async function createBrightwebClientApp(argvOptions, runtimeOptions = {})
 
   if (install) {
     const installCwd = workspaceMode ? workspaceRoot : targetDir;
-    await runInstall(packageManager, installCwd);
+    const installRunner = runtimeOptions.installRunner || runInstall;
+    await installRunner(packageManager, installCwd);
   }
 
   printCompletionMessage({

package/src/update.mjs

@@ -0,0 +1,481 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { stdout as output } from "node:process";
+import {
+  BRIGHTWEB_PACKAGE_NAMES,
+  CLI_DISPLAY_NAME,
+  MODULE_STARTER_FILES,
+  SELECTABLE_MODULES,
+} from "./constants.mjs";
+import {
+  TEMPLATE_ROOT,
+  createDbInstallPlan,
+  createNextConfig,
+  createPackageJson,
+  createPlatformModulesConfigFile,
+  createShellConfig,
+  detectPackageManager,
+  getDbModuleRegistry,
+  getVersionMap,
+  pathExists,
+  readJsonIfPresent,
+  runInstall,
+} from "./generator.mjs";
+
+const MANAGED_PLATFORM_FILES = [
+  "next.config.ts",
+  path.join("config", "modules.ts"),
+  path.join("config", "shell.ts"),
+];
+
+function resolveUpdateTargetDirectory(runtimeOptions, argvOptions) {
+  if (runtimeOptions.targetDir || argvOptions.targetDir) {
+    return path.resolve(runtimeOptions.targetDir || argvOptions.targetDir);
+  }
+
+  return process.cwd();
+}
+
+async function findWorkspaceRoot(startDir) {
+  let currentDir = path.resolve(startDir);
+
+  while (true) {
+    const registryPath = path.join(currentDir, "supabase", "module-registry.json");
+    const cliPackagePath = path.join(currentDir, "packages", "create-bw-app", "package.json");
+
+    if ((await pathExists(registryPath)) && (await pathExists(cliPackagePath))) {
+      return currentDir;
+    }
+
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) {
+      return null;
+    }
+
+    currentDir = parentDir;
+  }
+}
+
+function collectInstalledBrightwebPackages(manifest) {
+  const installed = new Map();
+
+  for (const section of ["dependencies", "devDependencies"]) {
+    const sectionManifest = manifest[section] || {};
+    for (const [packageName, version] of Object.entries(sectionManifest)) {
+      if (!packageName.startsWith("@brightweblabs/")) continue;
+      installed.set(packageName, { section, version });
+    }
+  }
+
+  return installed;
+}
+
+function parseConfiguredModules(content) {
+  const enabledModules = [];
+
+  for (const moduleDefinition of SELECTABLE_MODULES) {
+    const matcher = new RegExp(`key:\\s*"${moduleDefinition.key}"[\\s\\S]*?enabled:\\s*(true|false)`);
+    const match = content.match(matcher);
+    if (match?.[1] === "true") {
+      enabledModules.push(moduleDefinition.key);
+    }
+  }
+
+  return enabledModules;
+}
+
+async function detectTemplate(targetDir, installedBrightwebPackages) {
+  if (await pathExists(path.join(targetDir, "config", "modules.ts"))) {
+    return "platform";
+  }
+
+  return installedBrightwebPackages.size > 0 ? "platform" : "site";
+}
+
+function detectDependencyMode(installedBrightwebPackages) {
+  for (const { version } of installedBrightwebPackages.values()) {
+    if (typeof version === "string" && version.startsWith("workspace:")) {
+      return "workspace";
+    }
+  }
+
+  return "published";
+}
+
+function detectInstalledModules(installedBrightwebPackages) {
+  return SELECTABLE_MODULES
+    .filter((moduleDefinition) => installedBrightwebPackages.has(moduleDefinition.packageName))
+    .map((moduleDefinition) => moduleDefinition.key);
+}
+
+function getCanonicalBrightwebVersions({ manifest, template, dependencyMode, installedModules, versionMap }) {
+  const canonicalManifest = createPackageJson({
+    slug: manifest.name || path.basename(process.cwd()),
+    dependencyMode,
+    selectedModules: installedModules,
+    versionMap,
+    template,
+  });
+
+  const versions = {};
+
+  for (const section of ["dependencies", "devDependencies"]) {
+    for (const [packageName, version] of Object.entries(canonicalManifest[section] || {})) {
+      if (BRIGHTWEB_PACKAGE_NAMES.includes(packageName)) {
+        versions[packageName] = version;
+      }
+    }
+  }
+
+  return versions;
+}
+
+function mergeManagedPackageUpdates({ manifest, targetVersions, installedBrightwebPackages }) {
+  let changed = false;
+  const nextManifest = {
+    ...manifest,
+    dependencies: manifest.dependencies ? { ...manifest.dependencies } : undefined,
+    devDependencies: manifest.devDependencies ? { ...manifest.devDependencies } : undefined,
+  };
+  const packageUpdates = [];
+
+  for (const [packageName, details] of installedBrightwebPackages.entries()) {
+    if (!BRIGHTWEB_PACKAGE_NAMES.includes(packageName)) continue;
+    const targetVersion = targetVersions[packageName];
+    if (!targetVersion) continue;
+
+    const currentSection = nextManifest[details.section] || {};
+    if (currentSection[packageName] === targetVersion) continue;
+
+    currentSection[packageName] = targetVersion;
+    nextManifest[details.section] = currentSection;
+    packageUpdates.push({
+      packageName,
+      from: details.version,
+      to: targetVersion,
+      section: details.section,
+    });
+    changed = true;
+  }
+
+  return {
+    changed,
+    packageUpdates,
+    content: `${JSON.stringify(nextManifest, null, 2)}\n`,
+  };
+}
+
+async function getStarterFileStatus(targetDir, installedModules) {
+  const starterFiles = [];
+
+  for (const moduleKey of installedModules) {
+    const templateFolder = SELECTABLE_MODULES.find((moduleDefinition) => moduleDefinition.key === moduleKey)?.templateFolder;
+    if (!templateFolder) continue;
+
+    for (const relativePath of MODULE_STARTER_FILES[moduleKey] || []) {
+      const sourcePath = path.join(TEMPLATE_ROOT, "modules", templateFolder, relativePath);
+      const targetPath = path.join(targetDir, relativePath);
+      const exists = await pathExists(targetPath);
+
+      if (!exists) {
+        starterFiles.push({
+          moduleKey,
+          relativePath,
+          sourcePath,
+          targetPath,
+          status: "missing",
+        });
+        continue;
+      }
+
+      const [sourceContent, targetContent] = await Promise.all([
+        fs.readFile(sourcePath, "utf8"),
+        fs.readFile(targetPath, "utf8"),
+      ]);
+
+      starterFiles.push({
+        moduleKey,
+        relativePath,
+        sourcePath,
+        targetPath,
+        status: sourceContent === targetContent ? "current" : "drifted",
+      });
+    }
+  }
+
+  return starterFiles;
+}
+
+async function detectModulesConfigMismatch(targetDir, installedModules) {
+  const modulesConfigPath = path.join(targetDir, "config", "modules.ts");
+  if (!(await pathExists(modulesConfigPath))) {
+    return null;
+  }
+
+  const content = await fs.readFile(modulesConfigPath, "utf8");
+  const configuredModules = parseConfiguredModules(content);
+  const installed = new Set(installedModules);
+  const configured = new Set(configuredModules);
+
+  const mismatch = installedModules.length !== configuredModules.length
+    || installedModules.some((moduleKey) => !configured.has(moduleKey))
+    || configuredModules.some((moduleKey) => !installed.has(moduleKey));
+
+  if (!mismatch) {
+    return null;
+  }
+
+  return {
+    installedModules,
+    configuredModules,
+  };
+}
+
+function renderInstallCommand({ packageManager, dependencyMode, targetDir, workspaceRoot }) {
+  if (dependencyMode === "workspace" && workspaceRoot) {
+    return `cd ${workspaceRoot} && ${packageManager} install`;
+  }
+
+  return `cd ${targetDir} && ${packageManager} install`;
+}
+
+function renderPlanSummary(plan, options = {}) {
+  const lines = [
+    `${CLI_DISPLAY_NAME} update`,
+    "",
+    `Detected app type: ${plan.template}`,
+    `Dependency mode: ${plan.dependencyMode}`,
+    `Installed BrightWeb packages: ${plan.installedBrightwebPackages.length > 0 ? plan.installedBrightwebPackages.join(", ") : "none"}`,
+    `Installed modules: ${plan.installedModules.length > 0 ? plan.installedModules.join(", ") : "none"}`,
+  ];
+
+  if (plan.modulesConfigMismatch) {
+    lines.push(
+      `Config mismatch: installed modules (${plan.modulesConfigMismatch.installedModules.join(", ") || "none"}) differ from config/modules.ts (${plan.modulesConfigMismatch.configuredModules.join(", ") || "none"}). Using installed packages as source of truth.`,
+    );
+  }
+
+  lines.push("");
+
+  if (plan.packageUpdates.length > 0) {
+    lines.push("Packages to update:");
+    for (const update of plan.packageUpdates) {
+      lines.push(`- ${update.packageName}: ${update.from} -> ${update.to}`);
+    }
+  } else {
+    lines.push("Packages to update: none");
+  }
+
+  lines.push("");
+
+  if (plan.configFilesToWrite.length > 0) {
+    lines.push("Config files to rewrite:");
+    for (const relativePath of plan.configFilesToWrite) {
+      lines.push(`- ${relativePath}`);
+    }
+  } else {
+    lines.push("Config files to rewrite: none");
+  }
+
+  lines.push("");
+
+  if (plan.starterFilesMissing.length > 0 || plan.starterFilesDrifted.length > 0) {
+    lines.push("Starter file status:");
+    for (const relativePath of plan.starterFilesMissing) {
+      lines.push(`- missing: ${relativePath}`);
+    }
+    for (const relativePath of plan.starterFilesDrifted) {
+      lines.push(`- drifted: ${relativePath}`);
+    }
+  } else {
+    lines.push("Starter file status: all current");
+  }
+
+  lines.push("");
+
+  if (plan.dbInstallPlan.resolvedOrder.length > 0) {
+    lines.push(`Resolved database stack: ${plan.dbInstallPlan.resolvedOrder.join(" -> ")}`);
+  }
+
+  if (plan.dbInstallPlan.notes.length > 0) {
+    lines.push("Database notes:");
+    for (const note of plan.dbInstallPlan.notes) {
+      lines.push(`- ${note}`);
+    }
+  }
+
+  if (options.installCommand) {
+    lines.push("", `Next install command: ${options.installCommand}`);
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+export async function buildBrightwebAppUpdatePlan(argvOptions = {}, runtimeOptions = {}) {
+  const targetDir = resolveUpdateTargetDirectory(runtimeOptions, argvOptions);
+  const packageJsonPath = path.join(targetDir, "package.json");
+  const manifest = await readJsonIfPresent(packageJsonPath);
+
+  if (!manifest) {
+    throw new Error(`Target directory does not contain package.json: ${targetDir}`);
+  }
+
+  const installedBrightwebPackagesMap = collectInstalledBrightwebPackages(manifest);
+  const template = await detectTemplate(targetDir, installedBrightwebPackagesMap);
+  const dependencyMode = detectDependencyMode(installedBrightwebPackagesMap);
+  const workspaceRoot = runtimeOptions.workspaceRoot
+    ? path.resolve(runtimeOptions.workspaceRoot)
+    : argvOptions.workspaceRoot
+      ? path.resolve(argvOptions.workspaceRoot)
+      : dependencyMode === "workspace"
+        ? await findWorkspaceRoot(targetDir)
+        : null;
+  const packageManager = detectPackageManager(argvOptions.packageManager || runtimeOptions.packageManager);
+  const installedModules = detectInstalledModules(installedBrightwebPackagesMap);
+  const versionMap = await getVersionMap(workspaceRoot);
+  const dbRegistry = await getDbModuleRegistry(workspaceRoot);
+  const dbInstallPlan = template === "platform"
+    ? createDbInstallPlan({
+      selectedModules: installedModules,
+      workspaceMode: true,
+      registry: dbRegistry,
+    })
+    : {
+      selectedLabels: [],
+      resolvedOrder: [],
+      notes: [],
+    };
+  const canonicalVersions = getCanonicalBrightwebVersions({
+    manifest,
+    template,
+    dependencyMode,
+    installedModules,
+    versionMap,
+  });
+  const packageJsonUpdate = mergeManagedPackageUpdates({
+    manifest,
+    targetVersions: canonicalVersions,
+    installedBrightwebPackages: installedBrightwebPackagesMap,
+  });
+
+  const fileWrites = [];
+  if (packageJsonUpdate.changed) {
+    fileWrites.push({
+      relativePath: "package.json",
+      targetPath: packageJsonPath,
+      content: packageJsonUpdate.content,
+      type: "config",
+    });
+  }
+
+  if (template === "platform") {
+    const canonicalConfigFiles = {
+      "next.config.ts": createNextConfig({ template: "platform", selectedModules: installedModules }),
+      [path.join("config", "modules.ts")]: createPlatformModulesConfigFile(installedModules),
+      [path.join("config", "shell.ts")]: createShellConfig(installedModules),
+    };
+
+    for (const relativePath of MANAGED_PLATFORM_FILES) {
+      const targetPath = path.join(targetDir, relativePath);
+      const currentContent = (await pathExists(targetPath)) ? await fs.readFile(targetPath, "utf8") : null;
+      const nextContent = canonicalConfigFiles[relativePath];
+
+      if (currentContent !== nextContent) {
+        fileWrites.push({
+          relativePath,
+          targetPath,
+          content: nextContent,
+          type: "config",
+        });
+      }
+    }
+  }
+
+  const starterFiles = template === "platform"
+    ? await getStarterFileStatus(targetDir, installedModules)
+    : [];
+  const starterFilesMissing = starterFiles.filter((entry) => entry.status === "missing");
+  const starterFilesDrifted = starterFiles.filter((entry) => entry.status === "drifted");
+
+  if (argvOptions.refreshStarters) {
+    for (const entry of starterFiles.filter((candidate) => candidate.status !== "current")) {
+      fileWrites.push({
+        relativePath: entry.relativePath,
+        targetPath: entry.targetPath,
+        content: await fs.readFile(entry.sourcePath, "utf8"),
+        type: "starter",
+      });
+    }
+  }
+
+  const modulesConfigMismatch = template === "platform"
+    ? await detectModulesConfigMismatch(targetDir, installedModules)
+    : null;
+
+  return {
+    targetDir,
+    workspaceRoot,
+    template,
+    dependencyMode,
+    packageManager,
+    manifest,
+    installedModules,
+    installedBrightwebPackages: Array.from(installedBrightwebPackagesMap.keys()).sort(),
+    packageUpdates: packageJsonUpdate.packageUpdates,
+    configFilesToWrite: fileWrites.filter((entry) => entry.type === "config").map((entry) => entry.relativePath),
+    starterFilesMissing: starterFilesMissing.map((entry) => entry.relativePath),
+    starterFilesDrifted: starterFilesDrifted.map((entry) => entry.relativePath),
+    starterFilesToRefresh: fileWrites.filter((entry) => entry.type === "starter").map((entry) => entry.relativePath),
+    dbInstallPlan,
+    modulesConfigMismatch,
+    fileWrites,
+  };
+}
+
+export async function updateBrightwebApp(argvOptions = {}, runtimeOptions = {}) {
+  const plan = await buildBrightwebAppUpdatePlan(argvOptions, runtimeOptions);
+  const installCommand = renderInstallCommand({
+    packageManager: plan.packageManager,
+    dependencyMode: plan.dependencyMode,
+    targetDir: plan.targetDir,
+    workspaceRoot: plan.workspaceRoot,
+  });
+
+  output.write(renderPlanSummary(plan, { installCommand }));
+
+  if (argvOptions.dryRun) {
+    return {
+      dryRun: true,
+      plan,
+      installCommand,
+    };
+  }
+
+  for (const fileWrite of plan.fileWrites) {
+    await fs.mkdir(path.dirname(fileWrite.targetPath), { recursive: true });
+    await fs.writeFile(fileWrite.targetPath, fileWrite.content, "utf8");
+  }
+
+  const packageJsonChanged = plan.fileWrites.some((entry) => entry.relativePath === "package.json");
+  if (argvOptions.install && packageJsonChanged) {
+    const installRunner = runtimeOptions.installRunner || runInstall;
+    const installCwd = plan.dependencyMode === "workspace" && plan.workspaceRoot ? plan.workspaceRoot : plan.targetDir;
+    await installRunner(plan.packageManager, installCwd);
+  }
+
+  if (!argvOptions.install && packageJsonChanged) {
+    output.write(`Run \`${installCommand}\` to install updated package versions.\n`);
+  }
+
+  if (plan.fileWrites.length === 0) {
+    output.write("No managed changes were required.\n");
+  } else {
+    output.write(`Applied ${plan.fileWrites.length} managed change${plan.fileWrites.length === 1 ? "" : "s"}.\n`);
+  }
+
+  return {
+    dryRun: false,
+    plan,
+    installCommand,
+  };
+}

package/template/base/AGENTS.md

@@ -0,0 +1,26 @@
+# AGENTS.md
+
+This generated project is a BrightWeb platform starter. Use this file as the local entrypoint for AI agents working inside the app.
+
+## Start here
+
+- `README.md`: local setup commands and starter routes.
+- `docs/ai/README.md`: app-specific routing guide for agents.
+- `config/brand.ts`: client identity, naming, and contact defaults.
+- `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.
+
+## 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.
+- 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.
+
+## 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.

package/template/base/app/page.tsx

@@ -115,7 +115,7 @@ export default function HomePage() {
                 <li>`config/brand.ts` for client identity and contact details.</li>
                 <li>`config/modules.ts` for enabled platform modules.</li>
                 <li>`config/env.ts` for infra requirements and readiness checks.</li>
-                <li>`.env.example` for starter defaults; copy it to `.env.local` for per-client secrets and flags.</li>
+                <li>`.env.local` for per-client service credentials and local runtime overrides.</li>
               </ul>
             </div>
           </article>

package/template/base/config/bootstrap.ts

@@ -69,7 +69,7 @@ export function getStarterBootstrapChecklist() {
       {
         label: "Create per-client environment variables",
         done: config.envReadiness.allReady,
-        detail: "Copy `.env.example` to `.env.local` and fill the real values.",
+        detail: "Fill `.env.local` with the real service values for this client.",
       },
     ],
   };

package/template/base/config/brand.ts

@@ -9,13 +9,11 @@ export type StarterBrandConfig = {
 };
 
 export const starterBrandConfig: StarterBrandConfig = {
-  companyName: process.env.NEXT_PUBLIC_CLIENT_COMPANY_NAME?.trim() || "Starter Client",
-  productName: process.env.NEXT_PUBLIC_CLIENT_PRODUCT_NAME?.trim() || "Operations Platform",
-  slug: process.env.NEXT_PUBLIC_CLIENT_SLUG?.trim() || "starter-client",
-  tagline:
-    process.env.NEXT_PUBLIC_CLIENT_TAGLINE?.trim()
-    || "A configurable Brightweb starter app for shipping new client instances without rebuilding the platform.",
-  contactEmail: process.env.NEXT_PUBLIC_CLIENT_CONTACT_EMAIL?.trim() || "hello@example.com",
-  supportEmail: process.env.NEXT_PUBLIC_CLIENT_SUPPORT_EMAIL?.trim() || "support@example.com",
-  primaryHex: process.env.NEXT_PUBLIC_CLIENT_PRIMARY_HEX?.trim() || "#1f7a45",
+  companyName: "Starter Client",
+  productName: "Operations Platform",
+  slug: "starter-client",
+  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

@@ -10,14 +10,6 @@ export type StarterModuleConfig = {
   placement: "core" | "primary" | "admin";
 };
 
-function envFlag(value: string | undefined, defaultValue: boolean) {
-  if (typeof value !== "string") return defaultValue;
-  const normalized = value.trim().toLowerCase();
-  if (["1", "true", "yes", "on"].includes(normalized)) return true;
-  if (["0", "false", "no", "off"].includes(normalized)) return false;
-  return defaultValue;
-}
-
 export const starterModuleConfig: StarterModuleConfig[] = [
   {
     key: "core-auth",
@@ -32,7 +24,7 @@ export const starterModuleConfig: StarterModuleConfig[] = [
     key: "crm",
     label: "CRM",
     description: "Contacts, marketing audience, and CRM server/data layer.",
-    enabled: envFlag(process.env.NEXT_PUBLIC_ENABLE_CRM, true),
+    enabled: true,
     packageName: "@brightweblabs/module-crm",
     playgroundHref: "/playground/crm",
     placement: "primary",
@@ -41,7 +33,7 @@ export const starterModuleConfig: StarterModuleConfig[] = [
     key: "projects",
     label: "Projects",
     description: "Project portfolio, detail routes, and work-management server logic.",
-    enabled: envFlag(process.env.NEXT_PUBLIC_ENABLE_PROJECTS, true),
+    enabled: true,
     packageName: "@brightweblabs/module-projects",
     playgroundHref: "/playground/projects",
     placement: "primary",
@@ -50,7 +42,7 @@ export const starterModuleConfig: StarterModuleConfig[] = [
     key: "admin",
     label: "Admin",
     description: "User role governance, admin tools, and access-control surfaces.",
-    enabled: envFlag(process.env.NEXT_PUBLIC_ENABLE_ADMIN, true),
+    enabled: true,
     packageName: "@brightweblabs/module-admin",
     playgroundHref: "/playground/admin",
     placement: "admin",

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

@@ -0,0 +1,44 @@
+# Agent Guide
+
+This file is the local routing guide for AI agents working inside a generated BrightWeb platform app.
+
+It is intentionally app-scoped. It explains the generated project you are in, not the maintainer-only BrightWeb monorepo internals.
+
+## Project shape
+
+This app is a normal Next.js App Router project with BrightWeb runtime wiring layered on top.
+
+- `app/`: route tree, layouts, pages, starter previews, and playground routes.
+- `config/`: generated app configuration for brand, env readiness, enabled modules, bootstrap content, and shell registration.
+- `public/brand/`: starter logos used by the shell lockups.
+- `.env.local`: local service configuration for Supabase, Resend, and runtime URLs.
+
+## Fast routing map
+
+- `README.md`: first-run setup steps.
+- `config/brand.ts`: client name, product name, support inboxes, and brand color.
+- `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.
+- `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.
+- `app/playground/auth/page.tsx`: auth validation route.
+- `app/playground/*`: optional module playgrounds when those modules were selected at scaffold time.
+
+## Editing strategy
+
+- Change client identity first in `config/brand.ts`.
+- Check module presence in `config/modules.ts` before editing or creating module-specific routes.
+- Use `config/shell.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.
+
+## Validation checklist
+
+1. Confirm `.env.local` is populated with real values.
+2. Run the app locally.
+3. Validate `/`, `/bootstrap`, `/preview/app-shell`, and `/playground/auth`.
+4. Validate the playground route for each enabled optional module.
+5. If a starter route is removed, also remove any links or config references that still point to it.

package/template/modules/crm/app/api/crm/contacts/route.ts

@@ -0,0 +1,6 @@
+export const dynamic = "force-dynamic";
+
+export async function GET(request: Request) {
+  const { handleCrmContactsGetRequest } = await import("@brightweblabs/module-crm");
+  return handleCrmContactsGetRequest(request);
+}

package/template/modules/crm/app/api/crm/organizations/route.ts

@@ -0,0 +1,6 @@
+export const dynamic = "force-dynamic";
+
+export async function GET(request: Request) {
+  const { handleCrmOrganizationsGetRequest } = await import("@brightweblabs/module-crm");
+  return handleCrmOrganizationsGetRequest(request);
+}

package/template/modules/crm/app/api/crm/owners/route.ts

@@ -0,0 +1,6 @@
+export const dynamic = "force-dynamic";
+
+export async function GET(request: Request) {
+  const { handleCrmOwnersGetRequest } = await import("@brightweblabs/module-crm");
+  return handleCrmOwnersGetRequest(request);
+}

package/template/modules/crm/app/api/crm/stats/route.ts

@@ -0,0 +1,6 @@
+export const dynamic = "force-dynamic";
+
+export async function GET(request: Request) {
+  const { handleCrmStatsGetRequest } = await import("@brightweblabs/module-crm");
+  return handleCrmStatsGetRequest(request);
+}