create-lumen 2.0.0-beta.2 → 2.0.0-beta.4

package/README.md

@@ -1,6 +1,6 @@
 # create-lumen
 
-A scaffolder that generates production-ready **React + Vite** or **Next.js** projects (App Router / Pages Router), with a choice of architecture: feature-based, type-based, hybrid, or none.
+A scaffolder that generates production-ready **React + Vite** or **Next.js** projects (App Router / Pages Router), with a choice of architecture: feature-based, type-based, or none.
 
 Note: this repository is the CLI scaffolder itself, not a generated app. Generated projects live in the target folder you create.
 
@@ -81,24 +81,27 @@ create-lumen my-app      # after npm link
 ## Features
 
 - **Two frameworks:** React + Vite (SPA) or Next.js (App Router / Pages Router) — selected interactively or via `-f`
-- Architecture choice: feature-based, type-based, hybrid, or none (per-framework availability)
-- TypeScript or JavaScript output
-- CSS frameworks: Tailwind CSS v4 (CSS-first `@theme`, v3 dropped) or none
-- **UI kit: shadcn/ui** (gated to Tailwind; primitives + `cn` helper land in the mapped `paths.ui`)
-- Optional state management: Zustand or Redux Toolkit
-- Optional router (React Router — Vite only; Next.js uses filesystem routing)
-- Optional testing: Vitest or Jest (Next.js defaults to none until a Next-native overlay is verified)
+- **Architecture choice:** feature-based, type-based, or none (scoped per framework: React + Vite supports `feature-based`, `type-based`, and `none`; Next.js supports `feature-based` and `none`)
+- **TypeScript or JavaScript output**
+- **CSS frameworks:** Tailwind CSS v4 (CSS-first `@theme`, v3 dropped) or none
+- **UI kit: shadcn/ui** (gated to Tailwind; primitives + `cn` helper land in mapped `paths.ui`; official `@lumen` registry configured in `components.json` for Shadcn Registry v2)
+- **Fullstack Next.js database scaffolding:** Prisma ORM with SQLite, PostgreSQL, and Supabase (connection pooler port 6543, direct session port 5432, `.env.example`, client singleton)
+- **Next.js Docker containerization:** multi-stage production Dockerfile targeting Next.js `output: "standalone"`, `.dockerignore`, `docker-compose.yml`
+- **Next.js Route Groups & Auth Proxy:** `--route-groups` preset scaffolds logical App Router directory segments (`(public)`, `(auth)`, `(dashboard)`) with edge auth middleware
+- **Optional state management:** Zustand or Redux Toolkit
+- **Optional router:** React Router (Vite only; Next.js uses filesystem routing)
+- **Testing:** Vitest or Jest (Next.js defaults to none until explicitly selected; zero-babel Next SWC integration)
 - **Next.js-native overlays:** server/client boundary demos + `no-server-imports-in-client` ESLint rule, `next/font` (Geist), `next/image`, filesystem routing examples, route handlers (`route.ts`) / API routes (`pages/api`)
 - **Next.js options:** `bundler: turbopack|webpack`, `adapter: node|vercel|cloudflare|static` (`next.config` overlays), `reactCompiler`, `linter: biome` — all validated against the capability model
-- Linting: ESLint (default), Oxlint, or Biome
-- Code formatter: Prettier or Oxfmt (chosen after the linter; `eslint-config-prettier` is auto-wired for the ESLint + Prettier combo)
-- Manifest v2: Emits a deterministic `lumen.config.json` validated against JSON Schema Draft 2020-12, including architecture validation modes and harness command configuration.
-- Explicit path mapping: Target directories declared for `lumen-cli` code generation
-- Optional Axios setup and icon libraries
-- Auto `git init`, generated `README` (with a project description reflecting the chosen tooling) and `LICENSE`
+- **Linting:** ESLint (default flat config), Oxlint, or Biome
+- **Code formatter & scripts:** Prettier, Oxfmt, or none (with Biome handling lint + format via `biome check --write .`); auto-wired `format`, `format:check`, and `test:watch` scripts in `package.json`
+- **Manifest v2:** Emits a deterministic `lumen.config.json` validated against JSON Schema Draft 2020-12, including architecture validation modes and harness command configuration
+- **Explicit path mapping:** Canonical target directories declared for `lumen-cli` code generation (`paths.pages` resolves to `src/app` or `src/pages` in Next.js)
+- **Optional Axios setup and icon libraries**
+- **Auto `git init`**, generated `README` (with a project description reflecting the chosen tooling) and `LICENSE`
 - `.env.example` scaffolded, and the generated `.gitignore` excludes env files (`.env`, `.env.*`) while keeping `.env.example`
