create-bw-app 0.9.0 → 0.9.2

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,8 @@ 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.local`, `AGENTS.md`, `docs/ai/README.md`, and generated config files for brand and module state
+- 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
 - 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.9.0",
+  "version": "0.9.2",
   "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

@@ -42,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",
@@ -93,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
@@ -107,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,
@@ -294,7 +294,7 @@ function createPlatformBrandConfigFile({ slug, brandValues }) {
   ].join("\n");
 }
 
-function createPlatformModulesConfigFile(selectedModules) {
+export function createPlatformModulesConfigFile(selectedModules) {
   const selected = new Set(selectedModules);
 
   return [
@@ -414,6 +414,20 @@ function createGitignore() {
   ].join("\n");
 }
 
+function getPlatformStarterRoutes(selectedModules) {
+  return [
+    "/",
+    "/bootstrap",
+    "/preview/app-shell",
+    "/playground/auth",
+    ...selectedModules.map((moduleKey) => `/playground/${moduleKey}`),
+  ];
+}
+
+function getSiteStarterRoutes() {
+  return ["/"];
+}
+
 function createPlatformReadme({
   slug,
   selectedModules,
@@ -471,11 +485,14 @@ function createPlatformReadme({
       : []),
     "## Starter routes",
     "",
-    "- `/`",
-    "- `/bootstrap`",
-    "- `/preview/app-shell`",
-    "- `/playground/auth`",
-    ...selectedModules.map((moduleKey) => `- /playground/${moduleKey}`),
+    ...getPlatformStarterRoutes(selectedModules).map((route) => `- \`${route}\``),
+    "",
+    "## AI handoff",
+    "",
+    "- `AGENTS.md`",
+    "- `docs/ai/README.md`",
+    "- `docs/ai/examples.md`",
+    "- `docs/ai/app-context.json`",
     "",
   ].join("\n");
 }
@@ -508,14 +525,144 @@ function createSiteReadme({ slug, workspaceMode, packageManager }) {
     "",
     "## Starter surfaces",
     "",
-    "- `/`",
+    ...getSiteStarterRoutes().map((route) => `- \`${route}\``),
     "",
     "Edit `config/site.ts` to change the site name, copy, and public links.",
     "",
+    "## AI handoff",
+    "",
+    "- `AGENTS.md`",
+    "- `docs/ai/README.md`",
+    "- `docs/ai/examples.md`",
+    "- `docs/ai/app-context.json`",
+    "",
   ].join("\n");
 }
 
