create-lumen 2.0.0-alpha.0 → 2.0.0-alpha.1

package/README.md

@@ -72,7 +72,7 @@ create-lumen my-app      # after npm link
 - Optional testing: Vitest or Jest
 - 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
+- Manifest v2: Emits a deterministic `lumen.config.json` (optional but recommended) 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`
@@ -187,15 +187,30 @@ src/
 
 `create-lumen` is part of the Lumen ecosystem alongside **`lumen-cli`**:
 
-- **`create-lumen` (this repo):** The bootstrap scaffolder that initializes project repositories and writes an explicit, strictly validated `lumen.config.json` manifest (`manifestVersion: 2`) into the project root.
-- **`lumen-cli`:** The companion developer CLI that reads `lumen.config.json` to generate components, features, hooks, and services at the paths declared in `manifest.paths`.
+- **`create-lumen` (this repo):** The bootstrap scaffolder that initializes project repositories and writes an explicit, strictly validated `lumen.config.json` manifest (`manifestVersion: 2`) into the project root. The manifest is **optional but highly recommended** for full editor integration and agent interoperability. If omitted, `lumen-cli` will attempt to infer a basic configuration, but advanced features (like configurable harness and architecture validation) require the manifest.
+- **`lumen-cli`:** The companion developer CLI that reads `lumen.config.json` to generate components, features, hooks, services, and run diagnostics (harness and doctor) at the paths declared in `manifest.paths`. It also provides commands to inspect and update the manifest.
+
+### Manifest v2 Schema (v2.0.0-alpha.1+)
+
+The manifest now includes:
+- **`architecture.preset`**: The base architecture (`feature-based`, `type-based`, `hybrid`, `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.
 
 ### Ecosystem Documentation & Contracts
 
-- **[Manifest v2 Overview](./docs/manifest-v2.md):** Specification of the nested schema and validation behavior.
-- **[Shared Contract: `create-lumen` ↔ `lumen-cli`](./docs/contracts/manifest-v2-contract.md):** The agreed contract for path mapping, barrel conventions, and version negotiation.
+- **[Manifest v2 Overview](./docs/manifest-v2.md):** Specification of the nested schema, validation behavior, and the new harness and architecture validation fields.
+- **[Shared Contract: `create-lumen` ↔ `lumen-cli`](./docs/contracts/manifest-v2-contract.md):** The agreed contract for path mapping, barrel conventions, version negotiation, and the harness/configuration interface.
 - **[v1 to v2 Migration Guide](./docs/migration/v1-to-v2.md):** Complete guide for migrating generated projects and legacy flat configs to v2.
 
+### 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.
+
 ## Roadmap & Planning
 
 - **Changelog:** Notable changes are documented in [`docs/CHANGELOG.md`](./docs/CHANGELOG.md) (Keep a Changelog format).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-lumen",
-  "version": "2.0.0-alpha.0",
+  "version": "2.0.0-alpha.1",
   "description": "Scaffold a React + Vite project with architecture choice: feature-based or type-based.",
   "type": "module",
   "bin": {
@@ -15,6 +15,7 @@
     "register.js",
     "src/",
     "templates/",
+    "skills/",
     "schema/",
     "README.md",
     "LICENSE"

package/schema/fixtures/v2/invalid/architecture-preset-type-mismatch.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://lumen-sh.github.io/create-lumen/schema/lumen.config.v2.json",
+  "manifestVersion": 2,
+  "framework": {
+    "name": "react",
+    "variant": "vite"
+  },
+  "styling": {
+    "engine": "tailwind"
+  },
+  "architecture": {
+    "preset": "feature-based",
+    "type": "type-based",
+    "validation": "strict"
+  },
+  "ui": {
+    "kit": "none"
+  },
+  "docs": {
+    "language": "en"
+  },
+  "paths": {
+    "features": "src/features",
+    "components": "src/shared/components",
+    "services": "src/shared/services",
+    "hooks": "src/shared/hooks",
+    "pages": "src/app/router",
+    "ui": "src/shared/components/ui"
+  },
+  "tooling": {
+    "language": "ts",
+    "linter": "eslint",
+    "formatter": "prettier"
+  }
+}