-- `@/` path alias configured (`tsconfig`/`jsconfig` + Vite)
-- **Agent docs:** optional `.lumen/` context directory (project, architecture, conventions) via prompt or `--agent-docs`
+- `@/` path alias configured (`tsconfig`/`jsconfig` + Vite/Next)
+- **Agent docs:** deterministic root `AGENTS.md` referencing `lumen.config.json` as the Single Source of Truth (SSOT), providing AI agents with architecture rules, 3-tier component taxonomy, and harness commands
 
 Your selected options are cached and offered as defaults on subsequent runs.
 
@@ -214,7 +217,7 @@ src/
 ### Manifest v2 Schema (v2.0.0-alpha.1+)
 
 The manifest now includes:
-- **`architecture.preset`**: The base architecture (`feature-based`, `type-based`, `hybrid`, `none`).
+- **`architecture.preset`**: The base architecture (`feature-based`, `type-based`, `none`).
 - **`architecture.validation`**: Validation mode for `lumen doctor` (`strict`, `relaxed`, `none`).
 - **`harness.commands`**: An array of commands to run with `lumen harness` (e.g., lint, format, types, test, build), each with a name, shell command, required flag, and description.
 
@@ -231,11 +234,9 @@ The manifest now includes:
 
 ### Agent Interoperability
 
-Lumen is designed for both people and agents. When `agentDocs: true` is set in the manifest (or via the `--agent-docs` flag), `create-lumen` generates a `.lumen/` directory in the project root containing:
-- `project.json`: The resolved manifest.
-- `architecture.json`: The effective architecture preset and validation mode.
-- `conventions.md`: A markdown file documenting project-specific conventions (e.g., component naming, file organization).
-These files enable agents to understand the project without parsing the source code.
+Lumen is designed for both human developers and autonomous AI agents:
+- **`AGENTS.md`**: Scaffolds a deterministic root-level guide providing AI agents with architecture rules, 3-tier component taxonomy (`paths.ui`, `paths.components`, and feature components), harness commands, and Next.js guidelines (RSC vs `"use client"`).
+- **`lumen.config.json`**: Functions as the single source of truth (SSOT) defining canonical target paths (`paths.features`, `paths.pages`, `paths.ui`, etc.), tooling configurations, and architecture constraints without duplicating metadata into legacy `.lumen/` directories.
 
 ## Roadmap & Planning
 

package/bin/cli.js

