create-lumen 2.0.0-beta.1 → 2.0.0-beta.3

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.1",
-  "description": "Scaffold a React + Vite project with architecture choice: feature-based, type-based, hybrid, or none.",
+  "version": "2.0.0-beta.3",
+  "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"
           ]
         },
@@ -247,6 +245,36 @@
       ],
       "additionalProperties": false
     },
+    "database": {
+      "type": "object",
+      "properties": {
+        "orm": {
+          "type": "string",
+          "enum": [
+            "prisma",
+            "none"
+          ]
+        },
+        "provider": {
+          "default": "postgresql",
+          "type": "string",
+          "enum": [
+            "postgresql",
+            "supabase"
+          ]
+        }
+      },
+      "required": [
+        "orm"
+      ],
+      "additionalProperties": false
+    },
+    "docker": {
+      "type": "boolean"
+    },
+    "routeGroups": {
+      "type": "boolean"
+    },
     "reactCompiler": {
       "type": "boolean"
     },

package/src/agent-context.js

@@ -19,17 +19,19 @@ function resolveManifest(manifestOrResponses) {
 }
 
 /**
- * Render the short agent conventions markdown from a manifest.
- * Deterministic: derived only from stable manifest fields.
+ * Render the root AGENTS.md document from a manifest.
+ * Single Source of Truth (SSOT): references `lumen.config.json` directly.
+ * Byte-deterministic: derived only from stable manifest fields (no timestamps).
  * @param {object} manifest - validated manifest v2
  * @returns {string}
  */