package/schema/fixtures/v2/invalid/harness-empty-commands.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://lumen-sh.github.io/create-lumen/schema/lumen.config.v2.json",
+  "manifestVersion": 2,
+  "framework": {
+    "name": "react",
+    "variant": "vite"
+  },
+  "styling": {
+    "engine": "tailwind"
+  },
+  "architecture": {
+    "preset": "feature-based",
+    "validation": "strict"
+  },
+  "harness": {
+    "commands": []
+  },
+  "ui": {
+    "kit": "none"
+  },
+  "docs": {
+    "language": "en"
+  },
+  "paths": {
+    "features": "src/features",
+    "components": "src/shared/components",
+    "services": "src/shared/services",
+    "hooks": "src/shared/hooks",
+    "pages": "src/app/router",
+    "ui": "src/shared/components/ui"
+  },
+  "tooling": {
+    "language": "ts",
+    "linter": "eslint",
+    "formatter": "prettier"
+  }
+}

package/schema/fixtures/v2/invalid/harness-missing-command.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://lumen-sh.github.io/create-lumen/schema/lumen.config.v2.json",
+  "manifestVersion": 2,
+  "framework": {
+    "name": "react",
+    "variant": "vite"
+  },
+  "styling": {
+    "engine": "tailwind"
+  },
+  "architecture": {
+    "preset": "feature-based",
+    "validation": "strict"
+  },
+  "harness": {
+    "commands": [
+      { "name": "lint", "required": true },
+      { "name": "test", "command": "vitest run", "required": true },
+      { "name": "build", "command": "npm run build", "required": true }
+    ]
+  },
+  "ui": {
+    "kit": "none"
+  },
+  "docs": {
+    "language": "en"
+  },
+  "paths": {
+    "features": "src/features",
+    "components": "src/shared/components",
+    "services": "src/shared/services",
+    "hooks": "src/shared/hooks",
+    "pages": "src/app/router",
+    "ui": "src/shared/components/ui"
+  },
+  "tooling": {
+    "language": "ts",
+    "linter": "eslint",
+    "formatter": "prettier"
+  }
+}

package/schema/fixtures/v2/invalid/invalid-validation-mode.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://lumen-sh.github.io/create-lumen/schema/lumen.config.v2.json",
+  "manifestVersion": 2,
+  "framework": {
+    "name": "react",
+    "variant": "vite"
+  },
+  "styling": {
+    "engine": "tailwind"
+  },
+  "architecture": {
+    "preset": "feature-based",
+    "validation": "super-strict"
+  },
+  "ui": {
+    "kit": "none"
+  },
+  "docs": {
+    "language": "en"
+  },
+  "paths": {
+    "features": "src/features",
+    "components": "src/shared/components",
+    "services": "src/shared/services",
+    "hooks": "src/shared/hooks",
+    "pages": "src/app/router",
+    "ui": "src/shared/components/ui"
+  },
+  "tooling": {
+    "language": "ts",
+    "linter": "eslint",
+    "formatter": "prettier"
+  }
+}

package/schema/fixtures/v2/valid/harness-full.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://lumen-sh.github.io/create-lumen/schema/lumen.config.v2.json",
+  "manifestVersion": 2,
+  "framework": {
+    "name": "react",
+    "variant": "vite"
+  },
+  "styling": {
+    "engine": "tailwind"
+  },
+  "architecture": {
+    "preset": "feature-based",
+    "type": "feature-based",
+    "validation": "strict"
+  },
+  "harness": {
+    "commands": [
+      { "name": "lint", "command": "oxlint .", "required": true },
+      { "name": "format", "command": "oxfmt --check .", "required": true },
+      { "name": "types", "command": "tsc -b", "required": true },
+      { "name": "test", "command": "vitest run", "required": true },
+      { "name": "build", "command": "npm run build", "required": true }
+    ]
+  },
+  "ui": {
+    "kit": "none"
+  },
+  "docs": {
+    "language": "en"
+  },
+  "paths": {
+    "features": "src/features",
+    "components": "src/shared/components",
+    "services": "src/shared/services",
+    "hooks": "src/shared/hooks",
+    "pages": "src/app/router",
+    "ui": "src/shared/components/ui"
+  },
+  "tooling": {
+    "language": "ts",
+    "linter": "eslint",
+    "formatter": "prettier"
+  }
+}