@@ -32,12 +32,7 @@ console.log(
 const { main } = await import("@/main.js");
 
 main({
-  quickSetup: cliArgs.quickSetup,
-  projectName: cliArgs.projectName,
-  manifest: cliArgs.manifest,
-  template: cliArgs.template,
-  framework: cliArgs.framework,
-  arch: cliArgs.arch,
+  ...cliArgs,
 }).catch((e) => {
   console.error(chalk.red("\nError:"), e.message || e);
   process.exit(1);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-lumen",
-  "version": "2.0.0-beta.2",
-  "description": "Scaffold a React + Vite project with architecture choice: feature-based, type-based, hybrid, or none.",
+  "version": "2.0.0-beta.4",
+  "description": "Scaffold a React + Vite or Next.js project with architecture choice: feature-based, type-based, or none.",
   "type": "module",
   "bin": {
     "create-lumen": "bin/cli.js"

package/schema/fixtures/v2/valid/next-app-router-feature-based.json

@@ -24,7 +24,7 @@
     "components": "src/shared/components",
     "services": "src/shared/services",
     "hooks": "src/shared/hooks",
-    "pages": "app",
+    "pages": "src/app",
     "ui": "src/shared/components/ui"
   },
   "tooling": {

package/schema/fixtures/v2/valid/next-app-router-none.json

@@ -22,7 +22,7 @@
     "components": "src/components",
     "services": "src/services",
     "hooks": "src/hooks",
-    "pages": "app",
+    "pages": "src/app",
     "ui": "src/components/ui"
   },
   "tooling": {

package/schema/fixtures/v2/valid/next-pages-router-feature-based.json

@@ -24,7 +24,7 @@
     "components": "src/shared/components",
     "services": "src/shared/services",
     "hooks": "src/shared/hooks",
-    "pages": "pages",
+    "pages": "src/pages",
     "ui": "src/shared/components/ui"
   },
   "tooling": {

package/schema/fixtures/v2/valid/next-pages-router-none.json

@@ -22,7 +22,7 @@
     "components": "src/components",
     "services": "src/services",
     "hooks": "src/hooks",
-    "pages": "pages",
+    "pages": "src/pages",
     "ui": "src/components/ui"
   },
   "tooling": {

package/schema/lumen.config.v2.json

@@ -79,7 +79,6 @@
           "enum": [
             "feature-based",
             "type-based",
-            "hybrid",
             "none"
           ]
         },
@@ -88,7 +87,6 @@
           "enum": [
             "feature-based",
             "type-based",
-            "hybrid",
             "none"
           ]
         },
@@ -261,7 +259,8 @@
           "default": "postgresql",
           "type": "string",
           "enum": [
-            "postgresql"
+            "postgresql",
+            "supabase"
           ]
         }
       },

package/src/cleanup.js

@@ -16,10 +16,26 @@ export async function cleanupBoilerplate(projectPath, responses = {}) {
     (await fsp.stat(path.join(projectPath, "next.config.js")).catch(() => false));
 
   if (isNext) {
-    await deleteIfExists(`${projectPath}/src/app/App.tsx`);
-    await deleteIfExists(`${projectPath}/src/app/App.jsx`);
-    await deleteIfExists(`${projectPath}/src/app/hooks`);
-    await deleteIfExists(`${projectPath}/src/app/contexts`);
-    await deleteIfExists(`${projectPath}/src/app/providers`);
+    await deleteIfExists(`${projectPath}/src/main.tsx`);
+    await deleteIfExists(`${projectPath}/src/main.jsx`);
+    await deleteIfExists(`${projectPath}/src/App.tsx`);
+    await deleteIfExists(`${projectPath}/src/App.jsx`);
+    await deleteIfExists(`${projectPath}/src/App.css`);
+    await deleteIfExists(`${projectPath}/src/shared/styles`);
+
+    const isPagesRouter =
+      responses?.framework?.variant === "pages-router" ||
+      responses?.frameworkVariant === "pages-router" ||
+      (await fsp.stat(path.join(projectPath, "src", "pages")).catch(() => false));
+
+    if (isPagesRouter) {
+      await deleteIfExists(`${projectPath}/src/app`);
+    } else {
+      await deleteIfExists(`${projectPath}/src/app/App.tsx`);
+      await deleteIfExists(`${projectPath}/src/app/App.jsx`);
+      await deleteIfExists(`${projectPath}/src/app/hooks`);
+      await deleteIfExists(`${projectPath}/src/app/contexts`);
+      await deleteIfExists(`${projectPath}/src/app/providers`);
+    }
   }
 }

package/src/cli-args.js

