create-bw-app 0.9.4 → 0.9.6

package/README.md

@@ -41,6 +41,8 @@ pnpm dlx create-bw-app update --target-dir ./apps/client-portal
 Current updater behavior:
 
 - updates installed `@brightweblabs/*` packages only
+- in published mode, resolves those `@brightweblabs/*` target versions from npm at update time
+- fails the update if npm resolution fails unless you pass `--allow-stale-fallback`
 - re-syncs managed BrightWeb config files such as `next.config.ts`, `config/modules.ts`, and `config/shell.ts`
 - reports missing or drifted starter files and only rewrites them with `--refresh-starters`
 - prints the follow-up install command unless `--install` is passed
@@ -54,6 +56,8 @@ Current updater behavior:
 - prompts to install dependencies immediately
 - copies a clean Next.js App Router starter template
 - platform apps include BrightWeb auth, shell wiring, and optional module starter surfaces
+- platform apps include a local `components/` folder for app-owned UI alongside the shared BrightWeb packages
+- platform apps in published mode also write `supabase/module-registry.json`, `supabase/clients/<slug>/stack.json`, and the resolved shared SQL migrations under `supabase/modules/<module>/migrations`
 - site apps include Next.js, Tailwind CSS v4, and local component primitives
 - writes `package.json`, `next.config.ts`, `.gitignore`, and `README.md` for both templates
 - platform apps also write `.env.local`, `AGENTS.md`, `docs/ai/README.md`, `docs/ai/examples.md`, `docs/ai/app-context.json`, and generated config files for brand and module state
@@ -78,3 +82,4 @@ Platform mode always resolves to the `Core + Admin` database baseline. Selecting
 - `packages/create-bw-app/template/base`
 - `packages/create-bw-app/template/site/base`
 - `packages/create-bw-app/template/modules`
+- `packages/create-bw-app/template/supabase`

package/package.json

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

package/src/cli.mjs

@@ -42,6 +42,11 @@ function parseArgv(argv) {
       continue;
     }
 
+    if (token === "--allow-stale-fallback") {
+      options.allowStaleFallback = true;
+      continue;
+    }
+
     const [rawKey, inlineValue] = token.slice(2).split("=", 2);
     const key = toCamelCase(rawKey);
     const nextValue = inlineValue ?? argv[index + 1];

package/src/constants.mjs

@@ -136,6 +136,7 @@ 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
+  --allow-stale-fallback         Use baked-in BrightWeb package versions if npm lookup fails
   --install                      Run install after writing package changes
   --refresh-starters             Rewrite starter route files from the latest template
   --dry-run                      Print the update plan without writing files

package/src/generator.mjs