package/schema/fixtures/v2/valid/validation-none.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://lumen-sh.github.io/create-lumen/schema/lumen.config.v2.json",
+  "manifestVersion": 2,
+  "framework": {
+    "name": "react",
+    "variant": "vite"
+  },
+  "styling": {
+    "engine": "tailwind"
+  },
+  "architecture": {
+    "preset": "feature-based",
+    "validation": "none"
+  },
+  "harness": {
+    "commands": [
+      { "name": "lint", "command": "oxlint .", "required": true },
+      { "name": "test", "command": "vitest run", "required": true },
+      { "name": "build", "command": "npm run build", "required": true }
+    ]
+  },
+  "ui": {
+    "kit": "none"
+  },
+  "docs": {
+    "language": "en"
+  },
+  "paths": {
+    "features": "src/features",
+    "components": "src/shared/components",
+    "services": "src/shared/services",
+    "hooks": "src/shared/hooks",
+    "pages": "src/app/router",
+    "ui": "src/shared/components/ui"
+  },
+  "tooling": {
+    "language": "ts",
+    "linter": "eslint",
+    "formatter": "prettier"
+  }
+}

package/schema/fixtures/v2/valid/validation-relaxed.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://lumen-sh.github.io/create-lumen/schema/lumen.config.v2.json",
+  "manifestVersion": 2,
+  "framework": {
+    "name": "react",
+    "variant": "vite"
+  },
+  "styling": {
+    "engine": "tailwind"
+  },
+  "architecture": {
+    "preset": "feature-based",
+    "validation": "relaxed"
+  },
+  "harness": {
+    "commands": [
+      { "name": "lint", "command": "oxlint .", "required": true },
+      { "name": "test", "command": "vitest run", "required": true },
+      { "name": "build", "command": "npm run build", "required": true }
+    ]
+  },
+  "ui": {
+    "kit": "none"
+  },
+  "docs": {
+    "language": "en"
+  },
+  "paths": {
+    "features": "src/features",
+    "components": "src/shared/components",
+    "services": "src/shared/services",
+    "hooks": "src/shared/hooks",
+    "pages": "src/app/router",
+    "ui": "src/shared/components/ui"
+  },
+  "tooling": {
+    "language": "ts",
+    "linter": "eslint",
+    "formatter": "prettier"
+  }
+}

package/schema/lumen.config.v2.json