-function createPackageJson({
+export function createAppContextFile({
+  slug,
+  template,
+  selectedModules = [],
+  dbInstallPlan = { resolvedOrder: [] },
+}) {
+  if (template === "site") {
+    return `${JSON.stringify(
+      {
+        schemaVersion: 1,
+        template: "site",
+        app: {
+          slug,
+          name: titleizeSlug(slug),
+        },
+        docs: {
+          agentGuide: "AGENTS.md",
+          routingGuide: "docs/ai/README.md",
+          setupGuide: "README.md",
+          examples: "docs/ai/examples.md",
+        },
+        paths: {
+          readFirst: [
+            "AGENTS.md",
+            "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",
+          ],
+          packageOwned: [],
+        },
+        agentRules: {
+          editConfigBeforeCopyTweaks: true,
+          keepUiPrimitiveChangesLocal: true,
+          treatStarterHomeAsAppOwned: true,
+        },
+      },
+      null,
+      2,
+    )}\n`;
+  }
+
+  return `${JSON.stringify(
+    {
+      schemaVersion: 1,
+      template: "platform",
+      app: {
+        slug,
+        name: titleizeSlug(slug),
+      },
+      modules: {
+        enabled: selectedModules,
+        resolvedDatabaseStack: dbInstallPlan.resolvedOrder,
+      },
+      docs: {
+        agentGuide: "AGENTS.md",
+        routingGuide: "docs/ai/README.md",
+        setupGuide: "README.md",
+        examples: "docs/ai/examples.md",
+      },
+      paths: {
+        readFirst: [
+          "AGENTS.md",
+          "docs/ai/README.md",
+          "README.md",
+          "config/brand.ts",
+          "config/modules.ts",
+          "config/client.ts",
+          "config/bootstrap.ts",
+          "config/shell.ts",
+          ".env.local",
+        ],
+        appRoutesRoot: "app",
+        configRoot: "config",
+        brandAssetsRoot: "public/brand",
+      },
+      starterRoutes: getPlatformStarterRoutes(selectedModules),
+      ownership: {
+        appOwned: [
+          "app/**",
+          "config/**",
+          "docs/ai/**",
+          "public/brand/**",
+          "AGENTS.md",
+          "README.md",
+        ],
+        packageOwned: [
+          ...CORE_PACKAGES,
+          ...SELECTABLE_MODULES
+            .filter((moduleDefinition) => selectedModules.includes(moduleDefinition.key))
+            .map((moduleDefinition) => moduleDefinition.packageName),
+        ],
+      },
+      agentRules: {
+        checkModulesBeforeEditing: true,
+        preferAppLevelCompositionOverPackageForks: true,
+        treatStarterRoutesAsRemovable: true,
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+export function createPackageJson({
   slug,
   dependencyMode,
   selectedModules,
@@ -595,7 +742,7 @@ function createPackageJson({
   };
 }
 
-function createNextConfig({ template, selectedModules }) {
+export function createNextConfig({ template, selectedModules }) {
   if (template === "site") {
     return [
       'import type { NextConfig } from "next";',
@@ -629,7 +776,7 @@ function createNextConfig({ template, selectedModules }) {
   ].join("\n");
 }
 
-function createShellConfig(selectedModules) {
+export function createShellConfig(selectedModules) {
   const importLines = [];
   const registrationLines = [];
 
@@ -745,7 +892,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 });
 }
 
@@ -793,7 +940,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,
@@ -971,6 +1118,15 @@ async function scaffoldPlatformProject({
   );
   await fs.writeFile(path.join(targetDir, "config", "modules.ts"), createPlatformModulesConfigFile(selectedModules));
   await fs.writeFile(path.join(targetDir, "config", "shell.ts"), createShellConfig(selectedModules));
+  await fs.writeFile(
+    path.join(targetDir, "docs", "ai", "app-context.json"),
+    createAppContextFile({
+      slug: answers.slug,
+      template: "platform",
+      selectedModules,
+      dbInstallPlan,
+    }),
+  );
 
   const envFileContent = createEnvFileContent();
 
@@ -1007,6 +1163,7 @@ async function scaffoldSiteProject({
   await ensureDirectory(path.dirname(targetDir));
   await copyDirectory(baseTemplateDir, targetDir);
   await ensureDirectory(path.join(targetDir, "config"));
+  await ensureDirectory(path.join(targetDir, "docs", "ai"));
 
   await fs.writeFile(
     path.join(targetDir, "package.json"),
@@ -1025,6 +1182,13 @@ async function scaffoldSiteProject({
   await fs.writeFile(path.join(targetDir, "next.config.ts"), createNextConfig({ template: "site", selectedModules: [] }));
   await fs.writeFile(path.join(targetDir, ".gitignore"), createGitignore());
   await fs.writeFile(path.join(targetDir, "config", "site.ts"), createSiteConfigFile(answers.slug));
+  await fs.writeFile(
+    path.join(targetDir, "docs", "ai", "app-context.json"),
+    createAppContextFile({
+      slug: answers.slug,
+      template: "site",
+    }),
+  );
   await fs.writeFile(
     path.join(targetDir, "README.md"),
     createSiteReadme({
@@ -1140,7 +1304,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,515 @@
+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,
+  createAppContextFile,
+  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"),
+  path.join("docs", "ai", "app-context.json"),
+];
+
+const MANAGED_SITE_FILES = [
+  path.join("docs", "ai", "app-context.json"),
+];
+
+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: dependencyMode === "workspace",
+      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),
+      [path.join("docs", "ai", "app-context.json")]: createAppContextFile({
+        slug: manifest.name || path.basename(targetDir),
+        template: "platform",
+        selectedModules: installedModules,
+        dbInstallPlan,
+      }),
+    };
+
+    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",
+        });
+      }
+    }
+  } else {
+    const canonicalConfigFiles = {
+      [path.join("docs", "ai", "app-context.json")]: createAppContextFile({
+        slug: manifest.name || path.basename(targetDir),
+        template: "site",
+      }),
+    };
+
+    for (const relativePath of MANAGED_SITE_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

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

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

@@ -15,6 +15,8 @@ This app is a normal Next.js App Router project with BrightWeb runtime wiring la
 
 ## Fast routing map
 
+- `docs/ai/app-context.json`: machine-readable summary of this app's template, starter routes, and first-read files.
+- `docs/ai/examples.md`: common setup and customization workflows.
 - `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.

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

@@ -0,0 +1,38 @@
+# Agent Examples
+
+Use these workflows after reading `AGENTS.md`, `docs/ai/README.md`, and `docs/ai/app-context.json`.
+
+## First local setup
+
+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 `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.
+
+## Change brand identity
+
+Goal: update the starter to the real client name and support details.
+
+- Edit `config/brand.ts`.
+- 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.
+
+## Replace starter routes with product routes
+
+Goal: move from validation surfaces to product-owned pages.
+
+- Build the real routes in `app/` first.
+- Update `config/shell.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
+
+Goal: add or modify functionality without assuming a module exists.
+
+- Check `config/modules.ts` first.
+- If the module is enabled, edit the app-owned route or API surface before considering package forks.
+- If the module is not enabled, do not create links or routes that assume it exists.

package/template/site/base/AGENTS.md

@@ -0,0 +1,25 @@
+# AGENTS.md
+
+This generated project is a BrightWeb site starter. Use this file as the local entrypoint for AI agents working inside the app.
+
+## Start here
+
+- `README.md`: local setup commands and the starter surface list.
+- `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.
+- `config/site.ts`: site name, description, and starter CTAs.
+- `app/page.tsx`: starter landing page composition.
+- `app/globals.css`: global design language and theme tokens.
+
+## Working rules
+
+- Treat this starter as app-owned. Prefer editing local routes, sections, and UI primitives instead of introducing shared BrightWeb runtime dependencies.
+- Update `config/site.ts` before rewriting copy inline across multiple components.
+- Keep reusable UI tweaks inside `components/ui/` when the change should affect multiple sections.
+
+## First validation pass
+
+1. Run the local dev server from this project or workspace.
+2. Open `/` and confirm the starter content renders correctly.
+3. Check `config/site.ts`, `app/page.tsx`, and `app/globals.css` together before making large copy or layout changes.

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

@@ -0,0 +1,37 @@
+# Agent Guide
+
+This file is the local routing guide for AI agents working inside a generated BrightWeb site 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 a local UI layer and light configuration.
+
+- `app/`: route tree, layouts, and the starter landing page.
+- `components/ui/`: local UI primitives used by the starter surface.
+- `config/site.ts`: generated site identity, description, and CTA defaults.
+- `lib/`: helper utilities such as class merging.
+
+## Fast routing map
+
+- `docs/ai/app-context.json`: machine-readable summary of this app's template, starter routes, and first-read files.
+- `docs/ai/examples.md`: common setup and customization workflows.
+- `README.md`: first-run setup steps.
+- `config/site.ts`: site name, description, eyebrow, and starter CTA links.
+- `app/page.tsx`: starter composition for the home page.
+- `app/globals.css`: theme tokens, layout defaults, and base typography.
+- `components/ui/*`: local component primitives used by the starter.
+
+## Editing strategy
+
+- Change `config/site.ts` first when the task is mostly copy or link updates.
+- Change `app/page.tsx` first when the task is about page structure or section flow.
+- Change `app/globals.css` and `components/ui/*` when the task affects the visual system.
+- Keep changes local to this app unless the task explicitly requires a shared BrightWeb package.
+
+## Validation checklist
+
+1. Run the app locally.
+2. Validate `/` on desktop and mobile sizes.
+3. If you changed the visual system, check both `app/globals.css` and the affected `components/ui/*` files.

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

@@ -0,0 +1,35 @@
+# Agent Examples
+
+Use these workflows after reading `AGENTS.md`, `docs/ai/README.md`, and `docs/ai/app-context.json`.
+
+## First local setup
+
+Goal: get the generated site starter running and ready for edits.
+
+- Run the local dev server for this app or workspace.
+- Open `/` and confirm the starter renders correctly.
+- Review `config/site.ts`, `app/page.tsx`, and `app/globals.css` before making large changes.
+
+## Change site identity
+
+Goal: update the starter name, description, and CTA links.
+
+- Edit `config/site.ts`.
+- Validate `/` after the change.
+- If copy still exists outside the config file, update `app/page.tsx`.
+
+## Restyle the starter
+
+Goal: change the visual language without rewriting everything at once.
+
+- Start in `app/globals.css` for colors, spacing, and typography direction.
+- Update `components/ui/*` if shared primitives need to change.
+- Validate `/` on both desktop and mobile sizes.
+
+## Replace the starter sections
+
+Goal: turn the scaffold into a real site.
+
+- Edit `app/page.tsx` section by section.
+- Keep shared button, badge, and card behavior in `components/ui/*`.
+- Remove starter content only after the replacement section is in place.