create-win-project 1.3.0 → 1.4.0

package/README.md

@@ -1,15 +1,8 @@
-```
- ██╗    ██╗  ██╗ ███╗  ██╗
- ██║    ██║ ███║ ████╗ ██║
- ██║ █╗ ██║ ╚██║ ██╔██╗██║
- ██║███╗██║  ██║ ██║╚████║
- ╚███╔███╔╝  ██║ ██║ ╚███║
-  ╚══╝╚══╝   ╚═╝ ╚═╝  ╚══╝
-
- █▀█ █▀█ █▀█   █ █▀▀ █▀▀ ▀█▀
- █▀▀ █▀█ █ █   █ █▀  █    █
- █   █ █ █▄█ █▄█ █▄▄ █▄▄  █
-```
+<div align="center">
+  <img src="./public/logo.svg" alt="W1N Project logo" width="160">
+  <h1>W1N PROJECT</h1>
+  <p>Production-ready project scaffolding.</p>
+</div>
 
 # Are you confused creating architecture rules, AGENTS.md, and folder structures from scratch every time you pick a new stack?
 
@@ -19,7 +12,7 @@ Stop bikeshedding folders for 3 days. Stop pasting a 500-line `AGENTS.md` that b
 
 [![CI](https://github.com/itsw1n/create-win-project/actions/workflows/ci.yml/badge.svg)](https://github.com/itsw1n/create-win-project/actions/workflows/ci.yml)
 [![Node](https://img.shields.io/badge/node-24_LTS-green)](https://nodejs.org)
-[![Manifest-driven](https://img.shields.io/badge/architecture-manifest--driven-blue)](./playbooks)
+[![Definition-driven](https://img.shields.io/badge/architecture-definition--driven-blue)](./library)
 [![Lean docs](https://img.shields.io/badge/AGENTS.md-lean%20%26%20lazy-9cf)](./playbooks)
 [![Interactive](https://img.shields.io/badge/cli-interactive-ff69b4)](./index.js)
 
@@ -43,14 +36,14 @@ Manifests declare capabilities and package names. A tested compatibility profile
 ### Lane 1 — To run *this generator*
 **Node 24 LTS *OR* Docker — that's it.**
 
-- No global `prettier`, `eslint`, or `typescript` — they are generated inside your project (`package.json` devDeps + `.prettierrc` + `.editorconfig` + `eslint.config` via `lib/scaffold.js`).
+- No global `prettier`, `eslint`, or `typescript` — each stack generates them inside your project through its own dependency and file contributions.
 - Prefer zero host setup? Use Docker directly. Make is an optional convenience, never a prerequisite.
 
 ### Lane 2 — To run *what it generates* (depends on your answers)
 | You picked | You need | What the generator includes |
 |---|---|---|
-| **Next.js** or **React + Vite** | Node 24 LTS → `npm install` → `npm run dev` | Page/entry, Vite/Next config, strict TS, ESLint, tests, `frontend/.env.example` |
-| **Expo** | Node 24 LTS + Expo Go app → `npm install` → `npx expo start` | Expo Router layout/screen, `app.json`, Jest, TS |
+| **Next.js** or **React + Vite** | Node 22.14+ with npm 11.19+ (tested on Node 24) → `npm install` → `npm run dev` | Page/entry, Vite/Next config, strict TS, ESLint, tests, `frontend/.env.example` |
+| **Expo** | Node 22.14+ with npm 11.19+ (tested on Node 24) + Expo Go app → `npm install` → `npx expo start` | Expo Router layout/screen, `app.json`, Jest, TS |
 | **Supabase** | Docker for the generated local Supabase stack | Pinned local CLI, migrations/RLS tests, platform-native clients; login/callback/secure lifecycle only when login is selected |
 | **Spring Boot / PostgreSQL** | JDK 21 + Docker for DB **only if you selected them** | Maven app, public health + fail-closed security, Flyway/PostgreSQL; server session or OIDC Resource Server when login is selected |
 
@@ -112,6 +105,8 @@ npm run dev
 
 The generator asks whether to install dependencies. One local `npm install` provides Prettier, ESLint, TypeScript, and the selected test tools; global installs are neither required nor silently performed.
 
+Before automatic installation, the CLI checks the current Node, npm, PHP, and Composer versions needed by the selected stack. A mismatch never changes global tools: interactive users can create files without installing, view setup instructions, or cancel; noninteractive runs safely create files and skip installation. Node 22 is supported with npm 11.19 or newer. npm 10.9.8 and early npm 11 releases can crash while resolving current generated dependencies, so switch through Mise/NVM or update that managed Node installation before retrying.
+
 > The generator **never overwrites a non-empty folder** — it stages to a temp dir and moves into place only on success.
 
 ## Features
@@ -122,11 +117,11 @@ The generator asks whether to install dependencies. One local `npm install` prov
 - **Lean agent docs** — `AGENTS.md` (tiny, always on) + `RULES.md` (lazy index) generated per project.
 - **Stack-native profiles** — Small, Medium (recommended/default), and Large map to familiar architecture for each selected stack; Large defaults to a modular monolith, not microservices.
 - **Intent-based authentication** — choose Yes, Not yet, or No; the generator maps that intent to Supabase Auth, Spring server sessions, or external-provider OIDC validation as appropriate.
-- **Manifest-driven** — `*.manifest.json` drives compatibility, exact dependency requests, env prefixes (`NEXT_PUBLIC_`/`VITE_`/`EXPO_PUBLIC_`), conditional playbooks, and concern wiring.
+- **Definition-driven** — `library/**/definition.json` drives compatibility, exact dependency requests, env prefixes (`NEXT_PUBLIC_`/`VITE_`/`EXPO_PUBLIC_`), conditional playbooks, and concern wiring.
 - **Tested compatibility profiles** — exact direct dependencies and runtime/container versions are resolved from one catalog; current and previous profiles are verified in CI.
 - **Optional concerns, never mandated** — validation/Zod, data-fetching, state, t3-env, URL state are advisory (`CONTEXT.md` only) not forced.
 - **Runnable foundations** — profile-specific feature slices, health endpoints, security headers, selected auth plumbing, Spring `ProblemDetail`, PostgreSQL Testcontainers, and risk-based tests.
-- **Safety + contracts** — destination-exists guard, manifest ↔ heading checks, and a generated-output matrix covering every pairing, architecture profile, and applicable auth model.
+- **Safety + contracts** — destination-exists guard, definition ↔ heading checks, and a generated-output matrix covering every pairing, architecture profile, and applicable auth model.
 
 ## What you get
 
@@ -136,7 +131,7 @@ The generator asks whether to install dependencies. One local `npm install` prov
 | `RULES.md` | Lazy index — `concern → playbook §`. Read only what you touch. |
 | `CONTEXT.md` | Project context + any advisory "expected concerns". |
 | `playbooks/` | Curated rule playbooks (shipped lean). |
-| `package.json` | Generated from the selected stack's manifest. |
+| `package.json` | Generated from the selected stack's definition. |
 | `create-win-project.profile.json` | Separately records compatibility, architecture, and authentication selections. |
 | `.env.example` | Generated from the stack's declared env vars (prefixes already applied). |
 | Framework source/config | A working page or screen, health endpoint where applicable, strict TypeScript, lint, tests, and build scripts. |
@@ -144,10 +139,10 @@ The generator asks whether to install dependencies. One local `npm install` prov
 
 ## How it works
 
-The generator never hardcodes the folder or playbook list. It loads `playbooks/**/*.manifest.json` and resolves a *stack*:
+The generator never hardcodes the folder or playbook list. It loads `library/**/definition.json` and resolves a *stack*:
 
 ```jsonc
-// playbooks/stack/nextjs.manifest.json (excerpt)
+// library/stacks/nextjs/definition.json (excerpt)
 {
   "id": "nextjs",
   "kind": "frontend",
@@ -168,19 +163,15 @@ The generator never hardcodes the folder or playbook list. It loads `playbooks/*
 }
 ```
 
-Versions are resolved from `compatibility/profiles.json`; manifests never own them. The current tested profile is the default, while `--profile=YYYY.MM` selects a retained profile explicitly. Add a policy-only concern with a manifest + playbook. A new executable stack also needs a focused `lib/scaffold.js` implementation and a contract test — this prevents docs from advertising code that doesn't exist.
+Versions are resolved from `library/tested-versions.json`; definitions never own them. The current tested profile is the default, while `--profile=YYYY.MM` selects a retained profile explicitly. Add a policy-only concern with a definition + guidance file. A new executable stack also needs a focused stack implementation and a contract test — this prevents docs from advertising code that doesn't exist.
 
 ## Topics
 
-Next.js · React · Spring Boot · Supabase · PostgreSQL · TypeScript · Tailwind CSS · CSS Modules · project scaffolding · project template · `AGENTS.md` · coding agents · manifest-driven · lean documentation · lazy rules index
+Next.js · React · Spring Boot · Supabase · PostgreSQL · TypeScript · Tailwind CSS · CSS Modules · project scaffolding · project template · `AGENTS.md` · coding agents · definition-driven · lean documentation · lazy rules index
 
 ## Contributing
 
-1. Fork and create a feature branch.
-2. `npm install` and `npm test` must stay green.
-3. Add or update a `*.manifest.json` for new stacks/concerns; put package versions only in `compatibility/profiles.json`.
-4. Run `npm run verify:generated -- --profile=2026.09 --case=nextjs-supabase --architecture=medium --authentication=yes` for a focused executable check. CI runs every supported combination, architecture/auth model, and retained profile.
-5. Document migration work for major upgrades, then open a pull request.
+See [docs/CONTRIBUTING.md](./docs/CONTRIBUTING.md) — one workflow for every stack: quick start, 6-step vertical stack addition (`library/**` -> `src/stacks/<id>/` -> `available-stacks.js` -> tests/matrix -> verify), testing gates (`npm test`, `matrix:smoke` -> `dev`, `matrix:full` -> `main`), and version ownership (`library/tested-versions.json` only).
 
 ## License
 

package/{scripts/compatibility-matrix.mjs → checks/check-compatibility.js}

@@ -1,8 +1,10 @@
 import fs from 'fs-extra'
 
-const catalog = await fs.readJson(new URL('../compatibility/profiles.json', import.meta.url))
+const catalog = await fs.readJson(new URL('../library/tested-versions.json', import.meta.url))
 const scope = process.argv.find((arg) => arg.startsWith('--scope='))?.split('=')[1] || 'smoke'
-if (!['smoke', 'full'].includes(scope)) throw new Error('--scope must be smoke or full')
+const selectedStack = process.argv.find((arg) => arg.startsWith('--stack='))?.split('=')[1]
+if (!['none', 'smoke', 'stack', 'full'].includes(scope)) throw new Error('--scope must be none, smoke, stack, or full')
+if (scope === 'stack' && !selectedStack) throw new Error('--stack is required for stack scope')
 
 const cases = [
   'nextjs-none', 'nextjs-supabase', 'nextjs-springboot', 'nextjs-postgres', 'nextjs-laravel',
@@ -25,10 +27,11 @@ function authChoices(caseName) {
 }
 
 const current = catalog.defaultProfile
-const full = Object.entries(catalog.profiles).filter(([profile]) => profile === current).flatMap(([profile, versions]) =>
+const allProfiles = Object.entries(catalog.profiles).flatMap(([profile, versions]) =>
   cases.flatMap((caseName) => ['small', 'medium', 'large'].flatMap((architecture) =>
     authChoices(caseName).map((auth) => ({ profile, case: caseName, architecture, ...auth, node: versions.runtimes.node, java: versions.runtimes.java, php: versions.runtimes.php })))),
 )
+const currentFull = allProfiles.filter((entry) => entry.profile === current)
 
 const smokeSelections = [
   ['nextjs-none', 'small', 'not-yet', 'website'],
@@ -42,7 +45,22 @@ const smokeSelections = [
   ['laravel-inertia-react', 'large', 'yes', 'website'],
   ['react-laravel', 'medium', 'yes', 'website'],
 ]
-const smoke = full.filter((entry) => entry.profile === current && smokeSelections.some(([caseName, architecture, authentication, audience]) =>
-  entry.case === caseName && entry.architecture === architecture && entry.authentication === authentication && entry.audience === audience))
+const matchesSmoke = (entry) => smokeSelections.some(([caseName, architecture, authentication, audience]) =>
+  entry.case === caseName && entry.architecture === architecture && entry.authentication === authentication && entry.audience === audience)
+const smoke = currentFull.filter(matchesSmoke)
+// A complete run exhaustively verifies the current profile and keeps every
+// retained profile alive through the same representative compatibility lanes.
+const full = [...currentFull, ...allProfiles.filter((entry) => entry.profile !== current && matchesSmoke(entry))]
 
-process.stdout.write(JSON.stringify(scope === 'full' ? full : smoke))
+function belongsToStack(caseName, stackName) {
+  if (stackName === 'none') return caseName.endsWith('-none')
+  if (stackName === 'react') return caseName.startsWith('react-')
+  if (stackName === 'react-native') return caseName.startsWith('react-native-')
+  if (['nextjs'].includes(stackName)) return caseName.startsWith(`${stackName}-`)
+  return caseName.includes(stackName)
+}
+
+const stackCases = full.filter((entry) => belongsToStack(entry.case, selectedStack))
+const stack = [...new Map([...stackCases, ...smoke].map((entry) => [JSON.stringify(entry), entry])).values()]
+const selected = scope === 'full' ? full : scope === 'stack' ? stack : smoke
+process.stdout.write(JSON.stringify(selected.map((entry, index) => ({ ...entry, shard: `${index % 4 + 1}/4` }))))

package/{scripts/verify-generated.mjs → checks/check-generated-project.js}

@@ -3,7 +3,7 @@ import os from 'node:os'
 import path from 'node:path'
 import { spawnSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
-import { generateProject } from '../lib/generator.js'
+import { generateProject } from '../src/engine/create-project.js'
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
 const args = Object.fromEntries(process.argv.slice(2).map((arg) => {
@@ -32,7 +32,7 @@ const cases = {
 }
 
 if (!args.profile || !cases[args.case]) {
-  throw new Error(`Usage: node scripts/verify-generated.mjs --profile=<id> --case=<${Object.keys(cases).join('|')}> [--architecture=small|medium|large] [--authentication=yes|not-yet|none] [--auth-audience=website|multi-client]`)
+  throw new Error(`Usage: npm run verify:generated -- --profile=<id> --case=<${Object.keys(cases).join('|')}> [--architecture=small|medium|large] [--authentication=yes|not-yet|none] [--auth-audience=website|multi-client]`)
 }
 
 const architecture = args.architecture || 'medium'

package/{scripts/validate-content.mjs → checks/check-library.js}

@@ -1,18 +1,18 @@
 import fs from 'fs-extra'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { loadCatalog, resolveStack } from '../lib/catalog.js'
-import { buildRulesIndex } from '../lib/playbooks.js'
+import { loadCatalog, resolveStack } from '../src/engine/load-library.js'
+import { buildRulesIndex, resolvePlaybook } from '../src/engine/project-guidance.js'
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
-const playbooksDir = path.join(root, 'playbooks')
+const playbooksDir = path.join(root, 'library')
 const catalog = await loadCatalog(playbooksDir)
 const errors = []
 
 for (const manifest of catalog.manifests) {
   for (const entry of manifest._playbooks || []) {
     const relative = typeof entry === 'string' ? entry : entry.file
-    if (!await fs.pathExists(path.join(playbooksDir, relative))) {
+    if (!await fs.pathExists(await resolvePlaybook(playbooksDir, relative))) {
       errors.push(`${manifest.id}: missing playbook ${relative}`)
     }
   }
@@ -48,7 +48,7 @@ const markdownFiles = (await fs.readdir(playbooksDir, { recursive: true, withFil
 for (const file of markdownFiles) {
   const content = await fs.readFile(file, 'utf8')
   const relative = path.relative(playbooksDir, file)
-  const limit = relative.startsWith('stack/') || relative.startsWith('platform/') || relative.startsWith('capabilities/') ? 250 : 650
+  const limit = relative.startsWith('stacks/') || relative.startsWith('platforms/') || relative.startsWith('features/') ? 250 : 650
   if (content.split('\n').length > limit) errors.push(`${relative}: exceeds ${limit} lines`)
   for (const match of content.matchAll(/\[[^\]]*\]\(([^)]+)\)/g)) {
     const target = match[1].split('#')[0]

package/checks/classify-changes.js

@@ -0,0 +1,39 @@
+import { pathToFileURL } from 'node:url'
+
+const DOCUMENTATION = /^(?:README\.md|LICENSE|docs\/|\.github\/ISSUE_TEMPLATE\/|\.github\/PULL_REQUEST_TEMPLATE)/
+const FULL_IMPACT = /^(?:library\/tested-versions\.json|lib\/(?:generator|scaffold|catalog|compatibility|template)\.js|src\/engine\/|src\/stacks\/shared\/|templates\/(?:docker|gitignore|makefile)\/|checks\/(?:check-compatibility|check-generated-project|classify-changes)\.js|\.github\/workflows\/(?:compatibility|publish)\.yml)/
+
+const STACK_PATHS = [
+  ['nextjs', /^(?:src\/stacks\/frontends\/nextjs\/|library\/stacks\/nextjs\/|templates\/(?:agents|ci)\/nextjs\.)/],
+  ['react', /^(?:src\/stacks\/frontends\/react-vite\/|library\/stacks\/react-vite\/|templates\/(?:agents|ci)\/(?:react-vite|vite)\.)/],
+  ['react-native', /^(?:src\/stacks\/frontends\/react-native\/|library\/stacks\/expo\/|templates\/(?:agents|ci)\/(?:react-native|expo)\.)/],
+  ['springboot', /^(?:src\/stacks\/backends\/springboot\/|library\/(?:stacks\/springboot|features\/(?:flyway|postgresql))\/|templates\/ci\/springboot\.)/],
+  ['laravel', /^(?:src\/stacks\/backends\/laravel\/|library\/(?:stacks\/laravel|platforms\/laravel-ui|features\/laravel)\/|templates\/ci\/laravel\.)/],
+  ['supabase', /^(?:src\/stacks\/backends\/supabase\/|library\/features\/supabase\/)/],
+  ['postgres', /^(?:src\/stacks\/backends\/postgres\/|library\/features\/(?:postgresql|prisma)\/)/],
+  ['none', /^src\/stacks\/backends\/none\//],
+]
+
+export function classifyChanges(files) {
+  const changed = [...new Set(files.map((file) => file.trim()).filter(Boolean))]
+  if (!changed.length || changed.every((file) => DOCUMENTATION.test(file))) return { scope: 'none' }
+  if (changed.some((file) => FULL_IMPACT.test(file))) return { scope: 'full' }
+
+  const stacks = new Set()
+  let hasOrdinaryChange = false
+  for (const file of changed) {
+    const matches = STACK_PATHS.filter(([, pattern]) => pattern.test(file)).map(([stack]) => stack)
+    if (matches.length) matches.forEach((stack) => stacks.add(stack))
+    else if (!DOCUMENTATION.test(file)) hasOrdinaryChange = true
+  }
+  if (!hasOrdinaryChange && stacks.size === 1) return { scope: 'stack', stack: [...stacks][0] }
+  return { scope: 'smoke' }
+}
+
+async function main() {
+  let input = ''
+  for await (const chunk of process.stdin) input += chunk
+  process.stdout.write(JSON.stringify(classifyChanges(input.split(/\r?\n/))))
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) await main()

package/docs/ARCHITECTURE.md

@@ -1,4 +1,4 @@
-# Architecture
+# Architecture (completed — v1.4.0 target)
 
 `create-win-project` composes a validated project specification into two coordinated outputs:
 
@@ -14,40 +14,79 @@ CLI interview
     ↓
 validated answers
     ↓
-manifest catalog + compatibility resolver
+available-stacks + resolve-project + load-library + tested-versions
     ↓
 resolved stack descriptor
-    ├── runnable framework files
-    ├── optional CI / Docker / Makefile files
+    ├── runnable framework files (from src/stacks/*/create-files.js)
+    ├── optional CI / Docker / Makefile files (from templates/)
     ├── project context and documentation
     └── selected playbooks + RULES.md router
     ↓
 generated-project contract tests
 ```
 
-### CLI boundary
+### Source ownership (completed)
 
-`index.js` owns interaction and presentation. It gathers project identity, frontend, optional backend, styling, one Small/Medium/Large architecture profile, login intent, client audience when relevant, testing depth, and optional operational tooling. Medium is shown first and is the default. It does not contain stack dependency tables.
+Three explicit source boundaries. No `lib/` directory exists — `src/` is canonical.
 
-`generateProject()` validates the same answers again because it is also an exported programmatic API. A caller cannot bypass destination-name, Java-package, or testing-profile validation by skipping the CLI.
+- `src/cli` owns terminal arguments, questions and navigation, display, warnings, summaries, and system checks. It may call the engine and read stack descriptions. It must not contain stack dependency tables or `if (stack === "nextjs")` branches.
+- `src/engine` owns validated project orchestration, tested-version and library loading, safe writes, dependency installation, and template rendering. It must not import terminal code or concrete stack folders. It contains zero `stack.frontendKey` branches — it is stack-agnostic.
+- `src/stacks` owns stack rules, the explicit available-stack list, and stack-specific generated behavior. Stack modules must not import CLI or engine implementation modules. Each `src/stacks/<frontends|backends>/<id>/` owns its files, dependencies (names only), environment names, Docker and CI contributions.
 
-### Catalog and resolution
+During the migration `lib/` provided compatibility shims (`export * from '../src/...'`). After v1.4.0 those shims are deleted. `tests/architecture-boundaries.test.js` enforces dependency direction, and `tests/architecture/no-lib-legacy.test.js` bans `src -> lib` imports and one-line wrapper regressions.
+
+Root `index.js` remains the stable executable entry point. Generated-project paths such as `playbooks/`, `RULES.md`, and application folders are user-facing and do not change merely because generator source files move.
+
+### CLI boundary
+
+Root `index.js` is only the stable executable shim. `src/cli/main.js` coordinates the command, `arguments.js` parses and validates flags, `questions.js` defines the interview, `navigation.js` owns Back behavior, `display.js` owns terminal presentation (`w1nBanner` + `projectLocationNotice`), and `system-check.js` detects runtime support and `collectDiagnostics/printDoctor`. The CLI gathers project identity, frontend, optional backend, styling, one Small/Medium/Large architecture profile, login intent, client audience when relevant, testing depth, and optional operational tooling. Medium is shown first and is the default. CLI modules do not contain stack dependency tables.
 
-`lib/catalog.js` loads co-located `*.manifest.json` files and merges selected capabilities into one stack descriptor. `lib/compatibility.js` validates `compatibility/profiles.json` and resolves every package name to an exact version for the selected profile.
+`generateProject()` in `src/engine/create-project.js` validates the same answers again because it is also an exported programmatic API. A caller cannot bypass destination-name, Java-package, or testing-profile validation by skipping the CLI.
 
-Stack-specific behavior crosses into core orchestration through the contract in `lib/stacks/contract.js`. Every frontend, backend, or data adapter has a stable identity, declares compatible adapters and supported application/authentication/architecture models, and is added to the explicit registry. Registration is deliberate; adapters are never discovered by scanning directories.
+### Catalog and resolution
 
-Adapters may contribute data in these areas:
+`src/engine/load-library.js` walks `library/**/definition.json` and merges manifests into a catalog index. `src/engine/tested-versions.js` validates `library/tested-versions.json` and resolves every package name to an exact version for the selected profile. `src/engine/resolve-project.js` merges selected capabilities into one resolved stack descriptor. No versions live in definitions or scaffold code.
+
+Stack-specific behavior crosses into core orchestration through the contract in `src/stacks/rules.js` (`defineStackAdapter`). Every frontend, backend, or data adapter has a stable identity, declares compatible adapters and supported application/authentication/architecture models, and is added to the explicit registry in `src/stacks/available-stacks.js`. Registration is deliberate and explicit — adapters are never discovered by scanning directories; adding a file does not silently activate a stack.
+
+Adapters may contribute via `CONTRIBUTION_HOOKS`:
+
+- `prompts` in a core-defined prompt slot;
+- `authentication` models;
+- `files` via `create-files.js` (`(answers, context) -> FileMap`);
+- `environment` declarations (semantic names like `API_URL`);
+- `install` steps;
+- `docker` and `ci` fragments;
+- `verification` cases.
+
+Example:
+
+```js
+// src/stacks/frontends/nextjs/index.js
+import { defineStackAdapter } from '../../rules.js'
+export const nextjsAdapter = defineStackAdapter({
+  id: 'nextjs', kind: 'frontend', label: 'Next.js',
+  compatibleWith: { backend: ['none','postgres','supabase','springboot','laravel'] },
+  capabilities: { applicationShapes: ['fullstack','separate'], architectureProfiles: ['small','medium','large'], authenticationModels: ['public','undecided','supabase','session','oidc','sanctum-spa','laravel-oidc'] },
+  contributes: {
+    environment: ({ backend }) => backend.id === 'none' ? [] : ['API_URL'],
+    install: () => [{ cwd: '.', command: 'npm', args: ['install'] }],
+    docker: () => [{ template: 'nextjs', developmentPath: 'Dockerfile.dev', productionPath: 'Dockerfile' }],
+    ci: () => [{ template: 'nextjs', path: '.github/workflows/ci-frontend.yml' }],
+  }
+})
+```
 
-- questions in a core-defined prompt slot;
-- authentication models;
-- generated file descriptions;
-- environment declarations;
-- install steps;
-- Docker and CI fragments;
-- verification cases.
+- **Next.js** owns route-oriented Small; feature services/actions/queries and owned repositories or remote API clients in Medium; public feature APIs and enforced boundaries in Large — all in `src/stacks/frontends/nextjs/create-files.js`.
+- **React + Vite** owns thin browser features in Small, feature modules in Medium, and public feature APIs plus boundary checks in Large — in `src/stacks/frontends/react-vite/create-files.js`.
+- **React Native** owns Expo shell, mobile architecture profiles, local install and CI contributions in `src/stacks/frontends/react-native/create-files.js`. It deliberately contributes no frontend Docker workflow.
+- **Spring Boot** owns Maven launcher, application and security configuration, package-by-feature variants, migrations, tests, and runtime Docker/CI in `src/stacks/backends/springboot/create-files.js`.
+- **Laravel** owns composer definition, application files, authentication models, and Blade/Livewire/Inertia React UI variants in `src/stacks/backends/laravel/` — `create-files.js` + `composer.js` + `architecture.js` + `auth/{session,sanctum,oidc,public}.js` + `ui/{blade,livewire,inertia-react,shared}.js`. Names `auth/` and `ui/` are kept (not `login/`/`user-interface`) for conciseness; `create-files.js` is used everywhere for consistency with `create-project.js`.
+- **Supabase** owns framework-specific clients, native token lifecycle, local project config, migrations, RLS policies, and verification in `src/stacks/backends/supabase/` (`create-files.js` + `native.js`).
+- **PostgreSQL + Prisma** owns schema, client initialization, migration commands, database environment, Docker contribution in `src/stacks/backends/postgres/create-files.js`.
+- **no-backend** explicitly owns frontend-only compatibility and confirms no server files, install steps, Docker services, credentials, or pretend authentication are contributed.
 
-Core code owns prompt order, compatibility-profile resolution, atomic writes, process execution, and final composition. An adapter receives a read-only stack context and returns contributions; it cannot write arbitrary paths or install global tools. Adapter definitions do not accept dependency tables or version fields. Exact versions remain exclusively owned by `compatibility/profiles.json`.
+Core code owns prompt order, compatibility-profile resolution, atomic writes, process execution, and final composition. An adapter receives a read-only stack context (`createStackContext`) and returns contributions; it cannot write arbitrary paths or install global tools. Adapter definitions do not accept dependency tables or version fields. Exact versions remain exclusively owned by `library/tested-versions.json`.
 
 Manifests declare:
 
@@ -58,30 +97,23 @@ Manifests declare:
 - constraints shown to the agent;
 - concerns and their playbook sections.
 
-Client environment variables are semantic in manifests (`API_URL`) and receive exactly one framework prefix during resolution (`NEXT_PUBLIC_API_URL`, `VITE_API_URL`, or `EXPO_PUBLIC_API_URL`). Public prefixes always mean the value is shipped to the client.
+Client environment variables are semantic in definitions (`API_URL`) and receive exactly one framework prefix during resolution (`NEXT_PUBLIC_API_URL`, `VITE_API_URL`, or `EXPO_PUBLIC_API_URL`). Public prefixes always mean the value is shipped to the client.
 
-### Runnable scaffold
+### Runnable scaffold (stack-owned vertical)
 
-`lib/scaffold.js` owns the minimum executable vertical slice:
-
-- Next.js: route-oriented Small; familiar feature services/actions/queries and owned repositories or remote API clients in Medium; public feature APIs and enforced boundaries in Large.
-- React + Vite: thin browser features in Small, feature modules in Medium, and public feature APIs plus boundary checks in Large.
-- Expo: screens/data in Small, feature modules in Medium, and boundaries ready for offline sync, background work, and platform adapters in Large.
-- Spring Boot: conventional package-by-feature in Small, explicit API/service/repository ownership in Medium, and a verified Spring Modulith modular monolith in Large.
-
-Authentication is selected during generation. Supabase emits Supabase Auth clients and login examples; website-only Spring uses a secure server-managed session; multi-client Spring emits an OIDC Resource Server and delegates issuance, refresh, and revocation to the identity provider. `Not yet` is fail-closed for Spring and never emits pretend authentication. Existing projects are never told to rerun the generator to add auth.
-
-This module intentionally generates a small working example. Domain-specific features are added after product context is known; the generator does not invent business entities.
+Each `src/stacks/{frontends,backends}/<id>/create-files.js` is a pure function `(answers, stack, shared) -> FileMap` that owns its minimum executable vertical slice. `shared/` contains helpers only when at least two stacks genuinely share behavior—not forced sharing. Core composes stack adapters through their contribution hooks. This intentionally generates a small working example. Domain-specific features are added after product context is known; the generator does not invent business entities.
 
 ### Repository and operational files
 
-`lib/generator.js` coordinates writes and refuses to merge into a non-empty destination. It adds documentation, selected playbooks, CI, Docker, Makefile, environment examples, and repository conventions around the runnable foundation.
+`src/engine/create-project.js` coordinates writes and refuses to merge into a non-empty destination. It adds documentation, selected playbooks, CI, Docker, Makefile, environment examples, and repository conventions around the runnable foundation.
+
+Engine infrastructure is separated from generated-file decisions. `src/engine/write-files.js` validates destinations, stages writes, removes failed staging trees, and publishes completed trees atomically. `src/engine/render-templates.js` combines rendering with that safe write boundary (`writeRenderedFile` + `render`/`readTemplate`/`buildVars`). `src/engine/install-dependencies.js` is the only engine process runner and stops at the first failed package-manager step. `src/engine/tested-versions.js` and `src/engine/load-library.js` expose version resolution and library loading separately. After the migration `lib/` shims are deleted; `src/` is the sole implementation.
 
 The first `npm install` creates the lockfile. Generated CI uses `npm ci`, so the lockfile must be committed before CI is enabled. `create-win-project.profile.json` separately records the compatibility profile, architecture profile, and authentication intent/model/audience; after generation, that project owns its own upgrade lifecycle.
 
 ### Compatibility profile lifecycle
 
-Exactly one profile is `current` and one is `previous`. The current profile is the default. A profile owns exact npm, Spring Boot, runtime, and container versions; manifests and scaffold code may only request names or capabilities. Promotion copies the candidate into a new dated profile, marks the former current profile previous, and happens only after the generated-project matrix passes. Major changes also require migration notes. See `DEPENDENCY_MAINTENANCE.md`.
+Exactly one profile is `current` and one is `previous`. The current profile is the default. A profile owns exact npm, Spring Boot, runtime, and container versions; definitions and scaffold code may only request names or capabilities. Promotion copies the candidate into a new dated profile, marks the former current profile previous, and happens only after the generated-project matrix passes. Major changes also require migration notes. See `DEPENDENCY_MAINTENANCE.md`.
 
 ## Documentation model
 
@@ -91,7 +123,8 @@ Exactly one profile is `current` and one is `previous`. The current profile is t
 | `CONTEXT.md` | Product goals, boundaries, decisions, and project-specific facts. |
 | `RULES.md` | Generated concern-to-playbook section router. |
 | `playbooks/` | Reusable standards, recipes, rationale, and stack guidance. |
-| `docs/` | Documentation for the generated product, not generic framework teaching. |
+| `docs/` | Documentation for the generator (ARCHITECTURE, CONTRIBUTING, etc.), not generic framework teaching. |
+| `docs/CONTRIBUTING.md` | How to add a stack and run checks — the workflow, not the design. |
 
 Manifest section names are checked against Markdown headings. Numbered headings are normalized for matching, and generated contract tests reject unresolved `RULES.md` entries.
 
@@ -103,16 +136,26 @@ The generator itself has three verification levels:
 2. generated-output contract tests for required files, environment naming, playbook routing, profile-specific boundaries, auth metadata/code, testing profiles, and overwrite safety;
 3. a current-and-previous matrix across every supported stack combination, all three architecture profiles, and every applicable authentication model. It installs and runs lint, typecheck, tests, builds, Expo compatibility checks/web export, Spring MVC/security/Modulith tests and Maven packaging, Compose validation, and current-profile container builds.
 
+Additional architecture guards:
+
+- `tests/architecture-boundaries.test.js` enforces `src/engine` not importing `cli`/`stacks/frontends|backends` and `src/stacks` not importing `cli`/`engine`.
+- `tests/architecture/no-lib-legacy.test.js` bans `src/**` importing `lib/` and one-line wrapper regressions (`export * from '../../lib/...'`) and bans `lib/` existence after the migration.
+
+Tests mirror the production folders: `tests/cli`, `tests/engine`, `tests/stacks/frontends`, `tests/stacks/backends`.
+
 Canonical Markdown code examples should progressively move into extracted fixtures so examples compile against the versions they teach.
 
 ## Extension workflow
 
-When adding a stack or capability:
+When adding a stack or capability (see `docs/CONTRIBUTING.md` for the full checklist):
 
-1. Add its manifest, all five stack facets, and any platform/capability routes.
-2. Add the smallest runnable files needed in `lib/scaffold.js` or a focused scaffold module.
-3. Add every supported architecture/authentication combination to the generated-output matrix.
-4. Run install, lint/typecheck, tests, and production build for the new fixture.
-5. Update this architecture document if ownership or the generation pipeline changed.
+1. Add its `library/**/definition.json` (names only, no versions), playbooks, and `library/tested-versions.json` entry remains version-free.
+2. Create one new `src/stacks/<frontends|backends>/<id>/` directory with `index.js` (`defineStackAdapter`), `create-files.js`, `dependencies.js`/`environment.js` where needed, and `auth/`+`ui/` subfolders for Laravel-style stacks.
+3. Register it once in `src/stacks/available-stacks.js` (explicit array — no scanning).
+4. Add focused contract tests in `tests/stacks/<id>/` and add the stack's cases to `checks/check-compatibility.js`.
+5. Run `npm test`, `node checks/check-library.js`, and `npm run verify:generated -- --profile=<id> --case=<id>-<backend> --architecture=medium` for every supported arch/auth combo; run `npm run matrix:smoke` before `dev` and `matrix:full` before `main`.
+6. Update this architecture document only if ownership or the generation pipeline changed.
 
 Do not advertise a capability solely because a playbook mentions it. A generated capability must have executable configuration and contract coverage.
+
+Adding a stack must not require editing the engine or unrelated stacks.

package/docs/CONTENT_MODEL.md

@@ -6,16 +6,16 @@ The project separates always-loaded instructions, task-routed standards, generat
 |---|---|---|
 | Agent commands, workflow, authority limits, definition of done | `templates/agents/*.md` → generated `AGENTS.md` | Every project; keep short |
 | Product goal, scope, decisions, unknowns | generated `CONTEXT.md` | Every project; project-specific |
-| Concern routing | manifests → generated `RULES.md` | Selected stack/capability only |
+| Concern routing | definitions → generated `RULES.md` | Selected stack/capability only |
 | Reusable engineering policy and rationale | `playbooks/**/*.md` | A task touches that concern |
 | Setup, API, architecture, deployment for this product | generated `docs/` | Every project, then maintained with code |
-| Framework configuration and canonical patterns | `lib/scaffold.js` output plus tests | The capability is selected |
+| Framework configuration and canonical patterns | `src/stacks/` file contributions plus tests | The capability is selected |
 
 ## Authoring rules
 
 1. Put a rule in the narrowest applicable playbook. Do not repeat it in `AGENTS.md`, `README.md`, and stack guides.
 2. Write normative language only for behavior the generator configures or tests. Label uninstalled libraries and alternative architectures as optional.
-3. Route concerns to exact Markdown headings from their manifest. Heading changes and manifest changes belong in the same commit.
+3. Route concerns to exact Markdown headings from their definition. Heading changes and definition changes belong in the same commit.
 4. Prefer a compact rule, a reason, and one canonical example. Remove tutorial-length alternatives that compete with the default.
 5. Keep secrets, authentication, authorization, validation, accessibility, and failure behavior at explicit trust boundaries.
 6. Product docs describe the generated application. Playbooks teach reusable practices; they must not invent product endpoints or entities.