@@ -18,6 +18,7 @@ import {
 
 export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 export const TEMPLATE_ROOT = path.join(PACKAGE_ROOT, "template");
+const TEMPLATE_SUPABASE_ROOT = path.join(TEMPLATE_ROOT, "supabase");
 const TEMPLATE_KEY_SET = new Set(TEMPLATE_OPTIONS.map((templateOption) => templateOption.key));
 const DEFAULT_DB_MODULE_REGISTRY = {
   modules: {
@@ -112,12 +113,22 @@ export async function readJsonIfPresent(filePath) {
 }
 
 export async function getDbModuleRegistry(workspaceRoot) {
-  if (!workspaceRoot) {
-    return DEFAULT_DB_MODULE_REGISTRY;
+  const candidatePaths = [];
+
+  if (workspaceRoot) {
+    candidatePaths.push(path.join(workspaceRoot, "supabase", "module-registry.json"));
+  }
+
+  candidatePaths.push(path.join(TEMPLATE_SUPABASE_ROOT, "module-registry.json"));
+
+  for (const registryPath of candidatePaths) {
+    const registry = await readJsonIfPresent(registryPath);
+    if (registry) {
+      return registry;
+    }
   }
 
-  const registryPath = path.join(workspaceRoot, "supabase", "module-registry.json");
-  return (await readJsonIfPresent(registryPath)) || DEFAULT_DB_MODULE_REGISTRY;
+  return DEFAULT_DB_MODULE_REGISTRY;
 }
 
 function resolveModuleOrder(registry, enabledModules) {
@@ -172,20 +183,14 @@ function getModuleLabel(moduleKey) {
 }
 
 export function createDbInstallPlan({ selectedModules, workspaceMode, registry }) {
-  if (!workspaceMode) {
-    return {
-      selectedLabels: getSelectedModuleLabels(selectedModules),
-      resolvedOrder: [],
-      notes: [],
-    };
-  }
-
+  void workspaceMode;
+  const activeRegistry = registry?.modules ? registry : DEFAULT_DB_MODULE_REGISTRY;
   const requestedModules = Array.from(new Set(["core", ...selectedModules]));
   if (!requestedModules.includes("admin")) {
     requestedModules.push("admin");
   }
 
-  const resolvedOrder = resolveModuleOrder(registry, requestedModules);
+  const resolvedOrder = resolveModuleOrder(activeRegistry, requestedModules);
   const notes = [];
 
   if (!selectedModules.includes("admin") && resolvedOrder.includes("admin")) {
@@ -198,16 +203,16 @@ export function createDbInstallPlan({ selectedModules, workspaceMode, registry }
     }
 
     const dependents = resolvedOrder.filter((candidateKey) => {
-      const dependencyList = registry.modules?.[candidateKey]?.dependsOn || [];
+      const dependencyList = activeRegistry.modules?.[candidateKey]?.dependsOn || [];
       return dependencyList.includes(moduleKey);
     });
 
     if (dependents.length === 0) continue;
 
     const dependentLabels = dependents
-      .map((candidateKey) => registry.modules?.[candidateKey]?.label || getModuleLabel(candidateKey))
+      .map((candidateKey) => activeRegistry.modules?.[candidateKey]?.label || getModuleLabel(candidateKey))
       .join(", ");
-    const moduleLabel = registry.modules?.[moduleKey]?.label || getModuleLabel(moduleKey);
+    const moduleLabel = activeRegistry.modules?.[moduleKey]?.label || getModuleLabel(moduleKey);
     notes.push(`${moduleLabel} is included because ${dependentLabels} depends on it.`);
   }
 
@@ -467,20 +472,22 @@ function createPlatformReadme({
     "",
     ...moduleLines,
     "",
+    "## Resolved database stack",
+    "",
+    ...resolvedDbStackLines,
+    "",
     ...(workspaceMode
+      ? []
+      : [
+          "Bundled Supabase SQL migrations live under `supabase/modules/<module>/migrations`.",
+          "",
+        ]),
+    ...(dependencyNotes.length > 0
       ? [
-          "## Resolved database stack",
+          "## Dependency notes",
           "",
-          ...resolvedDbStackLines,
+          ...dependencyNotes,
           "",
-          ...(dependencyNotes.length > 0
-            ? [
-                "## Dependency notes",
-                "",
-                ...dependencyNotes,
-                "",
-              ]
-            : []),
         ]
       : []),
     "## Starter routes",
@@ -631,6 +638,7 @@ export function createAppContextFile({
           ".env.local",
         ],
         appRoutesRoot: "app",
+        componentsRoot: "components",
         configRoot: "config",
         brandAssetsRoot: "public/brand",
       },
@@ -638,6 +646,7 @@ export function createAppContextFile({
       ownership: {
         appOwned: [
           "app/**",
+          "components/**",
           "config/**",
           "docs/ai/**",
           "public/brand/**",
@@ -892,20 +901,34 @@ async function copyDirectory(sourceDir, targetDir) {
   await fs.cp(sourceDir, targetDir, { recursive: true });
 }
 
+async function copyFileIfPresent(sourcePath, targetPath) {
+  if (!(await pathExists(sourcePath))) {
+    return;
+  }
+
+  await ensureDirectory(path.dirname(targetPath));
+  await fs.copyFile(sourcePath, targetPath);
+}
+
 export async function ensureDirectory(targetDir) {
   await fs.mkdir(targetDir, { recursive: true });
 }
 
-async function writeWorkspaceClientStack(workspaceRoot, slug, selectedModules) {
-  const clientDir = path.join(workspaceRoot, "supabase", "clients", slug);
+function createScopedDbModuleRegistry(registry, moduleKeys) {
+  return {
+    modules: Object.fromEntries(
+      moduleKeys
+        .map((moduleKey) => [moduleKey, registry.modules?.[moduleKey]])
+        .filter(([, moduleConfig]) => Boolean(moduleConfig)),
+    ),
+  };
+}
+
+async function writeClientStack(baseRoot, slug, dbInstallPlan, options = {}) {
+  const generatedInWorkspaceMode = options.workspaceMode === true;
+  const clientDir = path.join(baseRoot, "supabase", "clients", slug);
   const stackPath = path.join(clientDir, "stack.json");
   const migrationsDir = path.join(clientDir, "migrations");
-  const registry = await getDbModuleRegistry(workspaceRoot);
-  const dbInstallPlan = createDbInstallPlan({
-    selectedModules,
-    workspaceMode: true,
-    registry,
-  });
   const enabledModules = dbInstallPlan.resolvedOrder;
 
   if (await pathExists(stackPath)) {
@@ -927,7 +950,9 @@ async function writeWorkspaceClientStack(workspaceRoot, slug, selectedModules) {
         enabledModules,
         clientMigrationPath: `supabase/clients/${slug}/migrations`,
         notes: [
-          "Generated by create-bw-app in workspace mode.",
+          generatedInWorkspaceMode
+            ? "Generated by create-bw-app in workspace mode."
+            : "Generated by create-bw-app in published mode.",
           `Selected app modules: ${dbInstallPlan.selectedLabels.length > 0 ? dbInstallPlan.selectedLabels.join(", ") : "none"}.`,
           `Resolved database stack: ${enabledModules.map((moduleKey) => getModuleLabel(moduleKey)).join(" -> ")}.`,
           "Platform always resolves to the Core + Admin database baseline; selecting Admin only controls whether the Admin starter UI and package wiring are scaffolded.",
@@ -940,6 +965,38 @@ async function writeWorkspaceClientStack(workspaceRoot, slug, selectedModules) {
   );
 }
 
+async function writeBundledSupabaseBaseline({ targetDir, slug, dbInstallPlan, registry }) {
+  const shippedModuleKeys = dbInstallPlan.resolvedOrder;
+  if (shippedModuleKeys.length === 0) {
+    return;
+  }
+
+  const targetSupabaseDir = path.join(targetDir, "supabase");
+  const targetModulesDir = path.join(targetSupabaseDir, "modules");
+  const scopedRegistry = createScopedDbModuleRegistry(registry, shippedModuleKeys);
+
+  await ensureDirectory(targetModulesDir);
+  await copyFileIfPresent(path.join(TEMPLATE_SUPABASE_ROOT, "README.md"), path.join(targetSupabaseDir, "README.md"));
+  await copyFileIfPresent(
+    path.join(TEMPLATE_SUPABASE_ROOT, "clients", "README.md"),
+    path.join(targetSupabaseDir, "clients", "README.md"),
+  );
+  await fs.writeFile(
+    path.join(targetSupabaseDir, "module-registry.json"),
+    `${JSON.stringify(scopedRegistry, null, 2)}\n`,
+    "utf8",
+  );
+
+  for (const moduleKey of shippedModuleKeys) {
+    await copyDirectory(
+      path.join(TEMPLATE_SUPABASE_ROOT, "modules", moduleKey),
+      path.join(targetModulesDir, moduleKey),
+    );
+  }
+
+  await writeClientStack(targetDir, slug, dbInstallPlan);
+}
+
 export async function runInstall(command, cwd) {
   return new Promise((resolve, reject) => {
     const child = spawn(command, ["install"], {
@@ -1084,6 +1141,7 @@ async function scaffoldPlatformProject({
   workspaceRoot,
   answers,
   dbInstallPlan,
+  dbRegistry,
 }) {
   const brandValues = createDerivedBrandValues(answers.slug);
   const baseTemplateDir = path.join(TEMPLATE_ROOT, "base");
@@ -1144,7 +1202,14 @@ async function scaffoldPlatformProject({
   );
 
   if (workspaceMode) {
-    await writeWorkspaceClientStack(workspaceRoot, answers.slug, selectedModules);
+    await writeClientStack(workspaceRoot, answers.slug, dbInstallPlan, { workspaceMode: true });
+  } else {
+    await writeBundledSupabaseBaseline({
+      targetDir,
+      slug: answers.slug,
+      dbInstallPlan,
+      registry: dbRegistry,
+    });
   }
 }
 
@@ -1299,6 +1364,7 @@ export async function createBrightwebClientApp(argvOptions, runtimeOptions = {})
       workspaceRoot,
       answers,
       dbInstallPlan,
+      dbRegistry: dbModuleRegistry,
     });
   }
 

package/src/update.mjs

@@ -76,6 +76,62 @@ function collectInstalledBrightwebPackages(manifest) {
   return installed;
 }
 
+async function resolvePublishedBrightwebVersions(installedBrightwebPackages, options = {}) {
+  const packageNames = Array.from(installedBrightwebPackages.keys()).sort();
+
+  if (packageNames.length === 0) {
+    return {};
+  }
+
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new Error("Published updates require fetch support to resolve BrightWeb package versions from npm.");
+  }
+
+  const fallbackVersionMap = options.fallbackVersionMap || {};
+  const allowStaleFallback = options.allowStaleFallback === true;
+  const resolvedVersions = {};
+  const failures = [];
+
+  await Promise.all(
+    packageNames.map(async (packageName) => {
+      try {
+        const response = await fetchImpl(`https://registry.npmjs.org/${encodeURIComponent(packageName)}/latest`);
+        if (!response?.ok) {
+          throw new Error(`npm registry responded with ${response?.status ?? "an unknown error"}`);
+        }
+
+        const payload = await response.json();
+        if (!payload?.version || typeof payload.version !== "string") {
+          throw new Error("npm registry response did not include a version");
+        }
+
+        resolvedVersions[packageName] = `^${payload.version}`;
+      } catch (error) {
+        const fallbackVersion = fallbackVersionMap[packageName];
+        if (allowStaleFallback && fallbackVersion) {
+          resolvedVersions[packageName] = fallbackVersion;
+          return;
+        }
+
+        const message = error instanceof Error ? error.message : "Unknown error";
+        failures.push(`${packageName}: ${message}`);
+      }
+    }),
+  );
+
+  if (failures.length > 0) {
+    const fallbackHint = allowStaleFallback
+      ? "No baked-in fallback version was available for at least one package."
+      : "Re-run with --allow-stale-fallback to use the CLI's baked-in BrightWeb package versions instead.";
+    throw new Error(
+      `Failed to resolve published BrightWeb package versions from npm.\n${failures.join("\n")}\n${fallbackHint}`,
+    );
+  }
+
+  return resolvedVersions;
+}
+
 function parseConfiguredModules(content) {
   const enabledModules = [];
 
@@ -339,6 +395,13 @@ export async function buildBrightwebAppUpdatePlan(argvOptions = {}, runtimeOptio
   const packageManager = detectPackageManager(argvOptions.packageManager || runtimeOptions.packageManager);
   const installedModules = detectInstalledModules(installedBrightwebPackagesMap);
   const versionMap = await getVersionMap(workspaceRoot);
+  const brightwebVersionOverrides = dependencyMode === "published"
+    ? await resolvePublishedBrightwebVersions(installedBrightwebPackagesMap, {
+      fetchImpl: runtimeOptions.fetchImpl,
+      fallbackVersionMap: versionMap,
+      allowStaleFallback: argvOptions.allowStaleFallback || runtimeOptions.allowStaleFallback,
+    })
+    : {};
   const dbRegistry = await getDbModuleRegistry(workspaceRoot);
   const dbInstallPlan = template === "platform"
     ? createDbInstallPlan({
@@ -356,7 +419,10 @@ export async function buildBrightwebAppUpdatePlan(argvOptions = {}, runtimeOptio
     template,
     dependencyMode,
     installedModules,
-    versionMap,
+    versionMap: {
+      ...versionMap,
+      ...brightwebVersionOverrides,
+    },
   });
   const packageJsonUpdate = mergeManagedPackageUpdates({
     manifest,

package/template/base/AGENTS.md

@@ -8,6 +8,7 @@ This generated project is a BrightWeb platform starter. Use this file as the loc
 - `docs/ai/README.md`: app-specific routing guide for agents.
 - `docs/ai/examples.md`: common setup and customization flows.
 - `docs/ai/app-context.json`: machine-readable app summary for quick discovery.
+- `components/`: local app components used by starter routes and future product surfaces.
 - `config/brand.ts`: client identity, naming, and contact defaults.
 - `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/app/playground/auth/page.tsx

@@ -1,4 +1,4 @@
-import { AuthPlayground } from "./auth-playground";
+import { AuthPlayground } from "../../../components/auth-playground";
 
 export default function AuthPlaygroundPage() {
   return <AuthPlayground />;

package/template/base/app/preview/app-shell/page.tsx

@@ -1,4 +1,4 @@
-import { AppShellPreview } from "../app-shell-preview";
+import { AppShellPreview } from "../../../components/app-shell-preview";
 
 export default function AppShellPreviewPage() {
   return (

package/template/base/{app/preview → components}/app-shell-preview.tsx

@@ -12,8 +12,8 @@ import {
   type ResolvedClientAppShellConfig,
 } from "@brightweblabs/app-shell";
 import { LayoutTemplate, Sparkles, Users } from "lucide-react";
-import { starterBrandConfig } from "../../config/brand";
-import { getStarterShellConfig } from "../../config/shell";
+import { starterBrandConfig } from "../config/brand";
+import { getStarterShellConfig } from "../config/shell";
 
 const mockUser = {
   email: "admin@starter-client.test",

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

@@ -9,6 +9,7 @@ It is intentionally app-scoped. It explains the generated project you are in, no
 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.
+- `components/`: local React components used by starter routes and app-owned product work.
 - `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.
@@ -18,6 +19,7 @@ This app is a normal Next.js App Router project with BrightWeb runtime wiring la
 - `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.
+- `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/modules.ts`: module metadata and enablement flags for CRM, Projects, and Admin.
 - `config/client.ts`: aggregated state consumed by starter pages.
@@ -33,6 +35,7 @@ This app is a normal Next.js App Router project with BrightWeb runtime wiring la
 
 - Change client identity first in `config/brand.ts`.
 - 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/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

@@ -18,6 +18,7 @@ Goal: get the generated starter running with real credentials.
 Goal: update the starter to the real client name and support details.
 
 - Edit `config/brand.ts`.
+- 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.
 
@@ -26,6 +27,7 @@ Goal: update the starter to the real client name and support details.
 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.
 - Remove `/bootstrap`, `/preview/app-shell`, or `/playground/*` only after links and config references are cleaned up.
 

package/template/modules/crm/app/api/crm/_shared/create-module-route-handler.ts

@@ -0,0 +1,13 @@
+type RouteHandler = (request: Request) => Response | Promise<Response>;
+
+type ModuleWithHandler<THandlerName extends string> = Record<THandlerName, RouteHandler>;
+
+export function createModuleRouteHandler<THandlerName extends string>(
+  loadModule: () => Promise<ModuleWithHandler<THandlerName>>,
+  handlerName: THandlerName,
+): RouteHandler {
+  return async function moduleRouteHandler(request: Request) {
+    const module = await loadModule();
+    return module[handlerName](request);
+  };
+}

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

@@ -1,6 +1,8 @@
+import { createModuleRouteHandler } from "../_shared/create-module-route-handler";
+
 export const dynamic = "force-dynamic";
 
-export async function GET(request: Request) {
-  const { handleCrmContactsGetRequest } = await import("@brightweblabs/module-crm");
-  return handleCrmContactsGetRequest(request);
-}
+export const GET = createModuleRouteHandler(
+  () => import("@brightweblabs/module-crm"),
+  "handleCrmContactsGetRequest",
+);

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

@@ -1,6 +1,8 @@
+import { createModuleRouteHandler } from "../_shared/create-module-route-handler";
+
 export const dynamic = "force-dynamic";
 
-export async function GET(request: Request) {
-  const { handleCrmOrganizationsGetRequest } = await import("@brightweblabs/module-crm");
-  return handleCrmOrganizationsGetRequest(request);
-}
+export const GET = createModuleRouteHandler(
+  () => import("@brightweblabs/module-crm"),
+  "handleCrmOrganizationsGetRequest",
+);

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

@@ -1,6 +1,8 @@
+import { createModuleRouteHandler } from "../_shared/create-module-route-handler";
+
 export const dynamic = "force-dynamic";
 
-export async function GET(request: Request) {
-  const { handleCrmOwnersGetRequest } = await import("@brightweblabs/module-crm");
-  return handleCrmOwnersGetRequest(request);
-}
+export const GET = createModuleRouteHandler(
+  () => import("@brightweblabs/module-crm"),
+  "handleCrmOwnersGetRequest",
+);

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

@@ -1,6 +1,8 @@
+import { createModuleRouteHandler } from "../_shared/create-module-route-handler";
+
 export const dynamic = "force-dynamic";
 
-export async function GET(request: Request) {
-  const { handleCrmStatsGetRequest } = await import("@brightweblabs/module-crm");
-  return handleCrmStatsGetRequest(request);
-}
+export const GET = createModuleRouteHandler(
+  () => import("@brightweblabs/module-crm"),
+  "handleCrmStatsGetRequest",
+);

package/template/supabase/README.md

@@ -0,0 +1,74 @@
+# Brightweb Supabase Structure
+
+This directory is the canonical home for the Brightweb database baseline and its forward migrations.
+
+## Directory map
+
+- `module-registry.json`: shared module dependency graph and migration source paths
+- `modules/core`: always-on platform foundations
+- `modules/admin`: RBAC and privileged governance behavior
+- `modules/crm`: organizations, CRM contacts, and invitation flows
+- `modules/projects`: project and work-management data
+- `clients/<client-slug>`: true client-only schema deltas plus the client stack plan
+- `.generated/<client-slug>`: materialized Supabase workdirs produced by `pnpm db:materialize`
+
+## Ownership rule
+
+Shared database changes should be authored by ownership area, not by client app:
+
+- `core` is applied to every client
+- shared module migrations are applied only when that module is enabled for the client
+- client-specific migrations are the exception, not the default
+
+In workspace scaffold mode, `create-bw-app` writes `supabase/clients/<slug>/stack.json` so the generated app modules and the database install plan stay aligned.
+
+The module baselines in this repo are the canonical Brightweb v1 install path. Future schema work should extend them with forward migrations instead of carrying historical cleanup sequences.
+
+Maintainer references:
+
+- `docs/internal/architecture/database-module-migration-structure.md`
+- `docs/internal/architecture/database-migration-authoring-workflow.md`
+- `docs/internal/architecture/database-migration-safety-policy.md`
+
+## Authoring workflow
+
+Create a new shared module migration:
+
+```bash
+pnpm db:new core profile_notification_cursor
+pnpm db:new admin role_change_guard
+pnpm db:new crm organization_invite_expiry
+pnpm db:new projects task_due_date_index
+```
+
+Create a client-only migration:
+
+```bash
+pnpm db:new client:acme bespoke_reporting_table
+```
+
+Print the effective apply order for a client:
+
+```bash
+pnpm db:plan acme
+```
+
+Materialize an installable Supabase workdir for a client stack:
+
+```bash
+pnpm db:materialize acme
+```
+
+This writes a generated workdir under `supabase/.generated/<client-slug>` with:
+
+- ordered migrations merged from `core`, enabled modules, and client-only deltas
+- a generated `config.toml`
+- a `manifest.json` showing the source file for each materialized migration
+
+## Related READMEs
+
+- `supabase/modules/core/README.md`
+- `supabase/modules/admin/README.md`
+- `supabase/modules/crm/README.md`
+- `supabase/modules/projects/README.md`
+- `supabase/clients/README.md`

package/template/supabase/clients/README.md

@@ -0,0 +1,19 @@
+# Client-Specific Migrations
+
+This directory is reserved for true client-only schema deltas.
+
+## Rule
+
+Only place SQL here when the change:
+
+- cannot be reused by other clients
+- should not be part of a shared module
+- is intentionally isolated to a single client deployment
+
+## Expected shape
+
+- `clients/<slug>/...`
+
+Temporary smoke-test client stacks should be removed after generator verification. This directory is for real client-specific deltas only.
+
+If a client-specific migration later proves reusable, move the concept into the appropriate shared module and stop extending the client-only path.

package/template/supabase/module-registry.json

@@ -0,0 +1,28 @@
+{
+  "modules": {
+    "core": {
+      "label": "Core",
+      "path": "supabase/modules/core/migrations",
+      "dependsOn": [],
+      "description": "Shared auth/profile, events, rate limits, and always-on platform foundations."
+    },
+    "admin": {
+      "label": "Admin",
+      "path": "supabase/modules/admin/migrations",
+      "dependsOn": ["core"],
+      "description": "RBAC, user governance, and privileged role-management behavior."
+    },
+    "crm": {
+      "label": "CRM",
+      "path": "supabase/modules/crm/migrations",
+      "dependsOn": ["core", "admin"],
+      "description": "Organizations, CRM contacts, org membership, and invitation flows."
+    },
+    "projects": {
+      "label": "Projects",
+      "path": "supabase/modules/projects/migrations",
+      "dependsOn": ["core", "admin", "crm"],
+      "description": "Projects, tasks, milestones, members, links, and project activity policies."
+    }
+  }
+}