@@ -75,6 +75,15 @@
     "architecture": {
       "type": "object",
       "properties": {
+        "preset": {
+          "type": "string",
+          "enum": [
+            "feature-based",
+            "type-based",
+            "hybrid",
+            "none"
+          ]
+        },
         "type": {
           "type": "string",
           "enum": [
@@ -83,10 +92,54 @@
             "hybrid",
             "none"
           ]
+        },
+        "validation": {
+          "default": "strict",
+          "type": "string",
+          "enum": [
+            "strict",
+            "relaxed",
+            "none"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "harness": {
+      "type": "object",
+      "properties": {
+        "commands": {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "minLength": 1
+              },
+              "command": {
+                "type": "string",
+                "minLength": 1
+              },
+              "required": {
+                "default": true,
+                "type": "boolean"
+              },
+              "description": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "name",
+              "command"
+            ],
+            "additionalProperties": false
+          }
         }
       },
       "required": [
-        "type"
+        "commands"
       ],
       "additionalProperties": false
     },

package/skills/create-lumen/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: create-lumen
+description: Scaffold and extend a lumen v2 project (manifestVersion 2). Read lumen.config.json, resolve generator paths via manifest.paths, respect feature barrels, @/* alias, harness commands, and validation modes.
+---
+
+# create-lumen
+
+## When to use
+
+Use this skill when the working directory contains (or should contain) a
+`lumen.config.json` with `manifestVersion: 2`: scaffolding follow-ups,
+`lumen g` generation, `lumen doctor` / `lumen harness` diagnostics.
+
+Do NOT guess layout. Every target directory comes from the manifest.
+
+## 1. Read `lumen.config.json`
+
+```bash
+cat lumen.config.json
+```
+
+Required top-level keys: `manifestVersion: 2`, `framework`, `styling`,
+`architecture`, `ui`, `docs`, `paths`, `tooling`, `harness`.
+Source of truth: `src/manifest/schema.js` (`parseManifest`, Zod strict).
+Full spec: `docs/contracts/manifest-v2-contract.md`, `docs/manifest-v2.md`.
+
+If `manifestVersion` is missing / `framework` is a string → **v1 manifest**:
+fail fast (exit 1), generate nothing, point to
+`docs/migration/v1-to-v2.md`.
+
+## 2. Resolve paths via `manifest.paths` (never hardcode)
+
+Generators MUST do `<root>/<manifest.paths.<key>>`. POSIX `/` separators.
+
+| Framework | Preset | features | components | services | hooks | pages | ui |
+|---|---|---|---|---|---|---|---|
+| React+Vite | `feature-based` | `src/features` | `src/shared/components` | `src/shared/services` | `src/shared/hooks` | `src/app/router` | `src/shared/components/ui` |
+| React+Vite | `type-based` | `src/features` | `src/components` | `src/services` | `src/hooks` | `src/pages` | `src/ui` |
+| Next App | `feature-based`/`hybrid` | `src/features` | `src/shared/components` | `src/shared/services` | `src/shared/hooks` | `app` | `src/shared/components/ui` |
+| Next Pages | `feature-based` | `src/features` | `src/shared/components` | `src/shared/services` | `src/shared/hooks` | `pages` | `src/shared/components/ui` |
+| Any | `none` | `src` | `src` (`components/` for Next) | `src/services` | `src/hooks` | per framework | `src…/ui` |
+
+Resolver: `src/manifest/paths.js` (`resolvePaths`). Fixtures:
+`schema/fixtures/v2/valid/react-vite-feature-based.json`,
+`full-kitchen-sink.json`.
+
+## 3. Feature structure + barrels
+
+New feature at `<paths.features>/<name>/` (e.g. `src/features/billing`):
+
+```bash
+lumen g feature billing
+lumen g component billing/InvoiceCard --feature billing
+lumen g hook useBilling --feature billing
+lumen g service billing-api --feature billing
+```
+
+Rules:
+
+- Private subfolders: `components/ hooks/ layouts/ pages/ services/ store/ types/`.
+- Public barrel required: `<feature>/index.ts` (or `.js` when
+  `tooling.language === "js"`). External code imports only the barrel:
+  `import { InvoiceCard } from "@/features/billing"`.
+- Extensions: `.tsx`/`.jsx` for JSX components, `.ts`/`.js` for pure logic,
+  per `tooling.language`.
+
+## 4. Path alias `@/*`
+
+`@/*` → `<root>/src/*` (guaranteed by `tsconfig` + Vite/Next config).
+Feature-based: shared imports via `@/shared/...`.
+Type-based: `@/components/...`, `@/hooks/...`, `@/services/...`.
+
+```ts
+import { Button } from "@/shared/components/ui/button";
+import { useBilling } from "@/features/billing";
+```
+
+## 5. `harness.commands` execution
+
+`lumen harness` runs each entry in order; `required: true` (default) fails
+the run on error, `required: false` warns and continues.
+
+```json
+{ "name": "lint", "command": "oxlint .", "required": true }
+```
+
+Defaults: `lint (oxlint .)`, `format (oxfmt --check .)`, `types (tsc -b)`,
+`test (vitest run)`, `build (npm run build)`.
+
+## 6. `architecture.validation` modes
+
+| Mode | Behavior |
+|---|---|
+| `strict` | Enforce barrels, encapsulation, path rules; fail on violation. |
+| `relaxed` | Warn on violation, still generate. |
+| `none` | Skip architecture checks. |
+
+Note: `architecture.preset` is canonical; legacy `type` is accepted as an
+alias (`parseManifest` normalizes both). Valid presets: React →
+`feature-based|type-based|none`; Next → `feature-based|hybrid|none`.
+
+## 7. Common errors — reject, don't patch around
+
+- **v1 rejection:** flat config (`css`, string `framework`/`architecture`) →
+  exit 1 + migration pointer. Never partially generate.
+- **`shadcn` → `tailwind`:** `ui.kit: "shadcn"` requires
+  `styling.engine: "tailwind"` (v4 CSS-first, no `tailwind.config.js`).
+- **`bundler`/`adapter` Next-only:** `framework.bundler` (`turbopack|webpack`)
+  and `adapter` (`node|vercel|cloudflare|static`) are prohibited on `react`.
+  `react` variant MUST be `vite`; `next` MUST be `app-router|pages-router`.

package/skills/create-lumen/references/manifest-v2.md

@@ -0,0 +1,9 @@
+# manifest-v2 pointer
+
+Canonical spec lives in `docs/` — do not duplicate it here.
+
+- Contract: `docs/contracts/manifest-v2-contract.md`
+- Shape / v1→v2 diff: `docs/manifest-v2.md`
+- Zod source of truth: `src/manifest/schema.js`
+- Path resolver: `src/manifest/paths.js`
+- Valid fixtures: `schema/fixtures/v2/valid/`

package/src/agent-context.js

@@ -0,0 +1,114 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { buildManifest } from "./manifest/emit.js";
+
+const VALIDATION_NOTES = {
+  strict: "strict: architecture boundaries are enforced — do not import across features except via barrels or shared paths; violations must be fixed.",
+  relaxed: "relaxed: architecture boundaries are advisory — prefer barrels and shared paths, but cross-imports only warn.",
+  none: "none: no architecture validation — paths are still the canonical locations.",
+};
+
+function resolveManifest(manifestOrResponses) {
+  if (manifestOrResponses && typeof manifestOrResponses.manifestVersion !== "undefined") {
+    return manifestOrResponses;
+  }
+  if (manifestOrResponses && manifestOrResponses._manifestSource) {
+    return manifestOrResponses._manifestSource;
+  }
+  return buildManifest(manifestOrResponses);
+}
+
+/**
+ * Render the short agent conventions markdown from a manifest.
+ * Deterministic: derived only from stable manifest fields.
+ * @param {object} manifest - validated manifest v2
+ * @returns {string}
+ */
+export function renderConventions(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 pathLines = Object.entries(paths)
+    .map(([key, value]) => `- ${key}: \`${value}\``)
+    .join("\n");
+
+  const harnessLines = (harness.commands ?? [])
+    .map((c) => `- \`${c.name}\`: \`${c.command}\` (${c.required === false ? "optional" : "required"})`)
+    .join("\n");
+
+  const harnessSummary = (harness.commands ?? []).map((c) => `\`${c.command}\``).join(", ");
+
+  return (
+    `# Lumen Agent Conventions\n` +
+    `\n` +
+    `Generated from \`lumen.config.json\`. Resolve every file location via \`paths.*\` in \`.lumen/architecture.json\` (preset: \`${preset}\`, validation: \`${validation}\`).\n` +
+    `\n` +
+    `## Rules\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` +
+    `\n` +
+    `## Paths\n` +
+    `\n` +
+    `${pathLines}\n` +
+    `\n` +
+    `## Harness\n` +
+    `\n` +
+    `${harnessLines}\n`
+  );
+}
+
+/**
+ * Build the deterministic agent-context payload from a validated manifest v2.
+ * No timestamps — output must be byte-stable.
+ * @param {object} manifest - validated manifest v2
+ * @returns {{ project: object, architecture: object, 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 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).
+ * @param {string} projectPath - absolute path to scaffolded project
+ * @param {object} manifestOrResponses
+ * @returns {Promise<string>} absolute path to the .lumen dir
+ */
+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;
+}

