create-bw-app 0.9.1 → 0.9.2

package/README.md

@@ -56,7 +56,8 @@ Current updater behavior:
 - 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.1",
+  "version": "0.9.2",
   "type": "module",
   "bin": "bin/create-bw-app.mjs",
   "files": [

package/src/generator.mjs

@@ -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,13 +525,143 @@ 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");
 }
 
+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,
@@ -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({

package/src/update.mjs

@@ -9,6 +9,7 @@ import {
 } from "./constants.mjs";
 import {
   TEMPLATE_ROOT,
+  createAppContextFile,
   createDbInstallPlan,
   createNextConfig,
   createPackageJson,
@@ -26,6 +27,11 @@ 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) {
@@ -337,7 +343,7 @@ export async function buildBrightwebAppUpdatePlan(argvOptions = {}, runtimeOptio
   const dbInstallPlan = template === "platform"
     ? createDbInstallPlan({
       selectedModules: installedModules,
-      workspaceMode: true,
+      workspaceMode: dependencyMode === "workspace",
       registry: dbRegistry,
     })
     : {
@@ -373,6 +379,12 @@ export async function buildBrightwebAppUpdatePlan(argvOptions = {}, runtimeOptio
       "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) {
@@ -380,6 +392,28 @@ export async function buildBrightwebAppUpdatePlan(argvOptions = {}, runtimeOptio
       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,

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.