-export function renderConventions(manifest) {
+export function renderAgentsMd(manifest) {
   const preset = manifest.architecture?.preset ?? manifest.architecture?.type ?? "feature-based";
   const validation = manifest.architecture?.validation ?? "strict";
   const paths = manifest.paths ?? {};
   const harness = manifest.harness ?? { commands: [] };
   const barrelFile = manifest.tooling?.language === "js" ? "index.js" : "index.ts";
+  const isNext = manifest.framework?.name === "next";
 
   const pathLines = Object.entries(paths)
     .map(([key, value]) => `- ${key}: \`${value}\``)
@@ -41,74 +43,96 @@ export function renderConventions(manifest) {
 
   const harnessSummary = (harness.commands ?? []).map((c) => `\`${c.command}\``).join(", ");
 
+  let nextSection = "";
+  if (isNext) {
+    nextSection =
+      `<!-- BEGIN:nextjs-agent-rules -->\n` +
+      `## This is NOT the Next.js you know\n` +
+      `This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory...) before writing any code. Heed deprecation notices.\n` +
+      `<!-- END:nextjs-agent-rules -->\n` +
+      `\n` +
+      `### Next.js Component Rules\n` +
+      `\n` +
+      `- By default, all components in the App Router are React Server Components (RSC).\n` +
+      `- Use the \`"use client"\` directive only at the top of files that require browser APIs, React state, or event handlers.\n` +
+      `- Never import server-only modules or secrets into client components.\n` +
+      `\n`;
+  }
+
+  const uiPath = paths.ui ?? "@/components/ui";
+  const componentsPath = paths.components ?? "@/components";
+
   return (
-    `# Lumen Agent Conventions\n` +
+    `# AGENTS.md\n` +
+    `\n` +
+    `> **Single Source of Truth (SSOT)**: Project configuration, paths, and harness definitions are defined in \`lumen.config.json\`. Consult \`lumen.config.json\` for the authoritative settings.\n` +
     `\n` +
-    `Generated from \`lumen.config.json\`. Resolve every file location via \`paths.*\` in \`.lumen/architecture.json\` (preset: \`${preset}\`, validation: \`${validation}\`).\n` +
+    `${nextSection}` +
+    `## Architecture & Conventions\n` +
     `\n` +
-    `## Rules\n` +
+    `- **Architecture Preset**: \`${preset}\`\n` +
+    `- **Validation Mode**: \`${validation}\` (${VALIDATION_NOTES[validation] ?? VALIDATION_NOTES.strict})\n` +
+    `- **Paths Resolution**: Resolve file locations via \`paths.*\` defined in \`lumen.config.json\` — never hardcode arbitrary alternative locations.\n` +
+    `- **Feature Barrels**: Every feature directory (under \`${paths.features ?? "src/features"}/<feature>/\`) must re-export its public API via \`${barrelFile}\`.\n` +
+    `- **Shared Imports**: Import shared utilities via \`@/shared\` (plus path aliases configured in tsconfig/jsconfig).\n` +
     `\n` +
-    `- Resolve all paths via \`paths.*\` — never hardcode alternative \`src/...\` locations.\n` +
-    `- Feature barrel: every \`src/features/<feature>/\` must re-export its public API via \`${barrelFile}\`.\n` +
-    `- Shared code: import shared utilities via \`@/shared\` (plus the \`@/...\` aliases from tsconfig/jsconfig).\n` +
-    `- Harness: before finishing, run each command in \`.lumen/project.json\` \`harness.commands\` in order (${harnessSummary}).\n` +
-    `- Validation mode \`${validation}\`: ${VALIDATION_NOTES[validation] ?? VALIDATION_NOTES.strict}\n` +
+    `## Component Taxonomy\n` +
     `\n` +
-    `## Paths\n` +
+    `Components must be organized strictly according to \`lumen.config.json\` path mappings:\n` +
+    `- **Atomic UI Primitives**: Base atoms and UI primitives (e.g. shadcn components) belong in \`paths.ui\` (\`${uiPath}\`).\n` +
+    `- **Compound Components**: Shared composite components belong in \`paths.components\` (\`${componentsPath}\`).\n` +
+    `- **Feature Components**: Domain-specific components belong inside their respective feature folder (e.g. \`${paths.features ?? "src/features"}/<feature>/components\`).\n` +
+    `\n` +
+    `Lumen CLI and AI agents must place primitive UI atoms under \`paths.ui\`, global compound components under \`paths.components\`, and feature-scoped components in their respective feature folders.\n` +
+    `\n` +
+    `## Path Mappings\n` +
     `\n` +
     `${pathLines}\n` +
     `\n` +
-    `## Harness\n` +
+    `## Validation Harness\n` +
+    `\n` +
+    `Before finishing work, run each harness command defined in \`lumen.config.json\` \`harness.commands\` in order (${harnessSummary}):\n` +
     `\n` +
     `${harnessLines}\n`
   );
 }
 
 /**
- * Build the deterministic agent-context payload from a validated manifest v2.
- * No timestamps — output must be byte-stable.
+ * Backward compatibility alias for renderAgentsMd.
+ * @param {object} manifest - validated manifest v2
+ * @returns {string}
+ */
+export function renderConventions(manifest) {
+  return renderAgentsMd(manifest);
+}
+
+/**
+ * Build deterministic agent context metadata.
+ * Retained for backwards compatibility with tests and callers.
  * @param {object} manifest - validated manifest v2
- * @returns {{ project: object, architecture: object, conventionsMd: string }}
+ * @returns {{ agentsMd: string, conventionsMd: string }}
  */
 export function buildAgentContext(manifest) {
-  const project = {
-    manifestVersion: manifest.manifestVersion,
-    framework: manifest.framework,
-    styling: manifest.styling,
-    tooling: manifest.tooling,
-    harness: manifest.harness,
-    docs: manifest.docs,
-  };
-  const architecture = {
-    preset: manifest.architecture?.preset ?? manifest.architecture?.type,
-    validation: manifest.architecture?.validation ?? "strict",
-    paths: manifest.paths,
+  const agentsMd = renderAgentsMd(manifest);
+  return {
+    agentsMd,
+    conventionsMd: agentsMd,
   };
-  const conventionsMd = renderConventions(manifest);
-  return { project, architecture, conventionsMd };
-}
-
-function writeJson(filePath, value) {
-  return fsp.writeFile(filePath, JSON.stringify(value, null, 2) + "\n", "utf8");
 }
 
 /**
- * Emit the .lumen agent context dir into a scaffolded project.
- * Accepts either a validated manifest v2 or scaffolder responses
- * (uses responses._manifestSource when present, else buildManifest).
- * Writes .lumen/project.json, .lumen/architecture.json, .lumen/conventions.md
- * with 2-space indent + trailing newline. Byte-deterministic (no timestamps).
+ * Emit AGENTS.md directly into project root.
+ * Accepts either a validated manifest v2 or scaffolder responses.
+ * Writes ${projectPath}/AGENTS.md with trailing newline. Byte-deterministic.
+ * Does not emit duplicate JSON files or .lumen/ directory.
  * @param {string} projectPath - absolute path to scaffolded project
  * @param {object} manifestOrResponses
- * @returns {Promise<string>} absolute path to the .lumen dir
+ * @returns {Promise<string>} absolute path to AGENTS.md
  */
 export async function emitAgentContext(projectPath, manifestOrResponses) {
   const manifest = resolveManifest(manifestOrResponses);
-  const { project, architecture, conventionsMd } = buildAgentContext(manifest);
-  const dir = path.join(projectPath, ".lumen");
-  await fsp.mkdir(dir, { recursive: true });
-  await writeJson(path.join(dir, "project.json"), project);
-  await writeJson(path.join(dir, "architecture.json"), architecture);
-  await fsp.writeFile(path.join(dir, "conventions.md"), conventionsMd, "utf8");
-  return dir;
+  const content = renderAgentsMd(manifest);
+  const filePath = path.join(projectPath, "AGENTS.md");
+  await fsp.writeFile(filePath, content, "utf8");
+  return filePath;
 }

package/src/cleanup.js

@@ -1,7 +1,40 @@
 import { deleteIfExists } from "@/utils/fs.js";
+import { promises as fsp } from "fs";
+import path from "path";
 
-export async function cleanupBoilerplate(projectPath) {
+export async function cleanupBoilerplate(projectPath, responses = {}) {
   await deleteIfExists(`${projectPath}/public`);
   await deleteIfExists(`${projectPath}/src/assets`);
   await deleteIfExists(`${projectPath}/.oxlintrc.json`);
+  await deleteIfExists(`${projectPath}/.provenance.json`);
+
+  const isNext =
+    responses?.framework?.name === "next" ||
+    responses?.frameworkName === "next" ||
+    (await fsp.stat(path.join(projectPath, "next.config.ts")).catch(() => false)) ||
+    (await fsp.stat(path.join(projectPath, "next.config.mjs")).catch(() => false)) ||
+    (await fsp.stat(path.join(projectPath, "next.config.js")).catch(() => false));
+
+  if (isNext) {
+    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`);
+
+    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

@@ -280,11 +280,31 @@ export function parseCliArgs(argv = process.argv.slice(2)) {
       architecture: { type: "string" },
       bundler: { type: "string", short: "b" },
       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" },
+      routeGroups: { type: "boolean" },
       "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 },
     },
@@ -303,9 +323,34 @@ export function parseCliArgs(argv = process.argv.slice(2)) {
 
   const bundler = values.bundler ? values.bundler.trim().toLowerCase() : null;
   const adapter = values.adapter ? values.adapter.trim().toLowerCase() : null;
+  let database = values.database || values.db || null;
+  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,
@@ -314,11 +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,
@@ -368,7 +422,10 @@ export function manifestToResponses(manifest, projectName) {
   const canClientRoute = isPromptVisible(framework, "router");
   const supportsBundler = isPromptVisible(framework, "bundler");
   const supportsAdapter = isPromptVisible(framework, "adapter");
+  const supportsDatabase = isPromptVisible(framework, "database");
   const supportsCompiler = isPromptVisible(framework, "reactCompiler");
+  const supportsRouteGroups = isPromptVisible(framework, "routeGroups");
+  const supportsDocker = isPromptVisible(framework, "docker");
 
   return {
     projectName,
@@ -382,6 +439,14 @@ export function manifestToResponses(manifest, projectName) {
       supportsAdapter && manifest.framework?.adapter
         ? manifest.framework.adapter
         : undefined,
+    database:
+      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",
@@ -390,7 +455,9 @@ export function manifestToResponses(manifest, projectName) {
     uiKit: manifest.ui?.kit || "none",
     docsLanguage: manifest.docs?.language || "en",
     reactCompiler: supportsCompiler ? manifest.reactCompiler : undefined,
+    routeGroups: supportsRouteGroups ? manifest.routeGroups : undefined,
     agentDocs: manifest.agentDocs,
+    docker: supportsDocker ? (manifest.docker ?? false) : false,
     // Sensible defaults for scaffolder conditional passes (Next.js ships no
     // verified test-runner overlay yet, so it defaults to none; explicit
     // vitest/jest selection still applies the standard overlays)
@@ -410,17 +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";