@@ -282,6 +282,10 @@ export function parseCliArgs(argv = process.argv.slice(2)) {
       adapter: { type: "string" },
       database: { type: "string" },
       db: { type: "string" },
+      "db-provider": { type: "string" },
+      dbProvider: { type: "string" },
+      "database-provider": { type: "string" },
+      databaseProvider: { type: "string" },
       "react-compiler": { type: "boolean" },
       reactCompiler: { type: "boolean" },
       "route-groups": { type: "boolean" },
@@ -289,7 +293,18 @@ export function parseCliArgs(argv = process.argv.slice(2)) {
       "agent-docs": { type: "boolean" },
       agentDocs: { type: "boolean" },
       docker: { type: "boolean" },
+      language: { type: "string", short: "l" },
+      lang: { type: "string" },
+      css: { type: "string", short: "c" },
+      styling: { type: "string" },
+      "css-framework": { type: "string" },
+      cssFramework: { type: "string" },
+      ui: { type: "string", short: "u" },
+      uiKit: { type: "string" },
+      "ui-kit": { type: "string" },
+      testing: { type: "string" },
       linter: { type: "string" },
+      formatter: { type: "string" },
       help: { type: "boolean", short: "h", default: false },
       version: { type: "boolean", short: "v", default: false },
     },
@@ -312,11 +327,30 @@ export function parseCliArgs(argv = process.argv.slice(2)) {
   if (database) {
     database = database.trim().toLowerCase();
   }
+  let databaseProvider =
+    values["db-provider"] ||
+    values.dbProvider ||
+    values["database-provider"] ||
+    values.databaseProvider ||
+    null;
+  if (databaseProvider) {
+    databaseProvider = databaseProvider.trim().toLowerCase();
+  }
   const reactCompiler = values["react-compiler"] ?? values.reactCompiler ?? null;
   const routeGroups = values["route-groups"] ?? values.routeGroups ?? null;
   const agentDocs = values["agent-docs"] ?? values.agentDocs ?? null;
   const docker = Boolean(values.docker);
+  const language = values.language || values.lang || null;
+  const cssFramework =
+    values.css ||
+    values.styling ||
+    values["css-framework"] ||
+    values.cssFramework ||
+    null;
+  const uiKit = values.ui || values.uiKit || values["ui-kit"] || null;
+  const testing = values.testing ? values.testing.trim().toLowerCase() : null;
   const linter = values.linter ? values.linter.trim().toLowerCase() : null;
+  const formatter = values.formatter ? values.formatter.trim().toLowerCase() : null;
 
   return {
     projectName,
@@ -325,14 +359,20 @@ export function parseCliArgs(argv = process.argv.slice(2)) {
     template: values.template || null,
     framework: values.framework ? values.framework.trim() : null,
     arch,
+    language,
+    cssFramework,
+    uiKit,
     bundler,
     adapter,
     database,
+    databaseProvider,
     reactCompiler,
     routeGroups,
     agentDocs,
     docker,
+    testing,
     linter,
+    formatter,
     help: Boolean(values.help),
     version: Boolean(values.version),
     positionals,
@@ -403,6 +443,10 @@ export function manifestToResponses(manifest, projectName) {
       supportsDatabase && manifest.database?.orm
         ? manifest.database.orm
         : "none",
+    databaseProvider:
+      supportsDatabase && manifest.database?.provider
+        ? manifest.database.provider
+        : undefined,
     architecture: manifest.architecture?.type || "feature-based",
     language: manifest.tooling?.language || "ts",
     cssFramework: manifest.styling?.engine || "tailwind",
@@ -433,20 +477,27 @@ export function manifestToResponses(manifest, projectName) {
  */
 export function printHelp() {
   console.log(`
-${chalk.bold.cyan("  create-lumen")} — Scaffold a React + Vite project with architecture choice
+${chalk.bold.cyan("  create-lumen")} — Scaffold a React + Vite or Next.js project with architecture choice
 
 ${chalk.bold("USAGE")}
   ${chalk.green("$")} ${chalk.bold("create-lumen")} [project-name] [options]
 
 ${chalk.bold("OPTIONS")}
   ${chalk.yellow("-y, --yes")}              Quick setup with recommended defaults (TS + Tailwind + Router + ESLint + Prettier)
-  ${chalk.yellow("-a, --arch")} <name>      Architecture preset (feature-based, type-based, none, hybrid)
+  ${chalk.yellow("-a, --arch")} <name>      Architecture preset (feature-based, type-based, none)
+  ${chalk.yellow("-l, --language")} <lang>  Language (ts, js)
+  ${chalk.yellow("-c, --css")} <framework>  Styling engine (tailwind, none)
   ${chalk.yellow("-m, --manifest")} <path>  Drive scaffolding from a lumen.config.json or inline JSON
   ${chalk.yellow("-t, --template")} <name>  Scaffold using a preset (${Object.keys(PRESETS).join(", ")})
   ${chalk.yellow("-f, --framework")} <name> Target framework (react, next, react:vite, next:app-router, etc.)
+  ${chalk.yellow("--testing")} <framework>  Testing framework (vitest, jest, none)
+  ${chalk.yellow("--linter")} <linter>      Linter (eslint, oxlint, biome, none)
+  ${chalk.yellow("--formatter")} <fmt>      Code formatter (prettier, oxfmt, none)
   ${chalk.yellow("--db, --database")} <orm> Database ORM (prisma, none)
+  ${chalk.yellow("--db-provider")} <provider> Database provider (postgresql, supabase)
   ${chalk.yellow("    --docker")}           Include multi-stage Dockerfile & docker-compose for Next.js standalone
   ${chalk.yellow("--route-groups")}         Include Next.js route groups preset (public, auth, private, admin)
+  ${chalk.yellow("--agent-docs")}           Generate root AGENTS.md referencing lumen.config.json
   ${chalk.yellow("-h, --help")}             Show this help message
   ${chalk.yellow("-v, --version")}          Show version number
 

package/src/configure.js

@@ -2,10 +2,31 @@ import { promises as fsp } from "fs";
 import path from "path";
 import { readFileContent } from "@/utils/fs.js";
 import { getPathAliases, getViteAliases } from "@/aliases.js";
-
-export async function configureProject(projectPath, language, cssFramework) {
+import { normalizeFramework } from "@/engine/capabilities.js";
+
+export async function configureProject(projectPath, languageOrResponses, cssFramework, framework = "vite") {
+  let language = languageOrResponses;
+  let css = cssFramework;
+  let fwArg = framework;
+  if (languageOrResponses && typeof languageOrResponses === "object") {
+    language = languageOrResponses.language;
+    css = languageOrResponses.cssFramework;
+    fwArg =
+      languageOrResponses.framework || {
+        name: languageOrResponses.frameworkName,
+        variant: languageOrResponses.frameworkVariant,
+      };
+  }
+  const fw = normalizeFramework(fwArg);
   const ext = language === "ts" ? "ts" : "js";
 
+  if (fw.name === "next") {
+    // Next.js ships its own tsconfig.json with next plugins and paths.
+    // Skip Vite tsconfig.app.json and vite.config mutations.
+    await configurePackageJson(projectPath, language, fw);
+    return;
+  }
+
   // Set up tsconfig/jsconfig with the @/* path alias
   if (language === "ts") {
     await configureTsconfig(projectPath);
@@ -14,12 +35,12 @@ export async function configureProject(projectPath, language, cssFramework) {
   }
 
   // Add path aliases to vite.config for non-tailwind setups
-  if (cssFramework !== "tailwind") {
+  if (css !== "tailwind") {
     await addPathAliasesToViteConfig(projectPath, ext);
   }
 
   // Add scripts to package.json
-  await configurePackageJson(projectPath, language);
+  await configurePackageJson(projectPath, language, fw);
 }
 
 async function configureTsconfig(projectPath) {
@@ -158,7 +179,8 @@ async function addPathAliasesToViteConfig(projectPath, ext) {
   }
 }
 
-async function configurePackageJson(projectPath, language) {
+async function configurePackageJson(projectPath, language, framework = "vite") {
+  const fw = normalizeFramework(framework);
   const pkgPath = path.join(projectPath, "package.json");
   try {
     const content = await readFileContent(pkgPath);
@@ -170,9 +192,15 @@ async function configurePackageJson(projectPath, language) {
     // (Next.js bases ship next dev/build/start) or merged overlay fragments
     // (e.g. the bundler-aware dev script). React/Vite bases already carry the
     // vite commands, so this is a no-op there too.
-    pkg.scripts.dev ??= "vite";
-    pkg.scripts.build ??= "vite build";
-    pkg.scripts.preview ??= "vite preview";
+    if (fw.name !== "next") {
+      pkg.scripts.dev ??= "vite";
+      pkg.scripts.build ??= "vite build";
+      pkg.scripts.preview ??= "vite preview";
+    } else {
+      if (pkg.scripts.preview && pkg.scripts.preview.includes("vite")) {
+        delete pkg.scripts.preview;
+      }
+    }
 
     if (language === "ts") {
       pkg.scripts.typecheck ??= "tsc -b";

package/src/css.js

@@ -17,7 +17,6 @@ export async function setupCssFramework({
   pkg: _pkg,
   framework = "vite",
 }) {
-  process.chdir(projectPath);
   const fw = normalizeFramework(framework);
   const isFilesystemRouted = hasCapability(fw, CAPABILITIES.FILESYSTEM_ROUTING);
   const cssDir = path.join(templatesDir, "css");
@@ -25,15 +24,26 @@ export async function setupCssFramework({
   // framework is "none"); type-based imports ./styles/globals.css (or
   // main.css). The chosen framework's styles land in the file the architecture
   // actually imports.
-  const stylesDir =
-    architecture === "feature-based" || architecture === "hybrid"
-      ? path.join(projectPath, "src", "shared", "styles")
-      : path.join(projectPath, "src", "styles");
+  let stylesDir;
+  if (fw.name === "next") {
+    stylesDir =
+      fw.variant === "pages-router"
+        ? path.join(projectPath, "src", "styles")
+        : path.join(projectPath, "src", "app");
+  } else {
+    stylesDir =
+      architecture === "feature-based"
+        ? path.join(projectPath, "src", "shared", "styles")
+        : path.join(projectPath, "src", "styles");
+  }
 
   // Vanilla CSS gets a stylesheet named main.css; tailwind keeps
   // globals.css (its idiomatic name — it injects framework directives).
   const mainFileName = cssFramework === "none" ? "main.css" : "globals.css";
 
+  // Ensure the styles dir exists
+  await fsp.mkdir(stylesDir, { recursive: true });
+
   async function writeCss(content, fileName) {
     await fsp.writeFile(path.join(stylesDir, fileName), content, "utf8");
   }
@@ -100,11 +110,11 @@ async function syncMainCssImport(projectPath, ext, architecture, mainFileName) {
   try {
     let content = await fsp.readFile(mainPath, "utf8");
     const expected =
-      architecture === "feature-based" || architecture === "hybrid"
+      architecture === "feature-based"
         ? `./shared/styles/${mainFileName}`
         : `./styles/${mainFileName}`;
     const wrong =
-      architecture === "feature-based" || architecture === "hybrid"
+      architecture === "feature-based"
         ? /import ['"]\.\/shared\/styles\/(globals|main)\.css['"]/
         : /import ['"]\.\/styles\/(globals|main)\.css['"]/;
     content = content.replace(wrong, `import '${expected}'`);

package/src/dependencies.js

@@ -34,6 +34,13 @@ export async function installAllDeps(responses, pkg, cwd) {
   for (const batch of devDepBatches) {
     await installDeps(pkg, true, batch, cwd);
   }
+
+  if (responses.database === "prisma") {
+    try {
+      const runner = pkg === "npm" ? "npx" : pkg;
+      await execa(runner, ["prisma", "generate"], { cwd, stdio: "pipe" });
+    } catch {}
+  }
 }
 
 // Pure dependency computation — the package list for a given matrix cell,
@@ -90,8 +97,8 @@ export function computeDeps(responses) {
 
   // Database
   if (responses.database === "prisma") {
-    deps.push("@prisma/client");
-    databaseDevDeps.push("prisma");
+    deps.push("@prisma/client@^6");
+    databaseDevDeps.push("prisma@^6");
     if (responses.language === "ts") {
       databaseDevDeps.push("tsx");
     }

package/src/engine/capabilities.js

@@ -60,7 +60,7 @@ export const FRAMEWORK_CAPABILITIES = {
       CAPABILITIES.DOCKER,
       CAPABILITIES.ROUTE_GROUPS,
     ],
-    allowedArchitectures: ["feature-based", "hybrid", "none"],
+    allowedArchitectures: ["feature-based", "none"],
     allowedStyling: ["tailwind", "none"],
     allowedUiKits: ["shadcn", "none"],
     allowedLanguages: ["ts", "js"],
@@ -85,7 +85,7 @@ export const FRAMEWORK_CAPABILITIES = {
       CAPABILITIES.DATABASE,
       CAPABILITIES.DOCKER,
     ],
-    allowedArchitectures: ["feature-based", "hybrid", "none"],
+    allowedArchitectures: ["feature-based", "none"],
     allowedStyling: ["tailwind", "none"],
     allowedUiKits: ["shadcn", "none"],
     allowedLanguages: ["ts", "js"],

package/src/engine/composition.js

@@ -166,7 +166,7 @@ export function resolveFragments(responses = {}, templatesDir) {
   });
 
   // =========================================================================
-  // Layer 3: Architecture (feature-based / type-based / hybrid / none)
+  // Layer 3: Architecture (feature-based / type-based / none)
   // =========================================================================
   const archSrcDir = path.join(templatesDir, "architectures", architecture, "src");
   const archMainSrc = path.join(templatesDir, "architectures", architecture, `main.${ext}`);
@@ -178,6 +178,11 @@ export function resolveFragments(responses = {}, templatesDir) {
     targetDir: "src",
     action: async ({ projectPath }) => {
       if (fw.name === "next") {
+        try { await fsp.rm(path.join(projectPath, "src", "main.tsx"), { force: true }); } catch {}
+        try { await fsp.rm(path.join(projectPath, "src", "main.jsx"), { force: true }); } catch {}
+        try { await fsp.rm(path.join(projectPath, "src", "App.tsx"), { force: true }); } catch {}
+        try { await fsp.rm(path.join(projectPath, "src", "App.jsx"), { force: true }); } catch {}
+        try { await fsp.rm(path.join(projectPath, "src", "App.css"), { force: true }); } catch {}
         if (fw.variant === "pages-router") {
           try { await fsp.rm(path.join(projectPath, "src", "app"), { recursive: true, force: true }); } catch {}
         } else {
@@ -379,6 +384,7 @@ export function resolveFragments(responses = {}, templatesDir) {
         "db:push": "prisma db push",
         "db:seed": "prisma db seed",
         "db:studio": "prisma studio",
+        postinstall: "prisma generate",
       },
       action: async ({ projectPath, templatesDir: tDir }) => {
         const prismaTplDir = path.join(tDir, "conditional", "database", "prisma");
@@ -428,9 +434,14 @@ export function resolveFragments(responses = {}, templatesDir) {
         const envExamplePath = path.join(projectPath, ".env.example");
         const envLines = [
           "",
-          "# Database (Prisma + PostgreSQL / Supabase)",
-          'DATABASE_URL="postgresql://postgres:[YOUR-PASSWORD]@db.[YOUR-PROJECT-REF].supabase.co:5432/postgres"',
-          'DIRECT_URL="postgresql://postgres:[YOUR-PASSWORD]@db.[YOUR-PROJECT-REF].supabase.co:5432/postgres"',
+          "# Database (Prisma + PostgreSQL)",
+          "# Local development with PostgreSQL or Docker compose (docker compose up -d db):",
+          'DATABASE_URL="postgresql://postgres:postgres@localhost:5432/app?schema=public"',
+          'DIRECT_URL="postgresql://postgres:postgres@localhost:5432/app?schema=public"',
+          "",
+          "# Supabase / cloud PostgreSQL with connection pooling (Transaction mode / port 6543):",
+          '# DATABASE_URL="postgresql://postgres:[YOUR-PASSWORD]@db.[YOUR-PROJECT-REF].supabase.co:6543/postgres?pgbouncer=true"',
+          '# DIRECT_URL="postgresql://postgres:[YOUR-PASSWORD]@db.[YOUR-PROJECT-REF].supabase.co:5432/postgres"',
         ].join("\n");
         try {
           let envContent = "";
@@ -452,7 +463,7 @@ export function resolveFragments(responses = {}, templatesDir) {
     const testingDir = path.join(templatesDir, "conditional", "testing", testingFramework);
     const testScripts =
       testingFramework === "vitest"
-        ? { test: "vitest", "test:run": "vitest run" }
+        ? { test: "vitest", "test:run": "vitest run", "test:watch": "vitest" }
         : { test: "jest", "test:watch": "jest --watch" };
 
     fragments.push({
@@ -519,7 +530,11 @@ export function resolveFragments(responses = {}, templatesDir) {
           try {
             await fsp.access(testSrc);
             const testDest = path.join(projectPath, "src", "__tests__", `${testFileName}.test.${ext}`);
-            await writeFileRecursive(testDest, await fsp.readFile(testSrc, "utf8"));
+            let testContent = await fsp.readFile(testSrc, "utf8");
+            if (responses.routeGroups === true && fw.variant === "app-router") {
+              testContent = testContent.replace("@/app/page", "@/app/(public)/page");
+            }
+            await writeFileRecursive(testDest, testContent);
           } catch {}
         } else {
           // Architecture-scoped test file
@@ -578,14 +593,24 @@ export function resolveFragments(responses = {}, templatesDir) {
       },
     });
   } else if (responses.linter === "biome") {
+    const isBiomeFormatter =
+      !responses.formatter ||
+      responses.formatter === "none" ||
+      responses.formatter === "biome";
+    const biomeScripts = {
+      lint: "biome check .",
+      "lint:fix": "biome check --write .",
+    };
+    if (isBiomeFormatter) {
+      biomeScripts.format = "biome check --write .";
+      biomeScripts["format:check"] = "biome check .";
+    }
+
     fragments.push({
       scope: FRAGMENT_SCOPES.TOOLING,
       category: "linter",
       id: "tooling:linter:biome",
-      scripts: {
-        lint: "biome check .",
-        "lint:fix": "biome check --write .",
-      },
+      scripts: biomeScripts,
       action: async ({ projectPath }) => {
         const configSrc = path.join(templatesDir, "conditional", "linting", "biome", "biome.json");
         try {
@@ -729,6 +754,19 @@ export function resolveFragments(responses = {}, templatesDir) {
         try {
           await fsp.rm(path.join(projectPath, "src", "app", "page.tsx"), { force: true });
         } catch {}
+        try {
+          await fsp.rm(path.join(projectPath, "src", "app", "page.module.css"), { force: true });
+        } catch {}
+        // Adjust existing test file if it imported @/app/page before route groups was applied
+        for (const testExt of ["tsx", "jsx", "ts", "js"]) {
+          const testPath = path.join(projectPath, "src", "__tests__", `page.test.${testExt}`);
+          try {
+            const content = await fsp.readFile(testPath, "utf8");
+            if (content.includes("@/app/page")) {
+              await fsp.writeFile(testPath, content.replace(/@\/app\/page/g, "@/app/(public)/page"), "utf8");
+            }
+          } catch {}
+        }
       },
     });
   }