package/src/main.js

@@ -17,6 +17,7 @@ import { installAllDeps } from "@/dependencies.js";
 import { generateReadme } from "@/readme.js";
 import { runProjectFormat } from "@/format.js";
 import { emitManifest } from "@/manifest/emit.js";
+import { emitAgentContext } from "@/agent-context.js";
 
 import { parseCliArgs, loadManifestSource, manifestToResponses, PRESETS } from "@/cli-args.js";
 
@@ -247,6 +248,19 @@ export async function main(options = {}) {
     throw err;
   }
 
+  // 12.7 Emit .lumen agent context dir (only when agentDocs is enabled)
+  if (responses.agentDocs === true || responses._manifestSource?.agentDocs === true) {
+    const agentSpin = spinner();
+    agentSpin.start("Writing .lumen agent context...");
+    try {
+      await emitAgentContext(projectPath, responses._manifestSource ?? responses);
+      agentSpin.stop(chalk.green(".lumen agent context written."));
+    } catch (err) {
+      agentSpin.stop(chalk.red("Failed to write .lumen agent context."));
+      throw err;
+    }
+  }
+
   // 13. Generate README.md + LICENSE (if requested)
   if (responses.readme) {
     const readmeSpin = spinner();

package/src/manifest/emit.js

@@ -1,8 +1,43 @@
 import { promises as fsp } from "fs";
 import path from "path";
-import { parseManifest, SCHEMA_URL, MANIFEST_VERSION } from "./schema.js";
+import { parseManifest, SCHEMA_URL, MANIFEST_VERSION, HARNESS_DEFAULT_COMMANDS } from "./schema.js";
 import { resolvePaths } from "./paths.js";
 
+const LINT_COMMANDS = {
+  eslint: "eslint .",
+  oxlint: "oxlint .",
+  biome: "biome check .",
+};
+
+const FORMAT_COMMANDS = {
+  prettier: "prettier --check .",
+  oxfmt: "oxfmt --check .",
+};
+
+/**
+ * Build default harness commands from tooling choices.
+ * Skips lint/format when tooling is "none"; skips types when language is not "ts".
+ * Test + build are always included so commands.length >= 1.
+ * @param {{ linter?: string, formatter?: string, language?: string }} tooling
+ * @returns {Array<{ name: string, command: string, required: boolean }>}
+ */
+export function defaultHarnessCommands(tooling = {}) {
+  const { linter = "none", formatter = "none", language = "ts" } = tooling;
+  const commands = [];
+  if (linter && linter !== "none" && LINT_COMMANDS[linter]) {
+    commands.push({ name: "lint", command: LINT_COMMANDS[linter], required: true });
+  }
+  if (formatter && formatter !== "none" && FORMAT_COMMANDS[formatter]) {
+    commands.push({ name: "format", command: FORMAT_COMMANDS[formatter], required: true });
+  }
+  if (language === "ts") {
+    commands.push({ name: "types", command: "tsc -b", required: true });
+  }
+  commands.push({ name: "test", command: "vitest run", required: true });
+  commands.push({ name: "build", command: "npm run build", required: true });
+  return commands.length > 0 ? commands : [...HARNESS_DEFAULT_COMMANDS];
+}
+
 /**
  * Build an ordered manifest v2 object from scaffolder responses.
  * Stable key ordering for byte-determinism.
@@ -35,9 +70,14 @@ export function buildManifest(responses, opts = {}) {
     engine: responses.cssFramework || "tailwind",
   };
 
-  const rawArch = responses.architecture || "feature-based";
+  const rawArch =
+    responses.architecturePreset || responses.architecture || "feature-based";
+  const normalizedArch = rawArch === "component-based" ? "type-based" : rawArch;
   const architecture = {
-    type: rawArch === "component-based" ? "type-based" : rawArch,
+    preset: normalizedArch,
+    type: normalizedArch,
+    validation:
+      responses.architectureValidation || responses.validation || "strict",
   };
 
   const ui = {
@@ -59,12 +99,17 @@ export function buildManifest(responses, opts = {}) {
     formatter: responses.formatter || "none",
   };
 
+  const harness = responses.harness ?? {
+    commands: defaultHarnessCommands(tooling),
+  };
+
   const manifest = {
     $schema: SCHEMA_URL,
     manifestVersion: MANIFEST_VERSION,
     framework,
     styling,
     architecture,
+    harness,
     ui,
     docs,
     paths,
@@ -83,6 +128,7 @@ export function buildManifest(responses, opts = {}) {
     "framework",
     "styling",
     "architecture",
+    "harness",
     "ui",
     "docs",
     "paths",

package/src/manifest/schema.js

@@ -13,7 +13,11 @@ export const FRAMEWORK_BUNDLERS = ["turbopack", "webpack"];
 export const FRAMEWORK_ADAPTERS = ["node", "vercel", "cloudflare", "static"];
 
 export const STYLING_ENGINES = ["tailwind", "bootstrap", "none"];
-export const ARCHITECTURE_TYPES = ["feature-based", "type-based", "hybrid", "none"];
+export const ARCHITECTURE_PRESETS = ["feature-based", "type-based", "hybrid", "none"];
+// Legacy alias: docs used architecture.type, canonical is architecture.preset.
+// Keep both in sync; parseManifest normalizes to expose both keys.
+export const ARCHITECTURE_TYPES = ARCHITECTURE_PRESETS;
+export const ARCHITECTURE_VALIDATIONS = ["strict", "relaxed", "none"];
 export const UI_KITS = ["shadcn", "none"];
 export const DOCS_LANGUAGES = ["en", "es"];
 export const TOOLING_LANGUAGES = ["ts", "js"];
@@ -40,7 +44,49 @@ const stylingSchema = z
 
 const architectureSchema = z
   .object({
-    type: z.enum(ARCHITECTURE_TYPES),
+    // Canonical key per docs/manifest-v2.md; legacy `type` kept as alias.
+    preset: z.enum(ARCHITECTURE_PRESETS).optional(),
+    type: z.enum(ARCHITECTURE_TYPES).optional(),
+    validation: z.enum(ARCHITECTURE_VALIDATIONS).optional().default("strict"),
+  })
+  .strict()
+  .superRefine((val, ctx) => {
+    if (!val.preset && !val.type) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["preset"],
+        message: 'architecture must define "preset" or legacy "type"',
+      });
+    }
+    if (val.preset && val.type && val.preset !== val.type) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["preset"],
+        message: `architecture.preset "${val.preset}" must match architecture.type "${val.type}"`,
+      });
+    }
+  });
+
+export const HARNESS_DEFAULT_COMMANDS = [
+  { name: "lint", command: "oxlint .", required: true },
+  { name: "format", command: "oxfmt --check .", required: true },
+  { name: "types", command: "tsc -b", required: true },
+  { name: "test", command: "vitest run", required: true },
+  { name: "build", command: "npm run build", required: true },
+];
+
+const harnessCommandSchema = z
+  .object({
+    name: z.string().min(1),
+    command: z.string().min(1),
+    required: z.boolean().optional().default(true),
+    description: z.string().optional(),
+  })
+  .strict();
+
+const harnessSchema = z
+  .object({
+    commands: z.array(harnessCommandSchema).min(1),
   })
   .strict();
 
@@ -85,6 +131,7 @@ export const manifestSchemaV2 = z
     framework: frameworkSchema,
     styling: stylingSchema,
     architecture: architectureSchema,
+    harness: harnessSchema.optional(),
     ui: uiSchema,
     docs: docsSchema,
     paths: pathsSchema,
@@ -130,16 +177,17 @@ export const manifestSchemaV2 = z
       });
     }
 
-    // architecture scoping per framework (#34)
+    // architecture scoping per framework (#34) — canonical `preset`, legacy `type` fallback
+    const archValue = architecture.preset ?? architecture.type;
     const allowedByFramework =
       framework.name === "react"
         ? ["feature-based", "type-based", "none"]
         : ["feature-based", "hybrid", "none"];
-    if (!allowedByFramework.includes(architecture.type)) {
+    if (!allowedByFramework.includes(archValue)) {
       ctx.addIssue({
         code: "custom",
         path: ["architecture", "type"],
-        message: `architecture.type "${architecture.type}" is not valid for framework "${framework.name}" (allowed: ${allowedByFramework.join(", ")})`,
+        message: `architecture.type "${archValue}" is not valid for framework "${framework.name}" (allowed: ${allowedByFramework.join(", ")})`,
       });
     }
 
@@ -205,7 +253,17 @@ export function parseManifest(raw) {
     err.cause = result.error;
     throw err;
   }
-  return result.data;
+  // Normalize: always expose architecture.preset + architecture.type (synced)
+  // + architecture.validation default, for backward/forward compat.
+  const data = result.data;
+  const preset = data.architecture.preset ?? data.architecture.type;
+  const type = data.architecture.type ?? data.architecture.preset;
+  data.architecture = {
+    preset,
+    type,
+    validation: data.architecture.validation ?? "strict",
+  };
+  return data;
 }
 
 // Re-export type helper for JSDoc (z.infer)